Skip to content

Commit

Permalink
librenms-health: Rewritten from scratch to fetch from LibreNMS MySQL/…
Browse files Browse the repository at this point in the history 
…MariaDB database (therefore the check comes with new parameters)
  • Loading branch information
@markuslf
markuslf committed Mar 29, 2024
1 parent d27776a commit 1ebdff8
Show file tree
Hide file tree
Showing 6 changed files with 376 additions and 296 deletions.
1 change: 1 addition & 0 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@ Icinga Director:
Monitoring Plugins:

* librenms-alerts: Rewritten from scratch to fetch from LibreNMS MySQL/MariaDB database (therefore the check comes with new parameters)
* librenms-health: Rewritten from scratch to fetch from LibreNMS MySQL/MariaDB database (therefore the check comes with new parameters)


### Added
Expand Down
11 changes: 7 additions & 4 deletions check-plugins/librenms-alerts/README.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,12 +6,13 @@ Overview

LibreNMS includes a highly customizable alerting system. The system requires a set of user-defined rules to evaluate the situation of each device, port, service, or other entity. This check warns of unacknowledged alerts in LibreNMS and reports the most recent alert for each device (only for those that do not have "Disabled alerting" in their LibreNMS device settings). If alerts have been triggered in LibreNMS, you will see them on the *Alerts > Notifications* page within the Web UI. When you acknowledge an alert in LibreNMS, this check will change the status for the corresponding device to OK.

This check requires direct access to the LibreNMS MySQL/MariaDB database. The API is simply too resource intensive for use in a large scale environment.
This check requires direct access to the LibreNMS MySQL/MariaDB database, because the API is simply too resource intensive for use in a large scale environment.

Notes:

* See `additional notes for all monitoring plugins accessing MySQL/MariaDB <https://github.com/Linuxfabrik/monitoring-plugins/blob/main/PLUGINS-MYSQL.rst>`_ on how to configure access to the database.
* When defining device groups in LibreNMS for use with ``--device--group``, do not use slashes in the name, as this will not work. See `this topic for example <https://github.com/laravel/framework/issues/22125>`_.
* This check could, but does not, return performance data for each device as LibreNMS provides direct integration with several time series databases such as Graphite, InfluxDB, OpenTSDB, Prometheus and RRDTool. The configuration options can be found in LibreNMS under Settings > Global Settings > Poller > Datastore.


Fact Sheet
Expand Down Expand Up @@ -47,7 +48,7 @@ Help
LibreNMS, you will see them on the *Alerts > Notifications* page within the
Web UI. When you acknowledge an alert in LibreNMS, this check will change the
status for the corresponding device to OK. This check requires direct access
to the LibreNMS MySQL/MariaDB database. The API is simply too resource
to the LibreNMS MySQL/MariaDB database, because the API is simply too resource
intensive for use in a large scale environment.
options:
Expand Down Expand Up @@ -82,7 +83,7 @@ Usage Examples

.. code-block:: bash
/librenms-alerts '--timeout' '3' --defaults-file=/var/spool/icinga2/.my.cnf --device-group="%network%" --severity=warn
./librenms-alerts '--timeout' '3' --defaults-file=/var/spool/icinga2/.my.cnf --device-group="%network%" --severity=warn
Output:

Expand All @@ -100,6 +101,8 @@ Output:
192.0.2.32 ! rack03-usw-pro-48server ! Ping Latency ! [WARNING]
...
The ``--lengthy`` switch reports Hostname, SysName, Hardware, Type, OS, Location, Uptime, Alert and State.


States
------
Expand All @@ -117,7 +120,7 @@ Perfdata / Metrics

Name, Type, Description
device_count, Number, Number of devices found
alert_count, Number, Number of alerts
alert_count, Number, Number of device alerts


Credits, License
Expand Down
107 changes: 79 additions & 28 deletions check-plugins/librenms-health/README.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,13 +4,15 @@ Check librenms-health
Overview
--------

Get health details of all devices in LibreNMS (mostly for quick debugging purposes). Depending on the number of devices and their sensors, the execution can take 300 seconds or longer.
This check plugin retrieves sensor information for each device from a LibreNMS instance.

You need to create an API token for a user with "Global Read" level (login with an admin account, then go to LibreNMS > Gear Icon > API > API Settings, choose this user and create the API token).
This check requires direct access to the LibreNMS MySQL/MariaDB database, because the API is simply too resource intensive for use in a large scale environment.

.. hint::
Notes:

This check could, but does not return any performance data, as LibreNMS offers direct integration into various time series databases like Graphite, InfluxDB, OpenTSDB, Prometheus and RRDTool. The configuration options can be found in LibreNMS under Settings > Global Settings > Poller > Datastore.
* See `additional notes for all monitoring plugins accessing MySQL/MariaDB <https://github.com/Linuxfabrik/monitoring-plugins/blob/main/PLUGINS-MYSQL.rst>`_ on how to configure access to the database.
* When defining device groups in LibreNMS for use with ``--device--group``, do not use slashes in the name, as this will not work. See `this topic for example <https://github.com/laravel/framework/issues/22125>`_.
* This check could, but does not, return performance data for each device or sensor as LibreNMS provides direct integration with several time series databases such as Graphite, InfluxDB, OpenTSDB, Prometheus and RRDTool. The configuration options can be found in LibreNMS under Settings > Global Settings > Poller > Datastore.


Fact Sheet
Expand All @@ -23,67 +25,115 @@ Fact Sheet
"Check Interval Recommendation", "Once an hour"
"Can be called without parameters", "No"
"Compiled for", "Linux, Windows"
"Requirements", "LibreNMS API Token"
"Uses SQLite DBs", "``$TEMP/linuxfabrik-lib-librenms-*.db``"
"Requirements", "Access to LibreNMS' MySQL/MariaDB database. User with no privileges, locked down to ``127.0.0.1`` - for example ``monitoring\@127.0.0.1``. Usernames in MySQL/MariaDB are limited to 16 chars in specific versions."
"3rd Party Python modules", "``pymysql``"


Help
----

.. code-block:: text
usage: librenms-health [-h] [-V] [--device-group DEVICE_GROUP]
usage: librenms-health [-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,network,power,printer,server,storage,wireless,workstation}]
[--insecure] [--lengthy] [--no-proxy]
[--timeout TIMEOUT] --token TOKEN [--url URL]
[--lengthy] [--timeout TIMEOUT]
This check fetches sensor information from a LibreNMS instance, using its API.
This check plugin retrieves sensor information for each device from a LibreNMS
instance. This check requires direct access to the LibreNMS MySQL/MariaDB
database, because the API is simply too resource intensive for use in a large
scale environment.
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 (instead of specifying them on
the command line), for 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.
Filter by LibreNMS Device Group. Supports SQL
Wildcards.
--device-hostname DEVICE_HOSTNAME
Filter by LibreNMS Hostname (repeating).
--device-type {appliance,collaboration,environment,firewall,loadbalancer,network,power,printer,server,storage,wireless,workstation}
Filter by LibreNMS Device Type (repeating).
--insecure This option explicitly allows to perform "insecure"
SSL connections. Default: False
--lengthy Extended reporting.
--no-proxy Do not use a proxy. Default: False
--timeout TIMEOUT Network timeout in seconds. Default: 3 (seconds)
--token TOKEN LibreNMS API token
--url URL LibreNMS API URL. Default: http://localhost
Usage Examples
--------------

.. code-block:: bash
./librenms-health --url http://librenms --token 03xyza61e74a9876f3dc7ab11234229d
./librenms-health '--timeout' '3' --defaults-file=/var/spool/icinga2/.my.cnf --device-group="%storage%"
Output:

.. code-block:: text
Everything is ok.
Hostname SysName Sensor Val (prev) Limit low/high
-------- ------- ------ ---------- --------------
10.80.32.109 S3900-48T4S Oper State 3 (None) None/None
10.80.32.109 S3900-48T4S Temperature Unit 1 sensor 1 37 (38) 27/57
10.80.32.12 brw38b1db3b30f4 Life time sheets 3492 (None) None/None
10.80.32.12 brw38b1db3b30f4 Sheets since powered on 0 (286) None/None
10.80.32.12 brw38b1db3b30f4 Printer Device Status 3 (5) None/None
Checked 113 devices. There are 4 alerts.
Hostname ! SysName ! Sensor ! Val (Range) ! State
-------------+----------+-----------------------------+-------------------+-----------
192.0.2.10 ! synoRZ01 ! System ! 33.0 (23.0..53.0) ! [OK]
192.0.2.11 ! synoRZ02 ! System ! Normal ! [OK]
192.0.2.11 ! synoRZ02 ! Power ! Normal ! [OK]
192.0.2.11 ! synoRZ02 ! FAN - System ! Normal ! [OK]
192.0.2.11 ! synoRZ02 ! FAN - CPU ! Normal ! [OK]
192.0.2.11 ! synoRZ02 ! Upgrade Availability ! Unavailable ! [OK]
192.0.2.11 ! synoRZ02 ! Volume 1 ! Normal ! [OK]
192.0.2.11 ! synoRZ02 ! Disk 17 MZILT1T9HAJQ/007 ! NotInitialized ! [WARNING]
192.0.2.11 ! synoRZ02 ! Disk 18 MZILT1T9HAJQ/007 ! NotInitialized ! [WARNING]
192.0.2.11 ! synoRZ02 ! Disk 1 MZILT1T9HAJQ/007 ! Normal ! [OK]
192.0.2.11 ! synoRZ02 ! Disk 2 MZILT1T9HAJQ/007 ! Normal ! [OK]
192.0.2.11 ! synoRZ02 ! Disk 3 MZILT1T9HAJQ/007 ! Normal ! [OK]
192.0.2.11 ! synoRZ02 ! Disk 4 MZILT1T9HAJQ/007 ! Normal ! [OK]
192.0.2.11 ! synoRZ02 ! System ! 40.0 ! [OK]
192.0.2.11 ! synoRZ02 ! Disk 17 MZILT1T9HAJQ/007 ! 32.0 (22.0..52.0) ! [OK]
192.0.2.11 ! synoRZ02 ! Disk 18 MZILT1T9HAJQ/007 ! 32.0 (22.0..52.0) ! [OK]
192.0.2.11 ! synoRZ02 ! Disk 1 MZILT1T9HAJQ/007 ! 25.0 (23.0..53.0) ! [OK]
192.0.2.11 ! synoRZ02 ! Disk 2 MZILT1T9HAJQ/007 ! 25.0 (23.0..53.0) ! [OK]
192.0.2.11 ! synoRZ02 ! Disk 3 MZILT1T9HAJQ/007 ! 25.0 (23.0..53.0) ! [OK]
192.0.2.11 ! synoRZ02 ! Disk 4 MZILT1T9HAJQ/007 ! 25.0 (23.0..53.0) ! [OK]
storinator02 ! synoRZ04 ! System ! Normal ! [OK]
storinator02 ! synoRZ04 ! Power ! Normal ! [OK]
storinator02 ! synoRZ04 ! FAN - System ! Normal ! [OK]
storinator02 ! synoRZ04 ! FAN - CPU ! Normal ! [OK]
storinator02 ! synoRZ04 ! Upgrade Availability ! Available ! [WARNING]
storinator02 ! synoRZ04 ! Volume 1 ! Normal ! [OK]
storinator02 ! synoRZ04 ! Disk 6 ST4000NM0035-1V4107 ! Normal ! [OK]
storinator02 ! synoRZ04 ! Disk 2 WD4002FYYZ-01B7CB1 ! Normal ! [OK]
storinator02 ! synoRZ04 ! Disk 5 WD4000FYYZ-01UL1B3 ! NotInitialized ! [WARNING]
storinator02 ! synoRZ04 ! Disk 1 WD4000FYYZ-01UL1B3 ! Normal ! [OK]
storinator02 ! synoRZ04 ! Disk 4 WD4002FYYZ-01B7CB1 ! Normal ! [OK]
storinator02 ! synoRZ04 ! Disk 3 WD4000FYYZ-01UL1B3 ! Normal ! [OK]
storinator02 ! synoRZ04 ! System ! 47.0 ! [OK]
storinator02 ! synoRZ04 ! Disk 6 ST4000NM0035-1V4107 ! 36.0 (26.0..56.0) ! [OK]
storinator02 ! synoRZ04 ! Disk 2 WD4002FYYZ-01B7CB1 ! 38.0 (27.0..57.0) ! [OK]
storinator02 ! synoRZ04 ! Disk 5 WD4000FYYZ-01UL1B3 ! 36.0 (26.0..56.0) ! [OK]
storinator02 ! synoRZ04 ! Disk 1 WD4000FYYZ-01UL1B3 ! 36.0 (25.0..55.0) ! [OK]
storinator02 ! synoRZ04 ! Disk 4 WD4002FYYZ-01B7CB1 ! 36.0 (27.0..57.0) ! [OK]
storinator02 ! synoRZ04 ! Disk 3 WD4000FYYZ-01UL1B3 ! 35.0 (25.0..55.0) ! [OK]
...
The ``--lengthy`` switch reports Hostname, SysName, Type, Location, Sensor, Class, Changed, Val (Range) and State.


States
------

* Always returns OK.
* OK, WARN, CRIT or UNKNOWN according to the same sensor state in LibreNMS
* OK if you disable the alerting for a particular sensor in LibreNMS


Perfdata / Metrics
Expand All @@ -94,7 +144,8 @@ Perfdata / Metrics
:header-rows: 1

Name, Type, Description
device_count, Number, Number of devices found
sensor_count, Number, Number of sensors found
alert_count, Number, Number of sensor alerts


Credits, License
Expand Down
Loading

0 comments on commit 1ebdff8

Please sign in to comment.