Corrigindo "Stale file handle" no NFS - Remontando o Compartilhamento

Corrigindo "Stale file handle" no NFS - Remontando o Compartilhamento
Tempo de leitura: Cerca de 11 min Dificuldade: Intermediario

O que "Stale file handle" realmente significa?

Conclusao: O cliente NFS esta segurando um file handle que nao corresponde mais ao objeto no servidor (ESTALE). O NFS identifica objetos por handle, nao por caminho, entao mudancas no servidor sao o gatilho.

Em uma montagem NFS, ls, cat ou salvar um arquivo falha assim:

ls: cannot access '/mnt/nfs/data': Stale file handle

O NFS identifica um arquivo por um file handle, nao por seu caminho. Um handle e composto aproximadamente de tres partes:

  • fsid -- identificador do filesystem exportado
  • numero de inode -- o inode do arquivo ou diretorio alvo
  • numero de geracao -- distingue inodes que foram reutilizados

O cliente faz cache desse handle no momento da montagem e no acesso, depois o reutiliza para operacoes posteriores. Se o objeto para o qual o handle aponta desaparece ou muda no servidor, o proximo acesso faz o kernel retornar ESTALE (Stale file handle).

Ponto-chave: Isso nao e uma falha de disco. O cliente esta simplesmente segurando uma referencia desatualizada, e a maioria dos casos e resolvida remontando no cliente. Suspeite do lado do cliente antes de mexer no servidor.

Por que um Stale file handle acontece?

Conclusao: Acontece quando o objeto para o qual um handle aponta muda no servidor. As quatro grandes causas sao deletar/recriar um arquivo, alterar exports, mudanca de fsid no reboot do servidor e mudancas de inode/geracao em uma restauracao.

Aqui estao os gatilhos comuns, ordenados por frequencia na pratica.

  • A. Um arquivo ou diretorio e deletado e recriado no servidor (mais comum) -- se um arquivo e removido e criado novamente por outro caminho enquanto o cliente o tem aberto, o inode/geracao muda e o handle fica obsoleto
  • B. Mudancas na configuracao de export -- editar /etc/exports e executar exportfs -r, ou alterar um caminho ou opcoes de export, quebra as premissas por tras dos handles existentes
  • C. O fsid muda no reboot do servidor -- se /etc/exports nao fixa fsid=, o servidor pode auto-atribuir um fsid diferente no reboot, invalidando handles existentes
  • D. Restauracao de backup ou snapshot -- uma restauracao pode alterar o numero de inode ou geracao de um arquivo, entao o mesmo caminho agora resolve para um handle diferente

A e D sao casos onde "o caminho e identico mas o objeto (inode) por baixo foi trocado." Parece correto pelo nome do arquivo, o que torna a causa raiz dificil de identificar. Quando voce vir ESTALE, primeiro suspeite que o objeto foi substituido no servidor.

Verifique a situacao primeiro

Conclusao: Identifique qual montagem NFS esta afetada e quais processos a estao usando antes de agir. Use findmnt para montagens e lsof / fuser para os processos que as utilizam.

1. Identificar a montagem NFS

$ findmnt -t nfs,nfs4
TARGET       SOURCE                  FSTYPE OPTIONS
/mnt/nfs     192.168.10.5:/export    nfs4   rw,relatime,vers=4.2,...

2. Reproduzir o ESTALE

$ ls /mnt/nfs
ls: reading directory '/mnt/nfs': Stale file handle

3. Encontrar processos usando a montagem

Uma remontagem requer que nada esteja usando a montagem alvo. Identifique os processos que a estao usando primeiro.

$ lsof +D /mnt/nfs 2>/dev/null
$ fuser -vm /mnt/nfs

Ate mesmo seu proprio shell dentro da montagem com cd conta como ocupado. Saia da montagem com cd / primeiro, depois tente a remontagem. Isso sozinho frequentemente permite que o umount funcione.

Como recuperar? (lado do cliente)

Conclusao: A correcao basica e "desmontar, depois remontar" para buscar o handle novamente. Se falhar como ocupado, use desmontagem lazy (umount -l); se isso ainda falhar, escale para forca (umount -f).

Passo 1: Desmontagem e remontagem normal

$ cd /
$ sudo umount /mnt/nfs
$ sudo mount /mnt/nfs

Se ha uma entrada no /etc/fstab, mount /mnt/nfs sozinho remonta. Isso resolve a maioria dos casos.

Passo 2: Desmontagem lazy quando esta ocupado

Quando umount falha com target is busy, verifique se voce pode parar os processos referenciando, depois use desmontagem lazy.

$ sudo umount -l /mnt/nfs   # lazy: desanexa assim que as referencias limparem
$ sudo mount /mnt/nfs

-l (lazy) desanexa o ponto de montagem do namespace imediatamente e o libera assim que a ultima referencia desaparece, entao voce pode prosseguir para a remontagem mesmo em um ambiente ocupado.

Passo 3: Desmontagem forcada quando o servidor nao responde

Se o servidor esta inativo ou inalcancavel e o I/O esta travando, use forca.

$ sudo umount -f /mnt/nfs

umount -f pode perder dados nao gravados. Se uma aplicacao esta no meio de uma gravacao, pare-a primeiro quando possivel. Use forca / lazy apenas como ultimos recursos escalantes.

Passo 4: Quando apenas um unico arquivo esta obsoleto

Se apenas um arquivo ou diretorio especifico esta obsoleto em vez de toda a montagem, sair e voltar ao diretorio pode limpar.

$ cd /
$ cd /mnt/nfs/data   # buscar o handle novamente

Se persistir, prossiga para a remontagem nos Passos 1-3.

O que verificar no servidor

Conclusao: Se uma remontagem do cliente nao ajuda, ou o problema atinge todos os clientes, suspeite do servidor. Verifique o estado do export e a consistencia do fsid.

Verificar o estado do export

$ sudo exportfs -v

Confirme que os caminhos e opcoes de export sao o que voce pretendia. Se voce acabou de alterar /etc/exports, re-exporte para garantir que esta aplicado.

$ sudo exportfs -ra

Verificar que o fsid esta fixado

Se Stale aparece apos cada reboot do servidor, o fsid auto-atribuido provavelmente esta mudando. Fixe-o explicitamente em /etc/exports.

# /etc/exports (lado do servidor)
/export  192.168.10.0/24(rw,sync,fsid=0,no_subtree_check)

fsid=0 e a pseudo-raiz do NFSv4. Atribua um valor unico (fsid=1, fsid=2, ...) ou um UUID para cada export adicional. Aplique mudancas com exportfs -ra.

Como prevenir?

Conclusao: Fixe fsid no servidor e evite deletar ou recriar arquivos em uso diretamente no servidor. Opcoes de montagem tambem podem amenizar travamentos.

  • Fixe fsid= explicitamente -- a medida mais eficaz contra fsid mudando no reboot
  • Nao modifique arquivos em uso diretamente no servidor -- delete ou substitua pelo cliente, ou quando nenhum cliente estiver referenciando
  • Faca mudancas de export durante uma janela de manutencao -- planeje edicoes de /etc/exports e re-exports junto com remontagens dos clientes
  • Entenda soft vs hard -- hard (padrao) continua tentando ate o servidor retornar, o que favorece integridade de dados mas trava facilmente em interrupcoes; soft desiste no timeout, travando menos mas arriscando gravacoes perdidas. Escolha pelo caso de uso

Copiar e colar: template de recuperacao do lado do cliente

# 1. Sair da montagem
cd /

# 2. Qual montagem esta afetada e quem a esta usando
findmnt -t nfs,nfs4
fuser -vm /mnt/nfs

# 3. Remontar (-l se ocupado, -f se travado)
sudo umount /mnt/nfs || sudo umount -l /mnt/nfs
sudo mount /mnt/nfs

Resumo

  • Stale file handle (ESTALE) significa que o cliente NFS esta segurando um file handle desatualizado; nao e uma falha de disco
  • A causa e uma mudanca do objeto no servidor (deletar/recriar, mudanca de export, mudanca de fsid, restauracao)
  • A correcao basica e uma remontagem no lado do cliente. Use umount -l quando ocupado e umount -f quando travado, escalando em passos
  • Se atinge todos os clientes ou recorre a cada reboot, verifique que fsid esta fixado no servidor

Proximas leituras