Runbook para reconstruir um servidor cPanel perdido por inteiro
O inventário que precisa estar fora da máquina, a sequência de reconstrução baseada na documentação do cPanel e como cronometrar um ensaio para saber o RTO real.

Resposta curta: não tente consertar: reconstrua numa máquina nova em sequência fixa, provisionar, licenciar, restaurar a estrutura do WHM, restaurar as contas, validar por /etc/hosts e só então apontar o DNS. Para isso, o tarball de /var/cpanel, /var/named e /var/cpanel/ssl precisa já estar fora do servidor.
Neste artigo
- Os oito artefatos que precisam estar fora da máquina antes do incidente
- Por que a ordem das seis etapas importa mais que a velocidade de cada uma
- Cronometrar T0 a T1 numa VM limpa para saber o RTO real
- Erros que o ensaio costuma revelar antes do desastre
- O que manter versionado fora do servidor entre um ensaio e outro
- Perda total é problema de ordem, e o RTO sai do cronômetro
Backup de conta resolve o caso em que uma conta foi apagada. Não resolve o caso em que o servidor inteiro deixou de existir: hardware condenado, datacenter perdido, volume corrompido sem snapshot válido. Nesse cenário você não tem WHM para abrir, não tem /home para montar e não tem a lista de pacotes que estavam instalados.
A documentação do cPanel trata esse caso na página Full Disaster Recovery, que descreve a recuperação como reconstrução de um servidor novo a partir de artefatos preservados fora da máquina. O que segue é um runbook organizado em cima dessa referência: o inventário do que precisa estar fora, a ordem de reconstrução e um ensaio cronometrado para você saber o RTO real em vez de supor.
Os caminhos e comandos abaixo seguem a documentação do cPanel & WHM e foram escritos tendo como referência inicial a série 110 (LTS), que já encerrou o ciclo de suporte. Antes de usar o script, confira a série que você roda (/usr/local/cpanel/cpanel -V) e os caminhos equivalentes na documentação da sua versão: a estrutura geral de /var/cpanel, /var/named e /etc/cpanel/ea4 se mantém nas séries LTS seguintes, mas arquivos individuais mudam de formato entre séries. O mesmo vale para a distribuição: a referência aqui é a família EL 8 (AlmaLinux 8, CloudLinux 8) com EasyApache 4. Em outras distribuições e séries, três coisas mudam: em AlmaLinux 9 e CloudLinux 9 não existe /etc/sysconfig/network-scripts por padrão (a configuração de rede está em NetworkManager, em /etc/NetworkManager/system-connections); em servidores Ubuntu suportados pelo cPanel, rpm -qa não existe e o equivalente é dpkg -l ou apt list --installed; e séries mais novas do cPanel podem mudar o formato de arquivos sob /var/cpanel, o que reforça duas coisas: restaurar na mesma série em que o tarball foi gerado e validar cada caminho da tabela abaixo no seu próprio servidor antes de tratá-lo como inventário fechado.
Os oito artefatos que precisam estar fora da máquina antes do incidente
O backup de contas (/home e os pacotes cpmove) é condição necessária e insuficiente. Ele restaura sites, e-mails e bancos. Não restaura a identidade do servidor: pacotes de hospedagem, revendedores, nameservers configurados, chaves de assinatura DNSSEC, certificados de serviço, filtros globais do Exim, regras de firewall.
O inventário abaixo é o conjunto que, na prática, determina se a reconstrução leva horas ou dias. A página Full Disaster Recovery cita explicitamente /var/cpanel, /var/named e os dados das contas como artefatos a preservar. As demais linhas da tabela (configuração de e-mail, /etc/named.conf, lista de pacotes, perfil do EA4, rede e firewall) não estão nela: são prática nossa, acumulada em reconstruções onde a falta de cada um desses itens custou tempo.
| Artefato | Caminho | Por que dói sem ele |
|---|---|---|
| Configuração do cPanel/WHM | /var/cpanel |
Pacotes, revendedores, features, limites, usuários e mapeamento de domínios |
| Zonas DNS | /var/named |
Reconstruir zona a zona na mão, com risco de TTL e registro perdido |
| SSL de serviço e armazenamento de certificados | /var/cpanel/ssl |
Certificados de hostname, IMAP/SMTP e chaves privadas das contas |
| Configuração de e-mail | /etc/exim.conf.local, /etc/dovecot, arquivos de configuração do Exim gerados pelo WHM |
Filtros globais, ACLs customizadas, limites de envio |
| Configuração do named | /etc/named.conf |
Views, forwarders, chaves TSIG, DNSSEC |
| Lista de pacotes | saída de rpm -qa |
Dependência instalada à mão que ninguém lembra |
| Perfil do EasyApache 4 | JSON do perfil, em /etc/cpanel/ea4/profiles/custom |
Versões de PHP, extensões, MPM, módulos do Apache |
| Rede e firewall | /etc/sysconfig/network-scripts ou netplan, regras do firewall em uso |
IPs adicionais, bindings, allowlists |
Um tarball diário desses caminhos, enviado para fora do servidor, é pequeno comparado ao backup de /home e é o que permite recriar o servidor em vez de recriar contas soltas.
Script de coleta dos metadados e por que o tar sai com status 1
Exemplo de coleta (os caminhos variam conforme o que você usa; confira antes de confiar no script):
#!/bin/bash
# exemplo de coleta de metadados do servidor
set -euo pipefail
DEST=/root/dr
STAMP=$(date +%F)
mkdir -p "$DEST"
rpm -qa | sort > "$DEST/rpm-qa.txt"
/usr/local/cpanel/cpanel -V > "$DEST/cpanel-version.txt"
cp /etc/cpupdate.conf "$DEST/cpupdate.conf"
ip addr show > "$DEST/ip-addr.txt"
tar czf "$DEST/meta-$STAMP.tar.gz" \
/var/cpanel \
/var/named \
/etc/named.conf \
/etc/exim.conf.local \
/etc/dovecot \
/etc/cpanel/ea4 \
"$DEST/rpm-qa.txt" \
"$DEST/cpanel-version.txt" \
"$DEST/cpupdate.conf" \
"$DEST/ip-addr.txt" && rc=0 || rc=$?
# 0 = ok, 1 = "file changed as we read it" (aviso), 2 = erro fatal
if [ "$rc" -eq 1 ]; then
echo "aviso: arquivo mudou durante a leitura, tarball gerado" >&2
elif [ "$rc" -ne 0 ]; then
echo "erro fatal no tar (status $rc)" >&2
exit "$rc"
fi
O tar recebe tratamento explícito de código de saída porque /var/cpanel tem arquivos sendo escritos por serviços ativos (cpsrvd, cpdavd, contadores de banda). Quando um arquivo muda entre o stat e a leitura, o GNU tar emite file changed as we read it e termina com status 1, mesmo tendo gravado o tarball. Com set -e e sem o tratamento acima, o script aborta exatamente nos dias em que o servidor está mais movimentado, e o backup de metadados nunca é gerado. Status 2 é erro real (destino cheio, caminho inexistente) e aí vale abortar.
O tarball contém chaves privadas. Trate como segredo: destino cifrado, permissão 600, e de preferência gpg antes do upload. Se o seu backup de metadados vazar, o atacante tem os certificados das contas.
Para o EasyApache 4, salvar o perfil é mais confiável do que anotar versões de PHP:
# gera um perfil com o estado atual do EA4
/usr/local/bin/ea_current_to_profile --output=/etc/cpanel/ea4/profiles/custom/dr.json
Por que a ordem das seis etapas importa mais que a velocidade de cada uma
A ordem importa mais do que a velocidade de cada passo. Restaurar conta antes de restaurar a estrutura do WHM gera contas sem pacote correto, sem revendedor dono, com limites errados. Apontar DNS antes de ter as contas prontas gera erro 404 indexado e e-mail rejeitado com bounce permanente.
A documentação do cPanel não publica uma sequência numerada de reconstrução nem prescreve o uso de ea_install_profile e restorepkg nessa ordem. Os seis passos abaixo são prática operacional nossa; o que vem da documentação é o princípio de reconstruir servidor novo a partir dos artefatos preservados, e as páginas de referência de cada comando citado.
Provisionar a máquina na mesma distribuição e com disco maior
Mesma distribuição e, idealmente, mesma versão maior do sistema operacional. Migração de conta entre versões de OS é suportada; reconstrução de configuração binária entre versões diferentes não é. Dimensione o disco acima do original: restauração precisa de espaço temporário para descompactar pacotes de conta.
Emitir a licença para o IP novo antes de instalar o cPanel
Transfira ou emita a licença para o IP novo antes de instalar. Não porque o instalador pare: ele conclui normalmente sem licença válida. O problema aparece depois, com o WHM respondendo tela de licença inválida e os serviços gerenciados inutilizáveis até que a licença esteja emitida para o IP e /usr/local/cpanel/cpkeyclt atualize o arquivo local. Emitir antes só evita que você descubra isso com o cronômetro correndo. Instale a mesma série (LTS, RELEASE, CURRENT) que o servidor antigo usava, para que o formato dos arquivos de configuração bata com o que está no tarball.
Restaurar pacotes, revendedores e perfil do EA4 antes de qualquer conta
Aqui entram os pacotes de hospedagem, os revendedores, as features, a configuração do Exim e do named, e o perfil do EA4. Aplicar o perfil primeiro evita restaurar um site PHP 8.2 num servidor que só tem 8.1.
# aplica o perfil salvo antes de restaurar contas
/usr/local/bin/ea_install_profile --install /etc/cpanel/ea4/profiles/custom/dr.json
Não sobrescreva /var/cpanel inteiro por cima de uma instalação nova e em execução. Pare os serviços relevantes, restaure arquivos específicos (pacotes, revendedores, features, /var/cpanel/users quando a documentação do seu cenário indicar), e revise. Sobrescrita cega de diretório de configuração em serviço ativo é a forma mais comum de transformar um desastre em dois.
Restaurar uma conta pequena, validar e só então disparar o lote
Use os pacotes de conta do backup, via /scripts/restorepkg ou pela fila de restauração do WHM. Restaure primeiro uma conta pequena e valide: arquivos, banco, caixas de e-mail, cron, certificado. Só depois dispare o lote.
Reaplicar SSL de serviço e deixar o AutoSSL para depois do DNS
Certificados de serviço (hostname, IMAP, SMTP) vêm de /var/cpanel/ssl. Certificados de conta costumam voltar com o pacote da conta, mas confira os que expiraram durante a janela do incidente. Se usava AutoSSL, rode uma passagem manual depois que o DNS apontar, não antes: validação HTTP falha enquanto o domínio ainda resolve para o IP morto.
Apontar o DNS por último, com TTL já baixado por rotina
DNS é o interruptor. Enquanto ele aponta para o IP antigo, o servidor novo é um laboratório privado que você pode testar com /etc/hosts local. Depois que aponta, erro vira incidente público.
Teste com entrada local antes:
# no seu desktop, exemplo fictício de IP
echo "203.0.113.10 exemplo.com.br www.exemplo.com.br" | sudo tee -a /etc/hosts
curl -sS -o /dev/null -w '%{http_code} %{time_total}\n' https://exemplo.com.br/
Se você controla os nameservers, baixe o TTL das zonas para algo curto (300 segundos, por exemplo) com antecedência, como rotina, não no dia do desastre: TTL baixado na hora só vale depois que o TTL antigo expirar.
Cronometrar T0 a T1 numa VM limpa para saber o RTO real
RTO estimado em reunião não é RTO. O único número confiável é o que você cronometrou numa máquina limpa.
Monte o ensaio assim:
- Provisione uma VM nova, sem nada do servidor atual.
- Marque
T0e instale o cPanel do zero com a licença de teste. - Aplique o perfil do EA4 e os arquivos de estrutura do tarball.
- Restaure uma conta representativa do seu parque (não a menor).
- Valide: site abre, formulário grava no banco, webmail lista mensagens, cron roda, certificado válido.
- Marque
T1.
# exemplo de cronometragem de uma etapa isolada
/usr/bin/time -v /scripts/restorepkg /backup/cpmove-exemplo.tar.gz 2> /root/dr/restore-exemplo.log
Anote o tempo de cada etapa separadamente. Instalação do cPanel, aplicação do EA4 e restauração da conta escalam de forma diferente: a primeira é quase constante, a segunda depende do número de extensões, a terceira depende do volume de dados e da quantidade de arquivos pequenos (um /home com milhões de arquivos de cache restaura muito mais devagar que um /home do mesmo tamanho com poucos arquivos grandes).
Com os tempos por etapa você projeta o total: tempo fixo de reconstrução mais tempo por conta, e descobre se precisa paralelizar a restauração ou priorizar contas por criticidade.
Erros que o ensaio costuma revelar antes do desastre
- Backup que não restaura. Arquivo existe, tarball abre, mas faltou o banco porque o usuário de backup não tinha permissão. Só se descobre restaurando.
- Dependência fora do EA4. Extensão PHP compilada à mão, binário em
/usr/local/bin, biblioteca instalada porwget && make. A lista derpm -qaajuda, mas não captura o que não veio de pacote. Documente à parte. - Chave de API e integração com IP fixo. Gateway de pagamento, API de terceiro e SMTP relay que fazem allowlist por IP continuam bloqueando o IP novo depois que tudo já está no ar.
- Reverso e SPF. IP novo sem PTR configurado e sem o registro SPF atualizado derruba entregabilidade de e-mail no primeiro dia.
- DKIM. Se as chaves não vieram em
/var/cpanel, o cPanel gera chaves novas e os registros publicados no DNS deixam de bater. - Licença presa ao IP antigo. Descobrir isso no meio do incidente custa o tempo de um ticket com o fornecedor da licença.
O que manter versionado fora do servidor entre um ensaio e outro
Um runbook envelhece. A cada mudança relevante no servidor (nova versão de PHP padrão, novo revendedor, mudança de firewall, novo IP adicional), o tarball de metadados muda sozinho, mas a documentação de dependências manuais não.
Mantenha três coisas versionadas num repositório fora do servidor:
- o script de coleta;
- a lista de dependências instaladas fora de pacote, com o comando de instalação;
- o registro dos tempos do último ensaio, com data e tamanho do
/homena época.
Refaça o ensaio quando o parque crescer de forma significativa ou quando mudar a versão maior do sistema operacional. Um ensaio por ano com número anotado vale mais do que um plano escrito que ninguém executou.
Perda total é problema de ordem, e o RTO sai do cronômetro
Perda total de servidor é um problema de ordem, não de heroísmo. Os artefatos de configuração precisam estar fora da máquina antes do incidente, em destino cifrado, porque contêm chaves privadas. A reconstrução segue uma sequência fixa: provisionar, licenciar, restaurar estrutura, restaurar contas, validar com /etc/hosts, e só então mover o DNS. E o RTO que você comunica para cliente ou para a diretoria deve sair de um cronômetro, não de uma estimativa.
A referência canônica para o procedimento no cPanel/WHM é a página Full Disaster Recovery da documentação oficial. Leia antes de escrever o seu runbook, e depois escreva o seu, porque o inventário do que está fora de pacote só existe no seu servidor.
Referências
- Documentação oficial (cpanel) — Full Disaster Recovery. Consultado em 2026-09-30.