blog
Painéis

Migrar para cPanel na mão: as 8 etapas na ordem certa

Plesk antigo, DirectAdmin, painel proprietário ou stack sem painel: nada disso é exportável pelo Transfer Tool. O roteiro documental para reconstruir a conta peça por peça, com verificação e rota de volta.

JR · · 16 min de leitura · 3 tabelas · 17 blocos de código

Resposta curta: são oito etapas, e a ordem importa mais que as ferramentas: inventário, criar a conta com o mesmo usuário e document root, rsync, permissões, banco, e-mail, validação no IP novo com curl --resolve e, por último, o DNS.

Neste artigo
  1. O que o Transfer Tool cobre e onde ele para
  2. O inventário que define se a conta pode ser criada idêntica
  3. Crie a conta antes de copiar arquivo, com o mesmo usuário e document root
  4. Copiar arquivos com rsync sem perder hard links, ACL e dono
  5. Dump com mysqldump e o que ele não leva por padrão
  6. Por que copiar o Maildir cru faz o cliente IMAP baixar tudo de novo
  7. Validar site e e-mail no IP novo com o DNS ainda na origem
  8. DNS registro a registro, roteamento de e-mail e reversão

O que o Transfer Tool cobre e onde ele para

A ferramenta de transferência do WHM fala com outro servidor cPanel (ou com um backup gerado por ele). Quando a origem é Plesk antigo, DirectAdmin, painel proprietário de hospedagem ou uma stack sem painel nenhum, não existe pacote para ela ler: não há cpmove, não há dump de metadados, não há mapa de contas. A própria documentação do cPanel trata esse caso como migração manual e descreve a reconstrução da conta peça por peça, arquivos, bancos, e-mail e DNS, em How to Manually Migrate Accounts to cPanel From Unsupported Control Panels.

O que muda na prática é a ordem. Migração manual mal ordenada não falha: ela custa retrabalho. Copiar 40 GB de public_html para um diretório provisório e depois descobrir que o usuário da conta ficou diferente significa refazer dono, refazer permissões e caçar caminho absoluto em arquivo de configuração. Por isso a sequência abaixo é fechada nesta ordem:

  1. Inventário da origem.
  2. Criar a conta no WHM com o mesmo usuário e o mesmo conjunto de domínios.
  3. Copiar arquivos com rsync.
  4. Corrigir dono e permissões.
  5. Migrar bancos de dados.
  6. Recriar e sincronizar caixas de e-mail.
  7. Validar site e e-mail no IP novo, com o DNS ainda apontando para a origem.
  8. Cortar o DNS e ajustar o roteamento de e-mail.

Este artigo é documental. Não há medição própria aqui: os números que aparecem em comandos são exemplos identificados como tais, e os parâmetros são os das ferramentas citadas e da documentação do cPanel. Confira as flags na versão que você tem instalada antes de rodar em produção.

Ordem das etapas na migração manual para cPanelInventário da origemUsuário, document root, PHP, bancosCriar conta no WHMMesmo usuário e mesmos domíniosCopiar arquivos e bancosrsync, chown, mysqldump, importRecriar e sincronizar e-mailContas pelo cPanel, depois imapsyncValidar e cortar DNScurl --resolve antes, roteamento depois
Ordem fechada da migração manual. Inverter etapas não quebra o site, gera retrabalho de dono, permissão e caminho absoluto.

O inventário que define se a conta pode ser criada idêntica

O inventário é o que define se a conta pode ser criada idêntica ou se você vai ter que reescrever caminho em configuração. Levante isso na origem antes de abrir o WHM.

Item na origem Onde olhar Para onde vai no cPanel
Usuário do sistema dono dos arquivos stat -c '%U:%G' /caminho/do/site Nome de usuário da conta
Document root real vhost do Apache/Nginx, ou php -i do site /home/usuario/public_html
Domínios e subdomínios servidos vhosts, painel de origem Domínio principal, addons, subdomínios
Versão do PHP e handler php -v, vhost, phpinfo() MultiPHP Manager e MultiPHP INI Editor
Extensões PHP usadas php -m EasyApache 4
Bancos, usuários e grants SHOW DATABASES, SHOW GRANTS MySQL/MariaDB da conta, com prefixo usuario_
Versão e engine do banco SELECT VERSION(), SHOW TABLE STATUS Define estratégia de dump e collation
Caixas de e-mail, senhas e quotas painel de origem, /etc/passwd do MTA Contas de e-mail do cPanel
Encaminhamentos, autoresponders, filtros painel de origem Forwarders, autoresponders, filtros do cPanel
Registros DNS publicados hoje dig na zona atual, painel de DNS Zone Editor, registro a registro
Cron jobs do usuário crontab -l -u usuario Cron Jobs do cPanel
Certificados TLS e chaves privadas /etc/ssl, painel de origem SSL/TLS, ou AutoSSL depois do corte
TTL atual dos registros dig +noall +answer dominio.com.br Reduzir antes do corte

Dois pontos do inventário decidem o resto. O primeiro é o nome de usuário: o WHM tem regras de comprimento e de caracteres, e não aceita nome começando com dígito. Se o nome da origem não couber, o home vai mudar e todo caminho absoluto gravado em wp-config.php, .env, settings.php, configuration.php, cron e open_basedir precisa ser reescrito. Descobrir isso depois de copiar é o retrabalho clássico.

O segundo é o servidor web da origem. Se o site vinha de Nginx puro, não existe .htaccess para copiar: as regras de rewrite estão no vhost e precisam ser traduzidas para .htaccess (ou para a configuração do proxy, se você usa Nginx na frente do Apache no cPanel). Nenhum rsync faz isso por você.

Crie a conta antes de copiar arquivo, com o mesmo usuário e document root

Crie a conta no WHM antes de copiar qualquer arquivo. O WHM cria o home com o esqueleto correto, o usuário do sistema, o grupo, o vhost, a entrada em /etc/localdomains, o banco de zona e as permissões base. Copiar por cima de uma estrutura já criada é barato. Criar a estrutura por cima de arquivos copiados com dono errado é caro.

Pelo WHM, é Account Functions, Create a New Account. Pela linha de comando, como root:

# exemplo: ajuste usuário, domínio, plano e e-mail de contato
whmapi1 createacct \
  username=exemplo \
  domain=exemplo.com.br \
  plan=revenda_basico \
  [email protected] \
  useregns=0

Confira o que foi criado antes de seguir:

getent passwd exemplo
ls -ld /home/exemplo /home/exemplo/public_html
grep -w exemplo.com.br /etc/userdomains /etc/localdomains

Resultado esperado: usuário existe, home é /home/exemplo (pode ser /home2 e afins em servidores com múltiplos pontos de montagem, confira), public_html existe e o domínio aparece nos dois arquivos de mapeamento. Se o domínio está em /etc/remotedomains e não em /etc/localdomains, o e-mail local vai sair pela internet em vez de cair na caixa do servidor. Isso se resolve no passo do DNS, mais adiante.

Depois da conta, crie os addon domains e subdomínios com o mesmo document root relativo da origem. Se na origem o addon servia de httpdocs/loja, aponte o addon para o caminho equivalente dentro de /home/exemplo. Cada addon criado com document root diferente do original é um conjunto de caminhos quebrados para consertar depois.

Por fim, ajuste a versão do PHP no MultiPHP Manager e confira as extensões com php -m na versão selecionada. Site que sobe com PHP errado gera erro 500 que você vai confundir com problema de permissão.

Com a conta pronta, copie. Rodando como root no destino, puxando da origem por SSH:

rsync -aHAX --numeric-ids --delete-after \
  -e 'ssh -p 22' \
  root@origem:/var/www/vhosts/exemplo.com.br/httpdocs/ \
  /home/exemplo/public_html/

O que cada flag faz e por que está aí:

A barra final no caminho de origem importa: com barra, o conteúdo do diretório vai para dentro do destino; sem barra, o diretório inteiro vira um subdiretório. Errar isso cria /home/exemplo/public_html/httpdocs.

Conferir a cópia por checksum com rsync em dry run

O rsync decide o que copiar por tamanho e mtime. Para conferir de verdade depois da cópia, rode um passe em modo simulação com comparação de conteúdo:

rsync -aHAXn --checksum --itemize-changes \
  root@origem:/var/www/vhosts/exemplo.com.br/httpdocs/ \
  /home/exemplo/public_html/

O -n é dry run, o --checksum força o cálculo de checksum dos dois lados em vez do teste rápido, e o --itemize-changes lista cada diferença com o motivo. Saída vazia (fora as linhas de sumário) é o resultado esperado. Esse passe lê todos os bytes dos dois lados: em site grande ele demora, e é justamente por isso que ele é a verificação e não o método de cópia.

Ajustar dono e permissões sem quebrar o diretório mail

Depois da cópia, todo o conteúdo está com UID numérico da origem. Corrija:

# o chown recursivo vai só no que foi copiado; mail, etc e .cpanel ficam como o WHM criou
chown -R exemplo:exemplo /home/exemplo/public_html

# guarda quem já era executável na origem, para devolver o u+x depois
find /home/exemplo/public_html -type f -perm -u+x > /root/exec-exemplo.txt

find /home/exemplo/public_html -name cgi-bin -prune -o -type d -exec chmod 755 {} +
find /home/exemplo/public_html -name cgi-bin -prune -o -type f -exec chmod 644 {} +

# CGI e demais executáveis voltam ao bit de execução
find /home/exemplo/public_html -type d -name cgi-bin -exec chmod -R 755 {} +
xargs -r -d '\n' chmod u+x < /root/exec-exemplo.txt

# dono e grupo do document root conforme a convenção do painel
# (confira na conta descartável: com Apache padrão costuma ser exemplo:nobody, modo 750)
chown exemplo:nobody /home/exemplo/public_html
chmod 750 /home/exemplo/public_html

Três ressalvas que separam quem já fez isso de quem vai aprender agora:

# leia as opções da sua versão antes de rodar
/scripts/mailperm --help || head -40 /scripts/mailperm

# uso confirmado: sem argumento, como root
/scripts/mailperm

Encontrar os caminhos absolutos herdados da origem

Procure na árvore copiada qualquer referência ao caminho antigo:

grep -rIl --exclude-dir=node_modules '/var/www/vhosts' /home/exemplo/public_html
grep -rIl --exclude-dir=node_modules '/home/usuarioantigo' /home/exemplo/public_html

O -I ignora binários, o -l lista só o nome do arquivo. Revise arquivo por arquivo antes de sair substituindo com sed: caminho antigo também aparece em log e em cache serializado, onde a substituição cega quebra o tamanho declarado da string.

Dump com mysqldump e o que ele não leva por padrão

Na origem, com o site ainda no ar:

mysqldump \
  --single-transaction \
  --routines \
  --triggers \
  --hex-blob \
  --default-character-set=utf8mb4 \
  banco_antigo > /tmp/banco_antigo.sql

Em MySQL 8, o mysqldump pede privilégio de PROCESS para ler tablespaces; se o usuário do dump não tiver, acrescente --no-tablespaces.

Criar banco e usuário pela conta cPanel, com o prefixo obrigatório

Crie o banco e o usuário pela conta, não como root solto, para que o mapeamento com a conta cPanel exista. Pelo cPanel é MySQL Databases; pela CLI, o painel expõe a API do usuário e a ferramenta de mapeamento /usr/local/cpanel/bin/dbmaptool. Confira os parâmetros na documentação da sua versão antes de usar. O ponto que importa: o cPanel normalmente exige o prefixo usuario_ no nome do banco e do usuário. Isto é, loja vira exemplo_loja, e o arquivo de configuração da aplicação precisa ser atualizado.

Importe no banco de destino, com o charset explícito. O nome aqui é exemplo_loja, o banco criado pela conta cPanel, e não banco_antigo:

mysql --default-character-set=utf8mb4 exemplo_loja < /tmp/banco_antigo.sql

Os três erros de collation que travam a importação

Origem MySQL 8, destino MariaDB. O dump traz utf8mb4_0900_ai_ci, que o MariaDB não conhece, e a importação morre em Unknown collation. Ajuste o dump antes de importar e confirme a collation padrão do servidor de destino com SHOW VARIABLES LIKE 'collation_server'.

sed -i 's/utf8mb4_0900_ai_ci/utf8mb4_unicode_ci/g' /tmp/banco_antigo.sql

Texto UTF-8 guardado em coluna latin1. Caso clássico de aplicação PHP antiga: os bytes são UTF-8, mas a coluna diz latin1, e o dump com --default-character-set=utf8mb4 converte os bytes de novo, produzindo ç no lugar de ç. O sintoma aparece depois da importação, não durante. Antes de decidir, olhe SHOW CREATE TABLE na origem e um SELECT HEX(coluna) de uma linha com acento. Se for esse cenário, o caminho é dumpar com --default-character-set=latin1, trocar as declarações de charset dentro do arquivo e importar como utf8mb4.

DEFINER de usuário inexistente. Views, triggers e procedures carregam DEFINER=usuario@localhost. Se esse usuário não existe no destino, a importação falha. Remover a cláusula exige cuidado, porque ela aparece em contextos diferentes; revise o resultado antes de importar:

grep -n 'DEFINER=' /tmp/banco_antigo.sql | head

Depois da importação, confira o que costuma sumir: SHOW PROCEDURE STATUS WHERE Db='exemplo_loja';, SHOW TRIGGERS; e a contagem de linhas das tabelas maiores contra a origem.

Por que copiar o Maildir cru faz o cliente IMAP baixar tudo de novo

A tentação é copiar /var/qmail/mailnames ou o equivalente da origem direto para /home/exemplo/mail. Não faça.

O layout do cPanel é Maildir por domínio: /home/exemplo/mail/exemplo.com.br/caixa/ com cur, new e tmp. A caixa do usuário padrão fica direto em /home/exemplo/mail. Mas a estrutura em disco é só metade da história. O Dovecot mantém dovecot-uidlist, dovecot.index* e maildirsize por pasta, e esses arquivos definem UIDVALIDITY e os UIDs que o cliente IMAP usa para saber o que já baixou. Diretório cru copiado de outro servidor chega sem eles (ou com os da origem, que não batem): o Dovecot regenera tudo, o cliente vê UIDVALIDITY nova, descarta o cache local e ressincroniza a caixa inteira. Em caixa de vários gigabytes, isso significa o usuário reclamando que o Outlook está baixando tudo de novo. E se a origem não guardava as flags no nome do arquivo Maildir (mbox com header Status, ou índice proprietário), o estado de lida se perde de verdade.

O caminho previsível é outro:

Recriar as caixas pelo cPanel para gerar a estrutura certa

Crie cada conta de e-mail pelo cPanel (Email Accounts) com o mesmo endereço e a mesma quota. Isso gera a estrutura Maildir correta, a entrada em /home/exemplo/etc/exemplo.com.br/ e a senha no formato que o Dovecot do servidor espera. Recrie também encaminhamentos, autoresponders e filtros, que não vivem no Maildir.

Sincronizar o conteúdo das caixas com imapsync

Com as duas pontas no ar, rode o imapsync em modo simulação primeiro:

imapsync --dry --automap \
  --host1 mail.origem.com.br --ssl1 \
  --user1 [email protected] --password1 'SENHA_ORIGEM' \
  --host2 203.0.113.10 --ssl2 \
  --user2 [email protected] --password2 'SENHA_NOVA'

O IP 203.0.113.10 é exemplo (faixa reservada para documentação). Apontar --host2 para o IP novo, e não para o nome do domínio, é o que permite sincronizar antes do corte de DNS. Com --ssl2 contra o IP, o certificado não vai bater com o nome: use o hostname do servidor em --host2 se quiser validação de certificado limpa.

O --automap mapeia as pastas especiais entre servidores com nomenclaturas diferentes (INBOX.Sent contra Sent, Lixeira contra Trash). Confira o mapa impresso pelo dry run antes de rodar de verdade: se a origem usa nomes em português e o destino em inglês, é aqui que você descobre.

Depois do dry run, remova o --dry e rode. O imapsync é incremental: rode uma vez com calma dias antes, e de novo no dia do corte para pegar o delta. A segunda passada só transfere o que chegou no meio, e preserva flags e estrutura porque fala IMAP dos dois lados.

Conferir as quotas antes de sincronizar, para não parar em OVERQUOTA

Caixa de destino com quota menor que a origem faz a sincronização parar no meio com erro de OVERQUOTA. Compare antes.

Validar site e e-mail no IP novo com o DNS ainda na origem

Este é o passo que separa migração de aposta. Tudo abaixo roda com o DNS ainda apontando para a origem, e o site de produção intacto.

Testar HTTP e HTTPS com curl --resolve

curl -sS -o /dev/null \
  -w 'http_code=%{http_code} ttfb=%{time_starttransfer}s size=%{size_download}\n' \
  --resolve exemplo.com.br:80:203.0.113.10 \
  http://exemplo.com.br/

O --resolve injeta a resolução na tabela interna do curl: o Host enviado é o domínio real, o TCP vai para o IP que você mandou. É o teste correto para vhost baseado em nome. Teste também www.exemplo.com.br, as páginas que dependem do banco, uma URL com querystring e uma que exercite regra de rewrite.

Para HTTPS antes do corte tem um detalhe: o AutoSSL do cPanel valida o domínio por HTTP, o que só funciona depois que o domínio resolve para o servidor novo (ou com validação por DNS). Antes do corte, a porta 443 vai responder com o certificado do hostname do servidor, então use -k para ignorar a validação e testar apenas se a aplicação responde:

curl -sSk -o /dev/null -w '%{http_code}\n' \
  --resolve exemplo.com.br:443:203.0.113.10 \
  https://exemplo.com.br/

Certificado válido é tarefa do pós-corte: assim que o DNS propagar, rode o AutoSSL para o usuário ou instale o certificado que você exportou da origem junto com a chave privada.

Testar IMAP autenticado no IP novo com openssl s_client

openssl s_client -crlf -connect 203.0.113.10:993
# depois do handshake:
a1 LOGIN [email protected] SENHA
a2 SELECT INBOX
a3 LOGOUT

O SELECT INBOX devolve EXISTS com a contagem de mensagens: compare com o que o imapsync reportou. Se o login falhar, o problema é senha ou o domínio ainda não estar reconhecido como local.

Testar SMTP autenticado na porta 587

openssl s_client -crlf -starttls smtp -connect 203.0.113.10:587
EHLO teste.exemplo.com.br
AUTH PLAIN <base64>

O blob do AUTH PLAIN é authzid\0authcid\0senha, com o authzid vazio:

printf '\[email protected]\0SENHA' | base64

Resposta esperada: 235 de autenticação aceita. Depois disso, envie uma mensagem de teste para um endereço externo seu e confirme a chegada, com o cabeçalho mostrando o IP novo. Se der 535, o problema é credencial. Se der timeout na 587, é firewall ou o serviço não está escutando.

DNS registro a registro, roteamento de e-mail e reversão

Por que não importar o arquivo de zona da origem

O arquivo de zona do painel antigo carrega SOA, NS, TTLs e registros glue daquele ambiente. Importado inteiro no cPanel, ele sobrescreve os NS corretos, traz IPs antigos em registros que você nem lembrava que existiam e mantém um serial que atrapalha a próxima alteração. O cPanel escreve a zona com o template dele quando a conta é criada. O trabalho é traduzir, registro a registro:

Registro O que fazer na zona nova
A do domínio e de www Apontar para o IP do servidor novo
AAAA Só se o servidor novo tem IPv6 e o serviço escuta nele
MX Manter o destino atual até você decidir mover o e-mail
TXT de SPF Reescrever incluindo o IP ou o host do servidor novo
DKIM O cPanel gera par de chaves próprio; publique o seletor novo ou importe a chave antiga
DMARC Copiar como está, revisar a política depois da estabilização
CNAME de terceiros (verificações, CDN, webmail) Copiar um a um; são os que mais somem
SRV (autodiscover, VoIP, XMPP) Copiar, conferindo porta e prioridade
CAA Ajustar para a autoridade que vai emitir o certificado novo
Registros de subdomínio que apontam para outro servidor Não mover para o IP novo por descuido

Antes do corte, reduza o TTL dos registros que vão mudar. Um valor baixo como 300 segundos (exemplo) precisa ser publicado com antecedência maior que o TTL antigo, senão os resolvers ainda estão com o valor anterior em cache no momento em que você corta.

Onde o domínio deve estar enquanto o MX aponta para o provedor antigo

O erro mais comum do dia seguinte: o site já responde no servidor novo, o MX ainda aponta para o provedor antigo, e mensagens enviadas de um endereço da conta para outro endereço do mesmo domínio somem. O Exim entrega localmente porque o domínio está em /etc/localdomains, a caixa local está vazia, e o usuário jura que o e-mail se perdeu.

A configuração está em WHM, Email Routing Configuration, e o efeito prático é em qual arquivo o domínio aparece:

Enquanto o MX apontar para o provedor antigo e você já estiver com o site no servidor novo, o domínio deve estar em remotedomains. Quando o MX passar a apontar para o servidor novo, ele volta para localdomains. Confira sempre com grep -w exemplo.com.br /etc/localdomains /etc/remotedomains depois de mexer, e teste o envio de uma caixa do domínio para outra.

Erros comuns e o sintoma que cada um produz

Sintoma Causa provável Correção
Erro 500 logo depois da cópia PHP em versão diferente da origem, ou extensão faltando MultiPHP Manager; conferir php -m
include falhando com caminho estranho Conta criada com usuário diferente, caminho absoluto herdado Recriar com o mesmo usuário ou reescrever configs
Site abre, painel administrativo não .htaccess ausente (origem era Nginx) Traduzir rewrites do vhost antigo
Função do sistema quebrada, tabelas ok Dump sem --routines Redumpar só as rotinas e importar
Unknown collation na importação MySQL 8 para MariaDB Substituir a collation no arquivo
Acentuação dupla depois de importar UTF-8 guardado em coluna latin1 Redumpar com --default-character-set=latin1
Cliente IMAP baixa a caixa inteira de novo Maildir copiado cru, UIDVALIDITY nova Refazer por imapsync
Permissão de e-mail quebrada após chmod -R find aplicado no home inteiro /scripts/mailperm
E-mail interno do domínio some Domínio no arquivo de roteamento errado Ajustar Email Routing
Webmail e site ok, certificado inválido AutoSSL ainda não rodou após o corte Executar AutoSSL para o usuário

Como reverter se o corte der errado

Não desligue a origem no dia do corte. A reversão só é barata enquanto ela existir e estiver íntegra.

  1. Mantenha os serviços da origem no ar por, no mínimo, o tempo que você levar para confirmar tráfego real e e-mail no servidor novo.
  2. Se precisar voltar, reponha os registros DNS antigos. Como o TTL está reduzido, a volta é rápida. Não suba o TTL de novo antes de ter certeza de que não vai cortar outra vez.
  3. Dados gravados no servidor novo durante a janela não voltam sozinhos. Banco: dump do novo e importação na origem. E-mail: imapsync no sentido inverso, com --host1 no servidor novo. Arquivos enviados por usuários (uploads): rsync do novo para a origem, restrito aos diretórios de upload.
  4. Só remova a conta da origem depois de um ciclo completo de uso, incluindo o fechamento de mês da aplicação, se houver rotina mensal.

Uma última recomendação contra o costume: se a origem é um cPanel e você chegou aqui por hábito, pare e use o Transfer Tool. O roteiro manual existe para painel que a ferramenta não lê. Fazer na mão o que a ferramenta faz melhor só adiciona superfície de erro.

Onde o domínio deve estar durante o corteSite já no servidor novoMX ainda no provedor antigoDomínio em remotedomainsExim consulta o MX e entrega foraMX passa para o servidor novoAlteração publicada na zonaDomínio volta para localdomainsExim entrega na caixa localConferir com grep nos dois arquivosTestar envio entre caixas do domínio
Roteamento de e-mail durante a janela. Domínio no arquivo errado faz mensagem interna cair em caixa local vazia.

Referências

  1. Documentação oficial (cpanel) — How to Manually Migrate Accounts to cPanel From Unsupported Control Panels. Consultado em 2026-09-25.
Leia também