Backup remoto não apaga as cópias antigas e enche o destino
A transferência e a limpeza são etapas distintas da mesma execução. Quando só a segunda falha, o destino enche em silêncio até o backup inteiro parar.

Resposta curta: o log da execução, em /usr/local/cpanel/logs/cpbackup/, é o único lugar que separa a fase de envio da fase de limpeza. A execução pode terminar marcada como bem-sucedida quando apenas a limpeza falha, porque o arquivo do dia chegou ao destino.
Neste artigo
- O destino lotado enquanto o painel mostra tudo verde
- Qual linha do log mostra se a fase de limpeza rodou
- Erro de permissão e erro de conexão pedem consertos opostos
- Apagar as cópias vencidas sem perder a única que ainda serve
- Três evidências de que a retenção voltou a apagar
- O que monitorar para a falha não voltar a passar despercebida
- Dez passos, do log ao alerta, na ordem em que valem a pena
O destino lotado enquanto o painel mostra tudo verde
A sequência costuma ser esta. O backup roda todas as noites, a interface do WHM mostra as execuções como concluídas, e um dia o envio para o destino remoto para de funcionar porque o provedor rejeita a escrita: quota estourada, pasta cheia, cota de API excedida. Quando alguém abre o destino, encontra meses de cópias que deveriam ter sido apagadas pela retenção.
O ponto que confunde é que a transferência e a limpeza são etapas diferentes da mesma execução. O backup pode enviar o arquivo novo com sucesso e falhar ao remover os antigos. Quando o erro ocorre só na fase de purge de um transporte, a execução ainda termina marcada como bem-sucedida, porque o arquivo do dia chegou ao destino. Quando o próprio upload falha, aí sim o status fica em erro e alguém olha. É o primeiro caso que passa despercebido. A retenção quebrada só aparece no log, e só na linha da fase de purge.
A documentação oficial do cPanel trata exatamente desse caso em How to Troubleshoot a Remote Transport Pruning Failure. Do KB vem o diagnóstico da falha de pruning: onde o log registra a fase de limpeza e como separar as causas. O teste manual por SFTP, o dry run com find, a validação do tarball com gzip -t e tar -tzf e as recomendações de monitoramento não estão no KB: são a organização da tarefa para quem precisa resolver hoje. Não há medição da Napoleon neste artigo.
Qual linha do log mostra se a fase de limpeza rodou
Os logs de backup do cPanel ficam em /usr/local/cpanel/logs/cpbackup/, um arquivo por execução, nomeado pelo carimbo de data e hora do início. O arquivo da execução é o único lugar que separa "enviei" de "apaguei".
Escopo de validade: o caminho dos logs, o layout de um arquivo de configuração por transporte em /var/cpanel/backups/ e o binário /usr/local/cpanel/bin/backup valem para o sistema de Backup (o que substituiu o Legacy Backup), presente desde o cPanel & WHM 11.38 e mantido nas branches atuais (11.110 e posteriores). Em servidor ainda com Legacy Backup habilitado, os caminhos e o binário são outros.
# última execução de backup
ls -lt /usr/local/cpanel/logs/cpbackup/ | head -n 5
# fase de transporte e de limpeza na última execução
LOG=$(ls -t /usr/local/cpanel/logs/cpbackup/*.log | head -n1)
grep -niE 'prune|prun|transport|remote|delete|remov' "$LOG" | head -n 40
Leia a sequência, não a linha isolada. Para cada destino remoto você deve encontrar, na ordem: validação do transporte, upload do arquivo do dia, e então a tentativa de remover as cópias fora da janela de retenção. Se a terceira etapa não aparece para um destino, ela não rodou. Se aparece com erro, a mensagem dela é o diagnóstico.
As definições dos destinos ficam em /var/cpanel/backups/, um arquivo por transporte, com o tipo (FTP, SFTP, Amazon S3, rsync, WebDAV, Google Drive), o caminho remoto e as credenciais ou referência ao token. Vale conferir qual destino o log está citando antes de mexer em qualquer coisa, principalmente em servidor com mais de um transporte configurado.
ls -l /var/cpanel/backups/
# cada transporte tem seu arquivo de configuração; confira tipo e caminho remoto
Erro de permissão e erro de conexão pedem consertos opostos
Essa é a bifurcação que decide o conserto. As duas famílias produzem a mesma consequência visível (o destino enche) e exigem ações opostas.
| Sinal no log da execução | Família provável | O que verificar primeiro |
|---|---|---|
| Negação de acesso ao apagar, upload funcionando | Permissão/escopo | Direito de exclusão na pasta remota; escopo do token |
| Falha de autenticação em todas as operações | Credencial | Senha, chave, token expirado ou revogado |
| Tempo esgotado na operação de remoção | Conexão | Latência, firewall de saída, limite de sessão do provedor |
| Nome do host não resolve | DNS | Resolver do servidor, registro do endpoint |
| Limite de requisições ou cota excedida | Provedor | Cota da API, espaço contratado no destino |
| Caminho remoto inexistente | Configuração | Pasta renomeada ou movida no destino |
O teste mais barato para separar as duas famílias é tentar, na mão, uma remoção no destino com as mesmas credenciais que o transporte usa. Se a conexão abre e o delete é negado, é permissão. Se a conexão nem abre, é rede, DNS ou credencial.
Testar na mão se o usuário remoto consegue apagar, não só enviar
Para um destino SFTP, com a mesma chave e o mesmo usuário do transporte (exemplo, troque host, usuário e caminho pelos seus):
# arquivo descartável para o teste
echo teste > /tmp/teste_purge.txt
# conexão e listagem
sftp -i /root/.ssh/id_backup [email protected] <<'EOF'
cd /backups/servidor01
ls -l
EOF
# direito de exclusão: cria e apaga um arquivo descartável
sftp -i /root/.ssh/id_backup [email protected] <<'EOF'
cd /backups/servidor01
put /tmp/teste_purge.txt
rm teste_purge.txt
EOF
Se o put passa e o rm é negado, você achou o problema: o usuário remoto tem escrita, mas não tem exclusão na pasta. Em muitos destinos isso acontece depois que alguém "endureceu" o acesso, ou quando a pasta passou a pertencer a outro usuário e o modo não dá permissão de escrita no diretório, que é o que governa remoção em sistemas de arquivos POSIX.
Para destinos baseados em token (serviços de nuvem com OAuth), o teste equivalente é olhar o escopo. Token emitido só com permissão de upload, ou revogado quando a senha da conta mudou, derruba a limpeza sem derrubar necessariamente o envio, se o envio usa outro caminho. Reautorizar o transporte no WHM, em Backup Configuration, costuma ser o conserto, e vale validar o destino pela própria interface antes de esperar a próxima janela.
Relógio, firewall, DNS e cota: as causas que ninguém olha
- Relógio do servidor fora de sincronia quebra assinatura de requisições em provedores de nuvem.
timedatectlresolve a dúvida em um comando. - Firewall de saída bloqueando a porta do destino após uma mudança de regra.
- Resolver DNS do servidor apontando para um recursor que não responde mais.
dig +short endpoint.do.provedorfecha a questão. - Espaço no destino: alguns provedores rejeitam até a operação de listagem quando a cota estourou, e o log mostra isso como erro genérico.
Apagar as cópias vencidas sem perder a única que ainda serve
Regra única: nunca apague antes de confirmar qual é a cópia íntegra mais recente. A tentação é mandar um delete por data e seguir a vida. O risco é apagar junto a única cópia que ainda serve, porque a mais nova pode ser justamente a que falhou pela metade quando o destino encheu.
Inventariar o destino e marcar as cópias que parecem completas
Liste por data e tamanho. Cópia truncada aparece como arquivo muito menor que os irmãos do mesmo perfil. Anote o nome exato das duas ou três mais recentes que parecem completas.
Validar o tarball com gzip -t e tar -tzf antes de apagar qualquer coisa
Baixe a mais recente e teste o arquivo antes de apagar qualquer coisa:
# teste de integridade do tarball sem extrair
gzip -t backup-5.13.2026_02-00-01_conta.tar.gz && echo gzip_ok
tar -tzf backup-5.13.2026_02-00-01_conta.tar.gz > /dev/null && echo tar_ok
O nome acima é exemplo. Se os dois testes passam, essa é sua âncora.
Fazer o dry run com find e revisar a lista antes de remover
Defina a janela pela política de retenção configurada no WHM e exclua dela a âncora validada. Faça uma passagem só listando, confira a lista com os olhos, e só então execute. Em destino montado localmente ou acessível por rsync, a listagem prévia é direta:
# lista o que SERIA apagado (não apaga nada)
find /mnt/destino/backups -maxdepth 1 -name '*.tar.gz' -mtime +30 -printf '%TY-%Tm-%Td %10s %p\n' | sort
Revise a saída. Confirme que a âncora não está nela. Só então repita trocando a listagem pela remoção. Em destinos acessados por SFTP ou API, o equivalente é gerar a lista, revisar, e alimentar o cliente com os nomes aprovados, um a um. É mais lento e é de propósito.
Liberar espaço para duas execuções completas, não para uma
Libere espaço suficiente para pelo menos duas execuções completas. Destino que volta a encher no dia seguinte não permite distinguir se a retenção voltou a funcionar ou se apenas não teve chance de rodar.
Três evidências de que a retenção voltou a apagar
Consertar sem provar é deixar o problema marcado para voltar. A prova tem três partes e é feita na execução seguinte.
Forçar uma execução fora da janela agendada
O cPanel permite disparar o backup fora da janela agendada:
/usr/local/cpanel/bin/backup --force
Rode em horário de baixa carga. A execução gera um novo arquivo em /usr/local/cpanel/logs/cpbackup/.
Reler a fase de purge no log da nova execução
LOG=$(ls -t /usr/local/cpanel/logs/cpbackup/*.log | head -n1)
grep -niE 'prune|prun|delete|remov|transport' "$LOG"
Você quer ver a etapa de remoção citada por destino, sem erro. Ausência de linha de erro não basta: a etapa precisa aparecer.
Contar os arquivos no destino, que é a prova que não depende de log
Conte os arquivos antes e depois no destino remoto. O número tem que cair para o que a política define. É a única evidência que não depende de interpretação de log.
# antes e depois, no destino acessível por rsync/SSH
ssh [email protected] 'ls -1 /backups/servidor01 | wc -l'
O que monitorar para a falha não voltar a passar despercebida
- Monitore ocupação do destino, não só a última execução. Um alerta em 80% de uso do espaço remoto dá margem para agir antes de o destino encher. Quanta margem depende do tamanho do destino e do volume diário gravado.
- Monitore a contagem de arquivos no destino. Se o número cresce todo dia e nunca cai, a limpeza não está rodando, independentemente do que o painel mostra.
- Trate token e credencial como item com validade. Registre quando foram emitidos e sob qual escopo. Token revogado por troca de senha da conta é causa comum e silenciosa.
- Separe pastas por servidor no destino. Permissão errada em uma pasta não derruba a retenção do resto, e o diagnóstico fica óbvio.
- Depois de qualquer mudança de permissão no destino, teste o
rm, não só oput. Escrita e exclusão são direitos distintos, e é a exclusão que a retenção usa.
Se o seu destino é um serviço com cota rígida, lembre que o backup precisa de espaço para o arquivo novo antes de a limpeza rodar. Dimensione o destino para a retenção mais uma cópia inteira, ou a primeira noite após encher será a noite em que nada entra e nada sai.
Dez passos, do log ao alerta, na ordem em que valem a pena
Os itens 1 a 4 são diagnóstico rápido e cabem em poucos minutos. Os itens 5 a 10 envolvem download, validação, remoção revisada e uma execução completa de backup: reserve a janela adequada.
- Abrir o log mais recente em
/usr/local/cpanel/logs/cpbackup/e procurar a fase de limpeza por destino. - Identificar o transporte citado em
/var/cpanel/backups/. - Testar conexão e exclusão na mão com as credenciais do transporte.
- Classificar: permissão/escopo, credencial, conexão/DNS, ou cota do provedor.
- Corrigir a causa (reautorizar token, ajustar direito de exclusão, liberar regra de saída, ampliar cota).
- Validar a cópia boa mais recente com
gzip -tetar -tzf. - Apagar as vencidas com listagem prévia revisada.
- Rodar
/usr/local/cpanel/bin/backup --forcee reler a fase de purge. - Conferir a contagem de arquivos no destino.
- Criar alerta de ocupação e de contagem para o destino remoto.
Fonte do diagnóstico da falha de pruning: documentação oficial do cPanel, How to Troubleshoot a Remote Transport Pruning Failure, consultada em 28 de setembro de 2026. O teste manual, o dry run, a validação de integridade e o monitoramento são organização da tarefa, não procedimento documentado pelo fabricante. Os nomes de arquivo, hosts e caminhos usados nos comandos são exemplos.
Referências
- Documentação oficial (cpanel) — How to Troubleshoot a Remote Transport Pruning Failure. Consultado em 2026-09-28.