openzfs
Clarify zpool status upgrade suggestion
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
Description
Change merely changes the output message to include '
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
- [x] 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:
- [x] My code follows the OpenZFS code style requirements.
- [ ] I have updated the documentation accordingly.
- [x] 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.
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.
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 get the motivation, but if we were to reword this I think we'd want to update all the
zpool commandhints 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.
At very least
checkstyleis 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.
