Quando os diretórios do IMAP somem: um relato de "pé no barro" no Roundcube

Recentemente, deparei com um daqueles problemas que fazem qualquer analista de infraestrutura coçar a cabeça. O cenário era o seguinte: os diretórios de e-mail existiam fisicamente no servidor, com data e hora de modificação recentes, mas simplesmente não apareciam para o usuário dentro do Webmail Roundcube.

Se você trabalha com administração de servidores de e-mail, sabe que o diretório /home/user/mail/domain.com é o coração da entrega. Eu conseguia listar os diretórios via terminal, via SSH, e eles estavam lá: .Pasta A, .Pasta B, .Arquivo Morto. Então, por que o Roundcube insistia em mostrar apenas a Inbox?

Abaixo está o roteiro operacional e forense completo que segui para depurar e solucionar essa falha no Dovecot e no Roundcube.

1. Anatomia física do maildir#

O Dovecot por padrão armazena e-mails no formato Maildir. Cada subpasta criada pelo usuário é representada fisicamente no disco como um diretório oculto iniciado por um ponto (.).

A estrutura correta de uma caixa postal saudável segue esta hierarquia:

/home/user/mail/domain.com.br/user/
├── cur/                    # Mensagens já processadas (lidas)
├── new/                    # Mensagens novas pendentes de leitura
├── tmp/                    # Arquivos temporários de trânsito do MDA
├── .Drafts/                # Rascunhos
│   ├── cur/
│   ├── new/
│   └── tmp/
├── .Sent/                  # Itens Enviados
│   ├── cur/
│   ├── new/
│   └── tmp/
├── .Trash/                 # Lixeira
│   ├── cur/
│   ├── new/
│   └── tmp/
├── .Pasta Personalizada/   # Diretório oculto de subpasta
│   ├── cur/
│   ├── new/
│   └── tmp/
├── subscriptions           # Arquivo plano listando pastas ativas (inscritas)
├── dovecot.index           # Índice principal de mensagens da Inbox
├── dovecot.index.cache     # Arquivos de cache de busca rápida
└── dovecot.index.log       # Histórico de transações de indexação

Se as pastas físicas existem no disco, mas as subpastas cur, new e tmp não existem dentro delas, o Dovecot desconsidera o diretório como uma caixa postal válida.

2. Diagnóstico de permissões e contexto do Dovecot#

O daemon do Dovecot precisa ler os diretórios de e-mail sob as permissões do usuário do sistema operacional associado à conta de hospedagem (e não sob o usuário root ou dovecot global).

Identificar quem executa os processos de entrega:#

ps aux | grep dovecot | head -3

Auditar dono (owner) e permissões do maildir:#

Em painéis de controle integrados como cPanel ou DirectAdmin, o dono do diretório deve ser o próprio usuário da conta (user) e o grupo correspondente (user ou mail).

# Verificar permissões atuais
ls -la /home/user/mail/domain.com.br/mail/

# O Dovecot precisa ter acesso de leitura. Se as permissões estiverem incorretas:
sudo -u dovecot ls -la /home/user/mail/domain.com.br/mail/

Correção de permissões:#

# 1. Ajustar o dono e grupo recursivamente
chown -R user:group /home/user/mail/domain.com.br/mail

# 2. Garantir permissões de leitura e execução em pastas (750 ou 755)
find /home/user/mail/domain.com.br/mail -type d -exec chmod 750 {} +

# 3. Garantir permissões de leitura e escrita em arquivos de mensagens (640 ou 644)
find /home/user/mail/domain.com.br/mail -type f -exec chmod 640 {} +

3. Verificação de quota e espaço em disco#

Quando uma conta atinge o limite máximo de quota de disco ou inodes (limites do sistema de arquivos ou do próprio painel), o Dovecot é impedido de atualizar ou criar arquivos de controle temporários, resultando no sumiço de pastas no cliente.

Verificar quotas no sistema de arquivos:#

# Quota do usuário do sistema
sudo repquota -a | grep user

# Consumo físico do diretório de mail
du -sh /home/user/mail/

Verificar quotas através do Dovecot:#

# Listar quotas de todas as caixas
doveadm quota get -A

# Obter quota de um usuário específico
doveadm quota get -u [email protected]

4. Backup preventivo e reindexação de índices corrompidos#

Arquivos de índice do Dovecot (dovecot.index*) atuam como cache para melhorar a performance. Se o servidor sofrer quedas repentinas de energia, estouro de quota ou travamento de E/S, esses índices podem ser corrompidos.

Procedimento seguro de reindexação:#

# 1. Criar diretório de backup com timestamp
BACKUP_DIR="/root/dovecot-index-backup-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$BACKUP_DIR"

# 2. Copiar os índices preventivamente mantendo a estrutura de caminhos
find /home/user/mail/domain.com.br -name "dovecot.index*" -exec cp --parents {} "$BACKUP_DIR/" \;

# 3. Excluir os índices corrompidos do diretório de produção
find /home/user/mail/domain.com.br -name "dovecot.index*" -delete

Na próxima conexão do usuário, o Dovecot lerá as mensagens do disco e recriará os índices do zero de forma limpa.

5. Arquivo subscriptions e encoding UTF-7 modificado#

O protocolo IMAP exige que o cliente saiba quais pastas exibir através do arquivo subscriptions localizado na raiz do Maildir. Se a pasta existir no disco mas não estiver listada nesse arquivo, ela não será exibida no Roundcube.

Verificar o arquivo de assinaturas:#

# Localizar o arquivo subscriptions
cat /home/user/mail/domain.com.br/mail/subscriptions

UTF-7 modificado para caracteres especiais:#

O IMAP usa uma variante do UTF-7. Nomes de pastas com acentos não são escritos em texto simples. Por exemplo, a pasta "Promoções" deve constar no arquivo como: Promo&AOcA9Q-es

Se o nome físico no disco for .Promoções mas no arquivo constar como Promoções puro, haverá incompatibilidade e a pasta sumirá.

# Inspecionar encoding do arquivo subscriptions procurando caracteres inválidos
hexdump -C /home/user/mail/domain.com.br/mail/subscriptions

Corrigir manualmente o arquivo:#

Se o arquivo estiver em branco ou corrompido, reconstrua-o buscando as pastas ocultas no disco:

# Listar diretórios físicos e gerar a lista de assinaturas base
echo -e "INBOX\nDrafts\nSent\nTrash" > /home/user/mail/domain.com.br/mail/subscriptions

Você também pode gerenciar as assinaturas usando a CLI do Dovecot de forma segura:

# Inscrever uma pasta específica para o usuário
doveadm mailbox subscribe -u [email protected] "Promo&AOcA9Q-es"

6. Testes diretos de conexão IMAP via CLI#

Para isolar se a falha reside no Roundcube ou no próprio servidor Dovecot, faça consultas diretas via terminal utilizando a linha de comando.

Testar conexão IMAP via openssl (porta 993/SSL):#

openssl s_client -connect localhost:993 -quiet

Após estabelecer o handshake, digite os comandos do protocolo:

a1 LOGIN [email protected] "senha_do_usuario"
a2 LIST "" "*"
a3 SELECT INBOX
a4 LOGOUT

Analise se o comando LIST retorna todas as pastas.

Testar conexão com cURL e lftp:#

# Listar mailboxes via curl (bypass de certificado)
curl -k "imaps://localhost" -u "[email protected]:senha" --list-only

# Conectar e listar com lftp
lftp -u "[email protected],senha" -e "set ssl:verify-certificate no; ls; bye" localhost

7. Configurações e logs do Roundcube#

Se o doveadm e o OpenSSL mostram as pastas corretamente mas o Roundcube ainda as omite, o erro está na interface PHP.

Localizar e auditar configurações do Roundcube:#

# Localizar o arquivo de configuração
find /var/www -name "config.inc.php" 2>/dev/null

# Verificar parâmetros de IMAP
grep -i "imap" /var/www/roundcube/config/config.inc.php

Certifique-se de que a variável $config['default_host'] ou $config['imap_host'] aponta para o endereço correto e que não existam filtros restritivos de pastas.

Acompanhar logs do servidor:#

Monitore os logs do Dovecot e os logs de erros do Roundcube simultaneamente durante as tentativas de login:

# Logs do Dovecot
tail -f /var/log/maillog | grep -i dovecot
# ou via journalctl
journalctl -u dovecot -f

# Logs de Erros do Roundcube
tail -f /var/log/roundcube/errors.log

# Verificar status geral e configurações efetivas do Dovecot
systemctl status dovecot
doveconf -n | head -20

8. Verificação pós-fix#

Após realizar as intervenções de permissão e limpeza de índices, ateste o sucesso do procedimento:

# 1. Verificar se novos arquivos de índice foram gerados
ls -la /home/user/mail/domain.com.br/mail/.*/dovecot.index*

# 2. Executar listagem via doveadm
doveadm mailbox list -u [email protected]

# 3. Validar status das pastas (exibe contagem de mensagens e tamanho)
doveadm mailbox status -u [email protected] "ALL"

Checklist: pastas IMAP não aparecem no Roundcube#

Utilize esta lista estruturada para o atendimento e triagem do incidente:

1. Camada física e permissões#

• [ ] As pastas físicas existem com o prefixo ponto no disco? (ex: /home/user/mail/domain.com.br/mail/.Pasta)
• [ ] A estrutura interna (cur, new, tmp) existe em cada subpasta?
• [ ] O ownership dos arquivos pertence ao usuário da conta de hospedagem (não ao root)?
• [ ] As permissões gerais estão definidas como 750 para diretórios e 640 para arquivos?

2. Índices e assinaturas#

• [ ] Foi realizado backup dos índices antes da delegação dos arquivos antigos?
• [ ] Os arquivos dovecot.index* corrompidos foram removidos?
• [ ] O arquivo subscriptions existe e está listando os nomes das subpastas?
• [ ] O encoding no arquivo subscriptions está no formato UTF-7 Modificado?

3. Serviços e cotas#

• [ ] A quota de disco da conta ou da VPS não está esgotada?
• [ ] O Dovecot está rodando e registrando atividade sem erros no /var/log/maillog?
• [ ] O teste de conexão local via OpenSSL (port 993) lista todos os diretórios com sucesso?
• [ ] O arquivo /var/log/roundcube/errors.log foi analisado procurando falhas de conexão de backend?

Veja também

E-mail Resolvendo o erro intermitente: AUTH command used when not advertised no Exim (cPanel)

Infraestrutura A ilusão do `sshd_config`: como realmente garantir a segurança da autenticação SSH no cPanel/CloudLinux

Infraestrutura Guia Definitivo de Troubleshooting de Let's Encrypt e SSL no DirectAdmin (CLI, CAA e Subdomínio WWW)

Este post está licenciado sob CC BY-NC.