Proxmox NFS “stale file handle”: por qué ocurre y cómo evitarlo

Qué significa realmente “stale file handle” (en términos de Proxmox)

Proxmox no es especial aquí; es “solo Linux”. Cuando Proxmox monta un almacenamiento NFS, depende del cliente NFS de Linux para mapear rutas (como /mnt/pve/nfs-prod) a objetos del sistema de archivos en el servidor. El cliente NFS almacena en caché un identificador opaco pequeño por cada archivo/directorio que toca: el file handle.

Ese handle lo emite el servidor NFS. Codifica “este objeto, en este sistema de archivos, desde la visión de este servidor”. El handle está diseñado para sobrevivir operaciones normales como reinicios y fallos de red. Pero no sobrevive ciertos eventos en el lado del servidor: cambios de exportación, sustitución de sistemas de archivos, reconstrucción de tablas de inodos, promoción de snapshots, o que alguien con acceso root “ayude” con optimismo.

Cuando Proxmox hace algo mundano—abrir un qcow2, listar un directorio, bloquear un disco de VM—y el servidor responde “no conozco ese handle ya”, el cliente reporta ESTALE. Proxmox lo muestra como “stale file handle” y entonces se desencadenan fallos: errores al iniciar VMs, fallos de backup, fallos en migraciones, o almacenamiento marcado como fuera de línea.

Matiz importante: un stale file handle no es “NFS está caído”. Es “NFS está arriba, pero la identidad del objeto cambió”. Esa diferencia importa tanto para el diagnóstico como para la prevención.

Aquí está el encuadre de fiabilidad que desearía que todos usaran: stale file handle es un problema de consistencia de identidad, no un problema de conectividad.

Una cita que debería estar en todo canal de incidentes NFS (idea parafraseada): La idea de John Allspaw: las condiciones para la falla están incorporadas en el sistema mucho antes del incidente. Los handles stale son exactamente eso—condiciones latentes más un desencadenante.

Broma corta #1: NFS significa “No, File’s Somewhere”… hasta que significa “Now File’s Stale”.

Hechos y contexto: por qué esto sigue afectando a la gente

Algo de historia y el “por qué” ayudan porque NFS tiene particularidades que no son obvias si creciste con discos locales, almacenamiento de objetos o sistemas de archivos distribuidos diseñados en este siglo.

1. NFS fue diseñado para servidores sin estado (especialmente v2/v3). Esa falta de estado empujó la complejidad al cliente: cachés, reintentos y casos límite extraños como los stale handles.
2. Los file handles son opacos por diseño. El servidor puede cambiar su estructura interna entre versiones o cambios de configuración; el cliente debe tratarlos como “galletas mágicas”.
3. NFSv3 suele ligar identidad a detalles de sistema de archivos/inodo. Sustituye el sistema de archivos o reasigna inodos y los handles antiguos dejan de tener sentido.
4. NFSv4 introdujo un “pseudo filesystem” y un modelo de montaje distinto. Mejoró algunas cosas, pero también añadió nuevas trampas alrededor de rutas de exportación, referencias y mapeo de identidades.
5. Algunos appliances NAS virtualizan sistemas de archivos por debajo. Cuando realizan failover, actualización o reequilibrio, la identidad subyacente puede cambiar incluso si la ruta de exportación se mantiene igual.
6. Los montajes hard son la opción por defecto en Linux por una razón. Un montaje “soft” puede convertir un dolor transitorio del servidor en corrupción silenciosa de datos, que es mucho peor que un proceso bloqueado.
7. “Stale file handle” es anterior a tu pila de virtualización. Aparece en la historia de UNIX; los hipervisores modernos solo amplifican el radio de impacto.
8. Las semánticas de bloqueo tienen una larga y confusa historia. NLM para v3 y el bloqueo integrado de v4 pueden interactuar con failovers y re-exportaciones de maneras que parecen “aleatorias” en los discos de VM.

Conclusión: NFS puede ser fiable, pero solo si tratas la identidad de archivos como parte de tu contrato de almacenamiento. Si tu servidor NFS puede cambiar silenciosamente el sistema de archivos subyacente, no tienes un contrato: tienes vibras.

Causas raíz que producen stale file handles

1) La exportación ahora apunta a un sistema de archivos diferente

Este es el clásico. La cadena de la ruta de exportación no cambió, pero el sistema de archivos subyacente cambió: nuevo dataset ZFS montado allí, nuevo volumen ext4, un sistema replicado promovido, o un volumen NAS distinto montado en el mismo directorio.

Los file handles de NFS típicamente incluyen un identificador de sistema de archivos. Si ese identificador cambia, los handles antiguos se vuelven stale. Esto suele suceder tras “mantenimiento de almacenamiento” cuando alguien desmonta y vuelve a montar la ruta de exportación, o tras failover cuando la exportación del nodo en espera no es idéntica byte a byte en los metadatos de identidad.

2) Reutilización de inodos o regeneración de la tabla de inodos (menos común, pero real)

Algunos sistemas de archivos y operaciones de recuperación pueden dar lugar a una identidad de inodo diferente para “la misma ruta”. Si el servidor decide que el objeto en esa ruta ahora es un inodo distinto, los handles que apuntaban al inodo antiguo quedan stale. Verás esto con reconstrucciones de sistema de archivos, rollbacks agresivos de snapshots y ciertos flujos de trabajo de restauración desde backup en la misma ruta.

3) Opciones de exportación o configuración del servidor NFS cambiaron en vuelo

Cambiar exports y recargar el servidor puede invalidar la idea del servidor sobre qué se estaba exportando y con qué ID de sistema de archivos. En NFSv3, fsid importa más de lo que la mayoría cree. En NFSv4, la pseudo-raíz y el árbol de exportaciones importan.

4) Failover del NAS donde el cliente habla con “la misma IP” pero otra personalidad de servidor

El NFS de alta disponibilidad suele usar una IP flotante. Perfecto. Pero si el failover cambia a un nodo que no conserva exactamente la identidad del sistema de archivos (o lo hace con retraso), los clientes pueden conservar handles antiguos y luego explotar. Algunos appliances tienen “periodos de gracia” o remapeo de handles; otros no. Algunos lo hacen hasta que habilitas una función que lo desactiva. Pregúntame cómo lo sé.

5) Rollback de snapshot / promoción de clon en el servidor

El rollback es seductor: “simplemente revertimos el dataset”. Si el rollback cambia la identidad de inodo o la generación del sistema de archivos, los handles se vuelven stale. Las imágenes de disco de VM son particularmente sensibles porque son de larga duración y están abiertas activamente.

6) Comportamiento del nodo Proxmox: entradas de directorio en caché y procesos ocupados

Incluso si el servidor ahora está “correcto”, los clientes pueden mantener referencias stale si los procesos tienen descriptores de archivo abiertos, directorios de trabajo actuales o dentries en caché apuntando a handles antiguos. Por eso “umount y remount” a veces lo arregla—y a veces falla con “device is busy”, que es Linux diciéndote educadamente que un proceso está acampando ahí.

7) Opciones de montaje “optimizadas” que cambian la semántica

Afinar NFS para rendimiento está bien. Afinarlo para vibras no lo está. Opciones como actimeo, lookupcache y un caché de atributos agresivo pueden magnificar la ventana en la que los clientes operan con suposiciones de identidad desactualizadas. Normalmente no obtendrás stale handles directamente por caché, pero sí mayores tasas de comportamientos extraños alrededor de rename/unlink y rollbacks rápidos.

Broma corta #2: La forma más rápida de generar stale file handles es decir “no te preocupes, es solo NFS” en voz alta. NFS te oye.

Guía rápida de diagnóstico (comprobar primero/segundo/tercero)

El objetivo es responder tres preguntas rápidamente:

• ¿Esto es un problema de identidad (ESTALE) o un problema de conectividad/rendimiento (timeouts)?
• ¿La falla está aislada a un nodo Proxmox o es en todo el clúster?
• ¿El servidor cambió lo que exporta, o el cliente cacheó algo roto?

Primero: confirma el error y el alcance

1. Revisa los logs de tareas de Proxmox por ESTALE / stale file handle.
2. En varios nodos, intenta listar la misma ruta. Si solo un nodo ve stale, suele ser estado de caché/proceso del cliente. Si todos los nodos ven stale, el servidor/export cambió.
3. Mira los logs del kernel en el cliente para mensajes NFS. A menudo incluyen la IP del servidor y el punto de montaje.

Segundo: verifica que el montaje sea lo que crees

1. Revisa findmnt para confirmar versión NFS, servidor, ruta exportada y opciones de montaje.
2. Consulta /proc/fs/nfsfs/volumes para ver la vista de volúmenes del cliente NFS y sus IDs.
3. En el servidor, confirma que los exports no cambiaron y que el sistema de archivos detrás del export es el mismo dataset/volume.

Tercero: decide si arreglar en cliente, servidor o ambos

• Si la exportación del servidor apunta a un lugar nuevo: arregla la identidad del servidor/export primero y luego remonta los clientes.
• Si el servidor es estable pero un nodo está roto: mata los procesos que tienen fds stale y luego remonta.
• Si el failover HA lo provocó: necesitas arreglar la preservación de identidad en el failover, no solo remotar. Remontar es una tirita.

Tareas prácticas: comandos, salida esperada y decisiones

A continuación hay comandos reales ejecutables que puedes usar en nodos Proxmox y en servidores NFS Linux típicos. Cada tarea incluye qué significa la salida y qué decisión tomar a continuación.

Task 1: Confirmar el montaje y la versión NFS

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

Significado: Estás montado en nfs01:/exports/prod usando NFSv4.1 con un montaje hard.

Decisión: Si el SOURCE no es lo que esperabas (host/export equivocado), para. Arregla la definición de almacenamiento en Proxmox o DNS antes de seguir persiguiendo stale handles.

Task 2: Reproducir el error stale de forma mínima

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

Significado: Este es un síntoma ESTALE verdadero en una búsqueda de directorio.

Decisión: Comprueba si otros nodos ven lo mismo. Si sí, sospecha un cambio de exportación/sistema de archivos en el servidor.

Task 3: Revisar mensajes del kernel por quejas del cliente NFS

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

Significado: Puedes tener tanto problemas de identidad (stale handle) como breves indisponibilidades del servidor. Pueden ocurrir juntos durante un failover/reinicio.

Decisión: Si “not responding” se repite, investiga también red/carga del servidor. Pero no ignores el stale handle: no se cura esperando.

Task 4: Identificar quién está “acamapado” en el montaje (bloquea el 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

Significado: Esos PIDs tienen directorio actual o archivos abiertos bajo el montaje.

Decisión: Si necesitas remontar, detén los servicios/tareas de Proxmox relevantes de forma ordenada primero, o acabarás haciendo el “umount lazy”.

Task 5: Ver la lista interna de volúmenes del cliente NFS (útil para “qué está realmente montado?”)

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

Significado: El cliente ve un volumen NFSv4 desde nfs01. FSID aquí no es tan descriptivo como en v3, pero confirma la vista del cliente.

Decisión: Si esperabas múltiples montajes o servidores distintos y solo ves uno, puede que estés montando vía un VIP HA y no notes los failovers.

Task 6: Revisar la configuración de storage de Proxmox para la entrada NFS

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

Significado: Proxmox está configurado para montar ese export con opciones específicas.

Decisión: Si te falta vers explícito y el entorno mezcla servidores, fija versiones intencionalmente. Las diferencias accidentales v3/v4 son una fuente recurrente de problemas.

Task 7: Validar exports desde el lado cliente (vista NFSv3; aún útil)

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

Significado: El servidor anuncia esos exports. En NFSv4 esto puede no contar toda la historia (pseudo-root), pero detecta desviaciones básicas.

Decisión: Si el export desapareció o cambiaron permisos, arregla eso primero. Un stale handle a veces sigue a una reconfiguración de export.

Task 8: En el servidor NFS, confirma la configuración de exports y el 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)

Significado: El servidor exporta con valores fsid explícitos. Eso es buena práctica para estabilidad, especialmente con NFSv3 y algunos escenarios HA.

Decisión: Si falta fsid y haces cosas ingeniosas (bind mounts, ZFS datasets, failover), añade fsid explícito y prueba. Si fsid cambió recientemente, espera stale handles hasta que los clientes remonten.

Task 9: Confirmar que el sistema de archivos subyacente detrás del export no cambió

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

Significado: La ruta export corresponde a un dataset ZFS tank/prod.

Decisión: Compáralo con tu línea base conocida. Si alguien lo reemplazó (por ejemplo, ahora es tank/prod-new), ese es el desencadenante del stale handle.

Task 10: Detectar “el directorio fue reemplazado” (cambios en número de inodo en el tiempo)

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

Significado: Estás recogiendo identificadores que ayudan a detectar incidentes de “remontamos otra cosa aquí”. Si dev cambia, el montaje cambió.

Decisión: Si dev/inode cambió comparado con registros anteriores, trátalo como un cambio de identidad en el servidor y planifica un remount coordinado de clientes (y arregla el flujo de trabajo que lo causó).

Task 11: Intentar un remount limpio en un nodo Proxmox (tras parar tareas dependientes)

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

Significado: Algo lo mantiene ocupado (a menudo backup, qemu, o una shell con cwd dentro).

Decisión: Usa fuser/lsof para identificar y detener los procesos específicos. No pases de inmediato a lazy unmount a menos que entiendas las implicaciones.

Task 12: Encontrar archivos abiertos bajo el montaje (más preciso que 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

Significado: Un proceso de VM y uno de backup tienen handles abiertos. Si esos handles están stale, seguirán fallando hasta que se reinicien y se refresque el montaje.

Decisión: Detén/migra las VM que usan ese almacenamiento antes de remount. Si no, estás apostando tu continuidad a un comportamiento indefinido.

Task 13: Usar un unmount lazy solo como último recurso controlado

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

Significado: El montaje volvió y la lista de directorios funciona. Lazy unmount separó el montaje del namespace mientras las referencias antiguas se drenan.

Decisión: Verifica de inmediato que los procesos qemu en ejecución no estén todavía referenciando el montaje antiguo. Si lo están, reinícialos limpiamente. Lazy unmount no es gratis.

Task 14: Confirmar que Proxmox ve el almacenamiento como disponible

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%

Significado: El almacenamiento está activo desde la perspectiva de Proxmox.

Decisión: Si sigue “inactive” pero el montaje en Linux funciona, revisa permisos, tipos de contenido y servicios de Proxmox. Si el montaje en Linux está roto, no culpes a Proxmox.

Task 15: Si sospechas failover, confirma con qué IP de servidor estás hablando

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

Significado: Existe conectividad RPC al objetivo resuelto nfs01. En un montaje VIP HA, esto no prueba qué nodo físico está activo, pero confirma disponibilidad del servicio.

Decisión: Si hay HA involucrado, verifica la preservación de identidad en el failover. Los stale handles que afectan a todo el clúster coincidiendo con failover del VIP son un problema de diseño.

Task 16: Comprobación de sanity en servidor: ¿alguien “recargó los exports” recientemente?

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.

Significado: Los exports se recargaron en la ventana del incidente. Eso no es automáticamente malo, pero es una pista de correlación fuerte.

Decisión: Si la recarga coincide con stale handles, revisa qué cambió (exports, puntos de montaje, fsid, bind mounts). Añade “cambios en exports requieren control de cambios” a la lista de políticas.

Errores comunes: síntoma → causa raíz → solución

1) Los discos de VM fallan intermitentemente al arrancar tras mantenimiento del NAS

Síntoma: qm start falla con errores de I/O; los logs de Proxmox muestran stale file handle en la ruta del disco de la VM.

Causa raíz: La ruta de exportación se mantuvo igual, pero el NAS cambió/retrocedió el volumen subyacente o cambió la identidad del sistema de archivos durante mantenimiento/failover.

Solución: Haz las exportaciones estables: fsid explícito (donde aplique), identidad de sistema de archivos consistente en nodos HA, evita “reemplazar lo que está montado bajo la ruta de export”. Tras corregir el servidor, remonta clientes y reinicia los procesos qemu afectados.

2) Solo un nodo Proxmox ve stale handles; los demás están bien

Síntoma: El almacenamiento está “activo” en el nodo A pero listar directorios lanza stale handle; el nodo B puede navegar normalmente.

Causa raíz: El nodo A tiene procesos con descriptores de archivo stale o dentries en caché; el nodo B remontoó o nunca tocó los objetos cambiados.

Solución: Identifica procesos con lsof/fuser, para/migra cargas que usan el montaje y luego remonta limpiamente en el nodo afectado.

3) Las copias de seguridad fallan con stale handle justo después de “restaurar en su lugar”

Síntoma: El job de backup muere al escanear directorios; los errores apuntan a una carpeta que fue restaurada recientemente.

Causa raíz: El flujo de restauración reemplazó directorios/archivos de un modo que cambió la identidad de inodo mientras los clientes aún tenían handles en caché a los objetos antiguos.

Solución: No restaures intercambiando árboles enteros bajo un export activo. Restaura en una nueva ruta, luego haz un corte controlado (y remonta clientes si debes reemplazar el árbol).

4) Alguien “lo arregló” con montajes soft y ahora tienes riesgo de corrupción silenciosa

Síntoma: Los errores stale “desaparecen”, pero ves errores aleatorios de aplicaciones y archivos truncados después.

Causa raíz: soft puede hacer que operaciones NFS fallen temprano; muchas aplicaciones no están diseñadas para manejar eso de forma segura para imágenes de VM o bases de datos.

Solución: Usa montajes hard para almacenamiento de VM. Aborda el problema de identidad/failover subyacente. Si necesitas fallos acotados, usa timeouts adecuados y monitorización, no soft.

5) Stale handle tras cambiar opciones de export (especialmente juegos de subtree/bind mount)

Síntoma: Tras una “limpieza”, algunos directorios lanzan stale file handle mientras otros funcionan.

Causa raíz: El árbol de export cambió; bind mounts o subdirectorios se exportaron de forma diferente; cambió la asignación de fsid.

Solución: Mantén un layout de export estable. Prefiere exportar un sistema de archivos/dataset dedicado por almacenamiento Proxmox. Evita exportar subdirectorios profundos de un volumen compartido para usos no relacionados.

6) “Usamos un VIP HA, así que está bien” (no lo está, por defecto)

Síntoma: Stale handles en todo el clúster durante pruebas de failover; todo vuelve tras remount/reinicio.

Causa raíz: El nodo standby no conserva la identidad del file handle o presenta un ID de sistema de archivos distinto detrás del mismo export.

Solución: Arregla HA NFS correctamente: almacenamiento compartido con identidad consistente y soporte NFS HA correcto, o una solución HA que garantice handles estables tras failover. Prueba con cargas en vivo, no solo con ls.

Tres micro-historias corporativas desde el frente

Micro-historia 1: El incidente causado por una suposición equivocada

Tenían un clúster Proxmox ordenado y un NAS ordenado. La ruta de export era /exports/prod y llevaba así años. Durante una renovación de almacenamiento, alguien creó un volumen nuevo y lo montó en /exports/prod durante una ventana de mantenimiento. Mismo nombre de directorio, mismos permisos, misma IP. Asumieron que “misma ruta” significaba “mismo almacenamiento”.

Funcionó un tiempo. Migraciones de VM nuevas aterrizaron en el volumen nuevo y funcionaron. Al día siguiente, las copias de seguridad comenzaron a fallar, luego un par de VMs se rebootearon por parches y no volvieron. Stale file handle por todos lados. El equipo on-call lo trató como una caída de NFS e hizo los rituales tradicionales: reiniciar servicios, luego reiniciar un nodo Proxmox, luego reiniciar el controlador NAS. El error cambió de forma pero no desapareció.

El punto de inflexión fue comparar la fuente del montaje en el servidor y el nombre del dataset ZFS detrás del export. Era nuevo. El volumen antiguo seguía ahí, montado en otro sitio. Los clientes habían cacheado handles de objetos en el sistema de archivos antiguo; la exportación ahora apuntaba al nuevo. El servidor NFS no estaba “caído”, estaba negándose educadamente a reconocer una vida pasada.

Lo arreglaron haciendo el trabajo aburrido: crear una nueva ruta de export para el volumen nuevo, añadirla como un almacenamiento Proxmox nuevo, migrar discos explícitamente y luego desmantelar el antiguo. La acción post-mortem fue contundente: “Dejar de reemplazar el sistema de archivos bajo una ruta de export existente.” A todos les pareció mal hasta la siguiente renovación, cuando nadie recibió una página.

Micro-historia 2: La optimización que salió mal

Otra empresa tenía quejas de rendimiento: los backups eran lentos, el I/O de discos de VM tenía picos, y alguien declaró que el problema era “chatter de metadata NFS”. Ajustaron las opciones de montaje agresivamente—caché de atributos, comportamiento de lookup cache, rsize/wsize mayores, retrans reducidos y un par de opciones copiadas de un blog escrito para otra carga.

El rendimiento mejoró en el camino feliz. Luego hicieron una prueba de failover planificada en su NAS HA. El failover en sí fue limpio, pero los nodos Proxmox empezaron a reportar stale handles e inconsistencias al listar directorios. Solo algunos nodos. Solo algunos subdirectorios. Parecía un incidente cósmico.

El problema real: el tuning aumentó la ventana en la que los clientes creían que su vista cacheada era correcta, mientras que el árbol de export del servidor estuvo brevemente en estado transitorio durante el failover. Los clientes no estaban equivocados por cachear; estaban equivocados por cachear tanto tiempo dado el comportamiento del servidor. Y como la “optimización” se desplegó gradualmente, distintos nodos se comportaron distinto. Buena suerte depurando eso a las 03:00.

Revirtieron a una base conservadora y luego arreglaron la secuencia de HA del servidor para que el export estuviera disponible solo cuando el sistema de archivos subyacente fuera totalmente consistente. La lección: si vas a tunear, hazlo contra un modelo de fallos. Si no, solo haces la falla más interesante.

Micro-historia 3: La práctica aburrida pero correcta que salvó el día

Un equipo empresarial trató las exportaciones NFS como contratos API. Cada almacenamiento Proxmox tenía su propio sistema de archivos/dataset dedicado. Los exports se declaraban con identificadores explícitos, los cambios se revisaban, y “reemplazar lo que está montado aquí” simplemente no estaba permitido. La política fue impopular porque eliminó una clase de “arreglos rápidos”. Ese era el punto.

Siguieron teniendo incidentes—parpadeos de red, bugs de firmware de NIC, un switch que decidió dejar caer paquetes como si purificara su aura. Pero los stale file handles fueron raros, y cuando ocurrían, el radio de impacto era pequeño. Un export, un dataset, un ID de almacenamiento. El diagnóstico fue rápido porque había menos ambigüedad.

Entonces un parche de servidor reinició el nodo NFS en un mal momento. Los clientes se quedaron parados (montaje hard haciendo su trabajo), la monitorización se encendió y el on-call siguió el runbook: confirma que NFS volvió, valida la identidad del export, remonta solo si es necesario, reinicia solo los jobs afectados. No hubo reinicios de nodos. No hubo “pruébalo otra vez” al azar. El incidente fue corto, aburrido y no un evento de carrera profesional.

Ese es el mayor cumplido en ops: el incidente se comportó exactamente como decía el runbook.

Prevención: qué estandarizar y qué prohibir

Estandarizar: exports estables que no se muevan

Si quieres menos stale handles, deja de hacer lo que los genera: cambiar la identidad del sistema de archivos bajo un export mientras los clientes están montados.

• Una storage Proxmox ↔ un sistema de archivos/dataset en el servidor. Evita exportar subdirectorios profundos de un volumen compartido para propósitos no relacionados. Aumenta la probabilidad de que alguien “limpie” el padre.
• Nunca reemplaces lo que está montado bajo una ruta de export. Crea una nueva ruta de export, haz el cutover explícito y luego retira la antigua.
• Usa identificadores de export explícitos cuando proceda. En muchos servidores NFS Linux, establecer fsid en exports es una mejora de estabilidad, especialmente en NFSv3 y en escenarios multi-export.
• Fija versiones NFS intencionalmente. Mezclar comportamientos v3/v4 entre nodos es caldo de cultivo para modos de fallo inconsistentes.

Estandarizar: opciones de montaje conservadoras para almacenamiento de VM

Para imágenes de VM, tus prioridades son la corrección y un comportamiento de fallo predecible, no ganancia de benchmark.

• Usa montajes hard. Si el servidor se cuelga, tu I/O se cuelga. Eso es honesto. Te permite hacer failover, arreglar o fencear sin corromper discos.
• Usa TCP. Sí, UDP existió históricamente. No, no lo quieres para cargas de disco de VM en 2025.
• Usa timeouts sensatos. Un patrón común es un timeo más largo con retrans limitados y buena alerta, así detectas “atascos” sin convertirlos en fallos silenciosos.
• Mantén la caché de atributos razonable. No te excedas a menos que puedas reproducir pruebas de fallo con las opciones afinadas.

Prohibir: “hacer rollback del dataset que aloja discos de VM”

Si tu servidor NFS aloja discos de VM activos y haces rollback de snapshots debajo de ellos, estás jugando a la ruleta del sistema de archivos. Incluso si el servidor sobrevive, los clientes no pueden reconciliar “el pasado” con handles en caché. En su lugar:

• Restaura en un nuevo dataset/ruta.
• Verifica integridad.
• Programa una migración/corte controlado.

Prohibir: exportar rutas que dependan de bind mounts sin control de cambios

Los bind mounts son útiles. También son una excelente manera de cambiar la identidad del sistema de archivos de forma invisible. Si debes usarlos, trata los cambios de bind mount como cambios de producción con ventana de mantenimiento, coordinación de clientes y plan de rollback.

Diseñar para HA: identidad estable en failover o no finjas que es HA

El NFS HA es difícil porque “la misma IP” no es “la misma identidad de sistema de archivos”. Si el failover cambia a un backend distinto que no puede preservar handles, verás stale handles en todo el clúster. Las soluciones incluyen:

• Un backend compartido con identidad consistente y soporte NFS HA correcto.
• Orquestación de failover que asegura que los exports aparezcan solo después de que el sistema de archivos esté montado de forma consistente y listo.
• Evitar NFS para discos de VM si tu historia de HA no puede garantizar identidad (usar almacenamiento en bloque o un sistema de archivos clusterizado diseñado para ello).

Listas de verificación / plan paso a paso

Paso a paso: cuando stale file handle afecta producción

1. Confirma el alcance: un nodo vs todos los nodos. Ejecuta ls en la misma ruta desde dos nodos.
2. Captura evidencia antes de “arreglar”: logs del kernel (dmesg), logs de tareas de Proxmox, salida de findmnt.
3. Identifica las cargas afectadas: qué VMs/CTs usan ese almacenamiento. Planea una pausa/migración si es necesario.
4. Revisa la identidad del export del servidor: confirma que el export apunta al sistema de archivos/dataset esperado; revisa recargas recientes de exports y cambios de montaje.
5. Arregla la deriva del lado servidor primero: si el export se movió, vuelve a colocarlo o crea un nuevo export y reconfigura Proxmox.
6. Detén procesos que tienen fds stale en el cliente: lsof/fuser, luego detén o migra VMs que usan el montaje.
7. Remonta limpiamente: desmonta, monta, verifica listado de directorios, verifica acceso a archivos.
8. Reinicia solo lo necesario: procesos qemu para VMs afectadas, jobs de backup, etc.
9. Post-incidente: identifica el disparador del servidor y escribe la política que lo impida en el futuro.

Lista de verificación: requisitos de “estabilidad de export” para datastores NFS de Proxmox

• Sistema de archivos/dataset dedicado por datastore
• No permitir “swap mount bajo la ruta”
• IDs de exportación explícitos (cuando aplique)
• Control de cambios para ediciones y recargas de exports
• Opciones de montaje documentadas y fijadas en /etc/pve/storage.cfg
• Pruebas de failover HA con archivos abiertos, no solo listados de directorios

Lista de verificación: “antes del mantenimiento” en el servidor NFS que aloja Proxmox

• Confirma qué storages Proxmox están respaldados por qué exports
• Quiesce o migra cargas de alto riesgo (VMs con mucha escritura, backups)
• Si el failover/upgrade cambia la identidad del export, programa una ventana de remount de clientes
• Comunica el comportamiento esperado: montajes hard pueden quedarse bloqueados durante el reinicio
• Después del mantenimiento: verifica exports, puntos de montaje e identidad de datasets antes de dar por verde

Preguntas frecuentes

1) ¿Es “stale file handle” un bug de Proxmox?

No. Proxmox muestra un error del cliente NFS de Linux (ESTALE). El desencadenante habitual es un cambio de identidad en el servidor o comportamiento de failover HA.

2) ¿Por qué reiniciar un nodo Proxmox a veces “lo arregla”?

Un reinicio elimina estado en caché y descriptores de archivo abiertos, forzando handles nuevos al remontar. Es un instrumento contundente que oculta la causa real y te cuesta más tiempo de inactividad del necesario.

3) ¿Debo usar NFSv3 o NFSv4.x para Proxmox?

Cualquiera puede funcionar, pero elige deliberadamente y estandariza. NFSv4.x simplifica algunos aspectos (un solo puerto, bloqueo integrado), mientras que v3 tiene semánticas más simples en ciertos entornos. Mezclar versiones entre nodos es pedir comportamientos inconsistentes.

4) ¿Son los montajes “soft” una buena forma de evitar VMs atascadas?

No para discos de VM. Los montajes soft pueden provocar fallos en medio de escrituras que las aplicaciones no manejan de forma segura. Montajes hard más buena monitorización es la opción adulta.

5) ¿Puede ocurrir stale file handle incluso si el servidor nunca se reinició?

Sí. Cualquier cambio que efectivamente reemplace la identidad del objeto del sistema de archivos—rollback de snapshot, remount de dataset, cambio de bind mount, reconfiguración de export—puede provocarlo.

6) ¿Por qué a veces afecta solo a un directorio dentro del montaje?

Porque los handles son por objeto. Si solo se reemplazó un subárbol (restaurado, revertido, remontado vía bind), solo los handles que referencian ese subárbol se vuelven stale.

7) ¿Cuál es la remediación más segura cuando discos de VM están en el NFS afectado?

Detén o migra las VMs que usan ese almacenamiento, remonta el datastore y luego reinicia las VMs. Si no puedes detenerlas, estás apostando a la integridad de datos y al tiempo de recuperación.

8) ¿El fsid explícito siempre evita stale handles?

No. Reduce una clase de problemas (especialmente en la identificación del export y cambios) pero no te salvará de reemplazar el sistema de archivos/dataset subyacente o de rollbacks destructivos.

9) ¿Cómo diferencio problemas de identidad de simples latencias/timeouts?

La latencia/timeouts aparecen como “server not responding” y I/O colgado; stale handle aparece como errores inmediatos Stale file handle en lookup/open. Pueden ocurrir juntos durante un failover.

10) Si debo hacer rollback en el servidor, ¿cuál es la opción menos mala?

Hacer el rollback en una ruta/dataset nuevo y cortar cambiando el storage de Proxmox al nuevo export (y remontando). No hagas rollback in-place bajo clientes activos.

Siguientes pasos prácticos

Si quieres menos incidentes de stale file handle, realiza esto en orden:

1. Audita la estabilidad de exports: confirma que cada datastore NFS de Proxmox mapea a un filesystem/dataset dedicado en el servidor que nunca se reemplaza en sitio.
2. Estandariza montajes: fija versión NFS y opciones en /etc/pve/storage.cfg. Elimina diferencias ad-hoc entre nodos.
3. Arregla HA honestamente: o garantizas identidad estable en failover o dejas de fingir que el VIP lo hace seguro.
4. Escribe el runbook: comprobaciones rápidas de diagnóstico, pasos de “quién tiene el montaje” y procedimiento controlado de remount.
5. Cambia la cultura: “simplemente remóntalo” no es una solución; es síntoma de contratos ausentes entre almacenamiento y cómputo.

Los stale file handles son el sistema diciéndote la verdad: algo cambió por debajo de ti. Haz esos cambios explícitos, controlados y probables—y la verdad será mucho menos dramática.