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

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

[Stoiko Ivanov]

primarily in order to warn users booting from ZFS with grub.

Signed-off-by: Stoiko Ivanov <s.ivanov@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>
+----
+
-- 
2.20.1

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

[Aaron Lauterer]

Looks good to me.

Reviewed-By: Aaron Lauterer <a.lauterer@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@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>
> +----
> +
> 

Re: [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@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@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>
> +----
> +