Documentação
Introdução
Descrição Geral
LoboGuard é uma solução avançada e segura de monitoramento, alerta, gestão e relatórios para infraestruturas Proxmox, utilizando o Telegram como interface de controle remoto e alertas. Este manual fornece um guia completo para a configuração inicial do sistema.
Pré-requisitos
- Acesso ao Telegram (app móvel, desktop ou web)
- Chave de licença LoboBrothers válida
- Servidor LoboGuard implementado e acessível
- Clusters Proxmox com acesso à API do LoboGuard
Funcionalidades Principais
Monitoramento
Supervisão contínua de:
- CPU e Memória
- Discos e Estados
- VMs/LXCs
- Nós
- Armazenamento
- Redes
- Backups
- CEPH
Alertas inteligentes
Notificações automáticas via Telegram com vários tipos de alerta:
- Alertas de recursos (CPU, RAM, Disco)
- Alertas de certificados SSL/TLS
- Alertas de sincronização de tempo
- Alertas de firewall e segurança
- Alertas de Alta Disponibilidade
- Alertas de armazenamento Ceph e ZFS
- Alertas de backup e snapshots
- Alertas de subscrição do sistema
Relatórios
Manuais e programados para:
- Estado Geral
- Estado VM/LXC
- Armazenamento
- Backups
- Redes
- Ceph
Arquitetura de Segurança Avançada
LoboGuard implementa múltiplas camadas de segurança para proteger sua infraestrutura:
- Autenticação Multi-Fator
- Controle de Acesso Granular
- Proteção Anti-Brute Force
- Auditoria Completa
- Tokens Únicos
- Timeouts de Sessão
Gestão remota
Controle via Telegram com autenticação segura:
- Ligar, desligar, reiniciar VMs/LXCs
- Gestão e execução de backups
- Gestão e execução de snapshots
Multi-cluster
Suporte para múltiplos ambientes Proxmox conforme a licença
- Basic 1 cluster
- Pro 3 clusters
- Max 10 clusters
Configuração Bot Telegram
Acesso ao BotFather
Passo 1: Aceder à aplicação Telegram
- Abrir o Telegram (móvel, desktop ou web)
- Na barra de pesquisa, digitar: @BotFather
- Clicar no bot oficial verificado com ✅
- Pressionar START ou enviar /start
Criar Novo Bot
Passo 1: Iniciar a criação
Passo 2: Configurar o nome do bot
- BotFather pedirá o nome do bot
- Responder com um nome descritivo: Bot de Gestão LoboGuard
Passo 3: Configurar o nome de utilizador do bot
- Deve terminar com "bot"
- Deve ser único em toda a plataforma Telegram
- Pode conter apenas letras, números e underscores
- Exemplo: loboguard_mgmt_bot
Obter Token do Bot
Uma vez completado o processo, BotFather fornecerá:
- Copiar e guardar o token imediatamente
- NÃO partilhar o token com terceiros
- Este token é a chave de acesso ao seu bot
IDs Telegram
Obter o seu ID de Chat Pessoal
Método 1: Usar bot auxiliar
- Procurar @userinfobot no Telegram
- Enviar-lhe /start
- O bot responderá com as suas informações:
First: Seu Nome
Lang: pt
Método 2: Usar o seu próprio bot
- Enviar /start ao seu bot recém-criado
- Abrir no navegador: https://api.telegram.org/bot
/getUpdates - Substituir
pelo seu token do bot - Procurar o campo "id" em "from": 12345678910
Criar e Configurar Grupo Privado para Alertas
Passo 1: Criar grupo privado
- Criar "Novo Grupo" no Telegram
- Nome de exemplo: "Alertas LoboGuard"
- Adicionar administradores que receberão alertas
Passo 2: Adicionar bot ao grupo
- Ir às informações do grupo → Editar
- Selecionar Adicionar membros
- Procurar o seu bot: @loboguard_mgmt_bot
- Adicioná-lo ao grupo
Passo 3: Configurar permissões
Nas informações do grupo:
Obter ID do Chat de Grupo
Método simples: No Telegram Web
- Selecionar o grupo
- Na barra do navegador: https://web.telegram.org/k/#-4819707521
- O ID do grupo é: -4819707521 (sempre com sinal negativo para grupos privados)
Acesso Inicial e Configuração
Acesso ao Sistema
Passo 1: Aceder ao servidor
- Navegar para: https://IP_SERVIDOR:8443
- Exemplo: https://192.168.1.139:8443
Passo 2: Tratar aviso do certificado
Os navegadores mostrarão avisos como:
- Chrome: "A sua ligação não é privada"
- Firefox: "Aviso: Risco de segurança potencial"
Passo 3: Aceitar certificado
- Clicar em Configurações avançadas
- Selecionar Continuar para [IP] (não seguro)
O certificado auto-assinado é seguro e um novo é gerado a cada instalação, embora se quiser evitar avisos do navegador, pode posteriormente carregar o seu próprio certificado SSL a partir da interface de administração.
Primeiro Acesso e Alteração de Password
Credenciais predefinidas:
Password: guard
Alteração de password obrigatória: O sistema redirecionará automaticamente para alteração de password.
Requisitos da nova password:
Aceder ao Painel de Configuração
Uma vez alterada a password:
- Clicar em Configuração no menu superior
- Acederá ao assistente de configuração passo a passo
Configuração Bot (Assistente)
O assistente guia através de 6 passos essenciais para configurar completamente o LoboGuard.
Configuração Licença (Passo 1/6)
Configuração:
- Inserir a chave de licença fornecida pela LoboBrothers
- Clicar Seguinte para validar
Uma vez ativada numa máquina, a licença não pode ser transferida para outra. Para alterações, contactar o suporte.
Configuração Telegram (Passo 2/6)
| Campo | Descrição | Exemplo |
|---|---|---|
| Token Bot | Token completo do BotFather | 8452961006:AAHWhRkptJ937RgUgd5vC-Ml6biyyrME76I |
| Chat ID | ID pessoal para gestão | 123456789 |
| Chat ID Alertas | ID do grupo para alertas | -123456789 ou -100123456789 |
Se houver problemas com o Chat ID Alertas, tente adicionar o prefixo -100 antes do ID do grupo, às vezes o ID real para a API é com -100 à frente.
Testar ligação: Clicar em Testar ligação Telegram. Se bem-sucedido, receberá mensagens de confirmação em ambos os chats.
Configuração Segurança (Passo 3/6)
| Parâmetro | Descrição | Recomendação |
|---|---|---|
| Bot Secret | Chave de acesso inicial | Usar password segura |
| ID Admin | Super administrador do bot | O seu Chat ID pessoal |
| Duração Ban | Tempo de bloqueio após falhas | 3600 segundos (1 hora) |
| Tentativas Auth Máx | Tentativas antes do ban | 5 tentativas |
| Contagem Ban Máx | Quantos bans antes do ban permanente | 3 tentativas |
| Método Confirmação | PIN e OTP (para ações críticas) | OTP (mais seguro e recomendado para produção) PIN (desenvolvimento ou conveniência) |
| Tentativas PIN Máx | Tentativas PIN | 3 tentativas |
| Tentativas OTP Máx | Tentativas código OTP | 3 tentativas |
| Expiração OTP | Validade do código | 300 segundos (5 min) |
Funções Admin:
Apenas o admin terá estas funcionalidades adicionais no Telegram, os outros receberão uma mensagem proibida.
- /auth_status: Ver utilizadores autenticados
- /reset_auth: Repor autenticações e bans
Configuração Email (Passo 4/6)
| Campo | Gmail | Outlook | Personalizado |
|---|---|---|---|
| Servidor SMTP | smtp.gmail.com | smtp.outlook.com | seu.servidor.smtp |
| Porta SMTP | 587 (STARTTLS) | 587 (STARTTLS) | 587/465/25 |
| Tipo Segurança | STARTTLS | STARTTLS | Conforme o provedor |
| Nome utilizador | voce@gmail.com | voce@outlook.com | seu.utilizador |
| Password | Password App | Password Normal/App | A sua password |
Na sua conta Gmail:
- Ativar verificação em 2 passos
- Gerar password de aplicação
- Usar Configuração Rápida → preset Gmail (Importante, se preencher manualmente não funcionará)
Configurar destinatários OTP: Adicionar emails que receberão códigos de verificação para ações críticas.
Configuração Monitorização (Passo 5/6)
Funcionalidades de Monitorização
Configurações Básicas de Monitorização
| Parâmetro | Descrição | Valor predefinido |
|---|---|---|
| Intervalo Monitorização (segundos) | Frequência das verificações de estado do sistema | 60 segundos |
Limiares de Recursos
| Métrica | Limiar de Alerta | Tempo de Alerta |
|---|---|---|
| Limiar CPU (%) | 90% | 300 segundos |
| Limiar RAM (%) | 90% | 300 segundos |
| Limiar Disco (%) | 90% | - |
Revisão Final (Passo 6/6)
Verificação final:
Clicar em Finalizar para completar a configuração básica.
Temos uma barra de ações rápidas, onde podemos testar a configuração, ir aos logs, fazer backup da nossa configuração, exportar, importar e gerir backups.
Este backup guardará toda a configuração principal do nosso bot e os clusters que adicionaremos a seguir na secção cluster, já que neste momento o nosso bot não iniciaria porque, embora tenha a configuração principal, não registámos os clusters que queremos gerir, monitorizar e reportar.
Configuração Cluster
Adicionar Clusters Proxmox
Aceder aos Clusters:
- Ir ao menu Clusters
- Clicar em Adicionar Cluster
| Campo | Descrição | Exemplo |
|---|---|---|
| Nome Cluster | Nome descritivo | PVE-LAB |
| URL API | Endpoint Proxmox completo | https://192.168.1.211:8006/api2/ |
| Nome utilizador | Utilizador com permissões API | monitor@pve |
| ID Token | Identificador do token | monitorcluster |
| Token Secret | Segredo do token API | xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx |
Configuração Permissões API
No Proxmox VE:
1. Apenas para monitorização (apenas leitura):
- Função: PVEAuditor
- Permissões: Leitura de estado, recursos e configurações
2. Para gestão completa:
- Funções: PVEAuditor + PVEVMAdmin
- Permissões: Leitura + controle de VMs/LXCs + backups + snapshots
Verificação SSL:
- ✅ Ativada: Para certificados válidos
- ❌ Desativada: Para certificados auto-assinados
Teste de ligação: Se a configuração estiver correta, verá: ✅Ligado com sucesso ao Proxmox VE X.X.X
Gestão de Exclusões
Para que serve? Imagine que tem contentores e máquinas desligadas e liga-as para problemas específicos ou testes, bem pode excluir essas máquinas ou contentores por ID de monitorização. O mesmo com armazenamento, simplesmente colocamos o nome do armazenamento.
Tipos de exclusões:
- Máquinas Virtuais: Excluir VMs por ID (ex: 100, 101, 102)
- Contentores: Excluir LXCs por ID (ex: 200, 201)
- Armazenamento: Excluir armazenamento por nome (ex: local-lvm, backup-storage)
Casos de uso:
- VMs/LXCs de teste ligadas ocasionalmente
- Armazenamento temporário ou de desenvolvimento
- Recursos que não requerem monitorização contínua
Uma vez feito isto, podíamos iniciar o nosso bot, para isso vamos ao dashboard.
Como pode ver o nosso bot não está a correr, temos de clicar em Start para começar a trabalhar.
Uma vez iniciado no nosso chat Telegram se tudo foi configurado corretamente dir-nos-á:
Como é a primeira vez que acedemos pedirá o bot-secret ou pin conforme o método selecionado na segurança
Não poderemos falar com ele até escrevermos o nosso bot secret ou neste caso como selecionámos pin na segurança, o pin. Como sistema de segurança e como mencionámos tem um limite de tentativas e um limite de bans, se cumprir o número de bans, ou seja 3 bans por defeito se não foi alterado, será banido permanentemente.
Cada Ban tem diferentes frases aleatórias e divertidas.
Se selecionou otp na segurança, primeiro pedirá o BOT_SECRET e depois o OTP, portanto, a segurança é muito alta.
Qualquer modificação na configuração ou cluster a partir da interface web, para ser refletida tem de ir ao dashboard e reiniciar o bot.
Com isto teríamos o nosso bot totalmente configurado e funcional. Antes de passar às funcionalidades do bot vamos explicar o resto das secções da interface.
Administração Sistema
Gestão Certificado SSL
Funções disponíveis:
- Ver estado atual: Informações do certificado ativo
- Carregar certificado: Carregar o seu próprio certificado
- CSR: Gerar CSR para autoridade de certificação
- Gerar auto-assinado: Criar novo certificado temporário
- Backup/Restaurar: Gerir backups de certificados
Administração Logs
Características:
- Limpeza manual: Apagar logs mais antigos que N dias
- Limpeza automática: Programada diariamente às 02:00
- Configuração flexível: Retenção personalizável
Configuração Definições Sistema
Informações Perfil:
- Alteração nome utilizador e nome completo
- Configuração email para notificações
- Idioma interface e tema
Segurança:
- Alteração password
- Autenticação de dois fatores (2FA)
- Timeout de sessão
Configuração Email:
- SMTP para notificações da interface web
- Necessário para recuperação de password
- Alertas por email para eventos do sistema
Tipos de Alertas:
Verificação e Testes
Testes de Ligação
Iniciar o bot:
- Ir ao Dashboard
- Clicar em Iniciar Bot
- Verificar estado: "A correr"
Mensagem de boas-vindas:
O bot enviará mensagens de confirmação indicando:
Resolução de Problemas Comuns
Erro: "Token do bot inválido"
Causas:
- Token copiado incorretamente ou incompleto
- Espaços extra no início/fim
- Token regenerado no BotFather
Solução:
- Verificar token completo sem espaços
- Regenerar se necessário: /mybots → selecionar bot → API Token → Revogar token atual
Erro: "Chat não encontrado" para Chat ID
Causas:
- ID incorreto ou não inicializado
- Bot bloqueado pelo utilizador
- Não enviou /start ao bot
Solução:
- Enviar /start ao bot pessoal
- Verificar que bot não está bloqueado
- Confirmar ID positivo para chats pessoais
Erro: "Chat não encontrado" para Chat ID Alertas
Causas:
- Bot não adicionado ao grupo
- ID do grupo incorreto
- Prefixo -100 em falta
Solução:
- Verificar que bot está no grupo
- Tentar com -100 + ID do grupo
- Confirmar permissões do bot no grupo
Erro: "Proibido: bot foi bloqueado"
Solução:
- Ir ao chat com o bot
- Pressionar START ou DESBLOQUEAR
- Reiniciar bot no Dashboard
Melhores Práticas de Segurança
Para Token do Bot
- 🔒 Nunca partilhar token publicamente
- 💾 Guardar em gestor de passwords
- 🔄 Regenerar se comprometido como vimos anteriormente /mybots → selecionar bot → API Token → Revogar token atual
Para Grupos
- 🔐 Manter grupos privados
- 👥 Apenas administradores necessários
- ⚙️ Rever permissões regularmente
Para o Sistema
- 🌐 Não expor à internet, se quiser acesso de outros locais use VPN ou sistemas seguros
- 🛡️ Configurar firewall adequadamente
- 💾 Realizar backups periódicos
- 🔐 Ativar 2FA na interface web e bot
- 📧 Configurar notificações de segurança
Resumo de Configuração
Ao completar este manual terá:
O bot estará completamente operacional para gerir a sua infraestrutura LoboGuard a partir do Telegram com capacidades completas de monitorização, alerta, gestão remota e relatórios.