Documentazione
Introduzione
Descrizione Generale
LoboGuard è una soluzione avanzata e sicura di monitoraggio, avviso, gestione e reporting per infrastrutture Proxmox, che utilizza Telegram come interfaccia di controllo remoto e avviso. Questo manuale fornisce una guida completa per la configurazione iniziale del sistema.
Prerequisiti
- Accesso a Telegram (app mobile, desktop o web)
- Chiave di licenza LoboBrothers valida
- Server LoboGuard distribuito e accessibile
- Cluster Proxmox con accesso API da LoboGuard
Funzionalità Principali
Monitoraggio
Supervisione continua di:
- CPU e Memoria
- Dischi e Stati
- VM/LXC
- Nodi
- Storage
- Reti
- Backup
- CEPH
Avvisi intelligenti
Notifiche automatiche via Telegram con più tipi di avviso:
- Avvisi risorse (CPU, RAM, Disco)
- Avvisi certificati SSL/TLS
- Avvisi sincronizzazione tempo
- Avvisi firewall e sicurezza
- Avvisi Alta Disponibilità
- Avvisi storage Ceph e ZFS
- Avvisi backup e snapshot
- Avvisi abbonamento sistema
Report
Manuali e programmati per:
- Stato Generale
- Stato VM/LXC
- Storage
- Backup
- Reti
- Ceph
Architettura di Sicurezza Avanzata
LoboGuard implementa più livelli di sicurezza per proteggere la tua infrastruttura:
- Autenticazione Multi-Fattore
- Controllo Accesso Granulare
- Protezione Anti-Brute Force
- Audit Completo
- Token Unici
- Timeout di Sessione
Gestione remota
Controllo da Telegram con autenticazione sicura:
- Accensione, spegnimento, riavvio VM/LXC
- Gestione ed esecuzione backup
- Gestione ed esecuzione snapshot
Multi-cluster
Supporto per più ambienti Proxmox secondo la licenza
- Basic 1 cluster
- Pro 3 cluster
- Max 10 cluster
Configurazione Bot Telegram
Accesso BotFather
Passo 1: Accedere all'applicazione Telegram
- Aprire Telegram (mobile, desktop o web)
- Nella barra di ricerca, digitare: @BotFather
- Cliccare sul bot ufficiale verificato con ✅
- Premere START o inviare /start
Creare un Nuovo Bot
Passo 1: Iniziare la creazione
Passo 2: Configurare il nome del bot
- BotFather chiederà il nome del bot
- Rispondere con un nome descrittivo: Bot di Gestione LoboGuard
Passo 3: Configurare il nome utente del bot
- Deve terminare con "bot"
- Deve essere unico su tutta la piattaforma Telegram
- Può contenere solo lettere, numeri e underscore
- Esempio: loboguard_mgmt_bot
Ottenere il Token del Bot
Una volta completato il processo, BotFather fornirà:
- Copiare e salvare il token immediatamente
- NON condividere il token con terzi
- Questo token è la chiave di accesso al tuo bot
ID Telegram
Ottenere il tuo ID Chat Personale
Metodo 1: Utilizzare un bot ausiliario
- Cercare @userinfobot in Telegram
- Inviargli /start
- Il bot risponderà con le tue informazioni:
First: Il Tuo Nome
Lang: it
Metodo 2: Utilizzare il tuo bot
- Inviare /start al tuo bot appena creato
- Aprire nel browser: https://api.telegram.org/bot
/getUpdates - Sostituire
con il tuo token bot - Cercare il campo "id" in "from": 12345678910
Creare e Configurare Gruppo Privato per Avvisi
Passo 1: Creare gruppo privato
- Creare "Nuovo Gruppo" in Telegram
- Nome esempio: "Avvisi LoboGuard"
- Aggiungere amministratori che riceveranno avvisi
Passo 2: Aggiungere bot al gruppo
- Andare alle informazioni del gruppo → Modifica
- Selezionare Aggiungi membri
- Cercare il tuo bot: @loboguard_mgmt_bot
- Aggiungerlo al gruppo
Passo 3: Configurare permessi
Nelle informazioni del gruppo:
Ottenere ID Chat di Gruppo
Metodo semplice: In Telegram Web
- Selezionare il gruppo
- Nella barra del browser: https://web.telegram.org/k/#-4819707521
- L'ID del gruppo è: -4819707521 (sempre con segno negativo per gruppi privati)
Accesso Iniziale e Configurazione
Accesso al Sistema
Passo 1: Accedere al server
- Navigare a: https://IP_SERVER:8443
- Esempio: https://192.168.1.139:8443
Passo 2: Gestire avviso certificato
I browser mostreranno avvisi come:
- Chrome: "La tua connessione non è privata"
- Firefox: "Avviso: Potenziale rischio di sicurezza"
Passo 3: Accettare certificato
- Cliccare su Impostazioni avanzate
- Selezionare Continua verso [IP] (non sicuro)
Il certificato auto-firmato è sicuro e uno nuovo viene generato ad ogni installazione, anche se per evitare avvisi del browser, puoi successivamente caricare il tuo certificato SSL dall'interfaccia di amministrazione.
Primo Accesso e Cambio Password
Credenziali predefinite:
Password: guard
Cambio password obbligatorio: Il sistema reindirizzerà automaticamente al cambio password.
Requisiti nuova password:
Accedere al Pannello Configurazione
Una volta cambiata la password:
- Cliccare su Configurazione nel menu superiore
- Accederai alla procedura guidata di configurazione passo dopo passo
Configurazione Bot (Procedura Guidata)
La procedura guidata guida attraverso 6 passaggi essenziali per configurare completamente LoboGuard.
Configurazione Licenza (Passo 1/6)
Configurazione:
- Inserire la chiave di licenza fornita da LoboBrothers
- Cliccare Avanti per validare
Una volta attivata su una macchina, la licenza non può essere trasferita su un'altra. Per modifiche, contattare il supporto.
Configurazione Telegram (Passo 2/6)
| Campo | Descrizione | Esempio |
|---|---|---|
| Token Bot | Token completo da BotFather | 8452961006:AAHWhRkptJ937RgUgd5vC-Ml6biyyrME76I |
| Chat ID | ID personale per gestione | 123456789 |
| Chat ID Avvisi | ID gruppo per avvisi | -123456789 o -100123456789 |
Se ci sono problemi con il Chat ID Avvisi, prova ad aggiungere il prefisso -100 prima dell'ID gruppo, a volte l'ID reale per l'API è con -100 davanti.
Testare connessione: Cliccare su Testa connessione Telegram. Se riuscito, riceverai messaggi di conferma in entrambe le chat.
Configurazione Sicurezza (Passo 3/6)
| Parametro | Descrizione | Raccomandazione |
|---|---|---|
| Bot Secret | Chiave di accesso iniziale | Usare password sicura |
| ID Admin | Super amministratore del bot | Il tuo Chat ID personale |
| Durata Ban | Tempo di blocco dopo errori | 3600 secondi (1 ora) |
| Max Tentativi Auth | Tentativi prima del ban | 5 tentativi |
| Max Conteggio Ban | Quanti ban prima del ban permanente | 3 tentativi |
| Metodo Conferma | PIN e OTP (per azioni critiche) | OTP (più sicuro e raccomandato per produzione) PIN (sviluppo o comodità) |
| Max Tentativi PIN | Tentativi PIN | 3 tentativi |
| Max Tentativi OTP | Tentativi codice OTP | 3 tentativi |
| Scadenza OTP | Validità codice | 300 secondi (5 min) |
Funzioni Admin:
Solo l'admin avrà queste funzionalità aggiuntive in Telegram, gli altri riceveranno un messaggio proibito.
- /auth_status: Vedere utenti autenticati
- /reset_auth: Resettare autenticazioni e ban
Configurazione Email (Passo 4/6)
| Campo | Gmail | Outlook | Personalizzato |
|---|---|---|---|
| Server SMTP | smtp.gmail.com | smtp.outlook.com | tuo.server.smtp |
| Porta SMTP | 587 (STARTTLS) | 587 (STARTTLS) | 587/465/25 |
| Tipo Sicurezza | STARTTLS | STARTTLS | Secondo il provider |
| Nome utente | tu@gmail.com | tu@outlook.com | tuo.utente |
| Password | Password App | Password Normale/App | La tua password |
Nel tuo account Gmail:
- Abilitare verifica in 2 passaggi
- Generare password applicazione
- Usare Configurazione Rapida → preset Gmail (Importante, se compili manualmente non funzionerà)
Configurare destinatari OTP: Aggiungere email che riceveranno codici di verifica per azioni critiche.
Configurazione Monitoraggio (Passo 5/6)
Funzionalità Monitoraggio
Impostazioni Monitoraggio Base
| Parametro | Descrizione | Valore predefinito |
|---|---|---|
| Intervallo Monitoraggio (secondi) | Frequenza controlli stato sistema | 60 secondi |
Soglie Risorse
| Metrica | Soglia Avviso | Tempo Avviso |
|---|---|---|
| Soglia CPU (%) | 90% | 300 secondi |
| Soglia RAM (%) | 90% | 300 secondi |
| Soglia Disco (%) | 90% | - |
Revisione Finale (Passo 6/6)
Verifica finale:
Cliccare Fine per completare la configurazione base.
Abbiamo una barra azioni rapide, dove possiamo testare la configurazione, andare ai log, fare backup della nostra configurazione, esportare, importare e gestire backup.
Questo backup salverà tutta la configurazione principale del nostro bot e i cluster che aggiungeremo successivamente nella sezione cluster, dato che al momento il nostro bot non si avvierebbe perché, anche se ha la configurazione principale, non abbiamo registrato i cluster che vogliamo gestire, monitorare e reportare.
Configurazione Cluster
Aggiungere Cluster Proxmox
Accedere ai Cluster:
- Andare al menu Cluster
- Cliccare Aggiungi Cluster
| Campo | Descrizione | Esempio |
|---|---|---|
| Nome Cluster | Nome descrittivo | PVE-LAB |
| URL API | Endpoint Proxmox completo | https://192.168.1.211:8006/api2/ |
| Nome utente | Utente con permessi API | monitor@pve |
| ID Token | Identificatore token | monitorcluster |
| Token Secret | Secret token API | xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx |
Configurazione Permessi API
In Proxmox VE:
1. Solo per monitoraggio (sola lettura):
- Ruolo: PVEAuditor
- Permessi: Lettura stato, risorse e configurazioni
2. Per gestione completa:
- Ruoli: PVEAuditor + PVEVMAdmin
- Permessi: Lettura + controllo VM/LXC + backup + snapshot
Verifica SSL:
- ✅ Abilitata: Per certificati validi
- ❌ Disabilitata: Per certificati auto-firmati
Test connessione: Se la configurazione è corretta, vedrai: ✅Connesso con successo a Proxmox VE X.X.X
Gestione Esclusioni
A cosa serve? Immagina di avere container e macchine spente e le accendi per problemi specifici o test, bene puoi escludere quelle macchine o container per ID di monitoraggio. Lo stesso con lo storage, mettiamo semplicemente il nome dello storage.
Tipi di esclusioni:
- Macchine Virtuali: Escludere VM per ID (es: 100, 101, 102)
- Container: Escludere LXC per ID (es: 200, 201)
- Storage: Escludere storage per nome (es: local-lvm, backup-storage)
Casi d'uso:
- VM/LXC di test accese occasionalmente
- Storage temporaneo o di sviluppo
- Risorse che non richiedono monitoraggio continuo
Una volta fatto questo, potremmo avviare il nostro bot, per questo andiamo alla dashboard.
Come puoi vedere il nostro bot non è in esecuzione, dobbiamo cliccare Start per iniziare a lavorare.
Una volta avviato nella nostra chat Telegram se tutto è stato configurato correttamente ci dirà:
Dato che è la prima volta che vi accediamo chiederà il bot-secret o pin secondo il metodo selezionato nella sicurezza
Non potremo parlargli finché non scriviamo il nostro bot secret o in questo caso dato che abbiamo selezionato pin nella sicurezza, il pin. Come sistema di sicurezza e come abbiamo menzionato ha un limite di tentativi e un limite di ban, se completi il numero di ban, cioè 3 ban per default se non è stato cambiato, sarà bannato permanentemente.
Ogni Ban ha diverse frasi casuali e divertenti.
Se hai selezionato otp nella sicurezza, prima chiederà il BOT_SECRET e poi l'OTP, pertanto, la sicurezza è molto alta.
Qualsiasi modifica nella configurazione o cluster dall'interfaccia web, perché sia riflessa devi andare alla dashboard e riavviare il bot.
Con questo avremmo il nostro bot totalmente configurato e funzionante. Prima di passare alle funzionalità del bot spiegheremo il resto delle sezioni dell'interfaccia.
Amministrazione Sistema
Gestione Certificato SSL
Funzioni disponibili:
- Vedere stato attuale: Informazioni certificato attivo
- Caricare certificato: Caricare il proprio certificato
- CSR: Generare CSR per autorità di certificazione
- Generare auto-firmato: Creare nuovo certificato temporaneo
- Backup/Ripristino: Gestire backup certificati
Amministrazione Log
Caratteristiche:
- Pulizia manuale: Eliminare log più vecchi di N giorni
- Pulizia automatica: Programmata quotidianamente alle 02:00
- Configurazione flessibile: Conservazione personalizzabile
Configurazione Impostazioni Sistema
Informazioni Profilo:
- Cambio nome utente e nome completo
- Configurazione email per notifiche
- Lingua interfaccia e tema
Sicurezza:
- Cambio password
- Autenticazione a due fattori (2FA)
- Timeout sessione
Configurazione Email:
- SMTP per notifiche interfaccia web
- Richiesto per recupero password
- Avvisi email per eventi sistema
Tipi di Avvisi:
Verifica e Test
Test di Connessione
Avviare il bot:
- Andare alla Dashboard
- Cliccare Avvia Bot
- Verificare stato: "In esecuzione"
Messaggio di benvenuto:
Il bot invierà messaggi di conferma indicando:
Risoluzione Problemi Comuni
Errore: "Token bot non valido"
Cause:
- Token copiato male o incompleto
- Spazi extra all'inizio/fine
- Token rigenerato in BotFather
Soluzione:
- Verificare token completo senza spazi
- Rigenerare se necessario: /mybots → seleziona bot → API Token → Revoca token attuale
Errore: "Chat non trovata" per Chat ID
Cause:
- ID errato o non inizializzato
- Bot bloccato dall'utente
- Non ha inviato /start al bot
Soluzione:
- Inviare /start al bot personale
- Verificare che bot non sia bloccato
- Confermare ID positivo per chat personali
Errore: "Chat non trovata" per Chat ID Avvisi
Cause:
- Bot non aggiunto al gruppo
- ID gruppo errato
- Prefisso -100 mancante
Soluzione:
- Verificare che bot sia nel gruppo
- Provare con -100 + ID gruppo
- Confermare permessi bot nel gruppo
Errore: "Proibito: bot è stato bloccato"
Soluzione:
- Andare alla chat con il bot
- Premere START o SBLOCCA
- Riavviare bot nella Dashboard
Best Practice di Sicurezza
Per Token Bot
- 🔒 Mai condividere token pubblicamente
- 💾 Salvare in gestore password
- 🔄 Rigenerare se compromesso come visto prima /mybots → seleziona bot → API Token → Revoca token attuale
Per Gruppi
- 🔐 Mantenere gruppi privati
- 👥 Solo amministratori necessari
- ⚙️ Rivedere permessi regolarmente
Per il Sistema
- 🌐 Non esporre a internet, se vuoi accesso da altri posti usa VPN o sistemi sicuri
- 🛡️ Configurare firewall appropriatamente
- 💾 Eseguire backup periodici
- 🔐 Attivare 2FA in interfaccia web e bot
- 📧 Configurare notifiche sicurezza
Riepilogo Configurazione
Al completamento di questo manuale avrai:
Il bot sarà completamente operativo per gestire la tua infrastruttura LoboGuard da Telegram con capacità complete di monitoraggio, avviso, gestione remota e reporting.