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