cPanel + Dovecot: erro `doveadm exit code 68` - diagnóstico e correção definitiva

cPanel + Dovecot: Erro doveadm exit code 68 - Diagnóstico e Correção Definitiva#

Durante a rotina de administração de servidores, principalmente no pós-migração de contas ou restauração de backups que ignoram o Dovecot Indexer, é comum encontrar inconsistência no uso de disco de e-mail no cPanel (Jupiter). O sintoma no painel costuma ser genérico: quota que não abre, tela travada ou leitura incompleta das caixas.

Quando você desce para a CLI, o erro real aparece:

doveadm: Error: cmd mailbox status: Mailbox [email protected]: Failed to lookup mailbox status: Mailbox doesn't exist
"/usr/bin/doveadm" reported error code "68"

Isso não é um "bug aleatório" de software. É um descompasso estrutural entre o metadado lógico da mailbox e a estrutura física da Maildir no disco.

O loop de cotas fantasmas#

Em servidores cPanel, o painel roda scripts automatizados em Perl (como generate_maildirsize ou rebuildmaildir) para ler o uso de disco das caixas. Esse script Perl interage com o sistema de arquivos utilizando chamadas como getdents() para varrer os diretórios físicos sob a pasta mail. Em seguida, o wrapper do cPanel executa comandos de recalque de cotas do Dovecot (doveadm quota recalc ou doveadm mailbox status).

Se houver uma conta órfã ou corrompida (que possui registros lógicos em tabelas do cPanel ou arquivos como o passwd mas sem uma pasta física correspondente ou vice-versa), o comando doveadm emite o erro exit code 67 (User doesn't exist) ou exit code 68 (Mailbox doesn't exist). Como a resposta do doveadm falha com um código de erro, o script em Perl é interrompido ou entra em um loop infinito ao tentar recalcular a conta subsequente, gerando uma falha sistêmica de visualização de cotas no painel:

2) Verificação de consistência em disco#

Primeira validação objetiva:

ls -la /home/usuario_cpanel/mail/dominio.com/conta_email/

Uma Maildir válida precisa ter obrigatoriamente os seguintes diretórios:

• cur/
• new/
• tmp/

Se uma dessas pastas não existe no disco, o Dovecot retorna o erro exit code 68 em operações de status/index por não conseguir resolver o caminho físico do INBOX.

Cota física (VFS) vs. cota lógica (Dovecot/zlib)#

Em ambientes de produção, é fundamental entender a diferença de arquitetura de cotas:

• Cota Física (VFS/Filesystem): É o espaço ocupado fisicamente pelos blocos de arquivos no disco, auditado pelo comando du -sh ou por cotas de sistema de arquivos Unix.
• Cota Lógica (Dovecot/Zlib): É o espaço calculado pelo Dovecot com base nos dados do cache do arquivo maildirsize. Se você utiliza o plugin de compressão zlib no Dovecot, os e-mails são armazenados compactados no disco. A cota física será menor que a cota lógica, e o plugin do zlib mapeia ambos os tamanhos (físico compactado vs. lógico descompactado) em campos separados (usando tags como ,S=) no arquivo de índices dovecot-uidlist.

Se o cache maildirsize for corrompido, o Dovecot apresentará divergências drásticas em relação ao uso de disco físico.

Teste complementar de confirmação#

Tentar criar uma mailbox e receber um erro "already exists" (porque o Dovecot a vê logicamente no arquivo dovecot-uidlist) enquanto os diretórios físicos não existem sob o caminho da Maildir é o sintoma clássico de descompasso.

Também validamos o status diretamente:

doveadm mailbox status -u [email protected] messages INBOX

Se falhar com "Mailbox doesn't exist" mas a conta estiver ativa no painel do cPanel, o estado órfão (zombie state) está confirmado.

3) Deep dive arquitetural: syscalls, maildirsize e ftruncate#

Para reconstruir o cache de cotas lógicas de forma consistente, precisamos compreender as syscalls envolvidas quando o daemon Dovecot realiza o recálculo e manipula as caixas:

1. getdents(): Utilizada pelo sistema operacional e wrappers do cPanel para listar o conteúdo dos diretórios de e-mail e indexar arquivos de mensagens (cur, new, tmp).
2. truncate() / ftruncate(): Quando invocamos o recalque de cotas via doveadm quota recalc ou o Dovecot processa novas mensagens, o arquivo de cache de cotas maildirsize é atualizado. O Dovecot abre o arquivo e executa a chamada ftruncate para truncar o arquivo para o tamanho correto antes de reescrever a lista sequencial de tamanhos de mensagens e limites de quota. Se o processo do Dovecot sofrer concorrência de I/O ou for finalizado durante a chamada ftruncate, o arquivo maildirsize pode ficar truncado com 0 bytes ou corrompido, gerando cotas fantasmas no painel.

A verificação do arquivo de senhas virtual do Dovecot userdomains e o arquivo do domínio em passwd (onde o cPanel mapeia a conta e o UID/GID do usuário cPanel) deve ser realizada para garantir que o Dovecot localiza o usuário durante as consultas.

4) Correção em massa & comandos de recuperação#

Em servidores com dezenas ou centenas de contas de e-mail, realizar correções manuais individualmente é ineficiente. Utilizamos o fluxo interno do cPanel e utilitários do Dovecot para recuperação forçada de cotas e estruturas de Maildir:

4.1 reconstrução do maildir e sincronismo do cPanel#

Para reestruturar as pastas ausentes (cur, new, tmp) de todos os usuários do domínio de uma vez, execute o rebuild nativo do cPanel:

/scripts/rebuildmaildir --force dominio.com

4.2 recalcular a cota via cPanel e Dovecot#

Se o arquivo de quotas maildirsize estiver corrompido ou desatualizado, force a regeneração dele chamando o gerador do cPanel para o usuário específico:

/scripts/generate_maildirsize --confirm usuario_cpanel

Em seguida, execute o recalque de cotas lógicas diretamente no Dovecot para a conta afetada:

doveadm quota recalc -u [email protected]

4.3 reindexação global no Dovecot#

Para reindexar todas as mailboxes do servidor e consolidar as alterações de quota física nos índices lógicos:

doveadm index -A '*'

Detalhe crítico: Manter o '*' entre aspas simples é obrigatório no bash para evitar que o shell tente expandir o caractere curinga para o diretório atual do sistema.

4.4 conferência amostral pós-recuperação#

Valide se o Dovecot responde com sucesso para as contas corrigidas:

doveadm mailbox status -u [email protected] messages INBOX
doveadm mailbox status -u [email protected] messages INBOX

5) Prevenção, monitoramento e contas órfãs#

Para evitar novos débitos técnicos de contas de e-mail zumbis e garantir que todos os usuários ativos do painel possuam cotas lógicas sadias, implementamos rotinas de monitoramento preventivo.

Você pode executar o seguinte comando em loop ou como script diário para varrer todas as contas do Dovecot e listar os usuários que estão disparando falhas lógicas de quota ou mailbox inexistente:

doveadm user '*' | xargs -I{} doveadm quota get -u {} 2>&1 | grep -E "doesn't exist|Error"

Alternativamente, para auditar as listagens gerais ou filtrar erros específicos de contas inexistentes focando no retorno de sucesso ou outros status de quota:

doveadm user '*' | xargs -I{} doveadm quota get -u {} 2>&1 | grep -v "doesn't exist"

Se o primeiro comando retornar algum usuário, ele representa uma conta órfã (mapeada nas tabelas do painel mas com problemas de indexação ou integridade de Maildir). Esta conta deve receber o fluxo de tratamento (rebuildmaildir e quota recalc) antes que o usuário reporte problemas ao tentar usar o Webmail.

6) Playbook pós-migração para não abrir débito técnico#

Toda migração de e-mail precisa de validação ativa. Esse foi o playbook que padronizei:

1. Finalizou rsync de mailbox -> rodar rebuild:

   /scripts/rebuildmaildir --force dominio.com

1. Regenerar e confirmar arquivos maildirsize das contas:

   /scripts/generate_maildirsize --confirm usuario_cpanel

1. Após DNS/serviço estabilizados -> reindexar e recalcular quotas no Dovecot:

   doveadm index -A '*'
   doveadm quota recalc -u [email protected]

1. Validar contas críticas:

   doveadm mailbox status -u [email protected] messages INBOX

1. Conferir painel de uso de disco e abertura de Webmail.
2. Registrar evidência no change log da migração (comandos + horário + resultado).

Considerações práticas#

O exit code 68 do doveadm é indicador de integridade quebrada entre camada lógica e física de e-mail. Ignorar isso gera efeito cascata: quota inconsistente, Webmail com erro, ticket recorrente e perda de confiança do cliente.

Quando você corrige causa-raiz (Maildir + index), o ambiente estabiliza.

Infra madura não é a que "reinicia serviço para voltar"; é a que valida estrutura, reconstrói com método e deixa evidência técnica do que foi feito.

Veja também

Servidores Do VestaCP ao cPanel: como resolver o erro de corrupção IMAP no Roundcube

Infraestrutura Quando o filesystem e o daemon entram em desincronia

Servidores A anatomia de um troubleshooting: cotas fantasmas, Dovecot e a ilusão do espaço físico em servidores cPanel

Este post está licenciado sob CC BY-NC.