improve fedora docs for safe dnf upgrading (incompatible kernel)

[ftc2]

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:

7. 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 :)

[jkool702]

@ftc2

i honestly have no clue what echo 'zfs' > /etc/dnf/protected.d/zfs.conf is supposed to actually accomplish

I believe this mainly ensures that if you run dnf update --allowerasing (or if allowerasing is enabled by default in the dnf config file) that dnf wont try to uninstall zfs to allow the updated kernel package that zfs is blocking to be installed.

eventually, perhaps the dnf system could be leveraged to automatically deal with this:

Believe it or not, this is probably going to happen quite soon (i.e., its all but guaranteed to work in zfs 2.3.2). The current setup (with zfs added to the protected packages list) almost works...when fedora updates to an incompatible kernel dnf silently stops trying to install new kernel-devel packages but otherwise continues to work normally.

if blocking kernel-devel in turn prevented the rest of the kernel packages from being updated (causing dnf to silently skip those as well but otherwise work normally) then the everything would work perfect. When they set this up the devs thought this would happen, but it didnt. BUT, the behavior for kernel-devel is correct, and explicitly blocking the other kernel packages too (instead of relying on kernel-devel to block them for you via dependencies) so they behave the same way is a super easy fix.

[jkool702]

@ftc2 - good news: the PR with the fix that makes DNF work correctly (openzfs/zfs#17271) has been merged and is included in the zfs 2.3.2 patchset.

[gmelikov]

2.3.2 is released, so let's close this issue.