Documentation
Introduction
General Description
LoboGuard is an advanced and secure monitoring, alerting, management, and reporting solution for Proxmox infrastructures, using Telegram as its remote control and alerting interface. This manual provides a complete guide for initial system setup.
Prerequisites
- Access to Telegram (mobile app, desktop or web)
- Valid LoboBrothers license key
- LoboGuard server deployed and accessible
- Proxmox clusters with API access from LoboGuard
Main Features
Monitoring
Continuous supervision of:
- CPU and Memory
- Disk and Status
- VMs/LXCs
- Nodes
- Storage
- Networks
- Backups
- CEPH
Intelligent alerts
Automatic notifications via Telegram with multiple alert types:
- Resource alerts (CPU, RAM, Disk)
- SSL/TLS certificate alerts
- Time synchronization alerts
- Firewall and security alerts
- High Availability alerts
- Ceph and ZFS storage alerts
- Backup and snapshot alerts
- System subscription alerts
Reports
Manual and scheduled for:
- General Status
- VM/LXC Status
- Storage
- Backups
- Networks
- Ceph
Advanced Security Architecture
LoboGuard implements multiple security layers to protect your infrastructure:
- Multi-Factor Authentication
- Granular Access Control
- Anti-Brute Force Protection
- Complete Auditing
- Unique Tokens
- Session Timeouts
Remote management
Control from Telegram with secure authentication:
- Power on, off, restart VMs/LXCs
- Backup management and execution
- Snapshot management and execution
Multi-cluster
Support for multiple Proxmox environments depending on the license
- Basic 1 cluster
- Pro 3 cluster
- Max 10 cluster
Telegram Bot Setup
BotFather Access
Step 1: Access Telegram application
- Open Telegram (mobile, desktop or web)
- In the search bar, type: @BotFather
- Click on the official verified bot with ✅
- Press START or send /start
Create New Bot
Step 1: Start creation
Step 2: Configure bot name
- BotFather will ask for the bot name
- Respond with a descriptive name: LoboGuard Management Bot
Step 3: Configure bot username
- Must end with "bot"
- Must be unique across the entire Telegram platform
- Can only contain letters, numbers and underscores
- Example: loboguard_mgmt_bot
Get Bot Token
Once the process is complete, BotFather will provide:
- Copy and save the token immediately
- DO NOT share the token with third parties
- This token is the access key to your bot
Telegram IDs
Get Your Personal Chat ID
Method 1: Using auxiliary bot
- Search for @userinfobot in Telegram
- Send /start to it
- The bot will respond with your information:
First: Your Name
Lang: en
Method 2: Using your own bot
- Send /start to your newly created bot
- Open in browser: https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates
- Replace <YOUR_TOKEN> with your bot token
- Look for the "id" field in "from": 12345678910
Create and Configure Private Group for Alerts
Step 1: Create private group
- Create "New Group" in Telegram
- Example name: "LoboGuard Alerts"
- Add administrators who will receive alerts
Step 2: Add bot to group
- Go to group information → Edit
- Select Add members
- Search for your bot: @loboguard_mgmt_bot
- Add it to the group
Step 3: Configure permissions
In the group information:
Get Group Chat ID
Simple method: In Telegram Web
- Select the group
- In the browser bar: https://web.telegram.org/k/#-4819707521
- The group ID is: -4819707521 (always with negative sign for private groups)
Initial Access and Configuration
System Access
Step 1: Access the server
- Navigate to: https://SERVER_IP:8443
- Example: https://192.168.1.139:8443
Step 2: Handle certificate warning
Browsers will show warnings such as:
- Chrome: "Your connection is not private"
- Firefox: "Warning: Potential Security Risk"
Step 3: Accept certificate
- Click on Advanced settings
- Select Continue to [IP] (not secure)
The self-signed certificate is secure and a new one is generated with each installation, although if you want to avoid browser warnings, you can later upload your own SSL certificate from the administration interface.
First Access and Password Change
Default credentials:
Password: guard
Mandatory password change: The system will automatically redirect to password change.
New password requirements:
Access Configuration Panel
Once the password is changed:
- Click on Configuration in the top menu
- You will access the step-by-step configuration wizard
Bot Configuration (Wizard)
The wizard guides through 6 essential steps to completely configure LoboGuard.
License Configuration (Step 1/6)
Configuration:
- Enter the license key provided by LoboBrothers
- Click Next to validate
Once activated on a machine, the license cannot be transferred to another. For changes, contact support.
Telegram Configuration (Step 2/6)
| Field | Description | Example |
|---|---|---|
| Bot Token | Complete token from BotFather | 8452961006:AAHWhRkptJ937RgUgd5vC-Ml6biyyrME76I |
| Chat ID | Personal ID for management | 123456789 |
| Alert Chat ID | Group ID for alerts | -123456789 or -100123456789 |
If there are problems with the Alert Chat ID, try adding the -100 prefix before the group ID, sometimes the real ID for the API is with -100 in front.
Test connection: Click on Test Telegram connection. If successful, you will receive confirmation messages in both chats.
Security Configuration (Step 3/6)
| Parameter | Description | Recommendation |
|---|---|---|
| Bot Secret | Initial access key | Use secure password |
| Admin ID | Bot superadministrator | Your personal Chat ID |
| Ban Duration | Block time after failures | 3600 seconds (1 hour) |
| Max Auth Attempts | Attempts before ban | 5 attempts |
| Max Ban Count | How many bans before permanent ban | 3 attempts |
| Confirmation Method | PIN and OTP (for critical actions) | OTP (more secure and recommended for production) PIN (development or convenience) |
| Max PIN Attempts | PIN attempts | 3 attempts |
| Max OTP Attempts | OTP code attempts | 3 attempts |
| OTP Expiration | Code validity | 300 seconds (5 min) |
Admin Functions:
Only the admin will have these extra functionalities in Telegram, the rest will get a forbidden message.
- /auth_status: View authenticated users
- /reset_auth: Reset authentications and bans
Email Configuration (Step 4/6)
| Field | Gmail | Outlook | Custom |
|---|---|---|---|
| SMTP Server | smtp.gmail.com | smtp.outlook.com | your.smtp.server |
| SMTP Port | 587 (STARTTLS) | 587 (STARTTLS) | 587/465/25 |
| Security Type | STARTTLS | STARTTLS | According to provider |
| Username | you@gmail.com | you@outlook.com | your.user |
| Password | App Password | Normal/App Password | Your password |
In your Gmail account:
- Enable 2-step verification
- Generate application password
- Use Quick Setup → Gmail preset (Important, if you fill manually, it won't work)
Configure OTP recipients: Add emails that will receive verification codes for critical actions.
Monitoring Configuration (Step 5/6)
Monitoring Features
Basic Monitoring Settings
| Parameter | Description | Default Value |
|---|---|---|
| Monitor Interval (seconds) | Frequency of system status checks | 60 seconds |
Resource Thresholds
| Metric | Alert Threshold | Alert Time |
|---|---|---|
| CPU Threshold (%) | 90% | 300 seconds |
| RAM Threshold (%) | 90% | 300 seconds |
| Disk Threshold (%) | 90% | - |
Final Review (Step 6/6)
Final verification:
Click Finish to complete the basic configuration.
We have a quick actions bar, where we can test the configuration, go to logs, backup our configuration, export, import and manage backups.
This backup will save all the main configuration of our bot and the clusters that we add next in the cluster section, since at the moment our bot would not start because, although it has the main configuration, we have not registered the clusters that we want to manage, monitor and report.
Cluster Configuration
Add Proxmox Clusters
Access Clusters:
- Go to Clusters menu
- Click Add Cluster
| Field | Description | Example |
|---|---|---|
| Cluster Name | Descriptive name | PVE-LAB |
| API URL | Complete Proxmox endpoint | https://192.168.1.211:8006/api2/ |
| Username | User with API permissions | monitor@pve |
| Token ID | Token identifier | monitorcluster |
| Token Secret | API token secret | xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx |
API Permissions Configuration
In Proxmox VE:
1. For monitoring only (read-only):
- Role: PVEAuditor
- Permissions: Reading status, resources and configurations
2. For complete management:
- Roles: PVEAuditor + PVEVMAdmin
- Permissions: Reading + control of VMs/LXCs + backups + snapshots
SSL Verification:
- ✅ Enabled: For valid certificates
- ❌ Disabled: For self-signed certificates
Connection test: If the configuration is correct, you will see: ✅Connected successfully to Proxmox VE X.X.X
Exclusions Management
What is this for? Imagine you have containers and machines turned off and you turn them on for specific issues or tests, well you can exclude those machines or containers by monitoring ID. The same with storage, we simply put the storage name.
Types of exclusions:
- Virtual Machines: Exclude VMs by ID (e.g: 100, 101, 102)
- Containers: Exclude LXCs by ID (e.g: 200, 201)
- Storage: Exclude storage by name (e.g: local-lvm, backup-storage)
Use cases:
- Test VMs/LXCs that are turned on occasionally
- Temporary or development storage
- Resources that do not require continuous monitoring
Once this is done, we could start our bot, for this we go to the dashboard.
As you can see our bot is not running, we must click Start to start working.
Once started in our Telegram chat if everything has been correctly configured it will tell us:
As it is the first time we access it will ask for the bot-secret or pin according to the method selected in security
We will not be able to talk to it until we write our bot secret or in this case as we selected pin in security, the pin. As a security system and as we have mentioned it has a limit of attempts and a limit of bans, if you fulfill the number of bans, that is, 3 bans by default if it was not changed, it will be banned permanently.
Each Ban has different random and fun phrases.
If you selected otp in security, first it will ask for the BOT_SECRET and then the OTP, therefore, the security is very high.
Any modification in the configuration or cluster from the web interface, for it to be reflected you have to go to the dashboard and restart the bot.
With this we would have our bot totally configured and working. Before moving on to the bot functionalities we are going to explain the rest of the interface sections.
System Administration
SSL Certificate Management
Available functions:
- View current status: Active certificate information
- Upload certificate: Upload your own certificate
- CSR: Generate CSR for certificate authority
- Generate self-signed: Create new temporary certificate
- Backup/Restore: Manage certificate backups
Log Administration
Characteristics:
- Manual cleanup: Delete logs older than N days
- Automatic cleanup: Scheduled daily at 02:00
- Flexible configuration: Customizable retention
System Settings Configuration
Profile Information:
- Username and full name change
- Email configuration for notifications
- Interface language and theme
Security:
- Password change
- Two-factor authentication (2FA)
- Session timeout
Email Configuration:
- SMTP for web interface notifications
- Required for password recovery
- Email alerts for system events
Alert Types:
Verification and Testing
Connection Tests
Start the bot:
- Go to Dashboard
- Click Start Bot
- Verify status: "Running"
Welcome message:
The bot will send confirmation messages indicating:
Common Problems Troubleshooting
Error: "Bot token invalid"
Causes:
- Token badly copied or incomplete
- Extra spaces at beginning/end
- Token regenerated in BotFather
Solution:
- Verify complete token without spaces
- Regenerate if necessary: /mybots → select bot → API Token → Revoke current token
Error: "Chat not found" for Chat ID
Causes:
- Incorrect or uninitialized ID
- Bot blocked by user
- Has not sent /start to bot
Solution:
- Send /start to personal bot
- Verify bot is not blocked
- Confirm positive ID for personal chats
Error: "Chat not found" for Alert Chat ID
Causes:
- Bot not added to group
- Incorrect group ID
- Missing -100 prefix
Solution:
- Verify bot is in the group
- Try with -100 + group ID
- Confirm bot permissions in group
Error: "Forbidden: bot was blocked"
Solution:
- Go to chat with the bot
- Press START or UNBLOCK
- Restart bot in Dashboard
Security Best Practices
For Bot Token
- 🔒 Never share the token publicly
- 💾 Save in password manager
- 🔄 Regenerate if compromised as we saw previously /mybots → select bot → API Token → Revoke current token
For Groups
- 🔐 Keep groups private
- 👥 Only necessary administrators
- ⚙️ Review permissions regularly
For the System
- 🌐 Do not expose to internet, if you want access from other places use VPN or secure systems
- 🛡️ Configure firewall appropriately
- 💾 Perform periodic backups
- 🔐 Activate 2FA in web interface and bot
- 📧 Configure security notifications
Configuration Summary
Upon completing this manual you will have:
The bot will be completely operational to manage your LoboGuard infrastructure from Telegram with complete monitoring, alerting, remote management and reporting capabilities.