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

[Thomas Lamprecht]

On 11/6/19 10:46 AM, Fabian Ebner wrote:
> 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

When does it has short-lived files? Can you be a bit more exact? I mean ZFS
cannot guess if the files are short-lifed so a user could wonder what is meant
at all here..

> +performance when those files are small. Use SSDs for the `special` device.

"when those files are small." sounds really weird, IMO.

maybe
"can further increase the performance for whole small files"
(with reference to below to tell the reader that it's explained better
there?

> +
> +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.

up to that size .. in [bytes,kbytes,...?]

> +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!
>
I've still no idea how to pass special_small_blocks, written out?
I'd mention that somewhere, best with a concrete example.