Troubleshoot cPanel: resolvendo travas no `.lock` e falhas na adição de domínios

Quando a criação de Addon Domain ou zona DNS "congela", o problema nem sempre é na interface do WHM. Em muitos casos, existe um lock preso em backend que bloqueia as próximas operações. Remover o arquivo de trava de forma descuidada ou encerrar processos de forma inadequada pode gerar corrupção nas tabelas internas do cPanel e inconsistências nos serviços.

1. O sintoma e a cadeia de hooks do cPanel#

No cPanel/WHM, operações administrativas como criação de contas, adição de domínios e atualizações de zonas DNS dependem de uma cadeia de execução sequencial:

Se qualquer script ou hook customizado de terceiros (como plugins de segurança, CDNs ou faturamento) travar ou sofrer timeout, o cPanel manterá o arquivo de trava (.lock) aberto por tempo indefinido, impedindo qualquer nova tarefa administrativa.

2. Auditoria e diagnóstico pré-intervenção#

Antes de forçar a remoção de qualquer recurso, realize uma auditoria completa no host para entender se a falha é decorrente de concorrência ou de gargalos do sistema.

2.1 backup preventivo de estado do cPanel#

Sempre gere uma cópia de segurança rápida dos arquivos de configuração críticos e do diretório de webcalls antes de alterar processos:

# Backup completo do estado do cPanel (configs e base)
sudo tar czf /root/cpanel-backup-$(date +%Y%m%d-%H%M%S).tar.gz \
  /var/cpanel/ \
  /etc/cpanel.config \
  /usr/local/cpanel/ 2>/dev/null || true

# Backup específico das filas de chamadas
sudo cp -r /var/cpanel/webcalls/ /root/webcalls-backup-$(date +%Y%m%d)/

2.2 auditoria de espaço em disco e inodes#

Travamentos persistentes de escrita frequentemente ocorrem porque o disco ou o limite de inodes (tabela de indexação de arquivos) atingiu 100%, impossibilitando o cPanel de gravar o fechamento do lock.

# Verificar ocupação do espaço em disco
df -h

# Verificar limite e ocupação de Inodes (vital para cPanel)
df -i

# Analisar ocupação de diretórios do cPanel
du -sh /var/cpanel/

2.3 rastreamento de hooks customizados#

Verifique se existem hooks de pós-processamento ativados que possam estar travando em chamadas externas sem timeout configurado:

# Listar hooks ativos no cPanel
cat /var/cpanel/hooks.yaml 2>/dev/null

# Listar scripts de hooks de terceiros
ls -la /usr/local/cpanel/3rdparty/bin/hooks/ 2>/dev/null || true

3. Localizando outros arquivos de lock comuns#

Embora /var/cpanel/webcalls/.lock seja a causa mais frequente de lentidão e travamento geral de adições de domínios, verifique outros locks que afetam subsistemas específicos do painel:

# Localizar todos os arquivos de lock ativos no diretório administrativo do cPanel
find /var/cpanel -name "*.lock" -type f 2>/dev/null

# Verificação de locks de cache de zonas DNS (impede atualização do BIND/PowerDNS)
ls -la /var/cpanel/zonecache/*.lock 2>/dev/null

# Verificação de locks de autenticação de e-mail
ls -la /var/cpanel/email/authlocks/*.lock 2>/dev/null

# Verificação de locks de rotinas de backup cPanel
ls -la /usr/local/cpanel/logs/backup/*.lock 2>/dev/null

4. Procedimento de correção seguro#

4.1 identificação do PID do processo proprietário#

Identifique de forma inequívoca qual PID detém o lock aberto na tabela do sistema:

# Usar lsof para capturar o PID proprietário (preferencial)
if command -v lsof &>/dev/null; then
    lsof /var/cpanel/webcalls/.lock
else
    # Fallback: fuser (pacote psmisc, disponível na maioria dos servidores cPanel)
    fuser /var/cpanel/webcalls/.lock
fi

Após obter o PID, inspecione a natureza do processo:

ps -p <PID> -o pid,ppid,comm,%cpu,%mem,etime,args

4.2 o risco do kill -9 e o protocolo correto de encerramento#

Siga sempre o protocolo seguro de desligamento:

# 1. Enviar solicitação de encerramento gracioso (SIGTERM)
kill -15 <PID>

# 2. Aguardar 5 segundos por PID para liberação de I/O em disco
#    (o sleep deve ser POR processo, não uma espera única em lote)
sleep 5

# 3. Validar se o processo foi de fato encerrado
if ps -p <PID> > /dev/null 2>&1; then
    echo "Processo resistente ao SIGTERM. Forçando encerramento bruto com SIGKILL..."
    kill -9 <PID>
fi

4.3 verificação pós-remoção#

Após forçar a saída do processo, certifique-se de que o lock e a porta de rede do socket foram devidamente liberados:

# Confirmar liberação do lockfile
lsof /var/cpanel/webcalls/.lock 2>/dev/null || echo "✅ Lockfile liberado com sucesso."

# Remover manualmente o arquivo órfão apenas se o PID proprietário não existir mais
if [ -f /var/cpanel/webcalls/.lock ] && ! pgrep -f "webcalls" > /dev/null; then
    echo "Removendo arquivo de lock órfão persistente..."
    sudo rm -f /var/cpanel/webcalls/.lock
fi

5. Logs específicos e depuração de erros#

Acompanhe as filas e saídas internas para identificar mensagens de erro durante a depuração:

# Logs gerais e operacionais do daemon cPanel
tail -n 100 /usr/local/cpanel/logs/error_log

# Logs do painel WHM (gerenciamento global)
tail -n 100 /usr/local/cpanel/logs/whmd.log

# Logs do daemon de DNS (importante se a falha for na adição de zonas)
tail -n 100 /usr/local/cpanel/logs/dnsadmin_log

# Logs de erro do servidor web Apache
tail -n 100 /usr/local/apache/logs/error_log

Se você encontrar logs contendo a mensagem abaixo, indica que o processo cPanel sofreu falha grave e interrompeu a rotina sem disparar os hooks de destruição do objeto Perl:

Cpanel::FileUtils::Flock ... destroyed at global destruct! ... DestroyDetector.pm

6. Health check do painel e reinício de serviços#

Após liberar o lock, verifique o estado de saúde geral do painel e reative os serviços utilizando os utilitários empacotados (restartsrv) nativos do cPanel:

# Verificar status global de serviços via WHM API
whmapi1 servicestatus

# Testar conectividade de porta local do painel (2087/2083)
curl -k -I https://localhost:2087/

# Reiniciar o serviço Apache de forma segura
sudo /usr/local/cpanel/scripts/restartsrv httpd

# Reiniciar o serviço DNS (BIND ou PowerDNS)
sudo /usr/local/cpanel/scripts/restartsrv named

# Reiniciar o serviço cPanel daemons geral (CPSRVDF)
sudo /usr/local/cpanel/scripts/restartsrv cpanel

7. Scripts de apoio operacional#

Script de correção e limpeza segura (fix-cpanel-lock.sh)#

Use este script automatizado para auditar e limpar travas ativas de forma não destrutiva:

#!/bin/bash
# fix-cpanel-lock.sh - Limpeza segura e não agressiva de locks presos no cPanel
set -euo pipefail

LOCK_FILE="/var/cpanel/webcalls/.lock"

echo "=== Analisando Lock do cPanel ==="

if [ ! -f "$LOCK_FILE" ]; then
    echo "✅ Nenhum lock ativo em: $LOCK_FILE"
    exit 0
fi

echo "⚠️ Arquivo de lock detectado."

# 1. Obter os PIDs
LOCK_PIDS=$(lsof -t "$LOCK_FILE" 2>/dev/null || true)

if [ -z "$LOCK_PIDS" ]; then
    echo "✅ Nenhum processo ativo retendo o arquivo. Limpando lock órfão..."
    sudo rm -f "$LOCK_FILE"
    echo "✅ Lock órfão removido com sucesso."
    exit 0
fi

echo "Processos vinculados ao lock:"
for PID in $LOCK_PIDS; do
    echo "  -> PID: $PID"
    ps -p "$PID" -o pid,ppid,comm,%cpu,%mem,etime 2>/dev/null || true
done

# 2. Procedimento de Encerramento Seguro (SIGTERM -> sleep -> SIGKILL por PID)
for PID in $LOCK_PIDS; do
    echo "Enviando sinal de encerramento gracioso (SIGTERM) para o PID: $PID"
    kill -15 "$PID" 2>/dev/null || true

    # sleep POR PID: aguardar flush de I/O antes de verificar próximo
    echo "Aguardando liberação de threads de disco para PID $PID..."
    sleep 5

    if ps -p "$PID" > /dev/null 2>&1; then
        echo "⚠️ PID $PID ainda ativo. Enviando sinal forçado (SIGKILL)..."
        kill -9 "$PID" 2>/dev/null || true
    else
        echo "✅ PID $PID encerrado com sucesso após SIGTERM."
    fi
done

# 4. Limpeza final do arquivo órfão (com sudo para garantir permissão)
if [ -f "$LOCK_FILE" ]; then
    sudo rm -f "$LOCK_FILE"
fi
echo "✅ Liberação e limpeza concluídas."

8. Plano de rollback e contingenciamento#

Caso a interrupção dos processos do cPanel cause falhas na interface administrativa ou indisponibilidade de algum serviço:

1. Restaurar os Locks Órfãos: Se a remoção manual causou erros inesperados no interpretador Perl, recrie a pasta temporária de webcalls ou reimporte o backup:

   sudo cp -r /root/webcalls-backup-$(date +%Y%m%d)/* /var/cpanel/webcalls/

1. Recompilar a Configuração do Apache/DNS: Se o Apache parou devido a um arquivo de configuração cortado no meio da escrita:

   # Reconstruir arquivos do Apache a partir dos templates do cPanel
   /usr/local/cpanel/scripts/rebuildhttpdconf

   # Validar sintaxe antes do restart (evita downtime por config inválida)
   httpd -t && sudo /usr/local/cpanel/scripts/restartsrv httpd

1. Reinicializar todos os daemons:

   sudo /usr/local/cpanel/scripts/restartsrv_all

Veja também

Servidores Guia Completo de Zonas DNS no cPanel e WHM: Correção do Erro 'DNS Entry Already Exists', killdns e Templates Avançados

Infraestrutura Como contornar o limite global de e-mails no cPanel e CloudLinux: resolvendo o erro XID psafa9

Infraestrutura Anatomia de um deadlock silencioso no CloudLinux e cPanel: processos fantasmas, travas de sessão e filas TCP

Este post está licenciado sob CC BY-NC.