Add ZFS feature flag information to Guide
When upgrading FreeNAS to 11.2-RC2, the upgrade boots with an alert pre-created: New feature flags are available for volume Main_pool. Refer to the "Upgrading a ZFS Pool" subsection in the User Guide "Installing and Upgrading" chapter and "Upgrading" section for more instructions.
The problem is that nowhere is the user actually told what these upgraded feature flag changes or enhancements are - The referred sections of the docs merely describe feature flags and the upgrade procedure generally.
Especially, when the user goes to the "pools" menu and sees an upgrade is available, the exact details should be linked so they can read before deciding if they want to upgrade their pools. But the GUI just says "An upgrade is available" and that it can't be reversed - again no info.
The actual info I'm expecting is "given on the forums"https://forums.freenas.org/index.php?resources/zfs-feature-flags-in-freenas.95 . This is a pretty good way to do it, listing the flags, and what they do. Perhaps it could be formatted as a bullet list/table (FreeNAS version/new flags/what they do), but that's semantics.
What I'd like is:
- A page or section "ZFS feature flag upgrades" in the docs, that's also crosslinked as needed from both "ZFS primer" + "Upgrading" sections;
- When the user goes to pools -> upgrade, the relevant docs info is linked and the user told to read it before deciding if they want to upgrade their pool.
As this will impact on all users moving to 11.2, and the info isn't obvious, can this be done before 11.2-REL? Thanks.
#6 Updated by Dru Lavigne about 3 years ago
Stilez: the intro (https://www.ixsystems.com/documentation/freenas/11.2/intro.html#new-features-in-release) to the 11.2 series Guide has had this since BETA1:
OpenZFS is up-to-date with Illumos and slightly ahead due to support for sorted scrubs which were ported from ZFS on Linux. Notable improvements include channel programs, data disk removal, more resilient volume import, the ability to import a pool with missing vdevs, pool checkpoints, improved compressed ARC performance, and ZIL batching. As part of this change, the default ZFS indirect block size is reduced to 32 KiB from 128 KiB. Note that many of these improvements need further testing so have not yet been integrated into the UI.
The tooltip itself won't be updated until U1 as the GUI is frozen in prep for RELEASE.
#7 Updated by Stilez y about 3 years ago
Dru - But nothing whatsoever in the text quoted gives a user the info they need to actually make an upgrade decision, when they are told a pool feature flag upgrade is available after 11.2 is released. Providing a list of "notable improvements" does not distinguish which of them are present simply by having upgraded the to 11.2, and which of them will only be obtained (or fully leveraged) by also upgrading their .
An 11.2 upgrader must balance the benefits of an irreversible pool upgrade, against the risk of ever needing to boot or run 11.1 again. That's fine, and the manual explains that choice clearly. But an 11.2-REL upgrader who tries to decide (per docs) whether they are better to upgrade their pool or not, simply can't assess their own use-case unless they know which of these benefits are obtained just by running 11.2 OS (even with a <= 11.1 feature flag pool), and which of these benefits will be obtained by matching 11.2 OS with an 11.2 feature flag upgraded pool.
That is the problem that I'm raising. I hope this makes it clear and the docs can clarify this aspect before release.
#8 Updated by Stephen Cunningham almost 3 years ago
I agree it would be helpful if more information was given since this is important. Currently the user is forced to research the feature flags or take a leap of faith. I know there are commands you can use to find some info but I don't see it listed in the documentation and information on the forums is limited. I found this ticket trying to find what different feature flags are on 11.3,11.2,11.1.
#18 Updated by Timothy Moore II almost 3 years ago
Testing: Check both the angulargui and legacy UI versions of the guide. Build the guide and verify the ZFS Primer chapter has a new ZFS Feature Flags subsection. Verify there is a link to zpool-features(7) and that it works. Check the Install, Storage, and Alert chapters for working links to "ZFS Feature Flags" section.
#19 Updated by Dru Lavigne almost 3 years ago
- Subject changed from Pool upgrade/feature flag changes highlighted in alerts on 11.1->11.2, but actual changes are nowhere described to Add ZFS feature flag information to Guide
- Needs Doc changed from Yes to No
- Needs Merging changed from Yes to No
Stilez: for now, the Guide contains references to get more info about feature flags. Please follow the related ticket for progress on additional work which will display this info in the UI in a future version.