# 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.

> 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).

João Rizzon · 2026-11-12 · Revenda

---

## 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](https://docs.cpanel.net/knowledge-base/cpanel-product/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: suporte@suaagencia.com.br
```

### Como rodar o bloqueio e registrar o comando

Rode o script de bloqueio com os valores da sua ficha, conferidos na [documentação oficial](https://docs.cpanel.net/knowledge-base/cpanel-product/interface-lock-scripts/). 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:

> **** A manutenção terminou às 23h10 e o seu painel já está liberado. Se encontrar qualquer comportamento diferente do normal, responda este e-mail que a gente verifica.

## 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](https://docs.cpanel.net/knowledge-base/cpanel-product/interface-lock-scripts/). 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.

