[pve-devel] [PATCH v2 docs] Add section for ZFS Special Device

[Fabian Ebner]

Signed-off-by: Fabian Ebner <f.ebner at proxmox.com>
---

Changes from v1:
    * Reworded the part that describes when a special device is useful
    * Moved that part to the top, so people know right away whether it's
      interesting for them
    * Add note about values for the special_small_blocks parameter
    * Split a long sentence

 local-zfs.adoc | 49 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 49 insertions(+)

diff --git a/local-zfs.adoc b/local-zfs.adoc
index b4fb7db..ba211ef 100644
--- a/local-zfs.adoc
+++ b/local-zfs.adoc
@@ -431,3 +431,52 @@ 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 if the pool has many
+short-lived files. Enabling `special_small_blocks` can further increase the
+performance when those files are small. 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>
+
+For ZFS datasets where the `special_small_blocks` property is set to a non-zero
+value, the `special` device is used to store small file blocks up to that size.
+Setting the `special_small_blocks` property on the 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=<size> <pool>
+
+.Opt in for small file blocks for a single dataset:
+
+ zfs set special_small_blocks=<size> <pool>/<filesystem>
+
+.Opt out from small file blocks for a single dataset:
+
+ zfs set special_small_blocks=0 <pool>/<filesystem>
+
+NOTE: The value for `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`.
+If the value for `size` is greater than or equal to the `recordsize` of the
+dataset, all data will be written to the `special` device, so be careful!
-- 
2.20.1