blog
Painéis

Plesk CLI: criar e suspender assinatura no terminal

Criar, consultar, suspender e reativar assinaturas pelo terminal, com a verificação de cada passo e o que fazer quando o utilitário devolve erro.

JR · · 8 min de leitura · 2 tabelas · 10 blocos de código

Resposta curta: Use plesk bin subscription --create para criar a assinatura (com -owner, -service-plan, -ip, -login e -passwd), --webspace-off para suspender e --webspace-on para reativar. Confirme cada passo com --info e com o código de saída, que é 0 no sucesso.

Neste artigo
  1. Antes de usar, confirme a versão e o help local
  2. Inventário antes de mexer
  3. Criar uma assinatura
  4. Suspender e reativar
  5. Quando o comando falha
  6. Colocando em script
  7. Quando a interface web não abre, o que a CLI ainda resolve

Antes de usar, confirme a versão e o help local

Todo o gerenciamento de assinaturas do Plesk em Linux passa por plesk bin, que chama os utilitários de linha de comando do painel. O que interessa aqui é plesk bin subscription, com apoio de customer e service_plan. A referência é a documentação oficial do Plesk CLI para Linux, na versão Onyx. Versões posteriores mantêm a maior parte das opções, mas confira no servidor antes de colocar algo em produção.

Duas condições valem para tudo o que segue:

plesk version
plesk bin subscription --help | less

O utilitário não depende da interface web. Se o sw-cp-server ou o nginx do painel estiver parado, os comandos continuam funcionando, desde que o banco esteja no ar. Aqui fica só o caminho de terminal.

Inventário antes de mexer

Criar ou suspender sem saber o que existe é a origem dos erros mais comuns: plano com nome digitado errado, dono inexistente, domínio já cadastrado. Faça o inventário primeiro.

# assinaturas existentes
plesk bin subscription --list

# planos de serviço disponíveis
plesk bin service_plan --list

# detalhes de uma assinatura: dono, plano, IP, status
plesk bin subscription --info example.com

--info é o comando que você vai repetir depois de cada alteração para confirmar o estado. Guarde a saída antes da mudança: ela é o seu ponto de reversão documentado.

plesk bin subscription --info example.com > /root/antes-example.com.txt

O nome passado em -service-plan precisa bater exatamente com o que service_plan --list devolve.

Criar uma assinatura

Uma assinatura no Plesk é um domínio principal com espaço de hospedagem, um usuário de sistema, um IP e, opcionalmente, um plano de serviço e um cliente dono. A ordem é: dono existe, plano existe, cria a assinatura.

Passo 1: criar o cliente, se ainda não existir

Se a assinatura vai pertencer ao administrador, pule este passo e use -owner admin.

read -rs PSA_PASSWORD && export PSA_PASSWORD
plesk bin customer --create cliente01 -name "Cliente Exemplo" -passwd '' -email [email protected]
unset PSA_PASSWORD

O login (cliente01) é o identificador que você usará em -owner. Dados acima são fictícios, apenas exemplo. A senha entra pela variável PSA_PASSWORD com -passwd '', lida por read -rs, para não aparecer em argv, em ps nem no histórico do shell (detalhes em Colocando em script). Confirme com --help que a sua versão suporta a variável.

Passo 2: criar a assinatura

read -rs PSA_PASSWORD && export PSA_PASSWORD
plesk bin subscription --create example.com \
  -owner cliente01 \
  -service-plan "Default Domain" \
  -ip 192.0.2.10 \
  -login exuser \
  -passwd ''; rc=$?
unset PSA_PASSWORD

O que cada opção faz, conforme a documentação:

Passo 3: conferir

Na execução bem-sucedida, o utilitário imprime uma linha iniciada por SUCCESS: e sai com código 0. Esse código foi guardado em rc no Passo 2, logo após o --create. Um echo $? depois do unset PSA_PASSWORD mostraria o código do unset, que é sempre 0, e não o da criação. Não confie só na mensagem: rode --info e verifique dono, plano e IP.

echo $rc
plesk bin subscription --info example.com

Para desfazer uma criação errada, plesk bin subscription --remove example.com. Isso apaga os arquivos do site também. Numa assinatura recém-criada não há o que perder; numa antiga, faça backup antes.

Ordem para criar uma assinaturaConfirmar versão e helpplesk version e --helpDono existe?Veja customer --list; senão, crie o clientePlano existe?Nome exato de service_plan --listIP registrado no painel?Revendedor: IP no pool deleCriar guardando o rcCódigo de saída lido logo após o createConferir com --infoDono, plano e IP conferidos
Ordem de decisão antes de criar uma assinatura.

Suspender e reativar

Suspensão desativa o espaço de hospedagem sem apagar dados. É a operação que mais aparece em automação de cobrança.

# suspender
plesk bin subscription --webspace-off example.com

# reativar
plesk bin subscription --webspace-on example.com

Pontos sobre o alcance da suspensão. O efeito exato sobre site, entrega de e-mail, FTP/SSH e DNS não foi medido para este texto: antes de automatizar, suspenda uma assinatura de teste e confira com curl -I, um envio de e-mail e uma tentativa de login FTP o que a sua versão faz.

Operação Comando Reversão Perde dados
Listar subscription --list não se aplica não
Consultar subscription --info <dominio> não se aplica não
Criar subscription --create <dominio> ... subscription --remove <dominio> não
Suspender subscription --webspace-off <dominio> subscription --webspace-on <dominio> não
Remover subscription --remove <dominio> só restaurando backup sim

Quando o comando falha

A descrição do erro sai no terminal e costuma dizer exatamente o que faltou. Os casos abaixo são os que decorrem diretamente dos requisitos documentados de cada opção.

Sintoma Causa provável O que fazer
Erro citando o plano nome em -service-plan diferente do cadastrado copie o nome de service_plan --list, com aspas
Erro citando o dono login em -owner inexistente plesk bin customer --list e crie o cliente antes
Erro citando o IP IP não registrado no painel registre o IP no Plesk antes de usar
Domínio ou login já existe criação repetida ou login de sistema em uso subscription --info para ver o que existe; troque o -login
Comando não encontrado PATH sem /usr/sbin ou Plesk não instalado chame /usr/sbin/plesk pelo caminho absoluto e confirme a instalação
Permissão negada execução sem root os utilitários de plesk bin exigem root; em automação com usuário não root, use sudo com regra restrita por operação (veja a regra de sudoers logo abaixo da tabela) em vez de liberar sudo amplo
Falha sem mensagem clara banco ou serviço interno com problema leia /var/log/plesk/panel.log

Sobre a regra de sudo: no sudoers, um comando listado com argumentos só casa com exatamente esses argumentos. Uma regra com /usr/sbin/plesk bin subscription e nada mais bloqueia --create example.com .... É preciso curinga explícito, de preferência um por operação. Edite com visudo -f /etc/sudoers.d/plesk-automacao:

Defaults:automacao env_keep += "PSA_PASSWORD"
automacao ALL=(root) NOPASSWD: /usr/sbin/plesk bin subscription --info *, \
  /usr/sbin/plesk bin subscription --webspace-off *, \
  /usr/sbin/plesk bin subscription --webspace-on *, \
  /usr/sbin/plesk bin subscription --create *

O risco do curinga: no sudoers, * também casa com espaços, então --webspace-off * aceita qualquer sequência de argumentos depois da opção, não só um domínio. Uma regra genérica /usr/sbin/plesk bin subscription * liberaria também --remove, que apaga dados. Liste só as operações que o script usa e deixe --remove fora da regra.

O env_reset, ativo por padrão, descarta PSA_PASSWORD ao passar pelo sudo, e o --create com -passwd '' falha ou fica sem a senha. A linha Defaults:automacao env_keep += "PSA_PASSWORD" acima mantém a variável. A alternativa é sudo --preserve-env=PSA_PASSWORD /usr/sbin/plesk bin subscription --create ..., que o sudo só aceita se a regra tiver a tag SETENV ou a variável estiver em env_keep. Valide a sintaxe com visudo -c e confira o que o usuário pode rodar com sudo -l -U automacao.

Não encontramos garantia documentada de que toda ação da CLI seja registrada em panel.log. Verifique no seu servidor: rode uma operação conhecida, como um --info, e procure por ela no log. Se aparecer, ele é o segundo lugar para olhar quando a saída do comando não explica a falha.

tail -n 50 /var/log/plesk/panel.log

Se a falha veio no meio de uma criação, rode --info antes de tentar de novo. Uma assinatura criada pela metade faz a segunda tentativa falhar com "já existe", e o correto é remover e recriar, não insistir.

Falha na criação: o que verificarLer a mensagem de erroCostuma dizer o que faltouErro cita plano, dono ou IP?Corrija o nome ou registre o IPAssinatura criada pela metade?Rode --info antes de repetirAssinatura já existeRemova e recrie, não insistaSem mensagem claraLeia /var/log/plesk/panel.log
Caminho de decisão para falhas na criação.

Colocando em script

Em automação, trate cada chamada como algo que pode falhar. O exemplo abaixo suspende uma lista de domínios lida de arquivo, registra o resultado e não para no primeiro erro, para que um domínio problemático não deixe os outros sem processar. Ele decide OK ou FALHA só pelo código de saída. A saída de --info de cada domínio vai para o log, mas o script não interpreta o campo de status, cujo texto pode variar entre versões: confira o log ou adapte um grep ao que a sua versão imprime.

#!/bin/bash
# exemplo: suspende os domínios listados em /root/suspender.txt (um por linha)
LOG=/root/suspensao-$(date +%F).log

while read -r dom; do
  [ -z "$dom" ] && continue
  if plesk bin subscription --webspace-off "$dom" >>"$LOG" 2>&1; then
    echo "OK $dom" >>"$LOG"
    plesk bin subscription --info "$dom" >>"$LOG" 2>&1
  else
    echo "FALHA $dom (codigo $?)" >>"$LOG"
  fi
done < /root/suspender.txt

grep -c '^FALHA' "$LOG"

Dois cuidados que evitam dor de cabeça:

Quando a interface web não abre, o que a CLI ainda resolve

A CLI resolve a tarefa urgente, mas não o problema da interface. Duas coisas ajudam a separar as duas frentes.

Primeiro, plesk login gera um link de acesso único para o administrador. Se o link abre, o problema era de credencial ou sessão, não de serviço. Se não abre, a falha provavelmente está na camada web do painel ou no acesso de rede até ela, não necessariamente com o painel fora do ar. Confira nesta ordem: systemctl status sw-cp-server (e o nginx do painel), a porta 8443 escutando (ss -ltnp | grep 8443) e liberada no firewall com teste de conexão feito de fora do servidor, a validade do certificado do painel e se o hostname usado no link resolve para o IP correto.

Segundo, a CLI funcionar enquanto a tela não abre é em si um diagnóstico: banco e utilitários estão saudáveis, e a falha provavelmente está na camada web do painel ou no caminho de rede até ela (firewall na 8443, DNS do hostname, certificado). Isso estreita bastante a busca.

Enquanto isso, as operações de assinatura do dia a dia (consultar, criar, suspender, reativar) podem seguir pelo terminal sem depender de nada além do acesso root ao servidor.

Referências

  1. Documentação oficial (plesk) — Plesk CLI (Linux). Consultado em 2026-10-21.
Leia também