bump version to 6.2-6
[pve-docs.git] / local-zfs.adoc
1 [[chapter_zfs]]
2 ZFS on Linux
3 ------------
4 ifdef::wiki[]
5 :pve-toplevel:
6 endif::wiki[]
7
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.
14
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
19 management.
20
21 .General ZFS advantages
22
23 * Easy configuration and management with {pve} GUI and CLI.
24
25 * Reliable
26
27 * Protection against data corruption
28
29 * Data compression on file system level
30
31 * Snapshots
32
33 * Copy-on-write clone
34
35 * Various raid levels: RAID0, RAID1, RAID10, RAIDZ-1, RAIDZ-2 and RAIDZ-3
36
37 * Can use SSD for cache
38
39 * Self healing
40
41 * Continuous integrity checking
42
43 * Designed for high storage capacities
44
45 * Protection against data corruption
46
47 * Asynchronous replication over network
48
49 * Open Source
50
51 * Encryption
52
53 * ...
54
55
56 Hardware
57 ~~~~~~~~
58
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.
62
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.
66
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
70 in ``IT'' mode.
71
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).
76
77
78 Installation as Root File System
79 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
80
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
83 time:
84
85 [horizontal]
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.
89
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.
93
94 RAID10:: A combination of RAID0 and RAID1. Requires at least 4 disks.
95
96 RAIDZ-1:: A variation on RAID-5, single parity. Requires at least 3 disks.
97
98 RAIDZ-2:: A variation on RAID-5, double parity. Requires at least 4 disks.
99
100 RAIDZ-3:: A variation on RAID-5, triple parity. Requires at least 5 disks.
101
102 The installer automatically partitions the disks, creates a ZFS pool
103 called `rpool`, and installs the root file system on the ZFS subvolume
104 `rpool/ROOT/pve-1`.
105
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`:
109
110 ----
111 zfspool: local-zfs
112         pool rpool/data
113         sparse
114         content images,rootdir
115 ----
116
117 After installation, you can view your ZFS pool status using the
118 `zpool` command:
119
120 ----
121 # zpool status
122   pool: rpool
123  state: ONLINE
124   scan: none requested
125 config:
126
127         NAME        STATE     READ WRITE CKSUM
128         rpool       ONLINE       0     0     0
129           mirror-0  ONLINE       0     0     0
130             sda2    ONLINE       0     0     0
131             sdb2    ONLINE       0     0     0
132           mirror-1  ONLINE       0     0     0
133             sdc     ONLINE       0     0     0
134             sdd     ONLINE       0     0     0
135
136 errors: No known data errors
137 ----
138
139 The `zfs` command is used configure and manage your ZFS file
140 systems. The following command lists all file systems after
141 installation:
142
143 ----
144 # zfs list
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  -
151 ----
152
153
154 [[sysadmin_zfs_raid_considerations]]
155 ZFS RAID Level Considerations
156 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
157
158 There are a few factors to take into consideration when choosing the layout of
159 a ZFS pool. The basic building block of a ZFS pool is the virtual device, or
160 `vdev`. All vdevs in a pool are used equally and the data is striped among them
161 (RAID0). Check the `zpool(8)` manpage for more details on vdevs.
162
163 [[sysadmin_zfs_raid_performance]]
164 Performance
165 ^^^^^^^^^^^
166
167 Each `vdev` type has different performance behaviors. The two
168 parameters of interest are the IOPS (Input/Output Operations per Second) and
169 the bandwidth with which data can be written or read.
170
171 A 'mirror' vdev (RAID1) will approximately behave like a single disk in regards
172 to both parameters when writing data. When reading data if will behave like the
173 number of disks in the mirror.
174
175 A common situation is to have 4 disks. When setting it up as 2 mirror vdevs
176 (RAID10) the pool will have the write characteristics as two single disks in
177 regard of IOPS and bandwidth. For read operations it will resemble 4 single
178 disks.
179
180 A 'RAIDZ' of any redundancy level will approximately behave like a single disk
181 in regard of IOPS with a lot of bandwidth. How much bandwidth depends on the
182 size of the RAIDZ vdev and the redundancy level.
183
184 For running VMs, IOPS is the more important metric in most situations.
185
186
187 [[sysadmin_zfs_raid_size_space_usage_redundancy]]
188 Size, Space usage and Redundancy
189 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
190
191 While a pool made of 'mirror' vdevs will have the best performance
192 characteristics, the usable space will be 50% of the disks available. Less if a
193 mirror vdev consists of more than 2 disks, for example in a 3-way mirror. At
194 least one healthy disk per mirror is needed for the pool to stay functional.
195
196 The usable space of a 'RAIDZ' type vdev of N disks is roughly N-P, with P being
197 the RAIDZ-level. The RAIDZ-level indicates how many arbitrary disks can fail
198 without losing data. A special case is a 4 disk pool with RAIDZ2. In this
199 situation it is usually better to use 2 mirror vdevs for the better performance
200 as the usable space will be the same.
201
202 Another important factor when using any RAIDZ level is how ZVOL datasets, which
203 are used for VM disks, behave. For each data block the pool needs parity data
204 which is at least the size of the minimum block size defined by the `ashift`
205 value of the pool. With an ashift of 12 the block size of the pool is 4k.  The
206 default block size for a ZVOL is 8k. Therefore, in a RAIDZ2 each 8k block
207 written will cause two additional 4k parity blocks to be written,
208 8k + 4k + 4k = 16k.  This is of course a simplified approach and the real
209 situation will be slightly different with metadata, compression and such not
210 being accounted for in this example.
211
212 This behavior can be observed when checking the following properties of the
213 ZVOL:
214
215  * `volsize`
216  * `refreservation` (if the pool is not thin provisioned)
217  * `used` (if the pool is thin provisioned and without snapshots present)
218
219 ----
220 # zfs get volsize,refreservation,used <pool>/vm-<vmid>-disk-X
221 ----
222
223 `volsize` is the size of the disk as it is presented to the VM, while
224 `refreservation` shows the reserved space on the pool which includes the
225 expected space needed for the parity data. If the pool is thin provisioned, the
226 `refreservation` will be set to 0. Another way to observe the behavior is to
227 compare the used disk space within the VM and the `used` property. Be aware
228 that snapshots will skew the value.
229
230 There are a few options to counter the increased use of space:
231
232 * Increase the `volblocksize` to improve the data to parity ratio
233 * Use 'mirror' vdevs instead of 'RAIDZ'
234 * Use `ashift=9` (block size of 512 bytes)
235
236 The `volblocksize` property can only be set when creating a ZVOL. The default
237 value can be changed in the storage configuration. When doing this, the guest
238 needs to be tuned accordingly and depending on the use case, the problem of
239 write amplification if just moved from the ZFS layer up to the guest.
240
241 Using `ashift=9` when creating the pool can lead to bad
242 performance, depending on the disks underneath, and cannot be changed later on.
243
244 Mirror vdevs (RAID1, RAID10) have favorable behavior for VM workloads. Use
245 them, unless your environmanet has specific needs and charactersitics where
246 RAIDZ performance characteristics are acceptable.
247
248
249 Bootloader
250 ~~~~~~~~~~
251
252 Depending on whether the system is booted in EFI or legacy BIOS mode the
253 {pve} installer sets up either `grub` or `systemd-boot` as main bootloader.
254 See the chapter on xref:sysboot[{pve} host bootladers] for details.
255
256
257 ZFS Administration
258 ~~~~~~~~~~~~~~~~~~
259
260 This section gives you some usage examples for common tasks. ZFS
261 itself is really powerful and provides many options. The main commands
262 to manage ZFS are `zfs` and `zpool`. Both commands come with great
263 manual pages, which can be read with:
264
265 ----
266 # man zpool
267 # man zfs
268 -----
269
270 [[sysadmin_zfs_create_new_zpool]]
271 Create a new zpool
272 ^^^^^^^^^^^^^^^^^^
273
274 To create a new pool, at least one disk is needed. The `ashift` should
275 have the same sector-size (2 power of `ashift`) or larger as the
276 underlying disk.
277
278 ----
279 # zpool create -f -o ashift=12 <pool> <device>
280 ----
281
282 To activate compression (see section <<zfs_compression,Compression in ZFS>>):
283
284 ----
285 # zfs set compression=lz4 <pool>
286 ----
287
288 [[sysadmin_zfs_create_new_zpool_raid0]]
289 Create a new pool with RAID-0
290 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
291
292 Minimum 1 disk
293
294 ----
295 # zpool create -f -o ashift=12 <pool> <device1> <device2>
296 ----
297
298 [[sysadmin_zfs_create_new_zpool_raid1]]
299 Create a new pool with RAID-1
300 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
301
302 Minimum 2 disks
303
304 ----
305 # zpool create -f -o ashift=12 <pool> mirror <device1> <device2>
306 ----
307
308 [[sysadmin_zfs_create_new_zpool_raid10]]
309 Create a new pool with RAID-10
310 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
311
312 Minimum 4 disks
313
314 ----
315 # zpool create -f -o ashift=12 <pool> mirror <device1> <device2> mirror <device3> <device4>
316 ----
317
318 [[sysadmin_zfs_create_new_zpool_raidz1]]
319 Create a new pool with RAIDZ-1
320 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
321
322 Minimum 3 disks
323
324 ----
325 # zpool create -f -o ashift=12 <pool> raidz1 <device1> <device2> <device3>
326 ----
327
328 Create a new pool with RAIDZ-2
329 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
330
331 Minimum 4 disks
332
333 ----
334 # zpool create -f -o ashift=12 <pool> raidz2 <device1> <device2> <device3> <device4>
335 ----
336
337 [[sysadmin_zfs_create_new_zpool_with_cache]]
338 Create a new pool with cache (L2ARC)
339 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
340
341 It is possible to use a dedicated cache drive partition to increase
342 the performance (use SSD).
343
344 As `<device>` it is possible to use more devices, like it's shown in
345 "Create a new pool with RAID*".
346
347 ----
348 # zpool create -f -o ashift=12 <pool> <device> cache <cache_device>
349 ----
350
351 [[sysadmin_zfs_create_new_zpool_with_log]]
352 Create a new pool with log (ZIL)
353 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
354
355 It is possible to use a dedicated cache drive partition to increase
356 the performance(SSD).
357
358 As `<device>` it is possible to use more devices, like it's shown in
359 "Create a new pool with RAID*".
360
361 ----
362 # zpool create -f -o ashift=12 <pool> <device> log <log_device>
363 ----
364
365 [[sysadmin_zfs_add_cache_and_log_dev]]
366 Add cache and log to an existing pool
367 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
368
369 If you have a pool without cache and log. First partition the SSD in
370 2 partition with `parted` or `gdisk`
371
372 IMPORTANT: Always use GPT partition tables.
373
374 The maximum size of a log device should be about half the size of
375 physical memory, so this is usually quite small. The rest of the SSD
376 can be used as cache.
377
378 ----
379 # zpool add -f <pool> log <device-part1> cache <device-part2>
380 ----
381
382 [[sysadmin_zfs_change_failed_dev]]
383 Changing a failed device
384 ^^^^^^^^^^^^^^^^^^^^^^^^
385
386 ----
387 # zpool replace -f <pool> <old device> <new device>
388 ----
389
390 .Changing a failed bootable device
391
392 Depending on how {pve} was installed it is either using `grub` or `systemd-boot`
393 as bootloader (see xref:sysboot[Host Bootloader]).
394
395 The first steps of copying the partition table, reissuing GUIDs and replacing
396 the ZFS partition are the same. To make the system bootable from the new disk,
397 different steps are needed which depend on the bootloader in use.
398
399 ----
400 # sgdisk <healthy bootable device> -R <new device>
401 # sgdisk -G <new device>
402 # zpool replace -f <pool> <old zfs partition> <new zfs partition>
403 ----
404
405 NOTE: Use the `zpool status -v` command to monitor how far the resilvering
406 process of the new disk has progressed.
407
408 .With `systemd-boot`:
409
410 ----
411 # pve-efiboot-tool format <new disk's ESP>
412 # pve-efiboot-tool init <new disk's ESP>
413 ----
414
415 NOTE: `ESP` stands for EFI System Partition, which is setup as partition #2 on
416 bootable disks setup by the {pve} installer since version 5.4. For details, see
417 xref:sysboot_systemd_boot_setup[Setting up a new partition for use as synced ESP].
418
419 .With `grub`:
420
421 ----
422 # grub-install <new disk>
423 ----
424
425 Activate E-Mail Notification
426 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
427
428 ZFS comes with an event daemon, which monitors events generated by the
429 ZFS kernel module. The daemon can also send emails on ZFS events like
430 pool errors. Newer ZFS packages ship the daemon in a separate package,
431 and you can install it using `apt-get`:
432
433 ----
434 # apt-get install zfs-zed
435 ----
436
437 To activate the daemon it is necessary to edit `/etc/zfs/zed.d/zed.rc` with your
438 favourite editor, and uncomment the `ZED_EMAIL_ADDR` setting:
439
440 --------
441 ZED_EMAIL_ADDR="root"
442 --------
443
444 Please note {pve} forwards mails to `root` to the email address
445 configured for the root user.
446
447 IMPORTANT: The only setting that is required is `ZED_EMAIL_ADDR`. All
448 other settings are optional.
449
450
451 [[sysadmin_zfs_limit_memory_usage]]
452 Limit ZFS Memory Usage
453 ~~~~~~~~~~~~~~~~~~~~~~
454
455 It is good to use at most 50 percent (which is the default) of the
456 system memory for ZFS ARC to prevent performance shortage of the
457 host. Use your preferred editor to change the configuration in
458 `/etc/modprobe.d/zfs.conf` and insert:
459
460 --------
461 options zfs zfs_arc_max=8589934592
462 --------
463
464 This example setting limits the usage to 8GB.
465
466 [IMPORTANT]
467 ====
468 If your root file system is ZFS you must update your initramfs every
469 time this value changes:
470
471 ----
472 # update-initramfs -u
473 ----
474 ====
475
476
477 [[zfs_swap]]
478 SWAP on ZFS
479 ~~~~~~~~~~~
480
481 Swap-space created on a zvol may generate some troubles, like blocking the
482 server or generating a high IO load, often seen when starting a Backup
483 to an external Storage.
484
485 We strongly recommend to use enough memory, so that you normally do not
486 run into low memory situations. Should you need or want to add swap, it is
487 preferred to create a partition on a physical disk and use it as swapdevice.
488 You can leave some space free for this purpose in the advanced options of the
489 installer. Additionally, you can lower the
490 ``swappiness'' value. A good value for servers is 10:
491
492 ----
493 # sysctl -w vm.swappiness=10
494 ----
495
496 To make the swappiness persistent, open `/etc/sysctl.conf` with
497 an editor of your choice and add the following line:
498
499 --------
500 vm.swappiness = 10
501 --------
502
503 .Linux kernel `swappiness` parameter values
504 [width="100%",cols="<m,2d",options="header"]
505 |===========================================================
506 | Value               | Strategy
507 | vm.swappiness = 0   | The kernel will swap only to avoid
508 an 'out of memory' condition
509 | vm.swappiness = 1   | Minimum amount of swapping without
510 disabling it entirely.
511 | vm.swappiness = 10  | This value is sometimes recommended to
512 improve performance when sufficient memory exists in a system.
513 | vm.swappiness = 60  | The default value.
514 | vm.swappiness = 100 | The kernel will swap aggressively.
515 |===========================================================
516
517 [[zfs_encryption]]
518 Encrypted ZFS Datasets
519 ~~~~~~~~~~~~~~~~~~~~~~
520
521 ZFS on Linux version 0.8.0 introduced support for native encryption of
522 datasets. After an upgrade from previous ZFS on Linux versions, the encryption
523 feature can be enabled per pool:
524
525 ----
526 # zpool get feature@encryption tank
527 NAME  PROPERTY            VALUE            SOURCE
528 tank  feature@encryption  disabled         local
529
530 # zpool set feature@encryption=enabled
531
532 # zpool get feature@encryption tank
533 NAME  PROPERTY            VALUE            SOURCE
534 tank  feature@encryption  enabled         local
535 ----
536
537 WARNING: There is currently no support for booting from pools with encrypted
538 datasets using Grub, and only limited support for automatically unlocking
539 encrypted datasets on boot. Older versions of ZFS without encryption support
540 will not be able to decrypt stored data.
541
542 NOTE: It is recommended to either unlock storage datasets manually after
543 booting, or to write a custom unit to pass the key material needed for
544 unlocking on boot to `zfs load-key`.
545
546 WARNING: Establish and test a backup procedure before enabling encryption of
547 production data. If the associated key material/passphrase/keyfile has been
548 lost, accessing the encrypted data is no longer possible.
549
550 Encryption needs to be setup when creating datasets/zvols, and is inherited by
551 default to child datasets. For example, to create an encrypted dataset
552 `tank/encrypted_data` and configure it as storage in {pve}, run the following
553 commands:
554
555 ----
556 # zfs create -o encryption=on -o keyformat=passphrase tank/encrypted_data
557 Enter passphrase:
558 Re-enter passphrase:
559
560 # pvesm add zfspool encrypted_zfs -pool tank/encrypted_data
561 ----
562
563 All guest volumes/disks create on this storage will be encrypted with the
564 shared key material of the parent dataset.
565
566 To actually use the storage, the associated key material needs to be loaded
567 with `zfs load-key`:
568
569 ----
570 # zfs load-key tank/encrypted_data
571 Enter passphrase for 'tank/encrypted_data':
572 ----
573
574 It is also possible to use a (random) keyfile instead of prompting for a
575 passphrase by setting the `keylocation` and `keyformat` properties, either at
576 creation time or with `zfs change-key` on existing datasets:
577
578 ----
579 # dd if=/dev/urandom of=/path/to/keyfile bs=32 count=1
580
581 # zfs change-key -o keyformat=raw -o keylocation=file:///path/to/keyfile tank/encrypted_data
582 ----
583
584 WARNING: When using a keyfile, special care needs to be taken to secure the
585 keyfile against unauthorized access or accidental loss. Without the keyfile, it
586 is not possible to access the plaintext data!
587
588 A guest volume created underneath an encrypted dataset will have its
589 `encryptionroot` property set accordingly. The key material only needs to be
590 loaded once per encryptionroot to be available to all encrypted datasets
591 underneath it.
592
593 See the `encryptionroot`, `encryption`, `keylocation`, `keyformat` and
594 `keystatus` properties, the `zfs load-key`, `zfs unload-key` and `zfs
595 change-key` commands and the `Encryption` section from `man zfs` for more
596 details and advanced usage.
597
598
599 [[zfs_compression]]
600 Compression in ZFS
601 ~~~~~~~~~~~~~~~~~~
602
603 When compression is enabled on a dataset, ZFS tries to compress all *new*
604 blocks before writing them and decompresses them on reading. Already
605 existing data will not be compressed retroactively.
606
607 You can enable compression with:
608
609 ----
610 # zfs set compression=<algorithm> <dataset>
611 ----
612
613 We recommend using the `lz4` algorithm, because it adds very little CPU
614 overhead. Other algorithms like `lzjb` and `gzip-N`, where `N` is an
615 integer from `1` (fastest) to `9` (best compression ratio), are also
616 available. Depending on the algorithm and how compressible the data is,
617 having compression enabled can even increase I/O performance.
618
619 You can disable compression at any time with:
620
621 ----
622 # zfs set compression=off <dataset>
623 ----
624
625 Again, only new blocks will be affected by this change.
626
627
628 [[sysadmin_zfs_special_device]]
629 ZFS Special Device
630 ~~~~~~~~~~~~~~~~~~
631
632 Since version 0.8.0 ZFS supports `special` devices. A `special` device in a
633 pool is used to store metadata, deduplication tables, and optionally small
634 file blocks.
635
636 A `special` device can improve the speed of a pool consisting of slow spinning
637 hard disks with a lot of metadata changes. For example workloads that involve
638 creating, updating or deleting a large number of files will benefit from the
639 presence of a `special` device. ZFS datasets can also be configured to store
640 whole small files on the `special` device which can further improve the
641 performance. Use fast SSDs for the `special` device.
642
643 IMPORTANT: The redundancy of the `special` device should match the one of the
644 pool, since the `special` device is a point of failure for the whole pool.
645
646 WARNING: Adding a `special` device to a pool cannot be undone!
647
648 .Create a pool with `special` device and RAID-1:
649
650 ----
651 # zpool create -f -o ashift=12 <pool> mirror <device1> <device2> special mirror <device3> <device4>
652 ----
653
654 .Add a `special` device to an existing pool with RAID-1:
655
656 ----
657 # zpool add <pool> special mirror <device1> <device2>
658 ----
659
660 ZFS datasets expose the `special_small_blocks=<size>` property. `size` can be
661 `0` to disable storing small file blocks on the `special` device or a power of
662 two in the range between `512B` to `128K`. After setting the property new file
663 blocks smaller than `size` will be allocated on the `special` device.
664
665 IMPORTANT: If the value for `special_small_blocks` is greater than or equal to
666 the `recordsize` (default `128K`) of the dataset, *all* data will be written to
667 the `special` device, so be careful!
668
669 Setting the `special_small_blocks` property on a pool will change the default
670 value of that property for all child ZFS datasets (for example all containers
671 in the pool will opt in for small file blocks).
672
673 .Opt in for all file smaller than 4K-blocks pool-wide:
674
675 ----
676 # zfs set special_small_blocks=4K <pool>
677 ----
678
679 .Opt in for small file blocks for a single dataset:
680
681 ----
682 # zfs set special_small_blocks=4K <pool>/<filesystem>
683 ----
684
685 .Opt out from small file blocks for a single dataset:
686
687 ----
688 # zfs set special_small_blocks=0 <pool>/<filesystem>
689 ----