Description
blindly running dnf upgrade
can result in updating to a kernel incompatible with openzfs, and this is a trap that new users frequently fall for (myself included). the documentation could do a lot more here.
https://openzfs.github.io/openzfs-docs/Getting%20Started/Fedora/index.html
eventually, perhaps the dnf system could be leveraged to automatically deal with this:
openzfs/zfs#17265
but in the meantime, i think it would be great to update the docs to provide the real-world workarounds that are frequently repeated in github issues when poor users can't access their data (or can't boot if they use openzfs as root fs, lol).
there are countless workaround posts, but here's a few for inspiration:
openzfs/zfs#17242 (comment)
openzfs/zfs#17116 (comment)
openzfs/zfs#16590 (comment)
specifically, i think that the documentation should:
- indicate that the fedora release cycle almost always eventually ships an incompatible kernel
- inform users that before installing, they should check if they're on a compatible kernel. if not, they need to use koji to install an older kernel. however, consider the current situation: fedora 42 ships with 6.14, but openzfs supports 6.13. is it advisable to downgrade fedora 42 to 6.13, or is it better to use fedora 41? i have no idea, but the docs should address that if needed.
- inform users that after installing, they need to be careful when updating and use
dnf upgrade --exclude
as needed (see links above). - provide instructions on how to fix a broken installation by using koji to downgrade the kernel (see Fedora 41 repo zfs#16590 (comment)). also provide instructions for how to fix this if the poor user boots from zfs (root on zfs).
also, regarding this part of the existing documentation:
By default ZFS may be removed by kernel package updates.
To lock the kernel version to only ones supported by ZFS to prevent this::echo 'zfs' > /etc/dnf/protected.d/zfs.conf
Pending non-kernel updates can still be applied::
dnf update --exclude=kernel*
i don't think this shows the workflow in enough detail, and i honestly have no clue what echo 'zfs' > /etc/dnf/protected.d/zfs.conf
is supposed to actually accomplish. it definitely does not protect you from installing an incompatible kernel and breaking openzfs :)