# Migrar contas cPanel: 7 conferências antes do DNS

Como separar falha real de aviso no log da fila do WHM, refazer só a conta que quebrou e conferir cada item antes de mudar o apontamento do domínio.

> sete conferências por conta separam uma fila do Transfer Tool marcada como concluída de uma migração pronta para o DNS: conta e domínios, home completo, banco, e-mail, zona ou DNS externo, cron e ambiente, e teste funcional por IP.

João Rizzon · 2026-09-18 · Revenda

---

A fila do Transfer Tool do WHM termina e mostra uma lista de itens. Alguns em verde, alguns em amarelo, alguns em vermelho. A tentação é olhar o verde, dizer "transferiu" e ir mudar o apontamento do domínio. É aí que a migração vira suporte de madrugada: o site abre, mas o formulário de contato não envia porque a conta de e-mail foi criada sem senha; o WooCommerce abre, mas a tabela de pedidos veio truncada; o domínio adicional do cliente virou subdomínio e a loja atende em `loja.dominio.com.br` em vez de `dominio.com.br`.

Este guia é sobre a parte que quase ninguém documenta: ler o relatório da sessão linha por linha, separar falha real de aviso, refazer só o item que falhou e conferir conta por conta **antes** de tocar no DNS. O procedimento e os parâmetros da ferramenta seguem a [documentação oficial do Transfer Tool](https://docs.cpanel.net/whm/transfers/transfer-tool/98/). As conferências no servidor são processo nosso, não medição: não há número de laboratório aqui, há checklist.

## O que o Transfer Tool resolve e o que sobra para você

O Transfer Tool (WHM » Transfers » Transfer Tool) conecta o WHM de destino ao servidor de origem e copia contas inteiras: diretório home, bancos de dados, contas de e-mail, zonas DNS, privilégios de revendedor. Você acessa o WHM do servidor **novo** e puxa as contas do **antigo**. Nunca o contrário. Quem tem acesso root no destino e credenciais de root ou de revendedor na origem faz tudo pela interface.

O que a ferramenta não faz, e é o que costuma quebrar entrega de agência:

- Não muda o DNS por você. A zona pode ser copiada, mas o apontamento do domínio nos nameservers continua onde estava.
- Não garante paridade de ambiente. Versão de PHP por domínio, extensões, limites (`memory_limit`, `max_input_vars`), módulos de servidor web: confira no destino.
- Não reconstrói o que estava fora do home. Cron do usuário costuma vir, mas tarefa criada fora do cPanel, regra de firewall, IP dedicado e integração que usa IP fixo na outra ponta precisam de ação manual.
- Não resolve conflito de nome. Usuário cPanel, nome de banco ou domínio que já exista no destino gera falha ou sobrescrita, dependendo das opções que você marcou.

Antes de abrir a primeira sessão, decida as opções da transferência olhando a tela (o conjunto varia conforme a versão do WHM e está descrito na documentação): sobrescrever contas existentes, pular a restauração da zona DNS, copiar privilégios de revendedor, transferir contas de revendedor junto com as contas filhas. Duas escolhas mudam o trabalho de conferência depois.

| Decisão na sessão | Quando faz sentido | Consequência na conferência |
|---|---|---||
| Copiar a zona DNS | Servidor novo será autoritativo com os mesmos registros | Precisa validar registro por registro, principalmente MX, SPF/DKIM e subdomínios apontando para IP antigo |
| Pular a restauração da zona DNS | Zona é gerenciada em DNS externo (Cloudflare, registrador, DNS do cliente) | Não espere arquivo de zona no destino; a ausência não é falha |
| Sobrescrever conta existente | Retransferência do mesmo cliente, segunda passada | Risco de perder alteração feita no destino depois da primeira passada |
| Transferir em lote grande | Muitas contas pequenas | Fila longa, relatório longo, mais chance de item isolado falhar sem você perceber |

Para o primeiro lote, mande poucas contas. Duas ou três. Leia o relatório inteiro, ajuste o que for ambiente e só depois mande o resto. Migrar trinta contas de uma vez e descobrir no fim que todas caíram no mesmo erro de versão de PHP custa duas vezes o tempo.

## Ler o relatório da fila sem pular linha

A sessão de transferência tem duas fases distintas, e o relatório reflete isso: a **transferência** (empacotar na origem e trazer para o destino) e a **restauração** (criar a conta, restaurar home, bancos, e-mail, zona). Um item pode transferir bem e falhar na restauração. A leitura útil é sempre por fase e por conta, com o log aberto, não pelo resumo colorido.

Na tela da sessão você tem o log da sessão inteira e o log de cada item. Abra os dois. O log da sessão diz onde a fila parou; o log do item diz o que aconteceu com aquela conta.

### Como separar falha real de aviso esperado no log

A regra prática: **se a mensagem descreve algo que não existirá no destino, é falha, mesmo que a linha esteja amarela.** Se descreve algo que você decidiu não trazer, é aviso.

| O que o log diz | Leitura | Ação |
|---|---|---||
| Conta restaurada, seguida de aviso sobre pacote (package) inexistente no destino | Aviso com efeito real: a conta pode ficar com limites diferentes | Criar o pacote equivalente e reaplicar na conta |
| Aviso de que a zona DNS não foi restaurada, com "skip DNS" marcado | Aviso esperado | Nenhuma, se o DNS é externo |
| Aviso de zona DNS não criada sem "skip DNS" marcado | Falha | Recriar a zona antes do apontamento |
| Conta de e-mail criada sem senha, ou falha ao restaurar credenciais | Falha silenciosa: cliente não autentica | Restaurar `shadow` do arquivo ou redefinir senha e avisar o cliente |
| Erro de importação de banco, tabela ou statement | Falha | Reimportar o dump inteiro, não a tabela |
| Domínio criado como subdomínio em vez de domínio adicional | Falha estrutural | Remover e recriar como addon domain |
| Aviso sobre versão de PHP, módulo ou extensão ausente | Aviso com efeito real | Ajustar ambiente e testar a aplicação |
| Aviso sobre certificado SSL não instalado | Aviso esperado antes do DNS | Emitir depois que o domínio apontar |

Certificado é o caso mais comum de falso alarme: AutoSSL não valida domínio que ainda aponta para o servidor antigo. Isso não é problema de migração, é ordem de operação.

## Os quatro erros que se disfarçam de aviso

### Zona DNS não criada, e o site que só cai na troca de nameserver

Acontece quando o domínio já existe em outra conta do destino, quando a zona chegou corrompida ou quando a criação foi interrompida. O sintoma clássico é o site funcionar via IP (ou via `hosts` local) e parar de funcionar no minuto em que você troca os nameservers, porque o servidor novo é consultado e não tem zona para responder.

Confira a existência do arquivo de zona no destino antes de qualquer apontamento:

```
ls -l /var/named/exemplo.com.br.db
grep -E "MX|TXT|^exemplo" /var/named/exemplo.com.br.db
```

Se usa DNS externo, o equivalente é abrir o painel de DNS e comparar os registros com a zona antiga. O ponto é o mesmo: alguém precisa responder pelo domínio depois da troca.

### Caixa de e-mail criada sem o hash de senha no shadow

As credenciais das caixas ficam em `/home/usuario/etc/dominio/shadow`, e a lista de caixas em `/home/usuario/etc/dominio/passwd`. Quando a restauração cria as caixas mas não traz os hashes, o cliente vê a pasta certa no webmail e recebe erro de autenticação no Outlook e no celular.

```
wc -l /home/usuario/etc/exemplo.com.br/passwd
cut -d: -f1,2 /home/usuario/etc/exemplo.com.br/shadow | head
```

Se o campo de senha vier vazio para alguma conta, resolva antes do DNS: restaure de novo aquela conta ou defina senha nova e comunique. Descobrir isso com o MX já apontado significa cliente sem e-mail durante o diagnóstico.

### Banco truncado, o erro que abre o site e esconde linhas

O erro mais caro, porque o site abre. Dump interrompido por timeout, tabela grande que estourou limite, `max_allowed_packet` menor no destino: o WordPress sobe, o tema funciona, e faltam pedidos, comentários ou linhas de log.

Não confie em tamanho de banco. Conte linhas nas tabelas que importam, nos dois servidores, e compare:

```
# no servidor antigo e no novo, como root
mysql usuario_wp -e "SELECT COUNT(*) FROM wp_posts; SELECT COUNT(*) FROM wp_postmeta;"
mysql usuario_wp -e "SELECT COUNT(*) FROM wp_users; SELECT COUNT(*) FROM wp_options;"
```

Em loja, conte também as tabelas de pedidos do WooCommerce. Divergência em `wp_options` e `wp_users` é sinal grave; divergência pequena em tabelas de cache, transients ou sessão é esperada, porque o site antigo continua vivo e escrevendo. Documente essa diferença na hora de comparar.

Se faltar linha em tabela de conteúdo, reimporte o banco inteiro a partir de um dump novo. Remendar tabela por tabela deixa inconsistência de chave.

### Addon domain que virou subdomínio

No cPanel, todo domínio adicional tem um subdomínio associado, e é exatamente por isso que uma restauração parcial às vezes cria só a metade subdomínio. O cliente reclama que "o outro site do meu plano não abre".

A fonte da verdade é o arquivo de dados do usuário:

```
grep -A 10 -E "addon_domains|sub_domains" /var/cpanel/userdata/usuario/main
```

Compare com o mesmo arquivo na origem. Se um domínio aparece só em `sub_domains` na origem e no destino, tudo certo. Se na origem estava em `addon_domains` e no destino não, remova o subdomínio órfão no cPanel da conta e recrie como domínio adicional, apontando para o mesmo document root. Corrigir na mão depois, com o DNS já apontado, gera minutos de site fora.

## Refazer só o item que falhou, sem retransferir a conta inteira

Retransferir a conta inteira porque uma caixa de e-mail ficou sem senha é desperdício, e ainda arrisca sobrescrever ajuste que você já fez no destino. A ordem que economiza tempo:

- **Item isolado, causa conhecida e local.** Corrija no destino: crie o pacote, recrie a zona, defina a senha da caixa, recrie o addon domain, reimporte o banco. Registre a correção no checklist da conta.
- **Item isolado, causa desconhecida.** Abra nova sessão do Transfer Tool só com aquela conta, com sobrescrita habilitada. Uma conta na fila significa um log curto e legível.
- **Mesmo erro em várias contas.** Não retransfira nada ainda. É ambiente: versão de PHP, extensão ausente, limite de banco, espaço em disco. Corrija o servidor e só então repita o lote.
- **Conta grande que sempre falha no home.** Traga o site com `rsync` direto entre servidores e use a fila apenas para conta, e-mail e banco. Site com muitos arquivos pequenos é o caso típico.

Antes de qualquer retentativa, confirme espaço em disco e inode no destino. Fila que falha em massa no meio do lote quase sempre é disco cheio, e o log vai mostrar erro de escrita, não erro de migração.

## As sete conferências por conta antes de tocar no DNS

Este é o artefato reutilizável. Uma linha por conta em planilha, as mesmas colunas em todo lote, e nenhum DNS tocado até a última coluna estar marcada. Teste sempre pelo IP do servidor novo (arquivo `hosts` local ou URL de pré-visualização), nunca pelo domínio ainda apontado para o servidor antigo, porque nesse caso você está testando o site velho.

Os dois comandos das primeiras linhas, para copiar e rodar nos dois servidores:

```
# 1. estrutura de domínios da conta
grep -A 10 -E "addon_domains|sub_domains" /var/cpanel/userdata/usuario/main

# 2. contagem de arquivos do home
find /home/usuario -type f | wc -l
```

| # | Conferência | Como validar | Critério |
|---|---|---|---||
| 1 | Conta e domínios | Comparar `addon_domains` e `sub_domains` em `/var/cpanel/userdata/usuario/main` nos dois servidores (comando 1 acima) | Mesma estrutura da origem |
| 2 | Home completo | Contar arquivos do home com `find` nos dois servidores (comando 2 acima) | Diferença explicável (cache, log) |
| 3 | Banco | `SELECT COUNT(*)` nas tabelas de conteúdo nos dois | Igual nas tabelas de conteúdo |
| 4 | E-mail | `passwd` e `shadow` em `/home/usuario/etc/dominio/` | Toda caixa da origem existe e tem hash |
| 5 | Zona ou DNS externo | `ls /var/named/dominio.db` ou painel externo | MX, SPF, DKIM e subdomínios conferidos |
| 6 | Cron e ambiente | cPanel » Cron Jobs e versão de PHP por domínio | Mesmas tarefas, mesma versão, extensões presentes |
| 7 | Teste funcional por IP | Login no admin, formulário de contato, checkout, envio SMTP autenticado | Fluxo crítico do cliente funcionando |

O item 7 é o único que pega erro de aplicação, não de migração. Faça login no WordPress, envie um formulário, adicione um produto ao carrinho, mande um e-mail autenticado pela caixa do cliente. Cinco minutos por conta.

### Padronizar o checklist quando o lote tem dezenas de contas

- Uma planilha por migração, uma linha por conta, sete colunas mais uma de observação. Preenchida enquanto você lê o log, não depois de memória.
- Antes de abrir a fila, gere o inventário da origem: lista de contas, domínios, bancos e caixas de e-mail. Sem inventário você não tem como saber que faltou uma conta, e o relatório só mostra o que ele tentou trazer.
- Guarde o log da sessão junto da planilha. Quando um cliente reclamar de algo três semanas depois, você distingue o que veio quebrado do que ele mudou.
- Congele alterações no servidor antigo durante a janela, principalmente e-mail e formulário que grava no banco. Se não for possível, migre e-mail por último e avise sobre a janela em que mensagem pode cair em dois lugares.

## A ordem de trocar o DNS, do TTL ao SSL

Com as sete conferências fechadas:

- Reduza o TTL dos registros com antecedência maior que o TTL vigente, ainda no DNS antigo: se está em 86400 (24 horas), reduza no dia anterior à troca. Baixar o TTL no mesmo minuto da migração não ajuda, porque o cache já distribuído continua valendo pelo tempo antigo.
- Deixe o servidor antigo ligado e a conta ativa depois do apontamento. Não suspenda, não cancele. Durante a propagação, parte dos visitantes e dos e-mails ainda chega lá.
- Troque o apontamento (nameserver no registrador ou registro A e MX no DNS externo).
- Valide a resposta dos dois lados antes de dizer que terminou:

```
dig +short exemplo.com.br A
dig +short exemplo.com.br MX
dig +short @ns1.seuservidor.com.br exemplo.com.br A
```

- Só depois emita o SSL. Com o domínio já resolvendo para o IP novo, o AutoSSL valida.
- Verifique se sobrou e-mail na caixa do servidor antigo nas 48 horas seguintes, e só então desligue a conta antiga. Manter o home antigo alguns dias custa pouco e vale como plano de retorno.

### A frase que você manda para o cliente

"O site e os e-mails já estão copiados e testados no servidor novo, acessando por IP. O que falta é trocar o endereço do domínio, e essa troca leva algumas horas para valer em toda a internet. Nesse intervalo, uma parte dos visitantes ainda vai ver o servidor antigo e algumas mensagens podem chegar na caixa antiga, por isso vamos manter o servidor antigo ligado por mais alguns dias. Nada se perde. Evite apenas publicar posts ou alterar produtos entre [hora de início] e [hora de fim]."

Funcional porque explica o efeito (dois lugares por algumas horas), o motivo (cache de DNS) e a única coisa que você precisa do cliente (não escrever durante a janela).

## Onde este procedimento ainda falha

Honestidade sobre os limites, porque saber onde a receita não cobre vale mais que confiar demais nela:

- **Contagem de arquivos nunca fecha exata.** Site vivo escreve cache e log. O critério é "diferença explicável", e isso depende de você conhecer a aplicação. Em site com upload constante, migre o home em duas passadas, a segunda com `rsync` na janela final.
- **Diferença de tabelas de cache e sessão no banco é normal.** Divergência em tabela de conteúdo não é. Se não souber classificar a tabela, trate como conteúdo.
- **Integração externa com IP na lista de permissões quebra depois do DNS.** Gateway de pagamento, API de ERP, relay de SMTP. Levante isso no inventário, não no relatório da fila, porque o Transfer Tool não tem como saber.
- **Plugin com licença atrelada a domínio ou servidor** pode desativar. Confira no item 7 do checklist, no teste funcional.
- **Nada aqui é medição de laboratório.** O comportamento da ferramenta e as opções da sessão vêm da [documentação do Transfer Tool](https://docs.cpanel.net/whm/transfers/transfer-tool/98/); os comandos de conferência são para você rodar no seu par de servidores e comparar resultados. O que aparece na sua fila depende da versão do WHM, do estado da origem e das opções marcadas.

O ganho real do checklist não é técnico, é comercial: migração conferida antes do DNS transforma um problema descoberto pelo cliente em um item corrigido antes de existir. Em revenda, com dezenas de contas para trazer, essa diferença é o que separa um fim de semana de trabalho de um mês de suporte.

