# 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.

> 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.

João Rizzon · 2026-10-07 · Servidores

---

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](https://docs.cpanel.net/knowledge-base/general-systems-administration/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):

```bash
#!/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:

```bash
# 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.

```bash
# 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:

```bash
# 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 `T0` e 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`.

```bash
# 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 por `wget && make`. A lista de `rpm -qa` ajuda, 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 `/home` na é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](https://docs.cpanel.net/knowledge-base/general-systems-administration/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.

