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

[Fabian Ebner]

Thanks for the suggestions, I'll do a v3.

On 11/6/19 8:40 PM, Thomas Lamprecht wrote:
> 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..
> 

Maybe "...workloads that involve creating or deleting a large number of 
files..." instead of talking about "short-lived files".

>> +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?
> 
Ok, I'll think of something.

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

I'll use concrete values in the examples. And it might also be better to 
explain the <size> parameter first (move the NOTE up) and then state the 
examples.