Skip to content

Check librenms-alerts

Overview

Checks for unacknowledged alerts in LibreNMS and reports the most recent alert per device. Only considers devices that do not have alerting disabled in their LibreNMS device settings. When you acknowledge an alert in the LibreNMS web UI (Alerts > Notifications), this check changes the status for the corresponding device to OK.

Important Notes:

  • Requires access to the LibreNMS MySQL/MariaDB database
  • See additional notes for all monitoring plugins accessing MySQL/MariaDB on how to configure database access.
  • When defining device groups in LibreNMS for use with --device-group, do not use slashes in the name (see this topic).
  • This check does not return per-device performance data because LibreNMS provides direct integration with time series databases (Graphite, InfluxDB, OpenTSDB, Prometheus, RRDTool) under Settings > Global Settings > Poller > Datastore.

Data Collection:

  • Queries the LibreNMS MySQL/MariaDB database directly (the API is too resource-intensive for large-scale environments)
  • Joins devices, alerts, alert_rules, device_groups, and locations tables to build the device/alert overview
  • Matches the same set of open, notifiable alerts that the LibreNMS UI and alerter consider as "needs attention": alerts.open = 1 and alerts.state IN (1, 3, 4, 5). LibreNMS encodes the alert lifecycle in alerts.state (LibreNMS/Enum/AlertState.php): 0 = CLEAR / RECOVERED, 1 = ACTIVE, 2 = ACKNOWLEDGED, 3 = WORSE, 4 = BETTER, 5 = CHANGED. WORSE and BETTER exist since LibreNMS 1.54 (July 2019); CHANGED was added in LibreNMS 25.2.0 (February 2025) and is now triggered whenever the alert diff detects a change, so a plugin that only looked at state 1 would miss a growing share of real alerts on LibreNMS 25.x.
  • Supports filtering by device group (--device-group, with SQL wildcards), device hostname (--device-hostname, repeatable), and device type (--device-type, repeatable)
  • In default (compact) mode, only devices with active alerts are shown; use --lengthy to display all devices with extended details (hardware, type, OS, location, uptime)

Fact Sheet

Fact Value
Check Plugin Download https://github.com/Linuxfabrik/monitoring-plugins/tree/main/check-plugins/librenms-alerts
Nagios/Icinga Check Name check_librenms_alerts
Check Interval Recommendation Every minute
Can be called without parameters No (--defaults-file with valid MySQL/MariaDB credentials is required)
Runs on Cross-platform
Compiled for Windows No
3rd Party Python modules pymysql

Help

usage: librenms-alerts [-h] [-V] [--always-ok] [--defaults-file DEFAULTS_FILE]
                       [--defaults-group DEFAULTS_GROUP]
                       [--device-group DEVICE_GROUP]
                       [--device-hostname DEVICE_HOSTNAME]
                       [--device-type {appliance,collaboration,environment,firewall,loadbalancer,management,network,power,printer,server,storage,wireless,workstation}]
                       [--lengthy] [--severity {warn,crit}]
                       [--timeout TIMEOUT]

Checks for unacknowledged alerts in LibreNMS and reports the most recent alert
per device. Only considers devices that do not have alerting disabled in their
LibreNMS settings. Requires direct access to the LibreNMS MySQL/MariaDB
database. Supports extended reporting via --lengthy.

options:
  -h, --help            show this help message and exit
  -V, --version         show program's version number and exit
  --always-ok           Always returns OK.
  --defaults-file DEFAULTS_FILE
                        Specifies a cnf file to read parameters like user,
                        host and password from (for MySQL/MariaDB cnf-style
                        files). Example: `/var/spool/icinga2/.my.cnf`.
                        Default: /var/spool/icinga2/.my.cnf
  --defaults-group DEFAULTS_GROUP
                        Group/section to read from in the cnf file. Default:
                        client
  --device-group DEVICE_GROUP
                        Filter by LibreNMS device group. Supports SQL
                        wildcards.
  --device-hostname DEVICE_HOSTNAME
                        Filter by LibreNMS hostname. Can be specified multiple
                        times.
  --device-type {appliance,collaboration,environment,firewall,loadbalancer,management,network,power,printer,server,storage,wireless,workstation}
                        Filter by LibreNMS device type. Can be specified
                        multiple times.
  --lengthy             Extended reporting.
  --severity {warn,crit}
                        Severity for alerting. Default: crit
  --timeout TIMEOUT     Network timeout in seconds. Default: 3 (seconds)

Usage Examples

./librenms-alerts --defaults-file=/var/spool/icinga2/.my.cnf --device-group="%network%" --severity=warn

Output:

There are 2 alerts. Checked 5 devices.

Hostname   ! SysName                 ! Alert        ! State
-----------+-------------------------+--------------+------------
192.0.2.33 ! rack03-usw              ! Ping Latency ! [WARNING]
192.0.2.32 ! rack03-usw-pro-48server ! Ping Latency ! [WARNING]

With --lengthy:

There are 2 alerts. Checked 5 devices.

Hostname   ! SysName                 ! Hardware ! Type    ! OS    ! Location ! Uptime ! Alert        ! State
-----------+-------------------------+----------+---------+-------+----------+--------+--------------+----------
192.0.2.10 ! synology                ! DS920+   ! storage ! linux ! DC1      ! 3M 2W  ! None         ! [OK]
192.0.2.33 ! rack03-usw              ! USW-48   ! network ! linux ! DC1      ! 1M 3W  ! Ping Latency ! [WARNING]
...

States

  • OK if there are no open, unacknowledged alerts. Acknowledged alerts (alerts.state = 2) and cleared/recovered alerts (alerts.state = 0) are reported as OK.
  • WARN or CRIT (default: CRIT, configurable via --severity) for each device with an open alert, i.e. alerts.state in ACTIVE (1), WORSE (3), BETTER (4) or CHANGED (5).
  • --always-ok suppresses all alerts and always returns OK.

Perfdata / Metrics

Name Type Description
alert_count Number Number of device alerts.
device_count Number Number of devices checked.

Credits, License