blog
Revenda

Como bloquear o cPanel dos clientes durante a manutenção

Processo para travar o cPanel dos clientes com mensagem de manutenção (personalizada, se a sua versão documentar o parâmetro), destravar sem esquecer nenhuma conta e evitar alteração no meio de migração ou recompilação.

JR · · 8 min de leitura · 3 tabelas · 4 blocos de código

Resposta curta: use os scripts de bloqueio de interface documentados pelo cPanel: eles travam o painel durante a janela e exibem uma mensagem de bloqueio (personalizada com o motivo, se a sua versão documentar o parâmetro de mensagem).

Neste artigo
  1. Por que o aviso por e-mail não impede alterações no painel
  2. O que conferir antes de travar o painel
  3. Como travar a interface e informar o motivo ao cliente
  4. O que o bloqueio de interface não impede
  5. Como destravar sem deixar conta esquecida travada
  6. Checklist para repetir em todas as janelas
  7. Erros que travam contas por engano ou geram chamado

Por que o aviso por e-mail não impede alterações no painel

Avisar o cliente sobre a janela de manutenção é a parte fácil. O problema aparece quando, no meio de uma migração ou de uma recompilação, alguém entra no cPanel e cria uma conta de e-mail, troca a versão do PHP ou instala um plugin pelo instalador de apps. A mudança cai no servidor antigo depois da cópia, ou interfere em um processo que está rodando. Resultado: dado perdido, configuração divergente e um chamado que começa com "eu só mexi numa coisinha".

O cPanel & WHM tem um recurso documentado para isso: os scripts de bloqueio de interface, descritos na página oficial Interface Lock Scripts. A ideia é travar o acesso à interface durante a janela e exibir uma mensagem de bloqueio (com o motivo escrito por você, se a versão documentar texto próprio), em vez de deixar o cliente encontrar um erro genérico.

Este guia organiza o uso desses scripts como processo de revenda: pré-requisitos, bloqueio, destravamento, conferência e erros comuns. Não fizemos medição própria aqui. Tudo que é parâmetro vem da documentação citada; o que é exemplo está marcado como exemplo.

O que conferir antes de travar o painel

O bloqueio é feito no servidor, então você precisa de acesso root via SSH (ou de quem administra o servidor, se você é revendedor em servidor de terceiros). Revenda sem root não executa esses scripts; nesse caso, o pedido vai para o provedor junto com a janela combinada.

Antes de começar, confira:

Para localizar os scripts no seu servidor, sem executar nada, liste o diretório de scripts e filtre por "lock":

ls /usr/local/cpanel/scripts/ | grep -i lock

Compare o resultado com os nomes da página oficial. Se o nome não bater, pare e verifique a versão instalada antes de seguir. Não reproduzimos aqui os nomes nem os argumentos: não conseguimos confirmá-los para todas as versões em produção, e um nome ou argumento errado pode travar mais contas do que o pretendido. Por isso, antes da primeira janela, preencha esta ficha uma vez por servidor, copiando da documentação da versão instalada:

Item Onde conferir Seu valor
Nome do script de bloqueio Página oficial + saída do ls (preencher)
Nome do script de desbloqueio Página oficial + saída do ls (preencher)
Parâmetro de escopo por conta, se existir Página oficial (preencher ou "não documentado")
Parâmetro de escopo por servidor, se existir Página oficial (preencher ou "não documentado")
Parâmetro de mensagem personalizada, se existir Página oficial (preencher ou "não documentado")
Forma de listar o que está travado, se existir Página oficial (preencher ou "não documentado")

Saída esperada do ls: um ou mais nomes de arquivo contendo "lock" que coincidem com os da documentação. Saída vazia significa que a versão não tem os scripts nesse caminho ou que o nome mudou; nos dois casos, não siga. Guarde a ficha preenchida no mesmo documento do checklist: ela vira a referência fixa para todos os sites que você mantém naquele servidor.

Como travar a interface e informar o motivo ao cliente

Defina se o bloqueio cobre o servidor ou só algumas contas

Decida se a janela afeta o servidor inteiro ou só as contas que vão migrar, mas só escolha um escopo que esteja na sua ficha como parâmetro documentado. Se a documentação da sua versão não descreve bloqueio por conta, não presuma que ele existe: o bloqueio será do servidor inteiro e o aviso prévio precisa ir para todos os clientes daquele servidor. Em migração parcial com escopo por conta disponível, travar todo mundo gera reclamação de cliente que não tinha nada a ver com a operação.

Que informações a mensagem de bloqueio precisa ter

Se a ficha registra parâmetro de mensagem personalizada, o texto aparece para o cliente quando ele tenta usar o painel. Se a documentação da sua versão não prevê texto próprio, o cliente verá a mensagem padrão do cPanel, e o aviso prévio por e-mail passa a carregar sozinho estas informações. Em qualquer caso, a mensagem precisa responder três perguntas: o que está acontecendo, até quando, e se o site e o e-mail continuam funcionando (só afirme isso se for verdade para a sua operação). Feche com um contato para dúvidas. Exemplo fictício:

Manutenção programada em andamento até 23h30 (horário de Brasília).
O painel está temporariamente bloqueado para evitar perda de alterações.
Sites e e-mails continuam funcionando normalmente.
Dúvidas: [email protected]

Como rodar o bloqueio e registrar o comando

Rode o script de bloqueio com os valores da sua ficha, conferidos na documentação oficial. O formato abaixo é só um molde: tudo entre < > é marcador seu, não sintaxe do cPanel.

/usr/local/cpanel/scripts/<script-de-bloqueio> <parametros-de-escopo-da-ficha> <parametro-de-mensagem-da-ficha>

Copie o comando exato que você rodou para o registro da janela, com o horário. Esse registro é o que vai garantir o destravamento completo depois.

Como confirmar que o bloqueio pegou na conta de teste

Se o bloqueio for por contas específicas, inclua a conta de teste na lista bloqueada; fora da lista, ela abre normalmente e você conclui por engano que o bloqueio falhou. Entre no cPanel com a conta de teste. O resultado esperado é ver a mensagem de bloqueio (a sua, ou a padrão se não houver mensagem personalizada documentada), e não a interface normal. Se a interface abriu com a conta de teste dentro do escopo, o bloqueio não pegou: não comece a migração até resolver.

Ciclo de uma janela de manutençãoConferir a fichaNomes dos scripts batem com o lsBloquearRegistrar comando e horárioValidar com conta de testeVê a mensagem de bloqueioExecutar a manutençãoConforme o procedimento da tarefaDesbloquear com o mesmo escopoConferir contra o registro
Ordem da janela: o desbloqueio repete o escopo registrado no bloqueio.

O que o bloqueio de interface não impede

A documentação trata do acesso à interface. Não presuma que o bloqueio também impede alterações por outros caminhos, como FTP, SSH da conta, cliente de e-mail ou integrações via API. Se a sua manutenção depende de que nada mude nos arquivos, teste esses caminhos com a conta de teste ou trate cada um separadamente.

Também vale separar bloqueio de suspensão. Suspender a conta no WHM tira o site do ar. O bloqueio de interface serve para o caso oposto: o site segue no ar enquanto o painel fica travado. Se o objetivo é só impedir mexida no painel, suspender é a ferramenta errada e vira incidente para o cliente.

Situação Ferramenta adequada Efeito para o cliente
Migração de contas, site deve seguir no ar Bloqueio de interface Vê a mensagem ao abrir o painel
Recompilação de PHP ou Apache Bloqueio de interface Evita troca de versão no meio do processo
Inadimplência ou abuso Suspensão de conta Site e serviços fora do ar
Alteração de arquivos por FTP precisa parar Tratar FTP à parte Depende do que for configurado
Qual ferramenta usar na janelaSite precisa seguir no ar?Sim: use bloqueio de interfaceArquivos mudam por FTP?Sim: trate FTP à parteSó algumas contas migram?Sim: bloqueio por conta, se a ficha permitirNão: suspensão de contaSó para inadimplência ou abuso
Suspender tira o site do ar. Bloquear a interface não tira.

Como destravar sem deixar conta esquecida travada

O erro mais caro desse processo não é na hora de bloquear. É esquecer uma conta travada depois da janela. O cliente descobre na manhã seguinte, abre chamado, e a manutenção bem feita vira reclamação.

Como rodar o destravamento com o mesmo escopo

Use o script de desbloqueio registrado na ficha, com o mesmo escopo que você usou no bloqueio. Molde, com os mesmos marcadores:

/usr/local/cpanel/scripts/<script-de-desbloqueio> <mesmos-parametros-de-escopo-do-registro>

Se travou por conta, destrave cada conta da lista registrada na etapa 3, incluindo a conta de teste. Se travou o servidor, destrave o servidor.

Como conferir o desbloqueio contra o registro da janela

Pegue o registro da janela (horário, escopo, comando) e marque item por item. Bloqueio feito por conta e destravamento feito por servidor, ou o contrário, é a receita para sobrar alguma conta travada.

Depois, verifique no servidor. Se a ficha registra uma forma documentada de listar o que está travado, rode-a e confirme que nenhuma conta da lista aparece. Se a documentação da sua versão não descreve essa listagem, não temos um método no servidor para indicar: faça teste de login por amostra. Entre em pelo menos uma conta de cada lote da lista (a de teste e mais uma ou duas de clientes, com autorização) e confirme a interface normal. Em janela por servidor, uma conta já representa todas.

Como validar o painel liberado com a conta de teste

Entre no cPanel com a conta de teste. Resultado esperado: interface normal, sem a mensagem de manutenção. Se a sua janela travou contas específicas, teste também uma delas (com autorização do cliente, ou peça para ele confirmar).

Que mensagem enviar ao cliente quando a janela acabar

Mande a mensagem de encerramento. Frase pronta para o cliente:

Checklist para repetir em todas as janelas

Padronize em um documento só e use em todos os servidores. A tabela abaixo é o mínimo:

Etapa O que fazer Como validar
Antes Ler a documentação da versão instalada Nomes dos scripts conferem com o ls
Antes Enviar aviso ao cliente E-mail enviado com data e horário
Antes Escrever a mensagem do bloqueio Texto responde o quê, até quando e se site e e-mail seguem funcionando, com contato no fim
Início Executar o bloqueio (com a conta de teste na lista, se o escopo for parcial) e registrar comando e horário Conta de teste vê a mensagem de bloqueio
Durante Executar a manutenção Conforme o procedimento da tarefa
Fim Executar o desbloqueio com o mesmo escopo Conta de teste vê a interface normal
Fim Conferir item por item contra o registro Listagem documentada sem contas da lista ou, sem ela, login normal em amostra de contas da lista
Fim Avisar o cliente Mensagem de encerramento enviada

Erros que travam contas por engano ou geram chamado

Se você é revendedor sem root, a parte que cabe a você é a do meio: combinar a janela com o provedor, mandar a lista de contas e o texto da mensagem, e fazer a validação com a conta de teste no fim. O restante do checklist vale igual.

Referências

  1. Documentação oficial (cpanel) — Interface Lock Scripts. Consultado em 2026-10-15.
Leia também