O que é

O gws-cli é um utilitário de linha de comando instalado automaticamente em todo servidor, em
/usr/local/bin/gws-cli. Ele existe para um cenário específico: você (ou um cliente) ficou sem
acesso ao painel, e a interface web não é uma opção — seja porque a senha foi esquecida, o 2FA
travou, o próprio IP foi banido pelo fail2ban, ou o SMTP não está configurado e a recuperação por
e-mail não funciona. Rodando por SSH como root, ele lê e grava direto nos arquivos de credencial e de
bloqueio do painel, sem depender de nada que possa estar quebrado.

Os dois lugares onde vive uma senha

O painel guarda credenciais em dois arquivos diferentes, e o gws-cli cobre os dois:

O login que você informa decide o destino. Se ele bate com o usuário do admin, o comando age no
settings.json; senão, procura entre os clientes cadastrados. Não existe alvo implícito —
passwd e 2fa-disable exigem sempre o login como argumento. Rodar sem login não altera nada por
padrão: o comando recusa e mostra a lista de logins do servidor, para você acertar de primeira.

Listando usuários: gws-cli users

Ponto de partida de qualquer recuperação — mostra o admin e todo cliente do módulo de usuários, com
status e método de 2FA de cada um:

Usuários do painel — v2.33.0
──────────────────────────────────────────────────────────────────
 LOGIN                  PAPEL    STATUS   2FA     SITES  NOME
 gabriel                admin    ativo    TOTP    -      -
 ariovaldo              cliente  ativo    TOTP    2      Ariovaldo José
 maria                  cliente  INATIVO  -       1      Maria Aparecida

    E-mail do admin: contato@seudominio.com.br
    Clientes no Módulo de Usuários: 2

Se o módulo de usuários estiver desativado, ou ainda sem nenhum cliente cadastrado, o comando
diferencia os dois casos em vez de simplesmente mostrar uma lista vazia.

Trocando a senha: gws-cli passwd <login>

Pede a nova senha duas vezes (mínimo 8 caracteres) e não a exibe na tela em nenhum momento:

gws-cli passwd gabriel
# Alterar senha — gabriel (admin do painel)
# Nova senha (mín. 8 caracteres): ••••••••••
# Confirmar senha: ••••••••••
# [✓] Senha atualizada. Entre no painel com o usuário gabriel

Para um cliente do módulo de usuários é o mesmo comando, só muda o login:

gws-cli passwd ariovaldo
# [✓] Senha de ariovaldo atualizada. Vale já no próximo login.

Nenhuma senha passa em texto puro por processo intermediário: o hash é gerado via PHP (bcrypt) e a
senha viaja só por variável de ambiente, nunca como argumento visível em ps.

Desativando o 2FA: gws-cli 2fa-disable <login>

Remove o segredo do autenticador e qualquer verificação pendente, imediatamente:

gws-cli 2fa-disable ariovaldo
# [✓] 2FA de ariovaldo desativado. Login só com usuário e senha.

O admin pode ter 2FA por e-mail ou TOTP; um cliente do módulo de usuários só tem TOTP. Se o
login já estiver sem 2FA ativo, o comando avisa em vez de falhar — é seguro rodar mais de uma vez.

Liberando um IP banido: gws-cli liberar <IP>

Um IP banido por muitas tentativas de senha erradas não sai só desbanindo: a lista branca evita
o próximo ban, mas não solta o atual; e a lista negra (bloqueio manual) é outro mecanismo,
independente do fail2ban. Antes só dava pra resolver as três coisas pelo painel — e duas delas nem
existiam por SSH. O liberar destrava as três de uma vez:

gws-cli liberar 45.33.32.156
#  1. Fail2ban     Ban removido de todos os jails.
#  2. Lista branca Adicionado à lista branca global.
#                  Lista branca reaplicada em todas as jails.
#  3. Lista negra  Removido da lista negra e regras reaplicadas.
# [✓] 45.33.32.156 liberado. Pode tentar o acesso de novo.

Não sabe o seu próprio IP? Rode sem argumento — o comando lê de onde a sua sessão SSH veio e já
devolve o comando pronto:

gws-cli liberar
# [✗] Uso: gws-cli liberar <IP>
#     Esta sessão SSH veio de 45.33.32.156. Para liberar este IP:
#       gws-cli liberar 45.33.32.156

Soltando o IP de terceiros: gws-cli unban <IP>

Quando quem foi banido não é você — um cliente que errou a senha, por exemplo — e você não quer
isentar o IP permanentemente, use só o unban: solta o bloqueio nos jails do fail2ban, sem tocar na
lista branca.

gws-cli unban 45.33.32.156
# [✓] Ban removido de todos os jails.

Se o IP voltar a errar a senha, volta a ser banido normalmente — diferente do liberar.

Verificando o estado do painel: gws-cli status

Mostra a URL de acesso ao painel (domínio e a porta 22222 de fallback), o admin, o método de 2FA
ativo, o número de clientes e o estado dos serviços (nginx, PHP-FPM, MariaDB, fail2ban) — útil
quando você não lembra sequer o endereço para entrar.

Segurança e auditoria

• Exige root: sudo gws-cli <comando>.
• Toda troca de senha e todo reset de 2FA gera um registro na aba Logs do painel (evento com o
  login alvo e root@ssh como autor) — a ação fica visível depois, mesmo tendo sido feita fora da
  interface web. Nenhuma senha é gravada nesse registro.
• A gravação em users.json preserva o dono e a permissão do arquivo (o processo do painel
  continua enxergando o arquivo normalmente depois de uma alteração via SSH).

Veja também

• Perdi o acesso ao painel
• Autenticação em duas etapas
• Usuários do painel
• Fail2ban

Em vídeo: Aula 42 · Recuperando o acesso pelo gws-cli