Monitoring LibreNMS with Vigilmon: Web UI, API Health Endpoint, Device Poller Status & SSL Alerts

LibreNMS is the leading open-source network monitoring system — auto-discovering SNMP devices, graphing bandwidth, and alerting on interface failures across networks with thousands of devices. When LibreNMS goes down, your network team loses visibility: you don't know when routers are dropping packets, when interfaces go down, or when bandwidth is saturating. When the poller jobs stop running (a common failure mode), the web UI appears healthy but is displaying stale data hours behind reality. Vigilmon gives you external monitoring for LibreNMS itself — the web UI, the API health endpoint, SSL certificates, and heartbeat checks for cron-based poller jobs — so you know the moment your network monitoring system stops monitoring.

What You'll Build

• An HTTP monitor for the LibreNMS web UI
• An HTTP monitor for the /api/v0/system health endpoint
• An HTTP monitor checking /api/v0/devices?status=down for poller health keywords
• SSL certificate monitoring for LibreNMS HTTPS
• Heartbeat monitors for LibreNMS scheduled poller cron jobs

Prerequisites

• LibreNMS installed and accessible via HTTPS
• A LibreNMS API token (generated under Settings → API → API Settings)
• Poller running via cron or systemd timer (default: every 5 minutes)
• A free account at vigilmon.online

Step 1: Understand LibreNMS's Monitoring Surface

LibreNMS's key endpoints for external monitoring:

# Web UI availability
curl -I https://librenms.example.com/

# System health endpoint (API key required)
curl -H "X-Auth-Token: YOUR_API_TOKEN" \
  https://librenms.example.com/api/v0/system

# List devices with status=down (poller health check)
curl -H "X-Auth-Token: YOUR_API_TOKEN" \
  "https://librenms.example.com/api/v0/devices?status=down"

# Check poller status
curl -H "X-Auth-Token: YOUR_API_TOKEN" \
  https://librenms.example.com/api/v0/poller

Key monitoring points:

• Web UI reachability (PHP application + web server)
• API layer health (database connectivity, application logic)
• Poller job completion (cron-based, outside the web process)
• SSL certificate expiry for HTTPS

Step 2: Create an HTTP Monitor for the LibreNMS Web UI

The LibreNMS web interface is the primary tool your network team uses to monitor devices, view graphs, and respond to alerts. Monitor its availability as an external user would see it:

1. Log in to Vigilmon → Add Monitor → HTTP.
2. URL: https://librenms.example.com/.
3. Check interval: 2 minutes.
4. Response timeout: 15 seconds.
5. Expected status: 200.
6. Keyword: LibreNMS (appears in the page title of all LibreNMS pages).
7. Label: LibreNMS web UI.
8. Click Save.

This monitor catches:

• PHP-FPM crash or Apache/nginx failure
• LibreNMS application errors preventing page render
• Database connection failures that break the front-end
• VM or container restarts taking LibreNMS offline

Authentication: LibreNMS requires login by default. The root URL (/) should redirect to /login and return 200 with the login form. The keyword LibreNMS is present on the login page, so no authenticated session is needed for this check.

Step 3: Create an HTTP Monitor for the API Health Endpoint

LibreNMS's /api/v0/system endpoint returns the system status including LibreNMS version, database connectivity, and PHP environment. This confirms the API layer — which the poller, alerts, and integrations depend on — is functional:

curl -H "X-Auth-Token: YOUR_API_TOKEN" https://librenms.example.com/api/v0/system
# Returns: {"status":"ok","data":{"local_ver":"24.x.x","local_sha":"...","php_ver":"...",...}}

1. Add Monitor → HTTP.
2. URL: https://librenms.example.com/api/v0/system.
3. Check interval: 2 minutes.
4. Response timeout: 10 seconds.
5. Expected status: 200.
6. Keyword: "status":"ok" (present in all healthy API responses).
7. Custom header: X-Auth-Token: YOUR_API_TOKEN.
8. Label: LibreNMS API health.
9. Click Save.

API token security: Use a dedicated read-only API token for monitoring. Create it under Settings → API → API Settings in LibreNMS, scoped to read-only access. Do not use an admin token for monitoring probes.

When the API health monitor fires but the web UI is green, LibreNMS's PHP application is serving pages but the API layer is degraded — check database connectivity and PHP error logs.

Step 4: Create an HTTP Monitor for Poller Device Status

LibreNMS's poller runs via cron every 5 minutes to collect SNMP data from all devices. A subtle failure mode: the poller stops running, but the web UI continues to show the last collected data without any visible error. After a few hours, graphs stop updating and device status becomes stale.

The /api/v0/devices?status=down endpoint lists devices currently down. Monitor this endpoint and alert if it contains an unexpected keyword — this can be part of your overall poller health story. More importantly, create a heartbeat for the poller (see Step 5).

For a keyword-based check on the API:

1. Add Monitor → HTTP.
2. URL: https://librenms.example.com/api/v0/devices.
3. Check interval: 5 minutes.
4. Expected status: 200.
5. Keyword: devices (always present in a healthy response, even with an empty device list).
6. Custom header: X-Auth-Token: YOUR_API_TOKEN.
7. Label: LibreNMS devices API.
8. Click Save.

This confirms the devices API endpoint is functional — a prerequisite for poller result reporting.

Step 5: Add Heartbeat Monitoring for LibreNMS Poller Jobs

The most important LibreNMS monitor is a heartbeat for the poller. LibreNMS uses cron to trigger polling every 5 minutes:

# Default LibreNMS cron entry (check /etc/cron.d/librenms)
*/5 * * * * librenms /opt/librenms/cronic /opt/librenms/poller-wrapper.py 16
*/5 * * * * librenms /opt/librenms/cronic /opt/librenms/discovery.php -h new >> /dev/null 2>&1

If this cron job is accidentally removed, disabled, or fails silently, LibreNMS stops collecting data — but the web UI shows no error.

Create a Heartbeat Monitor

1. Add Monitor → Heartbeat.
2. Label: LibreNMS poller cron.
3. Expected interval: 5 minutes.
4. Grace period: 2 minutes.
5. Click Save and copy the heartbeat URL.

Instrument the Poller Cron

Modify /etc/cron.d/librenms to ping Vigilmon after successful poller execution:

*/5 * * * * librenms /opt/librenms/cronic /opt/librenms/poller-wrapper.py 16 && curl -fsS https://vigilmon.online/heartbeat/abc123 > /dev/null 2>&1

Or use a wrapper script:

#!/bin/bash
# /opt/librenms/vigilmon-poller-wrapper.sh
/opt/librenms/poller-wrapper.py 16
if [ $? -eq 0 ]; then
  curl -fsS https://vigilmon.online/heartbeat/abc123 > /dev/null 2>&1
fi

# /etc/cron.d/librenms
*/5 * * * * librenms /opt/librenms/vigilmon-poller-wrapper.sh

Also monitor the discovery job with a separate heartbeat (runs hourly by default):

# /etc/cron.d/librenms
15 */6 * * * librenms /opt/librenms/cronic /opt/librenms/discovery.php -h all >> /dev/null 2>&1 && curl -fsS https://vigilmon.online/heartbeat/xyz789 > /dev/null 2>&1

Step 6: Monitor SSL Certificates

LibreNMS is typically accessed over HTTPS. An expired certificate causes:

• Browser warnings for your network team accessing the web UI
• API calls from monitoring integrations to fail with TLS errors
• Alert webhook deliveries to fail if they go through the same domain

# Check certificate expiry
openssl s_client -connect librenms.example.com:443 2>/dev/null | openssl x509 -noout -dates

1. Add Monitor → SSL Certificate.
2. Domain: librenms.example.com.
3. Alert when expiry is within: 30 days.
4. Alert again: 14 days, 7 days, 3 days, 1 day.
5. Click Save.

Step 7: Configure Alerting

In Vigilmon under Settings → Notifications, configure alert channels:

| Monitor | Trigger | Action | |---|---|---| | Web UI | Non-200 or keyword missing | Check systemctl status nginx php-fpm; check PHP error logs | | API health | Non-200 or status:ok missing | Database connectivity; check /opt/librenms/logs/librenms.log | | Devices API | Non-200 | API layer failure; check application logs | | Poller heartbeat | No ping within window | Check cron with crontab -l -u librenms; run poller manually | | Discovery heartbeat | No ping within window | Discovery cron disabled; run php discovery.php -h all | | SSL certificate | < 30 days to expiry | Renew Let's Encrypt cert; reload nginx |

Alert sensitivity: Use 1 consecutive failure for heartbeat monitors (a missed poll is never transient) and 2 consecutive failures for HTTP monitors.

Common LibreNMS Failure Modes and What Vigilmon Catches

| Scenario | Vigilmon monitor | |---|---| | PHP-FPM crash | Web UI returns 502/503; API health fails | | MySQL/MariaDB failure | API health returns error; web UI may show cached pages | | Poller cron removed or disabled | Heartbeat alert after 7-minute window; data goes stale silently | | Discovery job failure | Discovery heartbeat fires; new devices stop appearing | | Poller-wrapper.py error | Heartbeat not sent; SNMP polling stops for all devices | | SSL certificate expires | SSL monitor alerts; browser warnings for web UI | | Disk full on LibreNMS host | RRD writes fail silently; poller may still complete but data missing | | Nginx configuration error after update | Web UI returns 502; API health fails simultaneously | | SNMP daemon unreachable on devices | Poller completes but with errors; heartbeat may still fire | | Database table lock or slow query | API health returns errors; web UI may time out |

LibreNMS failing to collect data is an insidious failure: the web UI looks fine, graphs show data, but it's hours stale. By the time your team discovers that the poller stopped running, the backlog of missed SNMP collections is gone — you've been flying blind for hours. Vigilmon's heartbeat monitor catches this the moment the first 5-minute poller cycle is missed, and the API health and web UI monitors catch the less subtle failures. External monitoring for your network monitoring system closes the loop: when LibreNMS goes dark, Vigilmon lights up.

Start monitoring LibreNMS in under 5 minutes — register free at vigilmon.online.