blog
Servidores

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.

JR · · 9 min de leitura · 1 tabela · 8 blocos de código

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
  1. O destino lotado enquanto o painel mostra tudo verde
  2. Qual linha do log mostra se a fase de limpeza rodou
  3. Erro de permissão e erro de conexão pedem consertos opostos
  4. Apagar as cópias vencidas sem perder a única que ainda serve
  5. Três evidências de que a retenção voltou a apagar
  6. O que monitorar para a falha não voltar a passar despercebida
  7. 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

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

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.

  1. Abrir o log mais recente em /usr/local/cpanel/logs/cpbackup/ e procurar a fase de limpeza por destino.
  2. Identificar o transporte citado em /var/cpanel/backups/.
  3. Testar conexão e exclusão na mão com as credenciais do transporte.
  4. Classificar: permissão/escopo, credencial, conexão/DNS, ou cota do provedor.
  5. Corrigir a causa (reautorizar token, ajustar direito de exclusão, liberar regra de saída, ampliar cota).
  6. Validar a cópia boa mais recente com gzip -t e tar -tzf.
  7. Apagar as vencidas com listagem prévia revisada.
  8. Rodar /usr/local/cpanel/bin/backup --force e reler a fase de purge.
  9. Conferir a contagem de arquivos no destino.
  10. 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

  1. Documentação oficial (cpanel) — How to Troubleshoot a Remote Transport Pruning Failure. Consultado em 2026-09-28.
Leia também