Network UPS Tools (NUT) integration for Gladys Assistant
Monitor the status, load and battery runtime of the UPS devices on your NUT servers.
Published by prohand
- Devices
- Version 1.0.7
- Requires Gladys >=4.86.0
- ★ 0
The Network UPS Tools (NUT) integration lets Gladys retrieve values and states from UPS devices exposed by a reachable NUT upsd server on the local network.
This integration is designed for monitoring. It does not send shutdown, restart, or configuration commands to UPS devices.
Prerequisites
Your UPS must already work in NUT. From the machine hosting Gladys, the NUT server should answer the following command, after replacing the placeholders with your own values:
upsc <ups-name>@<server-address>
By default, upsd listens on TCP port 3493. Ensure that both network rules and NUT ACLs allow access from Gladys.
Configuration
- Open Integrations, then Network UPS Tools (NUT).
- In the Configuration tab, enter the first
upsdserver; its host is required. - Add up to four additional servers in the optional slots when needed.
- For each server, keep port
3493unless your installation uses another port. Enter NUT credentials when authentication is required. - Choose a refresh interval. The default value of 300 seconds is appropriate for most installations. Gladys polls devices once a minute at most: a longer interval is applied on the closest polling tick.
- Save, then use Test NUT connections.
Choosing the refresh interval
Every published value is kept in the Gladys history, and a UPS exposes up to twelve values. A short interval therefore grows the database quickly: at 60 seconds, a single UPS writes around 17,000 rows per day, against around 3,500 with the default interval of 300 seconds.
To reduce that volume further, the integration only publishes the values that changed since the previous reading; a value that stayed stable is republished at least once an hour so it is never displayed as stale. Go down to 60 seconds only when you need fine-grained monitoring — the remaining runtime during an outage, for instance — and raise the interval up to 86,400 seconds when you would rather spare the database.
Once the connection succeeds, Gladys discovers every UPS returned by the NUT server. Each UPS appears as a distinct Gladys device in discovery. In the Discovery tab, click Add for every UPS you want to integrate: you can add several devices independently. The list is rebuilt on each scan from the NUT LIST UPS command.
Available information
NUT drivers do not all report the same variables, so the integration only creates sensors for information actually provided by each UPS.
| Domain | Possible values |
|---|---|
| Battery | Charge, runtime, voltage, and temperature |
| Power | Input/output voltage and current |
| Load | Load percentage, real power, and apparent power |
| UPS | Temperature, status, and alarms |
Values are published only when they are numeric and actually reported by the driver. NUT text statuses are read during communication but are not published as Gladys features, keeping the discovery payload compatible with Core versions that do not yet recognize the text category.
Troubleshooting
| Symptom | Recommended checks |
|---|---|
| No UPS is found | Check every host, port, firewall, and that at least one UPS is configured in each ups.conf. |
| Access or authentication error | Check the ACLs in upsd.conf and credentials defined in upsd.users. |
| Some values are missing | Run upsc <ups>@<server>; Gladys can only create variables exposed by your NUT driver. |
| Stale data | A stable value is only rewritten once an hour, which is expected. Beyond that, verify that the NUT driver still communicates with the hardware and inspect the upsd logs. |
| The Gladys database grows too fast | Raise the refresh interval: the amount of history is directly proportional to it. Every UPS you add writes its own history. |
| Adding a UPS fails with "incomplete or invalid device" | Update the integration. That rejection (HTTP 422) came from features published without their min and max bounds, which are now always declared. |
| Values never change after adding the device | Update the integration: devices are now published with periodic polling enabled. |
| Some features are displayed without a name or an icon | Update the integration, then add the UPS again from the Discovery tab so its existing features are updated: the load and the apparent power were published on a category/type pair the Gladys front-end does not know how to draw. |
For detailed errors, open the integration logs in Gladys. You can also set LOG_LEVEL=debug for more detailed logs.
Resources
The official NUT network protocol specification details the discovery and read commands used by this integration.
Configuration settings
These are the settings Network UPS Tools (NUT) asks for in its configuration screen in Gladys.
| Setting | Type | Required | Description |
|---|---|---|---|
| NUT servers | section | No | Configure one or more reachable upsd servers. Every UPS exposed by every configured server is discovered as a separate Gladys device. |
| Server 1 host | string | Yes | IP address or DNS name of the first NUT upsd server. |
| Server 1 port | number | No | The default NUT TCP port is 3493. |
| Server 1 username (optional) | string | No | |
| Server 1 password (optional) | secret | No | Required when a username is configured. |
| Server 2 host (optional) | string | No | |
| Server 2 port | number | No | |
| Server 2 username | string | No | |
| Server 2 password | secret | No | |
| Server 3 host (optional) | string | No | |
| Server 3 port | number | No | |
| Server 3 username | string | No | |
| Server 3 password | secret | No | |
| Server 4 host (optional) | string | No | |
| Server 4 port | number | No | |
| Server 4 username | string | No | |
| Server 4 password | secret | No | |
| Server 5 host (optional) | string | No | |
| Server 5 port | number | No | |
| Server 5 username | string | No | |
| Server 5 password | secret | No | |
| Refresh interval (s) | number | No | How often each UPS is queried. Every reading is kept in the Gladys history, so a short interval quickly grows the database: keep 300 s unless you really need finer measurements. |
How to install Network UPS Tools (NUT) in Gladys
- In Gladys, open Integrations: Network UPS Tools (NUT) appears in the catalog, next to the native integrations, with a community badge.
- Click Install. Gladys pulls the Docker image (
ghcr.io/prohand/gladys-nut:1.0.7), starts it in a sandbox isolated from the core, and generates the integration's interface (devices, discovery and configuration). - Open the Configuration screen of the integration, fill in the settings, and save.
- You can also install it directly from its repository URL: https://github.com/prohand/gladys-nut.
Network UPS Tools (NUT) requires Gladys >=4.86.0. The catalog inside Gladys refreshes every hour, so a new version becomes available at most one hour after its release.
Not running Gladys yet? It is free and open source: follow the installation guide to get started.
About external integrations
Network UPS Tools (NUT) is an external integration: a community integration packaged as a Docker container and published on GitHub, that Gladys installs in one click and runs in a sandbox isolated from its core. It is published and maintained by prohand, not by the Gladys core team.
- Browse all external integrations
- Discover the native integrations built into Gladys
- Build and publish your own external integration
- Source code on GitHub — source of this documentation