Estudo de caso (RCA): investigando falha global de roteamento de e-mails pós-migração no cPanel

Investigação de falha global de roteamento de e-mails pós-migração (bug no cPanel/WHM)#

Quem já trabalhou no suporte corporativo e na gestão de servidores conhece a regra: quando um serviço crítico cai logo depois de uma migração noturna, o primeiro reflexo da diretoria costuma ser procurar um culpado na equipe técnica.

Neste estudo de caso de análise de causa raiz (RCA), relato um incidente real que atendi via chamado técnico. Dezenas de clientes corporativos pararam de receber e-mails após uma migração em lote. O gestor de infraestrutura foi acusado de ter errado o projeto da migração, mas uma investigação forense prática com reprodução em laboratório provou que o problema foi gerado por um bug nativo do cPanel/WHM.

Para manter a conformidade com a LGPD e o sigilo dos clientes, todos os domínios, IPs e identificadores foram anonimizados.

1. O cenário da migração e a pane nos e-mails#

Durante uma janela programada de modernização de parque, o gestor de infraestrutura migrou dezenas de contas corporativas de um servidor antigo para um novo cluster. A transferência rodou de madrugada (das 00:27 às 04:13) utilizando a ferramenta padrão do WHM: o Transfer Tool.

A maioria dessas empresas usava uma camada externa de gateway AntiSpam na nuvem. Nessa estrutura, o servidor cPanel nunca entrega caixas postais diretamente; ele precisa encaminhar as mensagens para o filtro externo. No cPanel, isso exige que a rota esteja configurada como Remote Mail Exchanger, o que grava o domínio no arquivo /etc/remotedomains do Exim.

Interface do cPanel com o roteamento configurado em Remote Mail Exchanger.

Quando o expediente começou na manhã seguinte, vários clientes abriram chamados urgentes avisando que não recebiam mensagens de fora. Em uma checagem rápida no novo servidor, vimos o sintoma: dezenas de domínios migrados haviam mudado sozinhos de Remote para Local Mail Exchanger (/etc/localdomains).

O início da cobrança interna#

Com os clientes pressionando, o clima pesou. A diretoria cobrou explicações duras do gestor de infraestrutura, assumindo que ele havia errado o projeto ou esquecido de conferir as contas na virada da noite.

Fui acionado pelo chamado de emergência para investigar o caso, colocar os e-mails de volta no ar e auditar o que realmente aconteceu.

2. Coleta de dados e auditoria nos logs#

Para tirar a discussão de palpites e focar em dados concretos, fui direto aos arquivos de log do servidor.

2.1. O que os logs da migração registraram#

Verifiquei os registros gerados pela rotina de restauração do Transfer Tool em /usr/local/cpanel/logs/cpbackup/ e /var/cpanel/transfers/. Encontrei avisos nos domínios afetados:

The system could not restore the zone "dominio-cliente-a.com.br" because it does not match any domain on this account.
The system disabled a CNAME record for "empreendimento.dominio-cliente-b.com.br." due to a conflict.

Esses avisos mostraram que a importação das zonas de DNS autoritativas não havia sido 100% limpa no destino.

2.2. Verificação no terminal#

Para checar se alguém havia mexido no painel de manhã, rodei consultas via SSH:

# 1. Conferindo a rota atual no Exim
grep dominio-cliente.com.br /etc/localdomains

# 2. Testando a resolucao do host de correio
ping mail.dominio-cliente.com.br

# 3. Verificando acessos ao Zone Editor nos logs do cPanel
grep usuario_cpanel /usr/local/cpanel/logs/access_log | grep zone_editor/index.html

Os logs do cPanel comprovaram que ninguém da equipe havia acessado o Zone Editor ou clicado em alterar roteamento após a migração. As contas não tinham recebido nenhuma edição manual.

Checagem dos arquivos do Exim e dos registros brutos do cPanel.

3. Reprodução prática em laboratório (PoC)#

Os logs provavam duas coisas: as zonas DNS tiveram falhas na importação e nenhum humano mexeu nas configurações pela manhã. Mas faltava responder: por que o cPanel mudou a rota sozinho de Remote para Local?

Para isolar o comportamento sem mexer no ambiente de produção, montei um teste idêntico em um servidor de desenvolvimento.

3.1. Preparando o teste#

Criei uma conta de teste no WHM e configurei o roteamento manualmente como Remote Mail Exchanger, reproduzindo o cenário dos clientes com AntiSpam externo.

Conferi como o Exim gravou a rota no disco:

cat /etc/localdomains | grep dominio-teste.com.br
cat /etc/remotedomains | grep dominio-teste.com.br

O domínio estava apenas em /etc/remotedomains, exatamente como esperado.

3.2. Simulando o estado pós-migração#

O cPanel trabalha por padrão com a opção "Automatically Detect Configuration", que tenta descobrir se o MX aponta para um IP local ou remoto.

Para reproduzir a zona incompleta deixada pela migração, entrei no Zone Editor e apaguei os registros MX e CNAME do domínio de teste.

3.3. O acionamento do script#

O cPanel roda periodicamente, via cron do sistema, um script em Perl que valida as rotas de correio de todas as contas. Chamei o script manualmente no terminal:

/scripts/checkalldomainsmxs --yes

3.4. O flagrante no terminal#

Assim que o script rodou, o terminal mostrou exatamente o que aconteceu na madrugada:

Checking and setting dominio123.com.br ....LOCAL MAIL EXCHANGER: This server will serve as a primary mail exchanger for dominio123.com.br's mail.: This configuration has been automatically detected based on your mx entries.<br />....Done

O script nativo do cPanel alterando o roteamento para LOCAL MAIL EXCHANGER.

Abri os arquivos do Exim para conferir o resultado:

cat /etc/localdomains

O domínio de teste havia sido retirado do /etc/remotedomains e gravado dentro de /etc/localdomains. Ninguém clicou em nada; foi uma rotina automática e cega do próprio painel.

Verificação no disco confirmando que a rota foi transferida para localdomains.

4. Análise de causa raiz (RCA)#

Com a reprodução gravada em vídeo e a análise dos logs, fechei a cadeia causal do problema:

[ Janela de Migração ]
         │
         ▼
[ Transfer Tool executado com "Update DNS Zone" desativado para preservar regras customizadas ]
         │
         ▼
[ Falha Nativa (Bug cPanel): Domínios perdem a persistência da rota ao migrar sem sobrescrita de DNS ]
         │
         ▼
[ Registros MX/CNAME ausentes no destino criam inconsistência lógica no resolver ]
         │
         ▼
[ Script /scripts/checkalldomainsmxs entra em modo fail-safe cego ]
         │
         ▼
[ Domínios transferidos de /etc/remotedomains para /etc/localdomains ]
         │
         ▼
[ E-mails externos param de chegar nas caixas corporativas ]

1. A decisão do gestor: Ele agiu com prudência. Como as contas tinham zonas DNS antigas e cheias de apontamentos customizados, ele desmarcou a sobrescrita de zonas na Transfer Tool para não apagar entradas essenciais dos clientes.
2. O bug do cPanel: Naquela versão, a ferramenta de transferência tinha uma falha: quando a opção de atualizar a zona DNS era desmarcada, o cPanel esquecia a configuração de roteamento de e-mails no destino.
3. O fallback agressivo: Sem os registros MX gravados localmente, o script periódico (checkalldomainsmxs) presumiu que o servidor local deveria assumir a entrega e forçou a rota para Local, quebrando o fluxo com o AntiSpam.

5. Resolução e o que fica de lição#

Anexei o relatório técnico e o vídeo da reprodução diretamente no ticket do chamado, citando também a confirmação oficial da própria equipe de suporte da cPanel (Ticket interno #95782358):

"Domains transferred with the Transfer Tool and the 'Update DNS Zone' option disabled do not have mail routing configured on the new server."

Procedimento de contorno adotado#

Para restabelecer as contas e proteger as próximas etapas da migração, padronizei este roteiro via terminal:

# 1. Reconstruir a zona DNS no BIND
/scripts/rebuilddnszone dominio-cliente.com.br

# 2. Fixar a rota Remota via API do WHM, desativando a deteccao automatica
whmapi1 set_manual_mx_redirects domain=dominio-cliente.com.br mx=remote

# 3. Conferir a presenca no remotedomains do Exim
grep -E '^dominio-cliente.com.br$' /etc/remotedomains

# 4. Rodar o script de checagem para validar estabilidade
/scripts/checkalldomainsmxs --yes

Conclusão#

Essa investigação rendeu dois resultados práticos:

1. Defesa técnica da equipe: A acusação de erro contra o gestor de infraestrutura foi desfeita com logs e provas repetíveis em laboratório. A cobrança interna foi encerrada.
2. Postura de engenharia: Na administração de sistemas e em operações de hosting, nunca se deve aceitar conclusões apressadas de erro humano antes de esgotar a análise dos logs. Falhas em softwares acontecem o tempo todo; o papel de quem cuida da infraestrutura é auditar com rigor até encontrar a causa real.

Veja também

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)

Infraestrutura Diário de suporte: driblando o pkgacct no cPanel e alinhando a comunicação com o cliente

Este post está licenciado sob CC BY-NC.