Network UPS Tools

Related articles
APC UPS
This document describes how to install the
Network UPS Tools (NUT)
. Network UPS Tools is compatible with thousands of models of UPS. You can check the
Hardware Compatibility List
to see if your UPS is supported.
Installation
Install
the
nut
package.
Configuration
NUT has 3 daemons associated with it:
The driver which communicates with the UPS.
A server (upsd) which uses the driver to report the status of the UPS.
A monitoring daemon (upsmon) which monitors the upsd server and takes action based on information it receives.
The idea is that if you have multiple systems connected to the UPS, one can communicate the status of the UPS over the network and the others can monitor that status by running their own upsmon services.  NUT has
extensive documentation on the configuration
however this is going to walk through a simple setup of a USB UPS and the associated server and monitor all in one system (common desktop configuration).
Driver configuration
The configuration here will depend on the type of UPS you have. Consult the previously mentioned Hardware Compatibility List to find what driver will likely work for your UPS. You can run the tool
nut-scanner(8)
which will detect NUT-compatible devices attached to your system.
For many UPS connected by USB, use the
usbhid-ups(8)
driver. For UPS with serial port, use
port=/dev/ttySX
, where X is the number of serial port (Example:
/dev/ttyS1
). For UPS with USB port, use
port=auto
.
/etc/nut/ups.conf
...
[
upsname
]
    driver = usbhid-ups
    port = auto
You can name the UPS device whatever you like.
ups.conf(5)
Start the driver as root with
upsdrvctl start
. If there are no errors, you should see a message like this one for the driver
usbhid-ups
:
# upsdrvctl start
Network UPS Tools - Generic HID driver 0.34 (2.4.1)
USB communication driver 0.31
Using subdriver: MGE HID 1.12
Detected EATON - Ellipse MAX 1100 [ADKK22008]
If the driver does not start cleanly, make sure you have picked the right one for your hardware. You might need to try other drivers by changing the
driver=
value in
ups.conf
.
At this point you should be able to
start/enable
nut-driver-enumerator.service
which will automatically create nut-driver@<ups name> systemd service instance and start it.
Can't claim USB device error
If you receive an error message like this one:
Can't claim USB device [
XXXX:YYYY
]: could not detach kernel driver from
interface 0: Operation not permitted
Driver failed to start (exit status=1)
Or a less specific one:
USB communication driver 0.33
No matching HID UPS found
Driver failed to start (exit status=1)
It is most likely a problem with permissions for accessing the device. You can fix that by specifying an
udev
rule that sets the correct group:
/etc/udev/rules.d/50-ups.rules
SUBSYSTEM=="usb", ATTR{idVendor}=="
XXXX
", ATTR{idProduct}=="
YYYY
", GROUP="nut"
Where
XXXX
and
YYYY
are the device manufacturer and product IDs. You can see these either in the error output (
[
XXXX:YYYY
]
) or by using
lsusb
.
Note
The
nut
group is added by the
nut
package. If you used different installation method, you may need to correct the group.
After this is done, reload and retrigger udev rules by running:
# udevadm control --reload
# udevadm trigger
upsd configuration
By default upsd listens only on localhost
tcp/3493
and this is fine for our purpose. Though it is not necessary for following this guide, you can configure upsd beyond the defaults by editing
/etc/nut/upsd.conf
. See
upsd.conf(5)
.
You will need to add a user for a monitor to connect to the server and issue commands. See
upsd.users(5)
.
/etc/nut/upsd.users
...
[
upsuser
]
     password =
password
upsmon primary
     actions = SET
     instcmds = ALL
At this point you should be able to
start/enable
nut-server.service
.
If it has started successfully, you can run
upsc
upsname
to get information from the UPS. Example output from the command:
battery.charge: 100
battery.charge.low: 10
battery.charge.warning: 20
battery.mfr.date: CPS
battery.runtime: 5550
battery.runtime.low: 300
battery.type: PbAcid
battery.voltage: 13.5
battery.voltage.nominal: 12
device.mfr: CPS
device.model: UPS CP1000AVRLCD
device.type: ups
driver.name: usbhid-ups
driver.parameter.pollfreq: 30
driver.parameter.pollinterval: 2
driver.parameter.port: auto
driver.parameter.synchronous: no
driver.version: 2.7.4
driver.version.data: CyberPower HID 0.4
driver.version.internal: 0.41
input.transfer.high: 140
input.transfer.low: 90
input.voltage: 122.0
input.voltage.nominal: 120
output.voltage: 122.0
ups.beeper.status: disabled
ups.delay.shutdown: 20
ups.delay.start: 30
ups.load: 0
ups.mfr: CPS
ups.model: UPS CP1000AVRLCD
ups.productid: 0501
ups.realpower.nominal: 600
ups.status: OL
ups.test.result: Done and passed
ups.timer.shutdown: -60
ups.timer.start: 0
ups.vendorid: 0764
upsmon configuration
The last step is to configure upsmon to listen to upsd and take action on events.
Add the following line to
/etc/nut/upsmon.conf
:
MONITOR
upsname
@localhost 1
upsduser
password
primary
Here
upsname
is the name of the UPS, and
upsduser
and
password
is the user and its password you set in
/etc/nut/upsd.users
.
You can also configure what alerts are sent, where they are sent, what action is taken when the battery is low, and more. See
upsmon.conf(5)
.
Then
start/enable
nut-monitor.service
.
Your logs should show upsmon starting and monitoring the UPS.
systemd targets
In order for the systemd service units to start on boot, you must
enable
nut.target
and
nut-driver.target
.
NUT-Monitor
NUT-Monitor
is a graphical user interface to monitor and manage devices connected to the Network UPS Tools server.
You can
install
nut-monitor with the
nut-monitor
AUR
package.
Troubleshooting
CyberPower UPS keeps disconnecting/reconnecting
Some
CyberPower UPS
products are known to keep disconnecting/reconnecting until the driver successfully attaches to it
[1]
. Once the disconnect/reconnect loop starts, it can be difficult for
upsd
to establish connection to the UPS using default configuration (which appears to impact the proprietary driver as well).
To mitigate this issue,
edit
nut-driver@.service
, add the following configuration, then
start/enable
nut-driver@cyberpower.service
.
/etc/systemd/system/nut-driver@.service.d/override.conf
[Unit]
StopWhenUnneeded=no

[Service]
PIDFile=/run/nut/usbhid-ups-%i.pid
Group=nut
User=nut
RestartSec=10s
Additionally, consider using
maxretry
in UPS configuration:
/etc/nut/ups.conf
maxretry = 5

[cyberpower]
        driver = "usbhid-ups"
        port = "auto"
        ...
EATON 5E650iUSB fails to start driver
According to an
issue on GitHub
, there is a bug in the kernel and the following
kernel parameter
can be used as a workaround:
usbhid.quirks=0x0463:0xffff:0x08
Can't claim USB device: Entity not found
When getting the following error from nut-driver:
Can't claim USB device [XXXX:XXXX]@0/0/0: Entity not found
Several users report (example
[2]
) that rebooting (power-cycling) the UPS can fix this issue.
Alternatively, you can try
upsdrvctl stop
before
starting
the
nut-driver@
ups_name
systemd service.
See also
Tutorial on networked NUT for Cyberpower UPS