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: Intermediário

O que "Stale file handle" realmente significa?

Conclusão: O cliente NFS está segurando um file handle que não corresponde mais ao objeto no servidor (ESTALE). O NFS identifica objetos por handle, não por caminho, então mudanças no servidor são 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, não por seu caminho. Um handle é composto aproximadamente de três partes:

  • fsid -- identificador do filesystem exportado
  • número de inode -- o inode do arquivo ou diretório alvo
  • número de geração -- distingue inodes que foram reutilizados

O cliente faz cache desse handle no momento da montagem e no acesso, depois o reutiliza para operações posteriores. Se o objeto para o qual o handle aponta desaparece ou muda no servidor, o próximo acesso faz o kernel retornar ESTALE (Stale file handle).

Ponto-chave: Isso não é uma falha de disco. O cliente está simplesmente segurando uma referência desatualizada, e a maioria dos casos é resolvida remontando no cliente. Suspeite do lado do cliente antes de mexer no servidor.

Por que um Stale file handle acontece?

Conclusão: Acontece quando o objeto para o qual um handle aponta muda no servidor. As quatro grandes causas são deletar/recriar um arquivo, alterar exports, mudança de fsid no reboot do servidor e mudanças de inode/geração em uma restauração.

Aqui estão os gatilhos comuns, ordenados por frequência na prática.

  • A. Um arquivo ou diretório é deletado e recriado no servidor (mais comum) -- se um arquivo é removido e criado novamente por outro caminho enquanto o cliente o tem aberto, o inode/geração muda e o handle fica obsoleto
  • B. Mudanças na configuração de export -- editar /etc/exports e executar exportfs -r, ou alterar um caminho ou opções de export, quebra as premissas por trás dos handles existentes
  • C. O fsid muda no reboot do servidor -- se /etc/exports não fixa fsid=, o servidor pode auto-atribuir um fsid diferente no reboot, invalidando handles existentes
  • D. Restauração de backup ou snapshot -- uma restauração pode alterar o número de inode ou geração de um arquivo, então o mesmo caminho agora resolve para um handle diferente

A e D são casos onde "o caminho é idêntico mas o objeto (inode) por baixo foi trocado." Parece correto pelo nome do arquivo, o que torna a causa raiz difícil de identificar. Quando você vir ESTALE, primeiro suspeite que o objeto foi substituído no servidor.

Verifique a situação primeiro

Conclusão: Identifique qual montagem NFS está afetada e quais processos a estão 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 estão usando primeiro.

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

Até mesmo seu próprio 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)

Conclusão: A correção básica é "desmontar, depois remontar" para buscar o handle novamente. Se falhar como ocupado, use desmontagem lazy (umount -l); se isso ainda falhar, escale para força (umount -f).

Passo 1: Desmontagem e remontagem normal

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

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

Passo 2: Desmontagem lazy quando está ocupado

Quando umount falha com target is busy, verifique se você 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 última referência desaparece, então você pode prosseguir para a remontagem mesmo em um ambiente ocupado.

Passo 3: Desmontagem forçada quando o servidor não responde

Se o servidor está inativo ou inalcançável e o I/O está travando, use força.

$ sudo umount -f /mnt/nfs

umount -f pode perder dados não gravados. Se uma aplicação está no meio de uma gravação, pare-a primeiro quando possível. Use força / lazy apenas como últimos recursos escalantes.

Passo 4: Quando apenas um único arquivo está obsoleto

Se apenas um arquivo ou diretório específico está obsoleto em vez de toda a montagem, sair e voltar ao diretório 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

Conclusão: Se uma remontagem do cliente não ajuda, ou o problema atinge todos os clientes, suspeite do servidor. Verifique o estado do export e a consistência do fsid.

Verificar o estado do export

$ sudo exportfs -v

Confirme que os caminhos e opções de export são o que você pretendia. Se você acabou de alterar /etc/exports, re-exporte para garantir que está aplicado.

$ sudo exportfs -ra

Verificar que o fsid está fixado

Se Stale aparece após cada reboot do servidor, o fsid auto-atribuído provavelmente está 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 é a pseudo-raiz do NFSv4. Atribua um valor único (fsid=1, fsid=2, ...) ou um UUID para cada export adicional. Aplique mudanças com exportfs -ra.

Como prevenir?

Conclusão: Fixe fsid no servidor e evite deletar ou recriar arquivos em uso diretamente no servidor. Opções de montagem também podem amenizar travamentos.

  • Fixe fsid= explicitamente -- a medida mais eficaz contra fsid mudando no reboot
  • Não modifique arquivos em uso diretamente no servidor -- delete ou substitua pelo cliente, ou quando nenhum cliente estiver referenciando
  • Faça mudanças de export durante uma janela de manutenção -- planeje edições de /etc/exports e re-exports junto com remontagens dos clientes
  • Entenda soft vs hard -- hard (padrão) continua tentando até o servidor retornar, o que favorece integridade de dados mas trava facilmente em interrupções; soft desiste no timeout, travando menos mas arriscando gravações perdidas. Escolha pelo caso de uso

Copiar e colar: template de recuperação 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 está segurando um file handle desatualizado; não é uma falha de disco
  • A causa é uma mudança do objeto no servidor (deletar/recriar, mudança de export, mudança de fsid, restauração)
  • A correção básica é 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 está fixado no servidor

Próximas leituras