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.

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
- Por que o aviso por e-mail não impede alterações no painel
- O que conferir antes de travar o painel
- Como travar a interface e informar o motivo ao cliente
- O que o bloqueio de interface não impede
- Como destravar sem deixar conta esquecida travada
- Checklist para repetir em todas as janelas
- 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:
- Versão do cPanel & WHM: o comportamento e os nomes dos scripts são os descritos na documentação da sua versão. Leia a página oficial antes de cada janela, não confie na memória da última vez.
- Lista de contas afetadas: bloqueio de um servidor inteiro é diferente de bloqueio de algumas contas. Saiba qual dos dois você precisa.
- Texto da mensagem pronto: a mensagem exibida ao cliente é o que reduz chamado durante a janela. Escreva antes, não na hora.
- Uma conta de teste: uma conta cPanel sua, sem cliente, para validar que o bloqueio está ativo e depois que saiu.
- Aviso prévio enviado: o bloqueio não substitui o aviso. Ele cobre quem não leu o aviso.
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.
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 |
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
- Bloquear antes de avisar: o cliente tenta entrar, vê a mensagem e acha que é problema. A mensagem ajuda, mas o aviso prévio evita o susto.
- Mensagem sem horário de término: "em manutenção" sem previsão gera chamado. Coloque um horário, mesmo que conservador.
- Escopo trocado entre bloqueio e desbloqueio: o mais comum para sobrar conta travada. Registre e repita o mesmo escopo.
- Confiar só no bloqueio: se FTP ou e-mail podem alterar o que você está migrando, o painel travado não protege nada. Trate esses caminhos à parte.
- Não testar com conta própria: sem conta de teste, você só descobre que o bloqueio falhou quando algum cliente altera algo no meio da janela.
- Usar sintaxe de memória: os argumentos estão na documentação oficial. Consulte a cada janela, principalmente depois de atualizar o cPanel.
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
- Documentação oficial (cpanel) — Interface Lock Scripts. Consultado em 2026-10-15.