Download the PHP package drakelid/librenms-ups-battery without Composer

LibreNMS UPS Battery

Rank your UPSes by battery runtime, load or any other sensor, on one page in LibreNMS.

Open it for an overview of every UPS: power status, runtime, charge, load, temperature, battery status, self-test and when the battery is due for replacement. Or pick a device type and a metric and get a sorted list of hostnames with their current value. Typical questions it answers:

• Which UPS batteries are due for replacement, and how many days are left?
• Which UPSes are on battery right now, or report a battery problem?
• Which UPSes have the shortest battery runtime?
• Which UPSes carry the highest load?
• How do runtime, load and charge compare side by side for every UPS?

The plugin only reads sensor data LibreNMS has already collected. It adds no tables, no migrations and no polling, and it works for any sensor class and device type, not just UPSes.

Illustrative sketch with example values.

Features

Reports

• UPS overview (the page opens here): one row per UPS with its brand logo, manufacturer, model, power status (on battery / on mains), runtime, charge, load, temperature, battery status, bad battery packs, suspect battery, last self-test result, battery install date and the next battery swap with the days left. A row opens to show every other sensor of the UPS (input/output voltage, frequency, ...). An Attention column says in a few words why a UPS is yellow or red. Summary cards above the table count UPSs on battery, overdue swaps, swaps due soon, battery problems and unreachable UPSs, and show the lowest runtime; click a card to show only those UPSs. A timeline shows how many battery swaps fall in each of the next 12 months, and bars show charge, load and how much of each battery's life has passed. "Needs attention only" hides the UPSs without a problem. See Battery replacement.
• Single metric view: ranked table of hostname, location, sensor, value and last update. Filter on device type, metric, OS, device group, sensor name and free text (hostname, sysName, display name, location).
• Compare metrics view: one row per device and one column per metric (up to six). Each cell shows the device's worst sensor for that metric, for example the shortest runtime or the highest load.
• Sort on any column, show the top 10, 25, 50, 100 or all rows, and optionally reduce each device to its lowest or highest sensor.
• Summary line with shown and total rows plus min, median and max (runtime as a duration such as "1 h 5 min").

Battery health

• Suspect batteries: a battery is flagged when the runtime is short although the load is low and the battery is charged, which points to a worn battery rather than a busy UPS. Shown as a "Battery" column in the compare view, as a filter, as a warning on the device page and in the weekly report (see Suspect batteries).
• Next battery swap per UPS, from the install date you enter (or the date the UPS reports) and the battery lifetime, on the UPS overview, the device page and in the weekly report.
• Weekly email report with the UPSes that have the shortest runtime, the suspect batteries and the battery swaps that are due (see Weekly report).
• Trend link: every sensor links to the LibreNMS graph for the last year, to see a battery slowly losing runtime.

Severity and freshness

• Configurable thresholds per metric for UPSes where LibreNMS has no useful sensor limits (see Thresholds). Without a rule the LibreNMS sensor limits are used. Rows turn red (critical) or yellow (warning); devices that are down are dimmed. The settings page shows the matching LibreNMS alert rules, so alerts and colours agree.
• Auto-refresh matching the polling interval, relative "last updated" times that keep ticking, and a warning icon for stale data.

Convenience

• Hover graph and links: hover a value for the sensor's last 24 hours, click it to open the sensor on the device page.
• Saved views: name and save the current filters per user. Every filter is also in the URL, so a view can be shared by copying the link.
• Kiosk view for a wall screen: add kiosk=1 to the address (or press "Kiosk view") for a large table without filters that refreshes by itself. Esc leaves it.
• CSV export of the current view or of all rows: semicolon separated, decimal comma, UTF-8 with BOM, so it opens correctly in Norwegian Excel. Cells that look like spreadsheet formulas are neutralised.
• Device page card: a "UPS Battery" panel on the device overview for devices with runtime, charge or load sensors.
• English and Norwegian (bokmål) interface, selectable in the plugin settings.

Permissions

• Every logged-in user can open the page and sees only the devices and device groups LibreNMS lets them see.
• Temperatures follow each user's °C/°F preference.
• Battery install dates can be set by users with the LibreNMS permission to update devices.
• The only data the plugin writes is each user's saved views (in the LibreNMS user preferences), the battery install dates (as a device attribute) and its settings.

Requirements

• LibreNMS 26.x with the package plugin system (developed against 26.9.1.1).
• PHP 8.2 or newer.
• For the install script: shell access to the LibreNMS server and access to packagist.org.

Installation

Install script (recommended)

Packagist with LibreNMS' own plugin installer (lnms plugin:add). The plugin is then registered in composer.json and composer.plugins.json, shows up in Plugin Admin and survives LibreNMS updates.

The script checks PHP and write access, picks the newest tagged release (or dev-main while no release has been tagged), runs lnms plugin:add, enables the plugin, refreshes the route and view caches and verifies the result.

Keep the script outside /root so the LibreNMS user can read it. bash install.sh --help lists everything.

Manual installation

Then open UPS Battery in the top navigation bar (or Overview > Plugins > UPS Battery). The plugin is enabled as soon as it is installed; disable and configure it under Overview > Plugins > Plugin Admin.

Update and remove

Development checkout

To try a local copy, point composer at the folder (a symlink, so edits show up immediately):

Verify the installation

scripts/verify.sh checks the plugin against your real LibreNMS data: PHP syntax, route registration, Blade compilation (including the settings page and device card), the unit tests if composer install has been run in the plugin folder, and a smoke test of the whole pipeline (query, sorting, compare view, CSV).

It prints the UPSes with the lowest runtime, so you can compare them with the device pages in LibreNMS. From a development checkout, run scripts/verify.sh in that folder instead.

Configuration

Open Overview > Plugins > Plugin Admin and choose ups-battery.

Invalid values never break the page; they are replaced by the defaults.

Thresholds

One rule set per line: <metric> <critical-rule> [<warning-rule>], where a rule is < or > followed by a number. Text after # is a comment.

Rules use the unit LibreNMS stores (minutes for runtime, % for load and charge, degrees Celsius for temperature, whatever unit a user has chosen) and replace the LibreNMS limits for that metric. Invalid lines are ignored and listed under the text box.

Matching alert rules. The page only colours rows. Under the form the settings page lists, for the saved thresholds, the equivalent LibreNMS alert rules, for example macros.device_up = 1 AND sensors.sensor_class = "runtime" AND sensors.sensor_current < 10. Paste them on the Advanced tab under Alerts > Alert Rules > Create rule to get alerts that agree with the colours. The warning rule leaves out the critical range, so a sensor never triggers both.

Battery replacement

The next battery swap of a UPS is worked out from, in this order:

1. the install date entered on the UPS overview (pencil in the Installed column) plus the Battery lifetime setting,
2. the recommended replacement date the UPS reports (APC, "Battery Recommended Days Remaining"),
3. the last replacement date the UPS reports plus the battery lifetime (APC, "Last Battery Replacement").

Without any of them the swap date is unknown and the UPS is counted under "No swap date". Enter the date when you replace a battery; leaving the prompt empty removes it. The date is stored as the LibreNMS device attribute ups-battery.battery_installed, so it survives plugin updates and is removed with the device.

Most UPS batteries (VRLA) last three to five years; set the lifetime to what the manufacturer specifies for your batteries and site temperature.

The other columns of the UPS overview come from the sensors LibreNMS has discovered: the Status column from the output source state ("On battery"/"On mains"), Battery from the battery status or replace-battery indicator plus the bad battery pack count, Self-test from the diagnostics result. These are known for APC and the standard UPS-MIB; for other vendors they are recognised by the sensor name. LibreNMS does not store the date of the last self-test, so only its result is shown.

Supported UPSs

The plugin reads the sensors LibreNMS discovers, so any UPS that LibreNMS monitors with a battery charge or a remaining battery time shows up. The sensor names of every UPS OS in LibreNMS were checked, and these are recognised in particular:

Other vendors' state sensors are recognised by their names (battery, output source, self-test). When a UPS has no output status, the Status column is worked out from its mains or input status, its input voltage or frequency, or its charger state; the tooltip says which sensor was used. Runtime-class sensors that are not a remaining battery time (time already spent on battery, battery dates, uptimes, filter and fan run hours) are not used as runtime, so routers, cooling units and similar devices do not appear as UPSs. If a UPS is missing or a column stays empty, run scripts/verify.sh and check which sensors LibreNMS has discovered for it.

Suspect batteries

A short runtime is normal at high load or while the battery is still charging. It is suspicious when the UPS is lightly loaded and fully charged, because then the battery itself is the likely cause. A battery is flagged when

runtime < limit, and load ≤ limit, and (charge is unknown or charge ≥ limit)

with the limits from the settings (10 minutes, 30 % and 95 % by default). For a device the shortest runtime, the highest load and the lowest charge decide. A battery cannot be judged without a runtime and a load sensor.

Where you see it: the Battery column in the compare view (select runtime and load), the Suspect batteries only filter next to it, a warning on the device page and a table in the weekly report. The CSV export has a suspect_battery column.

Weekly email report

Switch it on in the settings and enter one or more recipients. Every week, on the day and time you choose, LibreNMS' scheduler sends an HTML email with the number of UPSes, critical and warning counts, the UPSes with the shortest runtime (top 10, 25, 50 or 100), the suspect batteries and the battery swaps that are overdue or due within the warning window.

• It uses the email settings of LibreNMS (Global Settings > Alerting) and the scheduler LibreNMS already runs every minute, so nothing needs to be added to cron.
• It covers all devices of the selected default device type, regardless of who is logged in.
• The links in the email use APP_URL from the LibreNMS .env; set it if they point to localhost.
• Try it without sending anything: sudo -u librenms php artisan ups-battery:report --dry-run. Send to someone else once with [email protected].

Common UPS metrics

Which classes exist depends on what each UPS exposes over SNMP; the metric list only shows classes that exist for the selected device type.

API

The page is backed by JSON endpoints that can also be used directly. All routes require a logged-in user (session cookie).

limit=0 returns every row. sensor filters on the sensor name, suspect=1 keeps only suspect batteries (needs runtime and load in classes). Invalid parameters return HTTP 422 with {"message": "..."}. The full request and response shapes are in chapters 12 to 14 of the specification.

Troubleshooting

Development

GitHub Actions (integration.yml installs the plugin into a real LibreNMS (run it by hand or wait for the weekly run) and checks that it boots, registers its routes and command and compiles its views. It has not been run yet, so treat the first run as a test of the workflow itself.

SensorReportService, the controller, the hooks and the rendered pages need a LibreNMS with data. They are checked with scripts/verify.sh and the acceptance checklist in the specification.

Not planned: a LibreNMS dashboard widget. Widgets are core controllers and the plugin API has no widget hook, so it would need an upstream change in LibreNMS.

Documentation and license

• Project specification (Norwegian): requirements, design decisions, API shapes and acceptance criteria.
• Changelog.
• MIT license, see LICENSE.