Network UPS Tools - ArchWiki

Jump to content
From ArchWiki

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 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-monitorAUR 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-cyberpower.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

## See also

- Tutorial on networked NUT for Cyberpower UPS

Category:

- Power management