blog
Servidores

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.

JR · · 10 min de leitura · 1 tabela · 5 blocos de código

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
  1. Os oito artefatos que precisam estar fora da máquina antes do incidente
  2. Por que a ordem das seis etapas importa mais que a velocidade de cada uma
  3. Cronometrar T0 a T1 numa VM limpa para saber o RTO real
  4. Erros que o ensaio costuma revelar antes do desastre
  5. O que manter versionado fora do servidor entre um ensaio e outro
  6. 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.

Ordem da reconstrução de um servidor cPanelProvisionarMesma distro, disco maiorLicenciarIP novo antes de instalarEstruturaPacotes, revendedores, perfil EA4ContasUma pequena, validar, loteSSL de serviçoAutoSSL só depois do DNSDNSÚltimo passo, TTL já baixo
Sequência de reconstrução. Inverter a ordem gera contas sem pacote correto e erro indexado antes da validação.

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:

  1. Provisione uma VM nova, sem nada do servidor atual.
  2. Marque T0 e instale o cPanel do zero com a licença de teste.
  3. Aplique o perfil do EA4 e os arquivos de estrutura do tarball.
  4. Restaure uma conta representativa do seu parque (não a menor).
  5. Valide: site abre, formulário grava no banco, webmail lista mensagens, cron roda, certificado válido.
  6. 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.

Ensaio de T0 a T1 para medir o RTOT0VM limpa, instalar cPanelEstruturaPerfil EA4 e tarballRestaurar contaConta representativa, não a menorValidarSite, banco, webmail, cron, SSLT1RTO medido, tempo por etapa
Ensaio cronometrado numa VM limpa. Anote o tempo de cada etapa separadamente para projetar o total.

Erros que o ensaio costuma revelar antes do desastre

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:

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

  1. Documentação oficial (cpanel) — Full Disaster Recovery. Consultado em 2026-09-30.
Leia também