8 ZFS is a combined file system and logical volume manager designed by
9 Sun Microsystems. Starting with {pve} 3.4, the native Linux
10 kernel port of the ZFS file system is introduced as optional
11 file system and also as an additional selection for the root
12 file system. There is no need for manually compile ZFS modules - all
13 packages are included.
15 By using ZFS, its possible to achieve maximum enterprise features with
16 low budget hardware, but also high performance systems by leveraging
17 SSD caching or even SSD only setups. ZFS can replace cost intense
18 hardware raid cards by moderate CPU and memory load combined with easy
21 .General ZFS advantages
23 * Easy configuration and management with {pve} GUI and CLI.
27 * Protection against data corruption
29 * Data compression on file system level
35 * Various raid levels: RAID0, RAID1, RAID10, RAIDZ-1, RAIDZ-2 and RAIDZ-3
37 * Can use SSD for cache
41 * Continuous integrity checking
43 * Designed for high storage capacities
45 * Protection against data corruption
47 * Asynchronous replication over network
59 ZFS depends heavily on memory, so you need at least 8GB to start. In
60 practice, use as much you can get for your hardware/budget. To prevent
61 data corruption, we recommend the use of high quality ECC RAM.
63 If you use a dedicated cache and/or log disk, you should use an
64 enterprise class SSD (e.g. Intel SSD DC S3700 Series). This can
65 increase the overall performance significantly.
67 IMPORTANT: Do not use ZFS on top of hardware controller which has its
68 own cache management. ZFS needs to directly communicate with disks. An
69 HBA adapter is the way to go, or something like LSI controller flashed
72 If you are experimenting with an installation of {pve} inside a VM
73 (Nested Virtualization), don't use `virtio` for disks of that VM,
74 since they are not supported by ZFS. Use IDE or SCSI instead (works
75 also with `virtio` SCSI controller type).
78 Installation as Root File System
79 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
81 When you install using the {pve} installer, you can choose ZFS for the
82 root file system. You need to select the RAID type at installation
86 RAID0:: Also called ``striping''. The capacity of such volume is the sum
87 of the capacities of all disks. But RAID0 does not add any redundancy,
88 so the failure of a single drive makes the volume unusable.
90 RAID1:: Also called ``mirroring''. Data is written identically to all
91 disks. This mode requires at least 2 disks with the same size. The
92 resulting capacity is that of a single disk.
94 RAID10:: A combination of RAID0 and RAID1. Requires at least 4 disks.
96 RAIDZ-1:: A variation on RAID-5, single parity. Requires at least 3 disks.
98 RAIDZ-2:: A variation on RAID-5, double parity. Requires at least 4 disks.
100 RAIDZ-3:: A variation on RAID-5, triple parity. Requires at least 5 disks.
102 The installer automatically partitions the disks, creates a ZFS pool
103 called `rpool`, and installs the root file system on the ZFS subvolume
106 Another subvolume called `rpool/data` is created to store VM
107 images. In order to use that with the {pve} tools, the installer
108 creates the following configuration entry in `/etc/pve/storage.cfg`:
114 content images,rootdir
117 After installation, you can view your ZFS pool status using the
127 NAME STATE READ WRITE CKSUM
129 mirror-0 ONLINE 0 0 0
132 mirror-1 ONLINE 0 0 0
136 errors: No known data errors
139 The `zfs` command is used configure and manage your ZFS file
140 systems. The following command lists all file systems after
145 NAME USED AVAIL REFER MOUNTPOINT
146 rpool 4.94G 7.68T 96K /rpool
147 rpool/ROOT 702M 7.68T 96K /rpool/ROOT
148 rpool/ROOT/pve-1 702M 7.68T 702M /
149 rpool/data 96K 7.68T 96K /rpool/data
150 rpool/swap 4.25G 7.69T 64K -
157 Depending on whether the system is booted in EFI or legacy BIOS mode the
158 {pve} installer sets up either `grub` or `systemd-boot` as main bootloader.
159 See the chapter on xref:sysboot[{pve} host bootladers] for details.
165 This section gives you some usage examples for common tasks. ZFS
166 itself is really powerful and provides many options. The main commands
167 to manage ZFS are `zfs` and `zpool`. Both commands come with great
168 manual pages, which can be read with:
177 To create a new pool, at least one disk is needed. The `ashift` should
178 have the same sector-size (2 power of `ashift`) or larger as the
182 # zpool create -f -o ashift=12 <pool> <device>
185 To activate compression (see section <<zfs_compression,Compression in ZFS>>):
188 # zfs set compression=lz4 <pool>
191 .Create a new pool with RAID-0
196 # zpool create -f -o ashift=12 <pool> <device1> <device2>
199 .Create a new pool with RAID-1
204 # zpool create -f -o ashift=12 <pool> mirror <device1> <device2>
207 .Create a new pool with RAID-10
212 # zpool create -f -o ashift=12 <pool> mirror <device1> <device2> mirror <device3> <device4>
215 .Create a new pool with RAIDZ-1
220 # zpool create -f -o ashift=12 <pool> raidz1 <device1> <device2> <device3>
223 .Create a new pool with RAIDZ-2
228 # zpool create -f -o ashift=12 <pool> raidz2 <device1> <device2> <device3> <device4>
231 .Create a new pool with cache (L2ARC)
233 It is possible to use a dedicated cache drive partition to increase
234 the performance (use SSD).
236 As `<device>` it is possible to use more devices, like it's shown in
237 "Create a new pool with RAID*".
240 # zpool create -f -o ashift=12 <pool> <device> cache <cache_device>
243 .Create a new pool with log (ZIL)
245 It is possible to use a dedicated cache drive partition to increase
246 the performance(SSD).
248 As `<device>` it is possible to use more devices, like it's shown in
249 "Create a new pool with RAID*".
252 # zpool create -f -o ashift=12 <pool> <device> log <log_device>
255 .Add cache and log to an existing pool
257 If you have a pool without cache and log. First partition the SSD in
258 2 partition with `parted` or `gdisk`
260 IMPORTANT: Always use GPT partition tables.
262 The maximum size of a log device should be about half the size of
263 physical memory, so this is usually quite small. The rest of the SSD
264 can be used as cache.
267 # zpool add -f <pool> log <device-part1> cache <device-part2>
270 .Changing a failed device
273 # zpool replace -f <pool> <old device> <new device>
276 .Changing a failed bootable device
278 Depending on how {pve} was installed it is either using `grub` or `systemd-boot`
279 as bootloader (see xref:sysboot[Host Bootloader]).
281 The first steps of copying the partition table, reissuing GUIDs and replacing
282 the ZFS partition are the same. To make the system bootable from the new disk,
283 different steps are needed which depend on the bootloader in use.
286 # sgdisk <healthy bootable device> -R <new device>
287 # sgdisk -G <new device>
288 # zpool replace -f <pool> <old zfs partition> <new zfs partition>
291 NOTE: Use the `zpool status -v` command to monitor how far the resivlering
292 process of the new disk has progressed.
297 # pve-efiboot-tool format <new disk's ESP>
298 # pve-efiboot-tool init <new disk's ESP>
301 NOTE: `ESP` stands for EFI System Partition, which is setup as partition #2 on
302 bootable disks setup by the {pve} installer since version 5.4. For details, see
303 xref:sysboot_systemd_boot_setup[Setting up a new partition for use as synced ESP].
308 # grub-install <new disk>
311 Activate E-Mail Notification
312 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
314 ZFS comes with an event daemon, which monitors events generated by the
315 ZFS kernel module. The daemon can also send emails on ZFS events like
316 pool errors. Newer ZFS packages ship the daemon in a separate package,
317 and you can install it using `apt-get`:
320 # apt-get install zfs-zed
323 To activate the daemon it is necessary to edit `/etc/zfs/zed.d/zed.rc` with your
324 favourite editor, and uncomment the `ZED_EMAIL_ADDR` setting:
327 ZED_EMAIL_ADDR="root"
330 Please note {pve} forwards mails to `root` to the email address
331 configured for the root user.
333 IMPORTANT: The only setting that is required is `ZED_EMAIL_ADDR`. All
334 other settings are optional.
337 Limit ZFS Memory Usage
338 ~~~~~~~~~~~~~~~~~~~~~~
340 It is good to use at most 50 percent (which is the default) of the
341 system memory for ZFS ARC to prevent performance shortage of the
342 host. Use your preferred editor to change the configuration in
343 `/etc/modprobe.d/zfs.conf` and insert:
346 options zfs zfs_arc_max=8589934592
349 This example setting limits the usage to 8GB.
353 If your root file system is ZFS you must update your initramfs every
354 time this value changes:
357 # update-initramfs -u
366 Swap-space created on a zvol may generate some troubles, like blocking the
367 server or generating a high IO load, often seen when starting a Backup
368 to an external Storage.
370 We strongly recommend to use enough memory, so that you normally do not
371 run into low memory situations. Should you need or want to add swap, it is
372 preferred to create a partition on a physical disk and use it as swapdevice.
373 You can leave some space free for this purpose in the advanced options of the
374 installer. Additionally, you can lower the
375 ``swappiness'' value. A good value for servers is 10:
378 # sysctl -w vm.swappiness=10
381 To make the swappiness persistent, open `/etc/sysctl.conf` with
382 an editor of your choice and add the following line:
388 .Linux kernel `swappiness` parameter values
389 [width="100%",cols="<m,2d",options="header"]
390 |===========================================================
392 | vm.swappiness = 0 | The kernel will swap only to avoid
393 an 'out of memory' condition
394 | vm.swappiness = 1 | Minimum amount of swapping without
395 disabling it entirely.
396 | vm.swappiness = 10 | This value is sometimes recommended to
397 improve performance when sufficient memory exists in a system.
398 | vm.swappiness = 60 | The default value.
399 | vm.swappiness = 100 | The kernel will swap aggressively.
400 |===========================================================
403 Encrypted ZFS Datasets
404 ~~~~~~~~~~~~~~~~~~~~~~
406 ZFS on Linux version 0.8.0 introduced support for native encryption of
407 datasets. After an upgrade from previous ZFS on Linux versions, the encryption
408 feature can be enabled per pool:
411 # zpool get feature@encryption tank
412 NAME PROPERTY VALUE SOURCE
413 tank feature@encryption disabled local
415 # zpool set feature@encryption=enabled
417 # zpool get feature@encryption tank
418 NAME PROPERTY VALUE SOURCE
419 tank feature@encryption enabled local
422 WARNING: There is currently no support for booting from pools with encrypted
423 datasets using Grub, and only limited support for automatically unlocking
424 encrypted datasets on boot. Older versions of ZFS without encryption support
425 will not be able to decrypt stored data.
427 NOTE: It is recommended to either unlock storage datasets manually after
428 booting, or to write a custom unit to pass the key material needed for
429 unlocking on boot to `zfs load-key`.
431 WARNING: Establish and test a backup procedure before enabling encryption of
432 production data. If the associated key material/passphrase/keyfile has been
433 lost, accessing the encrypted data is no longer possible.
435 Encryption needs to be setup when creating datasets/zvols, and is inherited by
436 default to child datasets. For example, to create an encrypted dataset
437 `tank/encrypted_data` and configure it as storage in {pve}, run the following
441 # zfs create -o encryption=on -o keyformat=passphrase tank/encrypted_data
445 # pvesm add zfspool encrypted_zfs -pool tank/encrypted_data
448 All guest volumes/disks create on this storage will be encrypted with the
449 shared key material of the parent dataset.
451 To actually use the storage, the associated key material needs to be loaded
455 # zfs load-key tank/encrypted_data
456 Enter passphrase for 'tank/encrypted_data':
459 It is also possible to use a (random) keyfile instead of prompting for a
460 passphrase by setting the `keylocation` and `keyformat` properties, either at
461 creation time or with `zfs change-key` on existing datasets:
464 # dd if=/dev/urandom of=/path/to/keyfile bs=32 count=1
466 # zfs change-key -o keyformat=raw -o keylocation=file:///path/to/keyfile tank/encrypted_data
469 WARNING: When using a keyfile, special care needs to be taken to secure the
470 keyfile against unauthorized access or accidental loss. Without the keyfile, it
471 is not possible to access the plaintext data!
473 A guest volume created underneath an encrypted dataset will have its
474 `encryptionroot` property set accordingly. The key material only needs to be
475 loaded once per encryptionroot to be available to all encrypted datasets
478 See the `encryptionroot`, `encryption`, `keylocation`, `keyformat` and
479 `keystatus` properties, the `zfs load-key`, `zfs unload-key` and `zfs
480 change-key` commands and the `Encryption` section from `man zfs` for more
481 details and advanced usage.
488 When compression is enabled on a dataset, ZFS tries to compress all *new*
489 blocks before writing them and decompresses them on reading. Already
490 existing data will not be compressed retroactively.
492 You can enable compression with:
495 # zfs set compression=<algorithm> <dataset>
498 We recommend using the `lz4` algorithm, because it adds very little CPU
499 overhead. Other algorithms like `lzjb` and `gzip-N`, where `N` is an
500 integer from `1` (fastest) to `9` (best compression ratio), are also
501 available. Depending on the algorithm and how compressible the data is,
502 having compression enabled can even increase I/O performance.
504 You can disable compression at any time with:
507 # zfs set compression=off <dataset>
510 Again, only new blocks will be affected by this change.
516 Since version 0.8.0 ZFS supports `special` devices. A `special` device in a
517 pool is used to store metadata, deduplication tables, and optionally small
520 A `special` device can improve the speed of a pool consisting of slow spinning
521 hard disks with a lot of metadata changes. For example workloads that involve
522 creating, updating or deleting a large number of files will benefit from the
523 presence of a `special` device. ZFS datasets can also be configured to store
524 whole small files on the `special` device which can further improve the
525 performance. Use fast SSDs for the `special` device.
527 IMPORTANT: The redundancy of the `special` device should match the one of the
528 pool, since the `special` device is a point of failure for the whole pool.
530 WARNING: Adding a `special` device to a pool cannot be undone!
532 .Create a pool with `special` device and RAID-1:
535 # zpool create -f -o ashift=12 <pool> mirror <device1> <device2> special mirror <device3> <device4>
538 .Add a `special` device to an existing pool with RAID-1:
541 # zpool add <pool> special mirror <device1> <device2>
544 ZFS datasets expose the `special_small_blocks=<size>` property. `size` can be
545 `0` to disable storing small file blocks on the `special` device or a power of
546 two in the range between `512B` to `128K`. After setting the property new file
547 blocks smaller than `size` will be allocated on the `special` device.
549 IMPORTANT: If the value for `special_small_blocks` is greater than or equal to
550 the `recordsize` (default `128K`) of the dataset, *all* data will be written to
551 the `special` device, so be careful!
553 Setting the `special_small_blocks` property on a pool will change the default
554 value of that property for all child ZFS datasets (for example all containers
555 in the pool will opt in for small file blocks).
557 .Opt in for all file smaller than 4K-blocks pool-wide:
560 # zfs set special_small_blocks=4K <pool>
563 .Opt in for small file blocks for a single dataset:
566 # zfs set special_small_blocks=4K <pool>/<filesystem>
569 .Opt out from small file blocks for a single dataset:
572 # zfs set special_small_blocks=0 <pool>/<filesystem>