Proxmox NFS « stale file handle » : pourquoi ça arrive et comment l’éviter

Ce que « stale file handle » signifie réellement (en termes Proxmox)

Proxmox n’est pas spécial ici ; c’est « juste Linux ». Quand Proxmox monte un stockage NFS, il repose sur le client NFS Linux pour mapper des chemins (comme /mnt/pve/nfs-prod) aux objets du système de fichiers côté serveur. Le client NFS met en cache un petit identifiant opaque pour chaque fichier/répertoire qu’il touche : le file handle.

Ce handle est émis par le serveur NFS. Il encode « cet objet, sur ce système de fichiers, selon la vue du serveur ». Le handle est conçu pour survivre à des opérations normales comme des redémarrages et des petits incidents réseau. Mais il ne survit pas à certains événements côté serveur : export déplacé, système de fichiers remplacé, table d’inodes reconstruite, snapshot promu, ou un administrateur root bien intentionné qui « aide » le serveur.

Quand Proxmox effectue une opération banale — ouvrir un qcow2, lister un répertoire, verrouiller un disque VM — et que le serveur répond « je ne connais plus ce handle », le client signale ESTALE. Proxmox l’affiche comme « stale file handle » puis cela se répercute en échecs : démarrage de VM, sauvegardes, migrations, ou stockage marqué hors-ligne.

Nuance importante : un stale file handle n’est pas « NFS est en panne ». C’est « NFS est accessible, mais l’identité de l’objet a changé ». Cette différence importe pour le diagnostic et la prévention.

Voici l’encadrement fiabilité que j’aimerais voir utilisé : stale file handle est un problème de cohérence d’identité, pas un problème de connectivité.

Une citation à mettre dans tous les canaux d’incident NFS (idée paraphrasée) : l’idée de John Allspaw : les conditions de défaillance sont intégrées dans le système bien avant l’incident. Les handles obsolètes sont exactement cela — des conditions latentes plus un déclencheur.

Petite blague #1 : NFS signifie « No, File’s Somewhere »… jusqu’à ce que ça devienne « Now File’s Stale ».

Faits et contexte : pourquoi cela continue de poser problème

Un peu d’histoire et du « pourquoi » aident, car NFS a des particularités qui ne sont pas évidentes si vous venez de disques locaux, d’objets ou de systèmes distribués conçus récemment.

1. NFS a été conçu pour des serveurs sans état (surtout v2/v3). Cette absence d’état a poussé la complexité côté client : cache, retransmissions et cas limites bizarres comme les stale handles.
2. Les file handles sont opaques par conception. Le serveur peut changer leur structure interne entre versions ou configurations ; le client doit les traiter comme des « cookies magiques ».
3. NFSv3 lie souvent l’identité aux détails filesystem/inode. Remplacez le système de fichiers ou réattribuez des inodes et les anciens handles deviennent sans valeur.
4. NFSv4 a introduit un « pseudo filesystem » et un modèle de montage différent. Cela a amélioré certains points, mais ajouté de nouveaux pièges autour des chemins exportés, des referrals et de l’idmapping.
5. Certaines appliances NAS virtualisent les systèmes de fichiers en interne. Lors d’un basculement, d’une mise à jour ou d’un rééquilibrage, l’identité sous-jacente peut changer même si le chemin d’export reste identique.
6. Les montages « hard » sont le comportement par défaut pour une raison. Un montage « soft » peut transformer une douleur serveur transitoire en corruption silencieuse des données, ce qui est bien pire qu’un processus bloqué.
7. « Stale file handle » est plus ancien que votre pile de virtualisation. On le retrouve dans le folklore UNIX ; les hyperviseurs modernes amplifient simplement la portée des dégâts.
8. La sémantique des verrous a une histoire longue et compliquée. NLM pour v3 et le verrou intégré pour v4 peuvent interagir avec les basculements et les ré-exports de manière à ressembler à des problèmes « aléatoires » sur les disques VM.

Conclusion : NFS peut être fiable, mais seulement si vous considérez l’identité des fichiers comme faisant partie du contrat de stockage. Si votre serveur NFS peut remplacer silencieusement le système de fichiers derrière un export, vous n’avez pas de contrat — vous avez des impressions.

Causes racines qui produisent des stale file handles

1) L’export pointe maintenant vers un système de fichiers différent

C’est le classique. La chaîne de caractères du chemin d’export est inchangée, mais le système de fichiers sous-jacent a changé : nouveau dataset ZFS monté là, nouveau volume ext4, filesystem répliqué promu, ou un autre volume NAS monté dans le même répertoire.

Les file handles NFS incluent typiquement un identifiant de système de fichiers. Si cet identifiant change, les anciens handles deviennent obsolètes. Cela arrive souvent après une « maintenance stockage » où quelqu’un démonte et remonte le chemin d’export, ou après un basculement où l’export du nœud secondaire n’a pas la même identité métadonnée.

2) Réutilisation d’inodes ou régénération de la table d’inodes (moins courant, mais réel)

Certaines filesystems et certaines opérations de récupération peuvent aboutir à une identité d’inode différente pour « le même chemin ». Si le serveur considère que l’objet à ce chemin est maintenant un inode différent, les handles qui faisaient référence à l’ancien inode deviennent obsolètes. Vous verrez cela avec des reconstructions de filesystem, des rollbacks agressifs de snapshots, ou certaines restaurations dans le même chemin.

3) Options d’export ou configuration du serveur NFS modifiées en cours d’exécution

Changer les exports et recharger le serveur peut invalider l’idée du serveur sur ce qui était exporté et avec quel ID filesystem. En NFSv3, fsid compte plus que la plupart des gens le réalisent. En NFSv4, la pseudo-racine et l’arborescence des exports importent.

4) Basculement NAS où le client parle à « la même IP » mais à une personnalité serveur différente

Les solutions NFS hautement disponibles utilisent souvent une IP flottante. Très bien. Mais si le basculement commute vers un nœud qui ne préserve pas exactement l’identité du filesystem (ou la préserve après un délai), les clients peuvent garder d’anciens handles et planter ensuite. Certaines appliances ont des « périodes de grâce » ou des remappages ; d’autres non.

5) Rollback de snapshot / promotion de clone côté serveur

Le rollback est séduisant : « on va juste revenir au dataset précédent ». Si le rollback change l’identité d’inode ou la génération du filesystem, les handles deviennent obsolètes. Les images disques VM sont particulièrement sensibles car elles sont de longue durée et souvent ouvertes.

6) Comportement du nœud Proxmox : entrées de répertoire en cache et processus occupés

Même si le serveur est maintenant « correct », les clients peuvent garder des références obsolètes si des processus ont des descripteurs ouverts, des répertoires de travail courants ou des dentries en cache pointant vers d’anciens handles. C’est pourquoi « umount et remount » résout parfois le problème — et pourquoi ça échoue parfois avec « device is busy », ce que Linux dit poliment quand un processus est campé là.

7) Options de montage « d’optimisation » qui changent la sémantique

Optimiser NFS pour la performance, oui. L’optimiser pour les vibes, non. Des options comme actimeo, lookupcache et un caching d’attributs agressif peuvent élargir la fenêtre pendant laquelle les clients opèrent sur des hypothèses d’identité obsolètes. En général, le caching ne génère pas directement des stale handles, mais il augmente la fréquence des comportements étranges autour de rename/unlink et des rollbacks rapides.

Petite blague #2 : Le moyen le plus rapide de générer des stale file handles est de dire « ne t’inquiète pas, c’est juste NFS » à voix haute. NFS vous entend.

Playbook de diagnostic rapide (vérifier d’abord/deuxièmement/troisièmement)

L’objectif est de répondre rapidement à trois questions :

• Est-ce un problème d’identité (ESTALE) ou un problème de connectivité/performance (timeouts) ?
• La panne est-elle isolée à un nœud Proxmox ou généralisée au cluster ?
• Le serveur a-t-il changé ce qu’il exporte, ou le client a-t-il mis en cache quelque chose de cassé ?

Premier : confirmer l’erreur et la portée

1. Vérifiez les logs de tâches Proxmox pour ESTALE / stale file handle.
2. Sur plusieurs nœuds, essayez de lister le même chemin. Si un seul nœud voit le stale, c’est en général l’état cache/processus côté client. Si tous les nœuds voient le stale, l’export/le serveur a changé.
3. Consultez les logs kernel sur le client pour les messages NFS. Ils incluent souvent l’IP du serveur et le point de montage.

Deuxième : vérifier que le montage est bien ce que vous pensez

1. Vérifiez findmnt pour confirmer la version NFS, le serveur, le chemin exporté et les options de montage.
2. Consultez /proc/fs/nfsfs/volumes pour voir la vue des volumes côté client et leurs IDs.
3. Côté serveur, confirmez que les exports n’ont pas changé et que le système de fichiers derrière l’export est le même dataset/volume.

Troisième : décider de réparer côté client, côté serveur, ou les deux

• Si l’export serveur pointe vers un nouvel emplacement : corrigez d’abord l’identité serveur/export, puis remontez les clients.
• Si le serveur est stable mais qu’un nœud est cassé : tuez les processus tenant des fds obsolètes, puis remontez.
• Si un basculement HA l’a déclenché : corrigez la préservation d’identité du basculement, pas seulement le remount. Le remount est un pansement.

Tâches pratiques : commandes, sorties attendues et décisions

Ci‑dessous des commandes réelles et exécutables que vous pouvez utiliser sur des nœuds Proxmox et des serveurs NFS Linux typiques. Chaque tâche inclut ce que signifie la sortie et quelle décision prendre ensuite.

Task 1: Confirm the mount and NFS version

cr0x@pve1:~$ findmnt -t nfs,nfs4 /mnt/pve/nfs-prod
TARGET           SOURCE                   FSTYPE OPTIONS
/mnt/pve/nfs-prod nfs01:/exports/prod     nfs4   rw,relatime,vers=4.1,rsize=1048576,wsize=1048576,hard,timeo=600,retrans=2,proto=tcp

Signification : Vous êtes monté sur nfs01:/exports/prod en NFSv4.1 avec un montage hard.

Décision : Si la SOURCE n’est pas celle attendue (hôte/export incorrect), arrêtez. Corrigez la définition du stockage Proxmox ou le DNS avant de chasser les stale handles.

Task 2: Reproduce the stale error in a minimal way

cr0x@pve1:~$ ls -la /mnt/pve/nfs-prod/images
ls: cannot access '/mnt/pve/nfs-prod/images': Stale file handle

Signification : C’est un vrai symptôme ESTALE sur une recherche de répertoire.

Décision : Vérifiez si d’autres nœuds voient la même chose. Si oui, suspectez un changement côté serveur/export/filesystem.

Task 3: Check kernel messages for NFS client complaints

cr0x@pve1:~$ dmesg -T | tail -n 20
[Thu Dec 26 01:58:41 2025] NFS: stale file handle
[Thu Dec 26 01:58:41 2025] NFS: server nfs01 not responding, still trying
[Thu Dec 26 01:58:57 2025] NFS: server nfs01 OK

Signification : Vous pouvez avoir à la fois des problèmes d’identité (stale handle) et une brève indisponibilité du serveur. Ils peuvent coexister lors d’un basculement/redémarrage.

Décision : Si « not responding » se répète, investiguez aussi la charge réseau/serveur. Mais n’ignorez pas le stale handle : il ne guérira pas en attendant.

Task 4: Identify who is “camping” in the mount (blocks unmount)

cr0x@pve1:~$ fuser -vm /mnt/pve/nfs-prod
                     USER        PID ACCESS COMMAND
/mnt/pve/nfs-prod:   root      21940 ..c.. pvedaemon
                     root      31211 ..c.. pve-backup
                     root      1402  ..c.. systemd

Signification : Ces PIDs ont un répertoire courant ou des fichiers ouverts sous le montage.

Décision : Si vous avez besoin de remonter, arrêtez d’abord proprement les services/tâches Proxmox concernés, sinon vous ferez la danse du « lazy unmount ».

Task 5: See NFS client’s internal volume list (useful for “what is mounted really?”)

cr0x@pve1:~$ cat /proc/fs/nfsfs/volumes
NV SERVER   PORT DEV     FSID              FSC
v4 nfs01    2049 0:50    0:0               yes

Signification : Le client voit un volume NFSv4 depuis nfs01. FSID ici n’est pas aussi descriptif qu’en v3, mais confirme la vue client.

Décision : Si vous attendiez plusieurs montages ou serveurs et que vous n’en voyez qu’un, vous montez peut‑être via un VIP HA sans vous apercevoir des basculements.

Task 6: Check Proxmox storage config for the NFS entry

cr0x@pve1:~$ cat /etc/pve/storage.cfg
nfs: nfs-prod
        server nfs01
        export /exports/prod
        path /mnt/pve/nfs-prod
        content images,iso,vztmpl,backup
        options vers=4.1,proto=tcp,hard,timeo=600,retrans=2

Signification : Proxmox est configuré pour monter cet export avec des options spécifiques.

Décision : Si vous n’avez pas d’option vers explicite et que l’environnement mélange des serveurs, épinglez les versions intentionnellement. Les différences accidentelles v3/v4 reviennent souvent hanter les opérations.

Task 7: Validate exports from the client side (NFSv3 view; still useful)

cr0x@pve1:~$ showmount -e nfs01
Export list for nfs01:
/exports/prod 10.10.20.0/24
/exports/dev  10.10.20.0/24

Signification : Le serveur annonce ces exports. En NFSv4 cela peut ne pas raconter toute l’histoire (pseudo-root), mais ça attrape la dérive basique.

Décision : Si l’export a disparu ou que les permissions ont changé, corrigez d’abord cela. Un stale handle suit parfois une reconfiguration d’export.

Task 8: On the NFS server, confirm the export config and fsid

cr0x@nfs01:~$ sudo exportfs -v
/exports/prod   10.10.20.0/24(rw,sync,wdelay,hide,no_subtree_check,sec=sys,fsid=100)
/exports/dev    10.10.20.0/24(rw,sync,wdelay,hide,no_subtree_check,sec=sys,fsid=101)

Signification : Le serveur exporte avec des valeurs fsid explicites. C’est une bonne pratique de stabilité, surtout pour NFSv3 et certains scénarios HA.

Décision : Si fsid manque et que vous faites quelque chose de « malin » (bind mounts, datasets ZFS, basculement), ajoutez un fsid explicite et testez. Si fsid a changé récemment, attendez-vous à des stale handles jusqu’au remount des clients.

Task 9: Confirm the underlying filesystem behind the export didn’t change

cr0x@nfs01:~$ mount | grep ' /exports/prod '
tank/prod on /exports/prod type zfs (rw,xattr,noacl)

Signification : Le chemin d’export mappe un dataset ZFS tank/prod.

Décision : Comparez avec votre ligne de base connue. Si quelqu’un l’a remplacé (par ex. maintenant tank/prod-new), c’est votre déclencheur de stale handle.

Task 10: Detect “the directory got replaced” (inode number changes across time)

cr0x@nfs01:~$ stat -c '%n inode=%i dev=%d' /exports/prod /exports/prod/images
/exports/prod inode=48 dev=46
/exports/prod/images inode=1024 dev=46

Signification : Vous collectez des identifiants qui aident à détecter les incidents de « nous avons remonté autre chose ici ». Si dev change, le montage a changé.

Décision : Si dev/inode a changé comparé aux enregistrements antérieurs, traitez cela comme un changement d’identité côté serveur et planifiez un remount coordonné des clients (et corrigez le workflow qui l’a provoqué).

Task 11: Try a clean remount on a Proxmox node (after stopping dependent tasks)

cr0x@pve1:~$ sudo systemctl stop pvedaemon pveproxy
cr0x@pve1:~$ sudo umount /mnt/pve/nfs-prod
umount: /mnt/pve/nfs-prod: target is busy.

Signification : Quelque chose le tient occupé (souvent backup, qemu, ou un shell avec cwd à l’intérieur).

Décision : Utilisez fuser/lsof pour identifier et arrêter les processus spécifiques. Ne passez pas directement au lazy unmount sans en comprendre les implications.

Task 12: Find open files under the mount (more precise than fuser)

cr0x@pve1:~$ sudo lsof +f -- /mnt/pve/nfs-prod | head
COMMAND     PID USER   FD   TYPE DEVICE SIZE/OFF NODE NAME
pve-backup 31211 root  cwd    DIR  0,50     4096    2 /mnt/pve/nfs-prod/backup
qemu-system 9982 root   27u   REG  0,50 2147483648  7 /mnt/pve/nfs-prod/images/101/vm-101-disk-0.qcow2

Signification : Une VM et un processus de backup ont des handles ouverts. Si ces handles sont obsolètes, ils continueront à échouer tant qu’ils ne sont pas redémarrés et que le montage n’est pas rafraîchi.

Décision : Arrêtez/migrez les VM qui tournent depuis ce stockage avant de remonter. Sinon vous misez sur l’uptime en acceptant un comportement indéfini.

Task 13: Use a lazy unmount only as a controlled last resort

cr0x@pve1:~$ sudo umount -l /mnt/pve/nfs-prod
cr0x@pve1:~$ sudo mount /mnt/pve/nfs-prod
cr0x@pve1:~$ ls /mnt/pve/nfs-prod
backup  images  iso  vztmpl

Signification : Le montage est revenu et la liste des répertoires fonctionne. Le lazy unmount a détaché le montage de l’espace de noms pendant que les anciennes références se vident.

Décision : Vérifiez immédiatement que les processus qemu en cours ne référencent plus l’ancien montage. S’ils le font, redémarrez‑les proprement. Le lazy unmount n’est pas sans coût.

Task 14: Confirm Proxmox sees the storage as available

cr0x@pve1:~$ pvesm status
Name       Type  Status     Total     Used    Available  %
local      dir   active   19660800  8214528    11446272  41.79%
nfs-prod   nfs   active  104857600 20971520    83886080  20.00%

Signification : Le stockage est actif du point de vue Proxmox.

Décision : S’il reste « inactive » alors que le montage Linux fonctionne, vérifiez permissions, types de contenu et services Proxmox. Si le montage Linux est cassé, ne blâmez pas Proxmox.

Task 15: If you suspect failover, confirm which server IP you’re actually talking to

cr0x@pve1:~$ rpcinfo -t nfs01 nfs 4
program 100003 version 4 ready and waiting

Signification : La connectivité RPC existe vers la cible résolue nfs01. Dans une configuration VIP HA, cela ne prouve pas quel nœud physique est actif, mais confirme la disponibilité du service.

Décision : Si le HA est impliqué, vérifiez la préservation d’identité lors du basculement. Des stale handles généralisés coïncidant avec un basculement VIP sont un problème de conception.

Task 16: Server-side sanity check: did someone “reload exports” recently?

cr0x@nfs01:~$ sudo journalctl -u nfs-server -u nfs-mountd --since "2 hours ago" | tail -n 30
Dec 26 01:54:02 nfs01 exportfs[18842]: exporting 10.10.20.0/24:/exports/prod
Dec 26 01:54:02 nfs01 systemd[1]: Reloaded NFS server and services.

Signification : Les exports ont été rechargés dans la fenêtre d’incident. Ce n’est pas automatiquement mauvais, mais c’est une piste de corrélation forte.

Décision : Si le reload coïncide avec les stale handles, examinez ce qui a changé (exports, mountpoints, fsid, bind mounts). Mettez « les changements d’export requièrent un contrôle de changement » dans la politique.

Erreurs courantes : symptôme → cause racine → correctif

1) Les disques VM échouent de façon intermittente après une maintenance NAS

Symptôme : qm start échoue avec des erreurs I/O ; les logs Proxmox montrent stale file handle sur le chemin du disque VM.

Cause racine : Le chemin d’export est resté le même, mais le NAS a remplacé/restauré le volume sous-jacent ou changé l’identité du filesystem pendant la maintenance/le basculement.

Correctif : Rendre les exports stables : fsid explicite (là où applicable), identité filesystem cohérente sur les nœuds HA, éviter de « remplacer ce qui est monté sous le chemin d’export ». Une fois le serveur corrigé, remontez les clients et redémarrez les processus qemu affectés.

2) Un seul nœud Proxmox voit des handles obsolètes ; les autres vont bien

Symptôme : Le stockage est « actif » sur le nœud A mais les listings renvoient stale handle ; le nœud B navigue normalement.

Cause racine : Le nœud A a des processus tenant des descripteurs de fichiers obsolètes ou des dentries en cache ; le nœud B a remounté ou n’a jamais accédé aux objets modifiés.

Correctif : Identifiez les processus avec lsof/fuser, arrêtez/migrez les charges utilisant le montage, puis remontez proprement sur le nœud affecté.

3) Les sauvegardes échouent avec stale handle juste après une « restauration sur place »

Symptôme : Le job de backup échoue en scannant des répertoires ; les erreurs pointent vers un dossier récemment restauré.

Cause racine : Le flux de restauration a remplacé des répertoires/fichiers d’une manière qui a changé l’identité d’inode pendant que les clients gardaient en cache des handles vers les anciens objets.

Correctif : Ne restaurez pas en remplaçant des arbres entiers sous un export actif. Restaurez vers un nouveau chemin, puis faites un basculement contrôlé (et remontez les clients si vous devez remplacer l’arbre).

4) Quelqu’un « a réglé » avec des montages soft et maintenant vous avez un risque de corruption silencieuse

Symptôme : Les erreurs stale handle « disparaissent », mais vous observez des erreurs applicatives aléatoires et des fichiers tronqués ensuite.

Cause racine : soft peut faire échouer les opérations NFS prématurément ; beaucoup d’applications ne gèrent pas cela en sécurité pour des images VM ou des bases de données.

Correctif : Utilisez des montages hard pour le stockage VM. Traitez la question d’identité/basculement sous-jacente. Si vous avez besoin d’une panne limitée, utilisez des timeouts appropriés et de la supervision, pas soft.

5) Stale handle après modification des options d’export (surtout jeux de subtree/bind mount)

Symptôme : Après un « nettoyage », certains répertoires renvoient stale file handle tandis que d’autres fonctionnent.

Cause racine : L’arbre d’export a changé ; des bind mounts ou des sous-répertoires ont été exportés différemment ; l’attribution de fsid a changé.

Correctif : Gardez une disposition d’export stable. Préférez exporter un filesystem/dataset dédié par stockage Proxmox. Évitez d’exporter des sous-répertoires profonds dont les parents peuvent être modifiés.

6) « On utilise un VIP HA, donc tout va bien » (ce n’est pas vrai par défaut)

Symptôme : Handles obsolètes sur tout le cluster lors de tests de basculement ; tout revient après remount/redémarrage.

Cause racine : Le nœud secondaire ne préserve pas l’identité des file handles ou présente un ID filesystem différent derrière le même export.

Correctif : Gérer correctement le HA NFS : backend partagé avec identité cohérente, ou une solution NFS HA qui garantit des file handles stables au basculement. Testez avec des charges live, pas seulement ls.

Trois micro-histoires d’entreprise issues du terrain

Mini-histoire 1 : L’incident causé par une mauvaise hypothèse

Ils avaient un cluster Proxmox propre et un NAS bien tenu. Le chemin d’export était /exports/prod depuis des années. Lors d’un rafraîchissement de stockage, quelqu’un a créé un nouveau volume et l’a monté sur /exports/prod pendant la fenêtre de maintenance. Même nom de répertoire, mêmes permissions, même IP. Ils ont supposé que « même chemin » signifiait « même stockage ».

Ça a marché un moment. Des migrations VM fraîches sont arrivées sur le nouveau volume et ont fonctionné. Le lendemain, les sauvegardes ont commencé à échouer, puis quelques VMs redémarrées pour patch ne revenaient pas. Stale file handle partout. L’équipe on-call a traité cela comme une panne NFS et a fait les rituels : redémarrer des services, redémarrer un nœud Proxmox, puis le contrôleur NAS. L’erreur a changé de forme mais n’est pas partie.

Le tournant a été la comparaison de la source de montage côté serveur et du nom du dataset ZFS derrière l’export. C’était neuf. L’ancien volume était toujours là, monté ailleurs. Les clients avaient mis en cache des handles d’objets sur l’ancien filesystem ; l’export pointait maintenant sur le nouveau. Le serveur NFS n’était pas « en panne », il refusait poliment de reconnaître une vie antérieure.

Ils ont corrigé le problème en faisant le travail ennuyeux : créer un nouveau chemin d’export pour le nouveau volume, l’ajouter comme nouveau stockage Proxmox, migrer explicitement les disques, puis décommissionner l’ancien. L’action post‑mortem était franche : « Ne remplacez pas le filesystem sous un chemin d’export existant. » Tout le monde a râlé jusqu’à la prochaine remise à jour, où personne n’a été réveillé.

Mini-histoire 2 : L’optimisation qui s’est retournée contre eux

Un autre shop avait des plaintes de performance : sauvegardes lentes, I/O disque VM en pics, et quelqu’un a déclaré que c’était le « metadata chatter » NFS. Ils ont ajusté agressivement les options de montage — cache d’attributs, comportement du lookup cache, rsize/wsize plus grands, retrans réduit, et quelques options copiées d’un billet de blog pour une autre charge.

La performance s’est améliorée au happy path. Puis ils ont fait un test de basculement planifié sur leur NAS HA. Le basculement lui‑même était propre, mais les nœuds Proxmox ont commencé à signaler des stale handles et des incohérences de listing. Seulement certains nœuds. Seulement certains sous-répertoires. On aurait dit un incident cosmique.

Le vrai problème : le tuning a élargi la fenêtre pendant laquelle les clients croyaient que leur vue en cache était correcte, alors que l’arbre d’export côté serveur était brièvement en état de transition. Les clients n’avaient pas tort de cacher ; ils avaient tort de cacher aussi longtemps étant donné le comportement serveur. Et comme « l’optimisation » a été déployée progressivement, les nœuds différaient dans leur comportement. Bon courage pour déboguer ça à 03:00.

Ils sont revenus à une baseline conservatrice puis ont corrigé l’ordonnancement HA côté serveur pour que l’export ne soit disponible qu’une fois le filesystem monté de façon cohérente. La leçon : si vous tunez, testez contre un modèle de défaillance. Sinon vous rendez la défaillance plus intéressante.

Mini-histoire 3 : La pratique ennuyeuse mais correcte qui a sauvé la mise

Une équipe d’entreprise traitait les exports NFS comme des contrats d’API. Chaque stockage Proxmox avait son propre filesystem/dataset dédié. Les exports étaient déclarés avec des identifiants explicites, les changements étaient revus, et « remplacer ce qui est monté ici » était tout simplement interdit. La politique était impopulaire parce qu’elle supprimait une classe de « quick fixes ». C’était le but.

Ils ont quand même eu des incidents — coupures réseau, bugs de firmware NIC, un switch qui décidait de lâcher des paquets comme s’il se purifiait. Mais les stale file handles étaient rares, et quand ils surviennent la portée était petite. Un export, un dataset, un ID de stockage. Le diagnostic était rapide parce qu’il y avait moins d’ambiguïté.

Puis un patch serveur a redémarré le nœud NFS au mauvais moment. Les clients se sont figés (montage hard faisant son travail), la supervision a sonné, et l’on‑call a suivi le runbook : confirmer que NFS est revenu, valider l’identité de l’export, remonter seulement si nécessaire, redémarrer uniquement les jobs impactés. Pas de reboots de nœuds. Pas d’essais hasardeux. L’incident a été court, ennuyeux, et pas dramatique pour la carrière.

C’est le compliment le plus élevé en ops : l’incident s’est comporté exactement comme le runbook l’indiquait.

Prévention : ce qu’il faut standardiser et ce qu’il faut interdire

Standardiser : des exports stables qui ne bougent pas

Si vous voulez moins de stale handles, arrêtez de faire ce qui les crée : changer l’identité du filesystem derrière un export pendant que des clients sont montés.

• Un stockage Proxmox ↔ un filesystem/dataset serveur dédié. Évitez d’exporter des sous‑répertoires profonds d’un volume partagé pour des usages non liés. Ça augmente la probabilité qu’un parent soit « nettoyé ».
• Ne remplacez jamais ce qui est monté sous un chemin d’export. Créez un nouveau chemin d’export, basculez explicitement, puis retirez l’ancien chemin.
• Utilisez des identifiants d’export explicites quand c’est pertinent. Sur de nombreux serveurs NFS Linux, définir fsid sur les exports améliore la stabilité, surtout en NFSv3 et dans les scénarios multi‑export.
• Épinglez les versions NFS intentionnellement. Les comportements mixtes v3/v4 entre nœuds sont un terrain propice aux modes d’échec incohérents.

Standardiser : options de montage conservatrices pour le stockage VM

Pour les images VM, vos priorités sont la cohérence et un comportement d’échec prévisible, pas des gains de benchmark.

• Utilisez des montages hard. Si le serveur se bloque, vos I/O se bloquent. C’est honnête. Cela permet de basculer, réparer ou isoler sans corrompre les disques.
• Utilisez TCP. Oui, UDP existe historiquement. Non, vous n’en voulez pas pour des workloads disque VM en 2025.
• Choisissez des timeouts sensés. Un pattern courant est un timeo plus long avec un retrans limité et une bonne alerte, pour détecter un blocage sans le transformer en échec silencieux.
• Conservez un caching d’attributs raisonnable. Ne déployez pas des réglages agressifs sans les tester avec des scénarios de panne.

Interdire : « rollback du dataset qui héberge des disques VM en fonctionnement »

Si votre serveur NFS héberge des disques VM actifs et que vous rollbackez des snapshots sous ces disques, vous jouez à la roulette du filesystem. Même si le serveur survit, les clients ne peuvent pas concilier « le passé » avec des handles en cache. Au lieu de cela :

• Restaurez dans un nouveau dataset/chemin.
• Vérifiez l’intégrité.
• Planifiez une migration/basculement contrôlé.

Interdire : exporter des chemins qui dépendent de bind mounts sans contrôle de changement

Les bind mounts sont pratiques. Ils sont aussi un excellent moyen de changer l’identité d’un filesystem de façon indétectable. Si vous devez les utiliser, traitez les changements de bind mount comme des changements de production avec fenêtre de maintenance, coordination client et plan de rollback.

Concevez le HA : identité stable au basculement ou ne prétendez pas au HA

Le HA NFS est difficile parce que « la même IP » n’est pas « la même identité de filesystem ». Si le basculement passe à un backend différent qui ne peut pas préserver les handles, vous verrez des stale handles sur tout le cluster. Les solutions comprennent :

• Un backend partagé avec identité cohérente et un support NFS HA correct.
• Une orchestration de basculement qui garantit que les exports n’apparaissent qu’après que le filesystem soit monté et cohérent.
• Éviter NFS pour les disques VM si votre story HA ne peut pas garantir l’identité (utiliser du block storage ou un filesystem clusterisé conçu pour cela).

Checklists / plan pas à pas

Étape par étape : quand le stale file handle frappe en production

1. Confirmer la portée : un nœud vs tous les nœuds. Lancez ls sur le même chemin depuis deux nœuds.
2. Capturer des preuves avant de « réparer » : logs kernel (dmesg), logs de tâches Proxmox, sortie de findmnt.
3. Identifier les charges impactées : quelles VMs/CT utilisent ce stockage. Planifiez une pause/migration si nécessaire.
4. Vérifier l’identité de l’export serveur : confirmez que l’export pointe le filesystem/dataset attendu ; vérifiez les reloads d’export récents et les changements de montage.
5. Corriger la dérive côté serveur en premier : si l’export a été déplacé, remettez‑le en place ou créez un nouvel export et reconfigurez Proxmox.
6. Arrêter les processus tenant des fds obsolètes côté client : lsof/fuser, puis arrêter ou migrer les VMs utilisant le montage.
7. Remonter proprement : unmount, mount, vérifier listing, vérifier accès fichiers.
8. Redémarrer seulement ce qui est nécessaire : processus qemu pour VMs affectées, jobs de backup, etc.
9. Post‑incident : identifier le déclencheur côté serveur et écrire la politique qui l’empêche de se reproduire.

Checklist : exigences de « stabilité d’export » pour les datastores NFS Proxmox

• Filesystem/dataset dédié par datastore
• Interdiction de « swap mount under path »
• IDs d’export explicites (là où applicable)
• Contrôle de changement pour les edits et reloads d’export
• Options de montage documentées et épinglées dans storage.cfg
• Tests HA avec fichiers ouverts, pas seulement des listings

Checklist : « avant maintenance » sur un serveur NFS hébergeant Proxmox

• Confirmer quels storages Proxmox sont backés par quels exports
• Quiescer ou migrer les charges à risque (VM en écriture intense, backups)
• Si un basculement/upgrade change l’identité d’export, programmer une fenêtre de remount client
• Communiquer le comportement attendu : les montages hard peuvent se bloquer pendant un reboot
• Après la maintenance : vérifier exports, points de montage et identité des datasets avant de déclarer « green »

FAQ

1) « stale file handle » est‑ce un bug Proxmox ?

Non. Proxmox remonte une erreur du client NFS Linux (ESTALE). Le déclencheur habituel est un changement d’identité côté serveur ou le comportement de basculement HA.

2) Pourquoi redémarrer un nœud Proxmox « règle » parfois le problème ?

Un redémarrage efface l’état en cache et les descripteurs ouverts, forçant de nouveaux handles après remount. C’est un instrument brutal qui masque la cause réelle et coûte plus de downtime que nécessaire.

3) Dois‑je utiliser NFSv3 ou NFSv4.x pour Proxmox ?

Les deux peuvent fonctionner, mais choisissez délibérément et standardisez. NFSv4.x simplifie certains aspects (port unique, verrou intégré), tandis que v3 a des sémantiques plus simples dans certains environnements. Mixer les versions entre nœuds est une source d’incohérences.

4) Les montages « soft » sont‑ils une bonne façon d’éviter les VMs bloquées ?

Non pour les disques VM. Les montages soft peuvent faire échouer des opérations en cours d’écriture d’une manière que les applications ne gèrent pas en sécurité. Les montages hard avec supervision sont l’option responsable.

5) Un stale file handle peut‑il survenir même si le serveur n’a jamais redémarré ?

Oui. Tout changement qui remplace effectivement l’identité d’un objet filesystem — rollback de snapshot, remount de dataset, switch de bind mount, reconfiguration d’export — peut le provoquer.

6) Pourquoi cela n’affecte‑t‑il parfois qu’un seul répertoire sous le montage ?

Parce que les handles sont par objet. Si seul un sous‑arbre a été remplacé (restauré, rollbacké, remount via bind), seuls les handles faisant référence à ce sous‑arbre deviennent obsolètes.

7) Quelle est la remédiation la plus sûre quand des disques VM sont sur le NFS affecté ?

Arrêtez ou migrez les VMs utilisant ce stockage, remontez le datastore, puis redémarrez les VMs. Si vous ne pouvez pas les arrêter, vous jouez avec l’intégrité des données et le temps de récupération.

8) Un fsid explicite empêche‑t‑il toujours les stale handles ?

Non. Il réduit une classe de problèmes (surtout autour de l’identification des exports et des changements) mais ne vous sauvera pas si vous remplacez le filesystem/dataset sous‑jacent ou faites des rollbacks destructeurs.

9) Comment distinguer problèmes d’identité de simples latences/timeouts ?

Les latences/timeouts apparaissent comme « server not responding » et I/O bloquées ; stale handle apparaît comme des erreurs immédiates « Stale file handle » lors d’un lookup/open. Ils peuvent coexister pendant un basculement.

10) Si je dois effectuer un rollback côté serveur, quelle est la moins mauvaise option ?

Rollback vers un nouveau chemin/dataset et bascule en changeant le stockage Proxmox vers le nouvel export (et remonter). Ne rollbackez pas en place sous des clients actifs.

Prochaines étapes pratiques

Si vous voulez moins d’incidents de stale file handle, faites ceci dans l’ordre :

1. Auditez la stabilité des exports : confirmez que chaque datastore NFS Proxmox mappe à un filesystem/dataset serveur dédié jamais remplacé in‑place.
2. Standardisez les montages : épinglez la version NFS et les options dans /etc/pve/storage.cfg. Éliminez les différences ad‑hoc entre nœuds.
3. Corrigez honnêtement le HA : garantissez l’identité stable au basculement ou cessez de prétendre que le VIP le rend sûr.
4. Rédigez le runbook : les vérifications de diagnostic rapide, les étapes « qui tient le montage », et la procédure de remount contrôlé.
5. Changez la culture : « juste remonter » n’est pas une solution ; c’est le symptôme d’un manque de contrats entre stockage et compute.

Les stale file handles sont le système qui vous dit la vérité : quelque chose a changé sous vos pieds. Rendre ces changements explicites, contrôlés et testables rendra la vérité beaucoup moins dramatique.