Skip to main content

Network UPS Tools (NUT) smart home integration, free and open source

Network UPS Tools (NUT) integration for Gladys Assistant

Monitor the status, load and battery runtime of the UPS devices on your NUT servers.

View on GitHubAll integrations

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.

Credentials travel in clear text​

The integration does not use TLS (STARTTLS): the NUT username and password, and every reading, cross the network in clear text. Keep it on a trusted network:

  • make upsd listen only on the interface Gladys reaches (LISTEN in upsd.conf), and filter port 3493 so that only the Gladys host can connect;
  • create a dedicated user in upsd.users for Gladys, with no actions nor instcmds: the integration only reads, so it never needs them;
  • never reuse that password elsewhere.

Configuration​

  1. Open Integrations, then Network UPS Tools (NUT).
  2. In the Configuration tab, enter the first upsd server; its host is required.
  3. Add up to four additional servers in the optional slots when needed.
  4. For each server, keep port 3493 unless your installation uses another port. Enter NUT credentials when authentication is required.
  5. 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.
  6. Click Save configuration, 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 under Discovered devices as a distinct Gladys device. In the Discover tab, click Add to Gladys for every UPS you want to integrate: you can add several devices independently. The list is rebuilt on each scan (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.

DomainPossible values
BatteryCharge, runtime, voltage, and temperature
PowerInput/output voltage and current
LoadLoad percentage, real power, and apparent power
UPSTemperature, 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.

Widget, scenes and actions (Gladys 5.1)​

The integration requires Gladys 5.1 or later.

"UPS" widget​

In Dashboard → Edit → New widget, in the Integration widgets section, choose UPS, then the UPS to show. The widget displays:

  • the battery charge (gauge) and the remaining runtime;
  • the UPS load and the input voltage;
  • a 24 h chart (battery charge and load);
  • the state (on mains, on battery, low battery…), the NUT alarms, the power and the server;
  • a Refresh button, which reads the UPS right away. It never sends a command to the UPS.

The widget shows the last reading the integration made (3 minutes old at most). When the UPS is slow to answer, it shows "Reading the UPS…" and updates a few seconds later.

Scene triggers​

In a scene, Add trigger → Integrations:

TriggerWhen
UPS: power failure, on batterythe UPS switches to battery (OB)
UPS: power restoredthe UPS is back on mains (OL)
UPS: battery lowNUT reports a low battery (LB)
UPS: battery to replaceNUT asks for a replacement (RB)
  • Leave the UPS field empty to react to every UPS.
  • The state is checked every minute, whatever the refresh interval: a power cut is seen within a minute.
  • Variables available in the scene: ups_name, status, battery_charge (%), battery_runtime (min), load (%).
  • When the integration starts, the first reading is the reference: no event is sent for a UPS already on battery.

"Read a UPS status" scene action​

In a scene, New action → Integrations. It reads the chosen UPS and returns to the following actions: ups_name, status (online, on_battery, low_battery, forced_shutdown, off, bypass, unknown), on_battery, low_battery, replace_battery, battery_charge, battery_runtime (min), load, input_voltage. A reading the UPS does not report is left out.

Example: every morning, read the UPS status then send a message with the remaining runtime.

Troubleshooting​

SymptomRecommended checks
No UPS is foundCheck every host, port, firewall, and that at least one UPS is configured in each ups.conf.
Access or authentication errorCheck the ACLs in upsd.conf and credentials defined in upsd.users.
Some values are missingRun upsc <ups>@<server>; Gladys can only create variables exposed by your NUT driver.
Stale dataA 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 fastRaise 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 deviceUpdate the integration: devices are now published with periodic polling enabled.
Some features are displayed without a name or an iconUpdate the integration, then add the UPS again from the Discover 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.
The connection status says "Connected, but 1 of 2 NUT servers do not answer"The UPS of the other servers are still read. Check the named server (host, port, firewall, upsd running); the status goes back to plain "connected" at its next answer.
A UPS stopped updating after a server was removed from the configurationIts server is no longer queried, which the logs say once. Add the server back, or delete the device in Gladys.
The UPS load is displayed as "Unknown"Update the integration, then add the UPS again from the Discover tab: the load (ups.load) is now published on a category that lets Gladys show its name, "Load".

For detailed errors, open the integration's Logs tab 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.

SettingTypeRequiredDescription
NUT serverssectionNoConfigure one or more reachable upsd servers. Every UPS exposed by every configured server is discovered as a separate Gladys device.
Server 1 hoststringYesIP address or DNS name of the first NUT upsd server.
Server 1 portnumberNoThe default NUT TCP port is 3493.
Server 1 username (optional)stringNo
Server 1 password (optional)secretNoRequired when a username is configured.
Server 2 host (optional)stringNo
Server 2 portnumberNo
Server 2 usernamestringNo
Server 2 passwordsecretNo
Server 3 host (optional)stringNo
Server 3 portnumberNo
Server 3 usernamestringNo
Server 3 passwordsecretNo
Server 4 host (optional)stringNo
Server 4 portnumberNo
Server 4 usernamestringNo
Server 4 passwordsecretNo
Server 5 host (optional)stringNo
Server 5 portnumberNo
Server 5 usernamestringNo
Server 5 passwordsecretNo
Refresh interval (s)numberNoHow often the readings are written to the Gladys history. Each one is a row in the database: keep 300 s unless you need finer measurements. The UPS status is still checked every minute for the scenes.

How to install Network UPS Tools (NUT) in Gladys​

  1. In Gladys, open Integrations: Network UPS Tools (NUT) appears in the catalog, next to the native integrations, with a community badge.
  2. Click Install. Gladys pulls the Docker image (ghcr.io/prohand/gladys-nut:2.3.0), starts it in a sandbox isolated from the core, and generates the integration's interface (devices, discovery and configuration).
  3. Open the Configuration screen of the integration, fill in the settings, and save.
  4. You can also install it directly from its repository URL: https://github.com/prohand/gladys-nut.

Network UPS Tools (NUT) requires Gladys >=5.1.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.

Subscribe to the Gladys Assistant newsletter

A few emails per month about new releases and project news. Sent by Pierre-Gilles Leymarie, founder of the project. Unsubscribe anytime 🙂
Last updated on