View source for Nut-ups

[WORK IN PROGRESS]

== Installing and Configuring Network UPS Tools (NUT) ==

This wiki page shows how to install and configure the NUT package to monitor and report the statistics for a USB attached Uninterruptible Power Supply (UPS). The UPS model used in the examples is an APC SmartUPS 1000, but any UPS on the [https://networkupstools.org/stable-hcl.html list of compatible models] should work.

The end goal is to make the UPS status available over the network so it can be monitored and used to trigger actions in a home automation system like Home Assistant.

=== Determining Your UPS USB Parameters ===

The first step is to plug in the USB cable between your UPS and your Alpine host to see how it appears to the system. This is done with the '''dmesg''' command. See the example below.

 <nowiki>
 alpine:/# dmesg
 [400269.428612] usb 1-3: new low-speed USB device number 3 using xhci_hcd
 [400269.580728] usb 1-3: New USB device found, idVendor=051d, idProduct=0002, bcdDevice= 0.06
 [400269.580751] usb 1-3: New USB device strings: Mfr=3, Product=1, SerialNumber=2
 [400269.580759] usb 1-3: Product: Smart-UPS 1000 FW:600.3.D USB FW:1.4
 [400269.580765] usb 1-3: Manufacturer: American Power Conversion
 [400269.580771] usb 1-3: SerialNumber: AS0235210142
 [400269.687883] usbcore: registered new interface driver usbhid
 [400269.687894] usbhid: USB HID core driver
 [400269.698356] hid-generic 0003:051D:0002.0001: hiddev96,hidraw0: USB HID v1.10 Device [American Power Conversion Smart-UPS 1000 FW:600.3.D USB FW:1.4] on usb-0000:00:15.0-3/input0</nowiki>

From this output, we can see a Smart-UPS 1000 has been detected. We can also see two important parameters: ''idVendor=051d'' and ''idProduct=0002''

These will be used later in the udev rules, so keep them handy.

=== Installing and Configuring NUT ===

The first step is to add the alpine package. After that, we'll rename three default configuration files and replace them with the parameters needed for our example USB attached APC Smart-UPS.

 <nowiki>
 alpine:/# apk update && apk add nut
 
 alpine:/# mv /etc/nut/nut.conf /etc/nut/nut.conf~
 
 alpine:/# cat <<EOF >/etc/nut/nut.conf
 MODE=netserver
 EOF
 
 alpine:/# mv /etc/nut/ups.conf /etc/nut/ups.conf~
 
 alpine:/# cat <<EOF >/etc/nut/ups.conf
 [SmartUPS_1000]
     driver = usbhid-ups
     port = auto
 EOF
 
 alpine:/# mv upsd.conf upsd.conf~
 alpine:/# cat <<EOF >upsd.conf
 LISTEN 0.0.0.0 3493
 EOF</nowiki>

The first command should be familiar. It updates the Alpine package manager database and installs the nut package. All of the configuration files delivered with the package will be in the '''/etc/nut''' subdirectory.

The next several commands will create a backup copy of the original configuration file and then write a new file with only the configuration parameters needed.

The line written to '''nut.conf''' instructs NUT to make the UPS status available on the network.

The lines in '''ups.conf''' define the name (in square brackets), the driver used to communicate with the UPS and the port. For USB attached UPSs, it's almost always going to be a driver of ''usbhid-ups'' and a port of ''auto''. All USB attached UPSs should act the same.

Finally, the line in '''upsd.conf''' is there to tell NUT it should make the UPS info available on all network interfaces. The default is localhost only, which is not very useful. You can also enter the network address of a specific interface if 0.0.0.0 (all interfaces) is not appropriate for your situation.

=== Configuring udev Rules ===

If you tried starting the '''nut-upsd''' service at this point, it would complain loudly about permissions. See the example below.

 <nowiki>
 libusb1: Could not open any HID devices: insufficient permissions on everything
 No matching HID UPS found
 upsnotify: failed to notify about state 4: no notification tech defined, will not spam more about it
 Driver failed to start (exit status=1)</nowiki>

This is due to the USB device having the wrong permissions.

Below is an example of how to configure udev for the USB attached Smart-UPS 1000.

 <nowiki>
 alpine:/# cd /etc/udev/rules.d
 
 cat <<EOF >62-nut-usbups.rules
 ATTR{idVendor}=="051d", ATTR{idProduct}=="0002", MODE="664", GROUP="nut"
 EOF
 
 alpine:/# udevadm control --reload-rules</nowiki>

Take a look at the line that starts with ''ATTR{idVendor}=="051d", ATTR{idProduct}=="0002"''

Thee are the vendor and product IDs found in the '''dmesg''' output above. The rest of the line tells udev what permissions and group ownership to use. It should be the same regardless of the UPS make and model, but the ''idVendor'' and ''idProduct'' will be unique to your UPS.

{{ note|There is also a file '''/lib/udev/rules.d/62-nut-usbups.rules''' that has information for all of the UPS models NUT knows about. You may be able to simply copy this rather than constructing your own rules from the information in the '''dmesg''' output. }}

Finally, the '''udevadm control''' command tells udev to read in the changes.

=== Testing the Configuration Thus Far ===

Unplug the UPS USB cable from the host, wait a moment, and then reinsert it. Check '''dmesg''' again to make sure it was detected and the idVendor and idProduct are correct.

Check the permissions on the files in the '''/dev/bus/usb''' subdirectories. One of these represents your UPS. If the udev rules work correctly, it should be the file with a group owner of ''nut'' and permissions of 0664. An example is shown below.

 alpine:/# ls -l /dev/bus/usb/001/003
 crw-rw-r-- 1 root nut 189, 2 Oct 10 00:53 /dev/bus/usb/001/003

Your directory and file names may be different, but at least one of the files should have the group ownership and permissions as shown in the example.

=== Starting NUT ===

The service is called '''nut-upsd''' and can be started as shown below.

 alpine:/# rc-service nut-upsd start
  * /run/nut: creating directory
  * /run/nut: correcting owner
 Using subdriver: APC HID 0.100
  * Starting UPS Server ...

Notice that the directory '''/run/nut''' is created automatically the first time.

=== Verifying Running State ===

A couple quick commands will ensure the NUT service is actually running as expected. These are shown in the example below.

 alpine:/# rc-service nut-upsd status
 * status: started
 alpine:/# netstat -tln | grep 3493
 tcp        0      0 0.0.0.0:3493            0.0.0.0:*               LISTEN

This shows the service running and making the UPS status available on all network interfaces (0.0.0.0) over the default TCP port for NUT (3493).

=== Configuring Automatic Startup ===

If everything looks good, go ahead and set the service to auto-start when the system is booted.

 alpine:/# rc-update add nut-upsd
  * service nut-upsd added to runlevel default

=== Next Steps ===

NUT can be configured to do things like send an email or initiate a graceful shutdown when the mains power is lost. The [https://networkupstools.org/ NUT home page] is your source for documentation on how to do this.

There is also a [https://www.home-assistant.io/integrations/nut/ NUT integration for Home Assistant] that can be installed to keep tabs on your UPS.