Documentación
Introducción
Descripción General
LoboGuard es una solución avanzada y segura de monitoreo, alertas, gestión y reportes para infraestructuras Proxmox, utilizando Telegram como interfaz de control remoto y alertas. Este manual proporciona una guía completa para la configuración inicial del sistema.
Requisitos Previos
- Acceso a Telegram (app móvil, desktop o web)
- Clave de licencia LoboBrothers válida
- Servidor LoboGuard desplegado y accesible
- Clústeres Proxmox con acceso API desde LoboGuard
Funcionalidades Principales
Monitoreo
Supervisión continua de:
- CPU y Memoria
- Discos y Estados
- VMs/LXCs
- Nodos
- Almacenamiento
- Redes
- Backups
- CEPH
Alertas inteligentes
Notificaciones automáticas vía Telegram con múltiples tipos de alerta:
- Alertas de recursos (CPU, RAM, Disco)
- Alertas de certificados SSL/TLS
- Alertas de sincronización de tiempo
- Alertas de firewall y seguridad
- Alertas de Alta Disponibilidad
- Alertas de almacenamiento Ceph y ZFS
- Alertas de backups y snapshots
- Alertas de suscripción del sistema
Reportes
Manuales y programados para:
- Estado General
- Estado VM/LXC
- Almacenamiento
- Backups
- Redes
- Ceph
Arquitectura de Seguridad Avanzada
LoboGuard implementa múltiples capas de seguridad para proteger su infraestructura:
- Autenticación Multi-Factor
- Control de Acceso Granular
- Protección Anti-Fuerza Bruta
- Auditoría Completa
- Tokens Únicos
- Timeouts de Sesión
Gestión remota
Control desde Telegram con autenticación segura:
- Encender, apagar, reiniciar VMs/LXCs
- Gestión y ejecución de backups
- Gestión y ejecución de snapshots
Multi-clúster
Soporte para múltiples entornos Proxmox según la licencia
- Basic 1 clúster
- Pro 3 clústeres
- Max 10 clústeres
Configuración Bot Telegram
Acceso a BotFather
Paso 1: Acceder a la aplicación Telegram
- Abrir Telegram (móvil, desktop o web)
- En la barra de búsqueda, escribir: @BotFather
- Hacer clic en el bot oficial verificado con ✅
- Presionar START o enviar /start
Crear Nuevo Bot
Paso 1: Iniciar la creación
Paso 2: Configurar nombre del bot
- BotFather pedirá el nombre del bot
- Responder con un nombre descriptivo: Bot de Gestión LoboGuard
Paso 3: Configurar nombre de usuario del bot
- Debe terminar con "bot"
- Debe ser único en toda la plataforma Telegram
- Solo puede contener letras, números y guiones bajos
- Ejemplo: loboguard_mgmt_bot
Obtener Token del Bot
Una vez completado el proceso, BotFather proporcionará:
- Copiar y guardar el token inmediatamente
- NO compartir el token con terceros
- Este token es la clave de acceso a tu bot
IDs Telegram
Obtener tu ID de Chat Personal
Método 1: Usar bot auxiliar
- Buscar @userinfobot en Telegram
- Enviarle /start
- El bot responderá con tu información:
First: Tu Nombre
Lang: es
Método 2: Usar tu propio bot
- Enviar /start a tu bot recién creado
- Abrir en el navegador: https://api.telegram.org/bot
/getUpdates - Reemplazar
con tu token del bot - Buscar el campo "id" en "from": 12345678910
Crear y Configurar Grupo Privado para Alertas
Paso 1: Crear grupo privado
- Crear "Nuevo Grupo" en Telegram
- Nombre de ejemplo: "Alertas LoboGuard"
- Añadir administradores que recibirán alertas
Paso 2: Añadir bot al grupo
- Ir a información del grupo → Editar
- Seleccionar Añadir miembros
- Buscar tu bot: @loboguard_mgmt_bot
- Añadirlo al grupo
Paso 3: Configurar permisos
En la información del grupo:
Obtener ID del Chat de Grupo
Método simple: En Telegram Web
- Seleccionar el grupo
- En la barra del navegador: https://web.telegram.org/k/#-4819707521
- El ID del grupo es: -4819707521 (siempre con signo negativo para grupos privados)
Acceso Inicial y Configuración
Acceso al Sistema
Paso 1: Acceder al servidor
- Navegar a: https://IP_SERVIDOR:8443
- Ejemplo: https://192.168.1.139:8443
Paso 2: Manejar advertencia del certificado
Los navegadores mostrarán advertencias como:
- Chrome: "Tu conexión no es privada"
- Firefox: "Advertencia: Riesgo de seguridad potencial"
Paso 3: Aceptar certificado
- Hacer clic en Configuración avanzada
- Seleccionar Continuar a [IP] (no seguro)
El certificado auto-firmado es seguro y se genera uno nuevo con cada instalación, aunque si quieres evitar las advertencias del navegador, puedes más tarde subir tu propio certificado SSL desde la interfaz de administración.
Primer Acceso y Cambio de Contraseña
Credenciales por defecto:
Contraseña: guard
Cambio de contraseña obligatorio: El sistema redirigirá automáticamente al cambio de contraseña.
Requisitos de la nueva contraseña:
Acceder al Panel de Configuración
Una vez cambiada la contraseña:
- Hacer clic en Configuración en el menú superior
- Accederás al asistente de configuración paso a paso
Configuración Bot (Asistente)
El asistente guía a través de 6 pasos esenciales para configurar completamente LoboGuard.
Configuración de Licencia (Paso 1/6)
Configuración:
- Introducir la clave de licencia proporcionada por LoboBrothers
- Hacer clic en Siguiente para validar
Una vez activada en una máquina, la licencia no puede transferirse a otra. Para cambios, contactar al soporte.
Configuración de Telegram (Paso 2/6)
| Campo | Descripción | Ejemplo |
|---|---|---|
| Token Bot | Token completo de BotFather | 8452961006:AAHWhRkptJ937RgUgd5vC-Ml6biyyrME76I |
| Chat ID | ID personal para gestión | 123456789 |
| Chat ID Alertas | ID del grupo para alertas | -123456789 o -100123456789 |
Si hay problemas con el Chat ID Alertas, intenta añadir el prefijo -100 antes del ID del grupo, a veces el ID real para la API es con -100 delante.
Probar conexión: Hacer clic en Probar conexión Telegram. Si es exitoso, recibirás mensajes de confirmación en ambos chats.
Configuración de Seguridad (Paso 3/6)
| Parámetro | Descripción | Recomendación |
|---|---|---|
| Bot Secret | Clave de acceso inicial | Usar contraseña segura |
| ID Admin | Super administrador del bot | Tu Chat ID personal |
| Duración Ban | Tiempo de bloqueo tras fallos | 3600 segundos (1 hora) |
| Intentos Auth Máx | Intentos antes del ban | 5 intentos |
| Conteo Ban Máx | Cuántos bans antes del ban permanente | 3 intentos |
| Método Confirmación | PIN y OTP (para acciones críticas) | OTP (más seguro y recomendado para producción) PIN (desarrollo o comodidad) |
| Intentos PIN Máx | Intentos PIN | 3 intentos |
| Intentos OTP Máx | Intentos código OTP | 3 intentos |
| Expiración OTP | Validez del código | 300 segundos (5 min) |
Funciones Admin:
Solo el admin tendrá estas funcionalidades adicionales en Telegram, el resto recibirán un mensaje prohibido.
- /auth_status: Ver usuarios autenticados
- /reset_auth: Resetear autenticaciones y bans
Configuración de Email (Paso 4/6)
| Campo | Gmail | Outlook | Personalizado |
|---|---|---|---|
| Servidor SMTP | smtp.gmail.com | smtp.outlook.com | tu.servidor.smtp |
| Puerto SMTP | 587 (STARTTLS) | 587 (STARTTLS) | 587/465/25 |
| Tipo Seguridad | STARTTLS | STARTTLS | Según proveedor |
| Nombre de usuario | tu@gmail.com | tu@outlook.com | tu.usuario |
| Contraseña | Contraseña App | Contraseña Normal/App | Tu contraseña |
En tu cuenta Gmail:
- Habilitar verificación en 2 pasos
- Generar contraseña de aplicación
- Usar Configuración Rápida → preset Gmail (Importante, si rellenas manualmente no funcionará)
Configurar destinatarios OTP: Añadir emails que recibirán códigos de verificación para acciones críticas.
Configuración de Monitoreo (Paso 5/6)
Características de Monitoreo
Configuraciones Básicas de Monitoreo
| Parámetro | Descripción | Valor por defecto |
|---|---|---|
| Intervalo Monitoreo (segundos) | Frecuencia de verificaciones de estado del sistema | 60 segundos |
Umbrales de Recursos
| Métrica | Umbral de Alerta | Tiempo de Alerta |
|---|---|---|
| Umbral CPU (%) | 90% | 300 segundos |
| Umbral RAM (%) | 90% | 300 segundos |
| Umbral Disco (%) | 90% | - |
Revisión Final (Paso 6/6)
Verificación final:
Hacer clic en Finalizar para completar la configuración básica.
Tenemos una barra de acciones rápidas, donde podemos probar la configuración, ir a logs, respaldar nuestra configuración, exportar, importar y gestionar backups.
Este backup guardará toda la configuración principal de nuestro bot y los clústeres que añadiremos después en la sección de clúster, ya que por el momento nuestro bot no arrancaría porque, aunque tiene la configuración principal, no hemos registrado los clústeres que queremos gestionar, monitorear y reportar.
Configuración de Clúster
Añadir Clústeres Proxmox
Acceder a Clústeres:
- Ir al menú Clústeres
- Hacer clic en Añadir Clúster
| Campo | Descripción | Ejemplo |
|---|---|---|
| Nombre Clúster | Nombre descriptivo | PVE-LAB |
| URL API | Endpoint Proxmox completo | https://192.168.1.211:8006/api2/ |
| Nombre de usuario | Usuario con permisos API | monitor@pve |
| ID Token | Identificador del token | monitorcluster |
| Token Secret | Secreto del token API | xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx |
Configuración de Permisos API
En Proxmox VE:
1. Solo para monitoreo (solo lectura):
- Rol: PVEAuditor
- Permisos: Lectura de estado, recursos y configuraciones
2. Para gestión completa:
- Roles: PVEAuditor + PVEVMAdmin
- Permisos: Lectura + control de VMs/LXCs + backups + snapshots
Verificación SSL:
- ✅ Habilitada: Para certificados válidos
- ❌ Deshabilitada: Para certificados auto-firmados
Prueba de conexión: Si la configuración es correcta, verás: ✅Conectado exitosamente a Proxmox VE X.X.X
Gestión de Exclusiones
¿Para qué sirve? Imagina que tienes contenedores y máquinas apagadas y las enciendes para problemas específicos o pruebas, pues puedes excluir esas máquinas o contenedores por ID de monitoreo. Lo mismo con almacenamiento, simplemente ponemos el nombre del almacenamiento.
Tipos de exclusiones:
- Máquinas Virtuales: Excluir VMs por ID (ej: 100, 101, 102)
- Contenedores: Excluir LXCs por ID (ej: 200, 201)
- Almacenamiento: Excluir almacenamiento por nombre (ej: local-lvm, backup-storage)
Casos de uso:
- VMs/LXCs de prueba que se encienden ocasionalmente
- Almacenamiento temporal o de desarrollo
- Recursos que no requieren monitoreo continuo
Una vez hecho esto, podríamos iniciar nuestro bot, para eso vamos al dashboard.
Como puedes ver nuestro bot no está funcionando, debemos hacer clic en Start para comenzar a trabajar.
Una vez iniciado en nuestro chat de Telegram si todo ha sido configurado correctamente nos dirá:
Como es la primera vez que accedemos pedirá el bot-secret o pin según el método seleccionado en seguridad
No podremos hablar con él hasta que escribamos nuestro bot secret o en este caso como seleccionamos pin en seguridad, el pin. Como sistema de seguridad y como hemos mencionado tiene un límite de intentos y un límite de bans, si cumples el número de bans, es decir 3 bans por defecto si no se cambió, será baneado permanentemente.
Cada Ban tiene diferentes frases aleatorias y divertidas.
Si seleccionaste otp en seguridad, primero pedirá el BOT_SECRET y luego el OTP, por tanto, la seguridad es muy alta.
Cualquier modificación en la configuración o clúster desde la interfaz web, para que se refleje debes ir al dashboard y reiniciar el bot.
Con esto tendríamos nuestro bot totalmente configurado y funcionando. Antes de pasar a las funcionalidades del bot vamos a explicar el resto de las secciones de la interfaz.
Administración del Sistema
Gestión de Certificado SSL
Funciones disponibles:
- Ver estado actual: Información del certificado activo
- Subir certificado: Subir tu propio certificado
- CSR: Generar CSR para autoridad de certificación
- Generar auto-firmado: Crear nuevo certificado temporal
- Backup/Restaurar: Gestionar backups de certificados
Administración de Logs
Características:
- Limpieza manual: Eliminar logs más antiguos que N días
- Limpieza automática: Programada diariamente a las 02:00
- Configuración flexible: Retención personalizable
Configuración de Ajustes del Sistema
Información del Perfil:
- Cambio de nombre de usuario y nombre completo
- Configuración de email para notificaciones
- Idioma de la interfaz y tema
Seguridad:
- Cambio de contraseña
- Autenticación de dos factores (2FA)
- Timeout de sesión
Configuración de Email:
- SMTP para notificaciones de interfaz web
- Requerido para recuperación de contraseña
- Alertas por email para eventos del sistema
Tipos de Alertas:
Verificación y Pruebas
Pruebas de Conexión
Iniciar el bot:
- Ir al Dashboard
- Hacer clic en Iniciar Bot
- Verificar estado: "Ejecutándose"
Mensaje de bienvenida:
El bot enviará mensajes de confirmación indicando:
Solución de Problemas Comunes
Error: "Token del bot inválido"
Causas:
- Token copiado mal o incompleto
- Espacios extra al principio/final
- Token regenerado en BotFather
Solución:
- Verificar token completo sin espacios
- Regenerar si es necesario: /mybots → seleccionar bot → API Token → Revocar token actual
Error: "Chat no encontrado" para Chat ID
Causas:
- ID incorrecto o no inicializado
- Bot bloqueado por el usuario
- No ha enviado /start al bot
Solución:
- Enviar /start al bot personal
- Verificar que el bot no esté bloqueado
- Confirmar ID positivo para chats personales
Error: "Chat no encontrado" para Chat ID Alertas
Causas:
- Bot no añadido al grupo
- ID del grupo incorrecto
- Prefijo -100 faltante
Solución:
- Verificar que el bot esté en el grupo
- Probar con -100 + ID del grupo
- Confirmar permisos del bot en el grupo
Error: "Prohibido: bot fue bloqueado"
Solución:
- Ir al chat con el bot
- Presionar START o DESBLOQUEAR
- Reiniciar bot en Dashboard
Mejores Prácticas de Seguridad
Para Token del Bot
- 🔒 Nunca compartir el token públicamente
- 💾 Guardar en gestor de contraseñas
- 🔄 Regenerar si se ve comprometido como vimos anteriormente /mybots → seleccionar bot → API Token → Revocar token actual
Para Grupos
- 🔐 Mantener grupos privados
- 👥 Solo administradores necesarios
- ⚙️ Revisar permisos regularmente
Para el Sistema
- 🌐 No exponer a internet, si quieres acceso desde otros lugares usa VPN o sistemas seguros
- 🛡️ Configurar firewall apropiadamente
- 💾 Realizar backups periódicos
- 🔐 Activar 2FA en interfaz web y bot
- 📧 Configurar notificaciones de seguridad
Resumen de Configuración
Al completar este manual tendrás:
El bot estará completamente operativo para gestionar tu infraestructura LoboGuard desde Telegram con capacidades completas de monitoreo, alertas, gestión remota y reportes.