Add section for ZFS Special Device

[pve-docs.git] / local-zfs.adoc

diff --git a/local-zfs.adoc b/local-zfs.adoc
index 76c92514e715958b8e78423b382dfece4ae4b853..f4db54b046a11f1a6c7255153f1ea3d4fd5f76ef 100644 (file)
--- a/local-zfs.adoc
+++ b/local-zfs.adoc
@@ -236,7 +236,7 @@ As `<device>` it is possible to use more devices, like it's shown in
 
 .Add cache and log to an existing pool
 
-If you have an pool without cache and log. First partition the SSD in
+If you have a pool without cache and log. First partition the SSD in
 2 partition with `parted` or `gdisk`
 
 IMPORTANT: Always use GPT partition tables.
@@ -269,7 +269,7 @@ Activate E-Mail Notification
 
 ZFS comes with an event daemon, which monitors events generated by the
 ZFS kernel module. The daemon can also send emails on ZFS events like
-pool errors. Newer ZFS packages ships the daemon in a separate package,
+pool errors. Newer ZFS packages ship the daemon in a separate package,
 and you can install it using `apt-get`:
 
 ----
@@ -314,7 +314,8 @@ time this value changes:
 
 
 [[zfs_swap]]
-.SWAP on ZFS
+SWAP on ZFS
+~~~~~~~~~~~
 
 Swap-space created on a zvol may generate some troubles, like blocking the
 server or generating a high IO load, often seen when starting a Backup
@@ -351,7 +352,8 @@ improve performance when sufficient memory exists in a system.
 |===========================================================
 
 [[zfs_encryption]]
-.Encrypted ZFS Datasets
+Encrypted ZFS Datasets
+~~~~~~~~~~~~~~~~~~~~~~
 
 ZFS on Linux version 0.8.0 introduced support for native encryption of
 datasets. After an upgrade from previous ZFS on Linux versions, the encryption
@@ -379,7 +381,7 @@ booting, or to write a custom unit to pass the key material needed for
 unlocking on boot to `zfs load-key`.
 
 WARNING: Establish and test a backup procedure before enabling encryption of
-production data.If the associated key material/passphrase/keyfile has been
+production data. If the associated key material/passphrase/keyfile has been
 lost, accessing the encrypted data is no longer possible.
 
 Encryption needs to be setup when creating datasets/zvols, and is inherited by
@@ -429,3 +431,56 @@ See the `encryptionroot`, `encryption`, `keylocation`, `keyformat` and
 `keystatus` properties, the `zfs load-key`, `zfs unload-key` and `zfs
 change-key` commands and the `Encryption` section from `man zfs` for more
 details and advanced usage.
+
+
+ZFS Special Device
+~~~~~~~~~~~~~~~~~~
+
+Since version 0.8.0 ZFS supports `special` devices. A `special` device in a
+pool is used to store metadata, deduplication tables, and optionally small
+file blocks.
+
+A `special` device can improve the speed of a pool consisting of slow spinning
+hard disks with a lot of changing metadata. For example workloads that involve
+creating or deleting a large number of files will benefit from the presence of
+a `special` device. ZFS datasets can be configured to store whole small files
+on the `special` device which can further improve the performance. Use SSDs for
+the `special` device.
+
+IMPORTANT: The redundancy of the `special` device should match the one of the
+pool, since the `special` device is a point of failure for the whole pool.
+
+WARNING: Adding a `special` device to a pool cannot be undone!
+
+.Create a pool with `special` device and RAID-1:
+
+ zpool create -f -o ashift=12 <pool> mirror <device1> <device2> special mirror <device3> <device4>
+
+.Add a `special` device to an existing pool with RAID-1:
+
+ zpool add <pool> special mirror <device1> <device2>
+
+ZFS datasets expose the `special_small_blocks=<size>` property. `size` can be
+`0` to disable storing small file blocks on the `special` device or a power of
+two in the range between `512B` to `128K`. After setting the property new file
+blocks smaller than `size` will be allocated on the `special` device.
+
+IMPORTANT: If the value for `special_small_blocks` is greater than or equal to
+the `recordsize` of the dataset, *all* data will be written to the `special`
+device, so be careful!
+
+Setting the `special_small_blocks` property on a pool will change the default
+value of that property for all child ZFS datasets (for example all containers
+in the pool will opt in for small file blocks).
+
+.Opt in for small file blocks pool-wide:
+
+ zfs set special_small_blocks=4K <pool>
+
+.Opt in for small file blocks for a single dataset:
+
+ zfs set special_small_blocks=4K <pool>/<filesystem>
+
+.Opt out from small file blocks for a single dataset:
+
+ zfs set special_small_blocks=0 <pool>/<filesystem>