[pve-devel] [PATCH docs] zfs: add section on zpool-features

[Dylan Whyte]

Hi,

I've just made some small corrections and wording changes that sounded 
right.


Reviewed-by: Dylan Whyte<d.whyte at proxmox.com>

On 3/30/21 8:26 PM, Stoiko Ivanov wrote:
> primarily in order to warn users booting from ZFS with grub.
>
> Signed-off-by: Stoiko Ivanov <s.ivanov at proxmox.com>
> ---
>   local-zfs.adoc | 36 ++++++++++++++++++++++++++++++++++++
>   1 file changed, 36 insertions(+)
>
> diff --git a/local-zfs.adoc b/local-zfs.adoc
> index 4819678..a003a7c 100644
> --- a/local-zfs.adoc
> +++ b/local-zfs.adoc
> @@ -699,3 +699,39 @@ in the pool will opt in for small file blocks).
>   ----
>   # zfs set special_small_blocks=0 <pool>/<filesystem>
>   ----
> +
> +[[sysadmin_zfs_features]]
> +ZFS Pool Features
> +~~~~~~~~~~~~~~~~~
> +
> +Changes to the on-disk format in ZFS are only done between major version changes
s/done/made/
> +and are specified through *features*. All features and the general mechanism
s/features and the general/features, as well as the general/
> +are well documented in the `zpool-features(5)` manpage.
> +
> +Since enabling new features can render a pool not importable by an older version
> +of ZFS, this needs to be actively done by the administrator by running
s/actively done/done actively/

s/administrator by/administrator, by/
> +`zpool upgrade` on the pool (see the `zpool-upgrade(8)` manpage).
> +
> +Unless you need to use one of the new features there is no upside to enabling
s/features there/features, there/
> +the new features.
s/the new features/them/
> +
> +On the other hand there are a few downsides on enabling new features:
s/On the other hand/In fact,/

s/a few/some/

s/downsides on/downsides to/
> +
> +* A system, with root on ZFS, still booting with `grub` will become unbootable
s/A system, with/A system with/

s/still booting with `grub`/that still boots using `grub`/
> +  if a new feature is active on the rpool, due to the incompatible
> +  implementation of ZFS in grub.
> +* The system will not be able to boot with an older kernel, which is still
> +  shipping the old ZFS modules
s/which is still shipping/which still ships with/

*Add full stop
> +* Booting an older {pve} ISO to do repair a non-booting system likewise will not
s/likewise will/will likewise/
s/to do repair/to repair/
> +  work
*Add full stop
> +
> +IMPORTANT: Do not upgrade your rpool if your system is still booted with `grub`.
> +Systems installed before PVE 5.4, and systems booting with legacy boot (see
> +xref:sysboot_determine_bootloader_used[how to determine the bootloader]), as
> +this will render your system unbootable.
I would change/rearrange to:

IMPORTANT: Do not upgrade your rpool, if your system is still booted 
with `grub`,

as this will render your system unbootable. This includes systems 
installed before

{pve} 5.4 and systems that boot using legacy boot (see

xref:sysboot_determine_bootloader_used[how to determine the bootloader]).
> +
> +.Enable new features for a pool:
> +----
> +# zpool upgrade <pool>
> +----
> +