lainmonitor/README.md

LainMonitor

LainMonitor is a Telegram bot designed to provide real‑time monitoring of both the local system and remote network clients (OPNsense firewalls and generic SSH hosts). It aggregates key metrics via SSH and REST APIs, and delivers concise reports through Telegram commands.

Features

• Local System Monitoring

  • Hostname and overall online/offline status
  • Uptime (human‑readable)
  • Load averages (1, 5, 15 minute)
  • Memory usage (via free -h)
  • Disk usage (via df -h)

• Remote Client Monitoring

  • OPNsense Firewalls (multiple hosts with per‑host trust‑on‑first‑use SSL)

    • System health status
    • Uptime
    • Memory and disk statistics
    • Load averages

  • Generic SSH Hosts

    • Hostname, uptime, load, memory, and disk via SSH

• Security & Resilience

  • Trust‑on‑first‑use SSL: automatically fetches and caches firewall certificates
  • Concurrency: parallel polling of remote hosts with ThreadPoolExecutor
  • Error handling: per‑task exceptions are logged and do not interrupt overall data gathering
  • Access control: only whitelisted Telegram chat IDs can invoke commands
  • Automatic bot restart on failure with backoff retry loop

Commands

• /status or /ping — Returns a combined report of local and remote metrics

Installation

1. Clone repository

   git clone https://git.lainlounge.xyz/hornet/lainmonitor.git
   cd lainmonitor
   

2. Install dependencies

   pip install -r requirements.txt
   

3. Configure

   • Copy config.py.example to config.py
   • Populate config.TOKEN with your Telegram bot token
   • Add your Telegram chat IDs to config.ALLOWED_CHATS
   • Define each host under config.HOSTS with correct credentials and API settings

4. Prepare SSL directory (created automatically at runtime):

   mkdir certs
   

Usage

• Run directly

  python3 lainmonitor.py
  

• Run as a service (systemd)

  [Unit]
  Description=LainMonitor Telegram Bot
  After=network.target
  
  [Service]
  ExecStart=/usr/bin/python3 /path/to/lainmonitor.py
  Restart=on-failure
  
  [Install]
  WantedBy=multi-user.target
  

  sudo systemctl enable lainmonitor
  sudo systemctl start lainmonitor
  

Dependencies

• pyTelegramBotAPI (Telebot) — Telegram Bot API client
• paramiko — SSH connectivity
• requests — HTTP/REST API client

Author

h@x

Original Script written by:

hornetmaidan

Contributions and feedback are welcome! :-)