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

[Aaron Lauterer]

Looks good to me.

Reviewed-By: Aaron Lauterer <a.lauterer 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
> +and are specified through *features*. All features and the general mechanism
> +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
> +`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
> +the new features.
> +
> +On the other hand there are a few downsides on enabling new features:
> +
> +* A system, with root on ZFS, still booting with `grub` will become unbootable
> +  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
> +* Booting an older {pve} ISO to do repair a non-booting system likewise will not
> +  work
> +
> +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.
> +
> +.Enable new features for a pool:
> +----
> +# zpool upgrade <pool>
> +----
> +
>