Versions des modules ZFS : éviter les conflits entre le noyau et ZFS

Ce que signifie réellement « conflit noyau vs ZFS »

Sur Linux, ZFS est un module noyau plus des outils userland. Le module noyau fait le vrai travail : ARC, transaction groups, ordonnancement IO,
sommes de contrôle, compression, état des vdevs, import/export de pool. Les outils userland (zpool, zfs, zdb,
zed) constituent le plan de contrôle.

Le « conflit » survient lorsque ces pièces ne s’accordent pas sur les interfaces, les attentes ou les fonctionnalités activées. Cela peut se manifester par :

• Le module ne se charge pas après une mise à jour du noyau (échec DKMS classique, en-têtes manquants, symboles incompatibles).
• Le module se charge mais le pool ne s’importe pas en raison d’attentes liées aux feature flags ou de formats sur disque non supportés.
• Les outils affichent une version, le noyau en exécute une autre, entraînant des erreurs étranges comme « unsupported pool version » ou des propriétés absentes.
• Échecs au démarrage parce que l’initramfs n’inclut pas le bon module, donc le pool root n’apparaît jamais.

Votre travail est de maintenir l’alignement entre : attentes ABI du noyau, compilation du module ZFS, et feature flags sur disque. En d’autres termes : ne laissez pas votre pile de stockage devenir un projet de groupe mal coordonné.

Blague n°1 : Une mise à jour du noyau, c’est comme un exercice d’évacuation surprise — sauf que le feu, c’est votre stockage, et les panneaux de sortie sont gérés par DKMS.

Faits intéressants et contexte historique (ce que l’on oublie souvent)

1. ZFS a commencé chez Sun Microsystems (milieu des années 2000) et a intégré la vérification d’intégrité de bout en bout, le copy-on-write et le stockage en pool quand la plupart des systèmes de fichiers dépendaient encore du « fsck and pray ».
2. Linux n’intègre pas ZFS dans l’arbre kernel principalement pour des incompatibilités de licence (CDDL vs GPL). C’est pourquoi vous vivez dans le monde des modules externes.
3. Les « versions de pool » ont été remplacées par des « feature flags » dans OpenZFS moderne. Les feature flags permettent une négociation incrémentale des capacités au lieu de numéros de version monolithiques.
4. FreeBSD et illumos intègrent ZFS différemment. Sur Linux vous manipulez des modules hors-arbre ; sur FreeBSD c’est plus intégré.
5. DKMS a popularisé le workflow « reconstruire après mise à jour du noyau » pour que les modules tiers (ZFS, NVIDIA, etc.) n’exigent pas de recompilation manuelle à chaque fois.
6. L’inclusion dans l’initramfs est une question de disponibilité du stockage, pas d’« optimisation du démarrage ». Si ZFS n’est pas dans l’initramfs et que votre root est sur ZFS, vous êtes sur le point de vivre une expérience formatrice.
7. OpenZFS est un projet multiplateforme. Les décisions de fonctionnalité sont souvent contraintes par la nécessité de « fonctionner sur Linux/FreeBSD/macOS », pas seulement par votre distribution.
8. La version du module noyau n’est pas la version du format du pool. Les gens confondent ces notions, puis ils « mettent à niveau » le pool et découvrent qu’on ne peut pas revenir en arrière.

Les trois couches de compatibilité à ne pas confondre

1) Noyau ↔ module ZFS noyau (compatibilité build/ABI)

Votre noyau en cours d’exécution exporte des symboles. Le module ZFS attend certains symboles et structures. Si le noyau change et que le module
ne correspond pas, modprobe zfs échoue ou se charge avec des pièces manquantes.

Sur de nombreuses distributions, vous verrez ZFS empaqueté selon deux formes générales :

• Builds DKMS : le source de ZFS est installé ; le module est compilé localement pour chaque noyau. Flexible, mais vous devenez une chaîne de build.
• kmods précompilés : paquets de modules construits par la distribution pour des noyaux spécifiques. Moins flexibles, généralement plus prévisibles.

2) Outils userland ZFS ↔ module noyau ZFS (compatibilité ioctl/API)

Les outils zfs/zpool communiquent avec le noyau via des ioctls et des interfaces sysfs/proc. Si le userland est plus récent que
le module (ou inversement), vous pouvez obtenir des comportements étranges : propriétés manquantes, « commande inconnue », ou messages trompeurs de type « pool is outdated ».

La plupart des distributions s’efforcent d’expédier des paires assorties. Les problèmes surviennent quand vous mélangez des dépôts, n’épargnez qu’une moitié de la pile, ou faites vos propres builds.

3) Feature flags du pool ↔ implémentation ZFS (compatibilité des fonctionnalités sur disque)

C’est la partie qui vous mord à travers les machines. Les pools portent des feature flags : encryption, large_dnode, spacemap_histogram, etc.
Un système ne peut importer un pool que s’il supporte les fonctionnalités activées. L’import peut être en lecture seule dans certains scénarios, mais « je veux juste le monter pour copier les données » n’est pas une stratégie.

La commande dangereuse n’est pas zpool import. C’est zpool upgrade. La première négocie ; la seconde effectue des changements irréversibles.

Un maxim de fiabilité à garder sur un post-it. Voici une idée paraphrasée de Werner Vogels (CTO d’Amazon) : Construisez des systèmes qui supposent que les choses vont échouer, et faites en sorte que la récupération soit routinière. —idée paraphrasée

Méthode de diagnostic rapide

Quand ZFS et le noyau « se battent », ne vagabondez pas. Suivez un ordre strict pour localiser le goulot : démarrage, module, ou feature flags du pool.

Première étape : le module est-il chargé et est-ce bien celui que vous pensez ?

• Vérifiez uname -r, puis confirmez que les modules ZFS sont chargés pour ce noyau.
• Consultez les logs du noyau pour « Unknown symbol » ou mismatch vermagic.
• Confirmez que les outils userland et le module noyau ont des versions alignées.

Deuxième étape : le pool est-il visible et importable ?

• zpool import sans importer : liste-t-il le pool ?
• Essayez zpool import -N (ne pas monter) pour isoler l’import des problèmes de montage/propriétés.
• Recherchez des feature flags non supportés sur cet hôte.

Troisième étape : est-ce un problème de démarrage/initramfs ?

• Si le root est sur ZFS et que vous êtes tombé dans un shell initramfs : vérifiez que /lib/modules/$(uname -r) contient ZFS, reconstruisez l’initramfs.
• Confirmez que le bon noyau a démarré (pas un noyau de secours sans kmod ZFS correspondant).

Quatrième étape : incidents de performance qui ressemblent à des « problèmes de version »

Parfois le système démarre correctement et vous ne voyez des problèmes qu’en charge. Si ZFS est retombé silencieusement sur un build différent du module, ou si vous exécutez une combinaison noyau/ZFS avec une régression connue, le symptôme est « ZFS est lent » ou « txg prend une éternité », pas « mismatch de module ».

• Vérifiez les stats ARC et la pression mémoire.
• Vérifiez les temps de sync txg et la saturation I/O.
• Vérifiez si vous êtes sur un noyau récemment mis à jour sans kmod ZFS précompilé correspondant (DKMS a peut-être compilé quelque chose, mais l’a-t-il fait correctement ?).

Tâches pratiques : commandes, sorties et la décision que vous prenez

Ci-dessous figurent des tâches réelles que vous pouvez exécuter sur un hôte Linux typique utilisant les paquets OpenZFS. Les commandes sont montrées avec des sorties représentatives ; votre
environnement diffèrera. L’essentiel est ce que la sortie signifie et ce que vous faites ensuite.

Task 1: Confirm the running kernel (the target you must match)

cr0x@server:~$ uname -r
6.8.0-52-generic

Meaning: ZFS module must be built for 6.8.0-52-generic specifically.
Decision: Any ZFS module build/install steps must reference this kernel version. If you’re troubleshooting, keep this value in your head.

Task 2: Check whether the ZFS module is loaded

cr0x@server:~$ lsmod | grep -E '^zfs|^spl'
zfs                  6340608  6
spl                   131072  1 zfs

Meaning: Kernel has ZFS and SPL loaded (SPL is the Solaris Porting Layer).
Decision: If nothing shows up, try loading it and look for errors in the next tasks.

Task 3: Try loading ZFS and read the error (the kernel will tell you)

cr0x@server:~$ sudo modprobe zfs
modprobe: ERROR: could not insert 'zfs': Unknown symbol in module, or unknown parameter (see dmesg)

Meaning: The module binary doesn’t match the kernel’s exported symbols (classic mismatch after kernel update).
Decision: Immediately check dmesg, then rebuild/reinstall ZFS modules for this kernel, or boot the previous kernel that matches.

Task 4: Read kernel logs for vermagic/symbol mismatch

cr0x@server:~$ dmesg | tail -n 30
[  112.941230] zfs: disagrees about version of symbol module_layout
[  112.941251] zfs: Unknown symbol spl_kmem_cache_alloc (err -22)
[  112.941260] zfs: Unknown symbol spl_kmem_cache_free (err -22)

Meaning: Module built against different kernel headers or different SPL/ZFS pair.
Decision: Treat this as “module build problem,” not “pool problem.” Fix the module chain before touching ZFS on-disk features.

Task 5: Confirm the installed ZFS package versions (userland and kmods)

cr0x@server:~$ apt-cache policy zfsutils-linux zfs-dkms libzfs4linux
zfsutils-linux:
  Installed: 2.2.2-0ubuntu9
  Candidate: 2.2.2-0ubuntu9
zfs-dkms:
  Installed: 2.2.2-0ubuntu9
  Candidate: 2.2.2-0ubuntu9
libzfs4linux:
  Installed: 2.2.2-0ubuntu9
  Candidate: 2.2.2-0ubuntu9

Meaning: Userland and DKMS source package are aligned in version.
Decision: If these versions differ significantly (or come from mixed repos), stop and align them before debugging anything else.

Task 6: Check DKMS status (did it actually build for the current kernel?)

cr0x@server:~$ dkms status
zfs/2.2.2, 6.8.0-52-generic, x86_64: installed

Meaning: DKMS claims a ZFS module build exists for the running kernel.
Decision: If it says “added” or “built” but not “installed,” you likely have a half-finished build. Rebuild and install.

Task 7: Force a DKMS rebuild for the current kernel (when you suspect a broken build)

cr0x@server:~$ sudo dkms remove -m zfs -v 2.2.2 --all
Deleting module zfs-2.2.2 completely from the DKMS tree.

cr0x@server:~$ sudo dkms install -m zfs -v 2.2.2 -k 6.8.0-52-generic
Building module:
Cleaning build area...
make -j8 KERNELRELEASE=6.8.0-52-generic...
Installing module...
DKMS: install completed.

Meaning: You removed stale builds and rebuilt for the specific kernel.
Decision: If this fails, the compiler toolchain, headers, or kernel changes are your problem—solve that before rebooting into production.

Task 8: Verify that the module on disk matches the running kernel

cr0x@server:~$ modinfo -F vermagic zfs
6.8.0-52-generic SMP preempt mod_unload modversions

Meaning: The module’s vermagic matches the running kernel.
Decision: If vermagic doesn’t match, you’re loading the wrong module or built for the wrong kernel. Fix packaging or boot the correct kernel.

Task 9: Verify userland and kernel module report consistent ZFS versions

cr0x@server:~$ zfs version
zfs-2.2.2-0ubuntu9
zfs-kmod-2.2.2-0ubuntu9

Meaning: Tools and kernel module are in sync.
Decision: If they differ (e.g., userland newer than kmod), expect missing properties and weird errors. Align packages; don’t “work around” it.

Task 10: List pools available to import (without doing it)

cr0x@server:~$ sudo zpool import
   pool: tank
     id: 1283947562198834211
  state: ONLINE
 action: The pool can be imported using its name or numeric identifier.
 config:

        tank        ONLINE
          mirror-0  ONLINE
            sda3    ONLINE
            sdb3    ONLINE

Meaning: The kernel can read labels and see the pool topology.
Decision: If the pool isn’t listed, this is not a “mountpoint” problem. It’s device discovery, encryption key availability, or kernel/module failure.

Task 11: Import without mounting datasets (separate import from mount issues)

cr0x@server:~$ sudo zpool import -N tank
cr0x@server:~$ zpool status -x
all pools are healthy

Meaning: Pool import works; any remaining problems are dataset mount properties, keys, or services.
Decision: If your original problem was “systemd mount units hang,” this narrows it: the pool is fine; the mount workflow is the fight.

Task 12: Check feature flags and compatibility before you “upgrade” anything

cr0x@server:~$ zpool get all tank | grep feature@
tank  feature@async_destroy          enabled   local
tank  feature@encryption             enabled   local
tank  feature@project_quota          active    local

Meaning: The pool has enabled/active features; importing elsewhere requires those features supported.
Decision: If you need cross-host portability (DR, forensic recovery), keep a matrix of which hosts support which features. Don’t enable features casually.

Task 13: See what upgrades are available (read-only decision support)

cr0x@server:~$ zpool upgrade
This system supports ZFS pool feature flags.

The following pools are formatted with legacy version numbers and can be upgraded to use feature flags:
  none

The following pools can be upgraded:
  pool 'tank' has the following supported feature flags:
    spacemap_histogram
    extensible_dataset
    bookmarks
    filesystem_limits

Meaning: “Can be upgraded” means “you can make on-disk changes this system understands.”
Decision: Only run zpool upgrade -a if you are comfortable making the pool potentially unimportable on older systems. Most environments should not auto-upgrade pools.

Task 14: Identify whether you’re using prebuilt kmods or DKMS (packaging shape matters)

cr0x@server:~$ dpkg -l | grep -E 'zfs-dkms|zfs-kmod|spl-dkms' | awk '{print $1, $2, $3}'
ii zfs-dkms 2.2.2-0ubuntu9

Meaning: This host relies on DKMS to compile the module for each kernel.
Decision: Treat kernel upgrades as “build events.” Ensure headers, compiler, and DKMS hooks are working before rebooting.

Task 15: Check if initramfs contains ZFS modules (boot reliability check)

cr0x@server:~$ lsinitramfs /boot/initrd.img-6.8.0-52-generic | grep -E '/zfs\.ko|/spl\.ko' | head
usr/lib/modules/6.8.0-52-generic/updates/dkms/spl.ko
usr/lib/modules/6.8.0-52-generic/updates/dkms/zfs.ko

Meaning: ZFS is present in initramfs for that kernel.
Decision: If not present and your root pool depends on it, rebuild initramfs before rebooting. This is one of those “cheap now, expensive later” checks.

Task 16: Rebuild initramfs after ZFS module changes (make boot use the new reality)

cr0x@server:~$ sudo update-initramfs -u -k 6.8.0-52-generic
update-initramfs: Generating /boot/initrd.img-6.8.0-52-generic

Meaning: The initramfs image is regenerated with current modules and hooks.
Decision: After DKMS rebuilds, always refresh initramfs on hosts that import pools during boot (especially root-on-ZFS).

Task 17: Confirm pool health and rule out “real storage” issues masquerading as version trouble

cr0x@server:~$ zpool status -v tank
  pool: tank
 state: ONLINE
  scan: scrub repaired 0B in 00:21:43 with 0 errors on Thu Dec 19 03:11:52 2025
config:

        NAME        STATE     READ WRITE CKSUM
        tank        ONLINE       0     0     0
          mirror-0  ONLINE       0     0     0
            sda3    ONLINE       0     0     0
            sdb3    ONLINE       0     0     0

errors: No known data errors

Meaning: Storage is healthy at the ZFS layer.
Decision: If you see checksum errors or degraded vdevs, don’t blame versions. Fix hardware/paths first; version churn during a real fault is how outages get longer.

Task 18: Check ZED events and service state (sometimes it’s not loading policy)

cr0x@server:~$ systemctl status zfs-zed.service
● zfs-zed.service - ZFS Event Daemon (zed)
     Loaded: loaded (/lib/systemd/system/zfs-zed.service; enabled; vendor preset: enabled)
     Active: active (running) since Thu 2025-12-26 08:14:12 UTC; 10min ago

Meaning: ZED is alive; it can handle hotplug and fault notifications.
Decision: If ZED is dead, you’ll miss automated replacements and alerts. It won’t cause module mismatch, but it will hide the story until it’s ugly.

Trois mini-récits d’entreprise (anonymisés, plausibles et douloureusement familiers)

Incident causé par une fausse hypothèse : « La mise à jour du noyau n’est que des correctifs de sécurité »

Une société SaaS de taille moyenne utilisait ZFS sur Linux pour des réplicas de bases de données. Ils avaient une fenêtre de patch hebdomadaire, et les mises à jour du noyau étaient traitées comme
une « hygiène de routine ». Le stockage n’était pas sur le ticket de changement parce que, citation, « ZFS est déjà installé ».

La session de patch a mis à jour le noyau et redémarré la flotte de nœuds. Une partie des nœuds est revenue correctement. Quelques-uns non. Les nœuds cassés sont tombés
en mode secours avec des systèmes de fichiers manquants, et l’astreinte a vu la fausse piste habituelle : « cannot import pool ».

La défaillance réelle était ennuyeuse : ces nœuds avaient une légère variante du noyau installée auparavant (même série majeure, build différent),
et DKMS n’a pas compilé ZFS pour ce noyau spécifique parce que les en-têtes n’étaient pas présents. Pas d’en-têtes, pas de module. Pas de module, pas de pool. ZFS a
fait exactement ce qu’il devait : il a refusé de faire semblant.

La correction n’était pas héroïque. Ils ont installé les en-têtes corrects, reconstruit DKMS, régénéré l’initramfs et redémarré. Puis ils ont mis à jour leur
workflow : les mises à jour du noyau sont des changements de stockage si vous exécutez des modules de stockage hors-arbre. L’« hypothèse erronée » était de penser que l’OS et
le stockage sont des couches séparées. Sur Linux, ce sont des colocataires.

Optimisation qui s’est retournée contre eux : « Activons tous les feature flags brillants partout »

Une entreprise standardisait ZFS pour le stockage d’artefacts de build. Quelqu’un a remarqué que « zpool upgrade » listait un buffet de fonctionnalités et a conclu :
plus de fonctionnalités = mieux. Ils ont mis à niveau les pools du cluster principal pendant une période calme. Rien n’a cassé immédiatement.

Des mois plus tard, un test de reprise après sinistre a déplacé un pool répliqué vers un environnement de secours plus petit qui était en retard de quelques versions OpenZFS.
L’import a échoué avec des fonctionnalités non supportées. L’hôte DR n’était pas « en tort », il était juste plus ancien.

L’équipe a essayé de réparer sous pression. Spoiler : on ne peut pas « rétrograder les feature flags ». Ils ont fini par déployer un hôte de secours plus récent
pour importer le pool, puis déplacer les données au niveau des systèmes de fichiers. Cela a coûté du temps, ajouté des risques, et transformé le test DR en improvisation.

La leçon : les feature flags du pool sont un contrat de compatibilité. Si vous devez déplacer des pools entre hôtes, traitez les feature flags comme des versions d’API.
N’activez que ce dont vous avez besoin, et seulement après avoir confirmé que vos environnements de récupération peuvent importer. « Parce que c’est disponible » n’est pas une exigence.

Pratique peu sexy mais correcte qui a sauvé la mise : pinning du noyau et mises à niveau ZFS en étapes

Une grande entreprise exécutait des charges mixtes : stockage VM, analytics et NFS legacy. Ils avaient le budget pour du bon matériel et la patience pour les processus.
Leur gestion des changements n’était pas glamour, mais elle fonctionnait.

Ils ont fixé les noyaux sur les nœuds de stockage à une série connue comme fiable et n’ont avancé qu’après une validation en staging. Les paquets ZFS étaient mis à jour
selon une cadence contrôlée, et ils n’ont jamais exécuté zpool upgrade automatiquement. Les pools sont restés sur un jeu de fonctionnalités conservateur jusqu’à
ce que la flotte entière — y compris les hôtes de récupération « break-glass » — soit confirmée compatible.

Puis un avis de sécurité du noyau est arrivé et tout le monde a paniqué. Ils ne l’ont pas fait. Ils ont déployé le nouveau noyau en staging, validé les builds DKMS,
vérifié le contenu de l’initramfs, testé les redémarrages et exécuté des tests I/O ciblés. Ce n’est qu’ensuite que la production a été mise à jour.

Un mois plus tard, une autre équipe a eu une mise à jour du noyau précipitée sur des nœuds de calcul généraux et a rencontré des problèmes de module avec un pilote non lié.
Les nœuds de stockage continuaient de servir. La discipline « ennuyeuse » de l’entreprise a rendu leur plateforme de stockage prévisible pendant que d’autres parties de la société pratiquaient l’ingénierie surprise.

Blague n°2 : La seule chose pire qu’une mise à jour surprise de ZFS est de découvrir que votre plan DR était « importer le pool et espérer ».

Comment mettre à jour sans transformer votre pool en projet scientifique

Règle 1 : Séparez « mise à jour logicielle » et « mise à jour du format sur disque »

La mise à jour des paquets (userland ZFS + kmod) est réversible : vous pouvez revenir en arrière sur les paquets, démarrer un noyau plus ancien, ou réinstaller des versions connues.
La mise à niveau des feature flags du pool n’est pas réversible en pratique.

Faites d’abord les mises à jour logicielles. Laissez tourner un moment. Confirmez la stabilité. Ensuite seulement envisagez les feature flags, et uniquement si vous avez une raison que vous pouvez expliquer sans dire « moderne ».

Règle 2 : Gardez noyaux et modules ZFS appariés intentionnellement

Sur les systèmes basés DKMS, les mises à jour du noyau sont des événements de build. Votre CI/CD peut être impeccable et vos hooks DKMS peuvent quand même échouer parce qu’un hôte manque des en-têtes,
ou parce qu’une nouvelle version du noyau a changé une interface interne suffisamment pour casser la compilation.

Si vous gérez une flotte, vous voulez :

• Une seule série de noyau par classe de nœud (stockage vs calcul)
• Une vérification automatisée que DKMS a construit pour les noyaux installés
• Un test de redémarrage avant de déclarer la mise à niveau « terminée »

Règle 3 : Traitez la portabilité des pools comme une exigence de premier ordre (ou abandonnez-la explicitement)

Certains environnements n’ont vraiment pas besoin d’importer les pools ailleurs. D’accord. Écrivez-le et acceptez le risque. Mais beaucoup d’organisations partent de l’hypothèse de portabilité pour le DR, la récupération forensique ou le support éditeur.
Si vous supposez pouvoir déplacer un pool, vous devez préserver la compatibilité.

Concrètement : maintenez une matrice de compatibilité des versions OpenZFS pour tous les hôtes susceptibles d’importer un pool. Si un environnement est en retard,
n’activez pas les fonctionnalités qu’il ne pourra pas gérer.

Règle 4 : Ne mélangez pas les dépôts de distribution et les « builds aléatoires » en production

Mélanger noyaux vendor, noyaux HWE, backports et builds ZFS tiers peut fonctionner — jusqu’au jour où ça ne fonctionne plus. Ensuite vous déboguez un écosystème,
pas un système. Vous voulez le plus petit nombre de pièces en mouvement qui satisfasse vos besoins.

Si vous devez dévier (noyau custom, ZFS custom), faites-le partout de manière cohérente et assumez la charge de tests. « Un hôte spécial » devient toujours l’hôte qui échoue de la manière la plus créative.

Règle 5 : Privilégiez des chemins de mise à jour prévisibles plutôt que la nouveauté maximale

La pile de stockage n’est pas l’endroit pour courir après chaque nouvelle version du noyau. Vos utilisateurs ne vous remercieront pas d’avoir trouvé en avance une régression.
Choisissez des lignes de noyau stables, gardez ZFS assorti, et dépensez votre budget d’innovation sur des choses qui améliorent les SLO.

Erreurs courantes : symptôme → cause racine → correction

1) Symptom: modprobe zfs fails after kernel upgrade

Root cause: ZFS module not built for the new kernel; missing headers; DKMS build failed; vermagic mismatch.

Fix: Install matching kernel headers, rebuild DKMS for that kernel, confirm modinfo -F vermagic zfs matches, rebuild initramfs, reboot.

2) Symptom: zfs version shows userland newer than kmod (or vice versa)

Root cause: Mixed repos, partial upgrades, pinned packages, or manual installs.

Fix: Align packages to the same OpenZFS release from the same repo channel. Don’t “just upgrade zfsutils-linux” without the kernel side.

3) Symptom: Pool won’t import on a different host; error mentions unsupported features

Root cause: Feature flags enabled on pool are not supported by that host’s ZFS implementation.

Fix: Import on a host that supports the features, then migrate data (send/receive, rsync, application-level replication). Prevent recurrence: stop enabling features without fleet-wide compatibility.

4) Symptom: System drops to initramfs shell; root pool not found

Root cause: ZFS modules missing from initramfs or not loaded early enough; wrong kernel booted; initramfs not regenerated after DKMS.

Fix: Boot an older working kernel, rebuild initramfs for the intended kernel, ensure ZFS hooks included, then test reboot.

5) Symptom: After upgrade, mounts hang or import is slow

Root cause: Not always versions. Could be device path changes, multipath issues, missing by-id naming, or a txg stall due to I/O timeouts.

Fix: Check dmesg for I/O errors, confirm device names stable, verify zpool status and scrub results, then investigate performance stats (ARC, txg, vdev queueing).

6) Symptom: You “fixed it” by rebooting, then it breaks again next reboot

Root cause: You loaded a module manually but didn’t rebuild/initramfs, or DKMS rebuilt for one kernel but you boot another.

Fix: Make the fix persistent: ensure the correct kernel is installed and default, DKMS built for it, initramfs updated, and packages pinned/managed properly.

7) Symptom: zpool import sees pool but import fails with “missing log” or “cannot open” devices

Root cause: Device discovery naming changed across boots (e.g., /dev/sdX churn), missing partition, failed HBA, or udev race; not primarily a module version issue.

Fix: Use persistent device paths (by-id), check HBAs, validate partitions, and only then blame software versions.

Listes de contrôle / plan étape par étape

Checklist A: Before a kernel upgrade on ZFS hosts

1. Confirm whether this host uses DKMS or prebuilt kmods (Task 14).
2. Ensure kernel headers for the new kernel will be installed alongside the kernel.
3. Confirm build tooling is present (compiler, make) if DKMS is used.
4. Run a dry check: after installing the new kernel (but before reboot), verify DKMS status shows the module built for the new kernel.
5. Regenerate initramfs for the new kernel (Task 16) and verify it contains zfs.ko (Task 15).
6. Have a rollback plan: ensure old kernel remains installed and bootable.

Checklist B: Safe OpenZFS package upgrade (userland + module)

1. Upgrade packages in lockstep (don’t upgrade zfsutils alone).
2. Confirm zfs version shows matching userland and kmod (Task 9).
3. Confirm modinfo -F vermagic zfs matches uname -r (Tasks 1 and 8).
4. Verify pool health (zpool status -v) before and after (Task 17).
5. Reboot in a controlled window and verify import/mount behavior.

Checklist C: Deciding whether to run zpool upgrade

1. Write down the reason (specific feature needed, performance bug fixed, operational necessity).
2. Confirm every system that might need to import the pool supports the features you’ll enable.
3. Confirm backups/replication are current.
4. Prefer upgrading a test pool first, then validating send/receive, scrub, and failover/import workflows.
5. Upgrade one pool at a time. Watch it. Then proceed.

Step-by-step: When a host won’t import pools after reboot

1. Confirm running kernel (uname -r).
2. Check module load (lsmod, modprobe zfs).
3. If modprobe fails, read dmesg for symbol/vermagic errors.
4. Confirm DKMS status for that kernel; rebuild if needed.
5. Verify initramfs contains ZFS modules; regenerate if missing.
6. Only after module issues are resolved: run zpool import and attempt zpool import -N.
7. Check feature flags and portability constraints if importing on a different host.

FAQ

1) What’s the difference between “ZFS version” and “pool version”?

« ZFS version » signifie généralement la release logicielle (userland et module noyau). « Pool version » était autrefois un numéro monolithique ; OpenZFS moderne utilise des feature flags.
Le logiciel peut être mis à jour sans changer le pool. Activer de nouvelles fonctionnalités du pool modifie la compatibilité sur disque.

2) If zfs version shows mismatched userland and kmod, is it always fatal?

Pas toujours immédiatement fatal. C’est toujours un mauvais signe. Vous pouvez avoir des propriétés manquantes, des erreurs étranges ou des différences de comportement subtiles.
En production, alignez-les. « Ça marche chez moi » est la manière dont les incidents incubent.

3) Why does ZFS break after a kernel update when ext4 doesn’t?

ext4 est dans l’arbre du noyau. ZFS ne l’est pas. Les mises à jour du noyau peuvent changer des interfaces internes, et les modules hors-arbre doivent être recompilés (DKMS) ou remplacés par des kmods précompilés.

4) Should I prefer DKMS or prebuilt kmods?

Les kmods précompilés sont généralement plus prévisibles si votre distro les supporte bien. DKMS est flexible et courant, mais transfère la fiabilité à votre environnement de build.
Si vous utilisez DKMS, investissez dans une validation pré-redémarrage et un staging.

5) Can I downgrade a pool after running zpool upgrade?

En pratique, non. Une fois que de nouveaux feature flags sont activés, les implémentations plus anciennes peuvent refuser l’import. Votre « rétrogradation » se transforme en « migration des données vers un nouveau pool ».

6) Is it safe to run zpool upgrade -a during routine upgrades?

Non. C’est l’équivalent stockage de « formater C: pour être propre ». Mettez à niveau les pools délibérément et parcimonieusement, après vérification des environnements de récupération/import.

7) My pool imports manually, but not on boot. What’s going on?

Généralement initramfs ou ordre de démarrage. Le module ZFS peut manquer dans l’initramfs, ou l’ordre des services est incorrect (clés non disponibles, périphériques pas prêts).
Vérifiez le contenu de l’initramfs et les unités systemd, et testez avec zpool import -N pendant le dépannage du démarrage.

8) Why does dkms status say “installed” but modprobe still fails?

DKMS peut être « installé » pour un noyau différent de celui sur lequel vous avez démarré, ou vous pouvez avoir plusieurs noyaux installés et charger des modules depuis le mauvais arbre.
Vérifiez uname -r, modinfo -F vermagic, et confirmez le chemin du module sous /lib/modules/$(uname -r).

9) Is a kernel/ZFS mismatch only a boot-time problem?

Principalement, mais pas exclusivement. Un scénario « fonctionne mais dégradé » peut arriver si vous êtes sur une nouvelle combinaison avec des régressions ou des valeurs par défaut modifiées.
Traitez les incidents de performance après des mises à jour comme suspects jusqu’à preuve du contraire.

10) What’s the safest portability strategy for DR?

Gardez les hôtes DR sur des versions OpenZFS égales ou plus récentes que la production, et évitez d’activer des feature flags tant que le DR n’est pas vérifié.
Si la portabilité est critique, standardisez les feature flags et documentez-les comme un contrat d’API.

Conclusion : actions suivantes qui réduisent vraiment les alertes

ZFS ne « casse » pas aléatoirement après les mises à jour du noyau. Les humains le cassent en laissant le noyau, le module, les outils et les feature flags dériver dans des combinaisons incompatibles.
La solution est ennuyeuse : contrôler les versions, vérifier les builds, tester les redémarrages et traiter les feature flags comme une promesse de compatibilité.

Faites ceci ensuite :

1. Choisissez votre modèle de mise à niveau (DKMS vs précompilé) et standardisez-le par classe de nœud.
2. Ajoutez une gate pré-redémarrage : confirmez que DKMS a construit pour le noyau cible et que l’initramfs inclut les modules ZFS.
3. Arrêtez les mises à niveau automatiques de pool. Exigez une décision explicite et une vérification de portabilité.
4. Documentez un flux « Diagnostic rapide » sur une page et faites-le suivre par l’astreinte. La cohérence bat la créativité à 02:00.