Clarify zpool status upgrade suggestion

[msplival]

Motivation and Context

The output of 'zpool status' can be confusing to the end user, suggesting upgrade of pools with 'zpool upgrade', where in fact more 'correct' message would be 'zpool upgrade '
This is the open issue explaining the problem in more detail: #17910

Description

Change merely changes the output message to include '' literal as a suggestion to end user on how to use 'zpool upgrade' command.

How Has This Been Tested?

I've compiled zfs on my machine (Ubuntu 24.04) with standard (Ubuntu provided) packages for needed dependencies.
I've created a test pool deliberately disabling some features:

zpool create \
  -o feature@blake3=disabled \
  -o feature@block_cloning=disabled \
  -o feature@vdev_zaps_v2=disabled \
  -o feature@head_errlog=disabled \
  -o feature@zilsaxattr=disabled \
  testpool /tmp/testpool.img

I then run 'zpool status' from ubuntu-provided zpool command:

(mario/zpool-clarify-upgrade-hint=1a54e) mario@MP52 ~/work/gits/zfs> zpool status
  pool: nvme-zfs
 state: ONLINE
  scan: scrub repaired 0B in 00:02:47 with 0 errors on Sun Nov  9 00:26:48 2025
config:

        NAME        STATE     READ WRITE CKSUM
        nvme-zfs    ONLINE       0     0     0
          nvme0n1   ONLINE       0     0     0

errors: No known data errors

  pool: testpool
 state: ONLINE
status: Some supported and requested features are not enabled on the pool.
        The pool can still be used, but some features are unavailable.
action: Enable all features using 'zpool upgrade'. Once this is done,
        the pool may no longer be accessible by software that does not support
        the features. See zpool-features(7) for details.
config:

        NAME                 STATE     READ WRITE CKSUM
        testpool             ONLINE       0     0     0
          /tmp/testpool.img  ONLINE       0     0     0

errors: No known data errors

Then, I run zpool from my compiled change:

(mario/zpool-clarify-upgrade-hint=1a54e) mario@MP52 ~/work/gits/zfs> ./zpool status
  pool: nvme-zfs
 state: ONLINE
  scan: scrub repaired 0B in 00:02:47 with 0 errors on Sun Nov  9 00:26:48 2025
config:

        NAME        STATE     READ WRITE CKSUM
        nvme-zfs    ONLINE       0     0     0
          nvme0n1   ONLINE       0     0     0

errors: No known data errors

  pool: testpool
 state: ONLINE
status: Some supported and requested features are not enabled on the pool.
        The pool can still be used, but some features are unavailable.
action: Enable all features using 'zpool upgrade <poolname>'. Once this is done,
        the pool may no longer be accessible by software that does not support
        the features. See zpool-features(7) for details.
config:

        NAME                 STATE     READ WRITE CKSUM
        testpool             ONLINE       0     0     0
          /tmp/testpool.img  ONLINE       0     0     0

errors: No known data errors

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Performance enhancement (non-breaking change which improves efficiency)
• Code cleanup (non-breaking change which makes code smaller or more readable)
• Quality assurance (non-breaking change which makes the code more robust against bugs)
• Breaking change (fix or feature that would cause existing functionality to change)
• Library ABI change (libzfs, libzfs_core, libnvpair, libuutil and libzfsbootenv)
• Documentation (a change to man pages or other documentation)

Checklist:

• My code follows the OpenZFS code style requirements.
• I have updated the documentation accordingly.
• I have read the contributing document.
• I have added tests to cover my changes.
• I have run the ZFS Test Suite with this change applied.
• All commit messages are properly formatted and contain Signed-off-by.

[amotin]

At very least checkstyle is unhappy: "./cmd/zpool/zpool_main.c: 10617: line > 80 characters". I personally not sure it is not too trivial -- the man pages are there and this is a sufficient reference IMHO.

[behlendorf]

I get the motivation, but if we were to reword this I think we'd want to update all the zpool command hints which might be printed. Skimming the zpool source I see we print hints to run 'zpool scrub', 'zpool import', 'zpool clear', 'zpool replace', 'zpool online', and other instances of 'zpool upgrade'. None of which mention needing to specify the pool name, this would become a bit of an oddball.

[msplival]

I get the motivation, but if we were to reword this I think we'd want to update all the zpool command hints which might be printed. Skimming the zpool source I see we print hints to run 'zpool scrub', 'zpool import', 'zpool clear', 'zpool replace', 'zpool online', and other instances of 'zpool upgrade'. None of which mention needing to specify the pool name, this would become a bit of an oddball.

I completely agree, my PR is, well, quite superficial. I'll see if adjusting print hints for other zpool commands is feasible and I'll update the PR.

[ykla]

At very least checkstyle is unhappy: "./cmd/zpool/zpool_main.c: 10617: line > 80 characters". I personally not sure it is not too trivial -- the man pages are there and this is a sufficient reference IMHO.

Sorry but I disagree with you.

zpool upgrade zroot is what I envisioned, which enables all features except those marked with (*). Running zpool upgrade alone simply lists the available features and does not actually upgrade them. I believe clarifying this point is very important. Because of this confusing explanation, I ended up going in circles for an hour between zpool upgrade, zpool status, and reboot.

Due to the long-term lack of maintenance in OpenZFS documentation and the absence of any systematic textbooks or guides on the market, this is likely why even AI may struggle to provide accurate information. Many seemingly minor improvements would significantly benefit end users.

Many similar confusing designs can end up wasting quite a bit of users’ time, such as entering a password but receiving no feedback or even no ****. While one could say this is for security, it isn’t sufficiently explained. I believe that adding a simple sentence—“Passwords are neither echoed nor displayed as *** on the screen, so nothing appears”—would clarify this without much effort.

[tonyhutter]

If we don't want to list the pool name, could we just say:

- Enable all features using 'zpool upgrade'.
+ Enable all features using 'zpool upgrade' on the pool.