NUT and UPS on Linux written by neko

Preface

The following information was collected for my wiki in the process of setting up a UPS for my home storage system in mid 2020. I think these instructions might prove interesting for someone looking to do the same. This document covers setting up NUT in a Master/Slave configuration aswell as a routine for an emergency shutdown in case of a power failure.

Prequisites

• NUT must support your UPS.¹
• Make sure the UPS is detected when plugged in by checking dmesg and lsusb, look out for related information like “usb device connected”

NUT

NUT (Network UPS Tools) is the linux standard way of monitoring a UPS and taking actions in case of a power failure.

Generally, all configuration is under /etc/nut.

A general config file for the full stack, called /etc/nut/nut.conf is supplied that allows setting up in which mode the stack is supposed to run:

• none: NUT is disabled
• standalone: Use this if you are only having this single system on the UPS. This launches all 3 component layers
• netserver: same as standalone, launching all 3 component layers, but allowing for remote access to have remote systems take actions
• netclient: this only launches upsmon to take action upon a remote machine

NUT comes with a driver part, accessed via upsc, that queries the UPS for information. The configuration file for the client is /etc/nut/ups.conf and contains information on how to access the UPS.

The server part of NUT, called upsd, allows accessing the information supplied by the client over the network. This is used for querying the UPS from remote machines. The related config file is /etc/nut/upsd.conf. Whoever is allowed to access the server is handled in /etc/nut/upsd.users.

The last part of the stack is upsmon. This part handles monitoring for changes in the UPS in case of a power failure and taking actions. upsmon can access upsd remotely or locally. upsmon is configured via /etc/nut/upsmon.conf

Installing and setting up NUT

Installing required packages

NUT is available in all major distros. For Debian, the following command should install the NUT Server, Client and the upsmon monitoring utility.

apt install nut

Mode setting

Edit the nut.conf and set the mode to either standalone, netserver or netclient. For my configuration, netserver is used as a secondary machine needs to access the information to shut down aswell.

MODE=netserver

Driver setup

If available, run nut-scanner to search for compatible UPS system. This might not be available on Debian. If not, go through the compatibility list of compatible devices linked below in the links section to see what driver supports your device.

Edit the driver configuration file and add a new UPS section. Name the UPS something you remember. You need it to access the UPS.

[upsname]
  driver = <your driver>
  port = auto

For my UPS, the Eaton Ellipse Eco 650, I chose:

[eaton]
  driver = usbhid-ups
  port = auto

Server setup

If the stack was set to netserver, we now need to edit the server config file. Firstly, by default the server only listens to localhost. Uncomment the listen directive and allow accesses from your local network or specific hosts:

LISTEN 0.0.0.0 3493

Now set up users in the upsd.users configuration. I set up a master user for the host system, and a slave user for all the systems that will access the information remotely. Select names for your users

[masterusername]
  password = pass
  upsmon master

[slaveusername]
  password = pass
  upsmon slave

upsmon setup

Lastly we need to set up what happens if a power failure is detected. For that, edit the upsmon.conf and add a MONITOR configuration directive. Take care to use the username of the master user.

MONITOR upsname@localhost 1 masterusername password <master or slave>

The supplied number in field 3 is the amount of required UPS devices to keep the systems running. In most cases, this will be 1. For a professional setup you might want more than a single UPS running.

In case of the Eaton UPS the following directive was used:

MONITOR eaton@localhost 1 monmaster pass master

Now make sure the supplied command for shutting down is correct. The directive should already be in your configuration. Find the line:

SHUTDOWNCMD "/sbin/shutdown -h +0"

Mind that this command may not be right for everyone. Mind that sometimes services take a long time to shut down. Change it out with a script if needed.

In case of a software RAID system, take special care: shutting down may be unsafe and may lead to long resync times after reboot. For my system, I used the following script:

#!/bin/sh

# shutdown script for upsmon
# remounts all filesystems as read only, then sets the raid to readonly and powers down

# print out warnings on my impact printer
echo "$(date) Emergency shutdown signal recieved from UPS, shutting down" | /usr/bin/lpr

# alert everyone currently on the system
wall "Emergency system shutdown due to power outage."

# set all mountpoints of the shared folders to read only
/usr/bin/mount -o remount,ro /media/share/Books/
/usr/bin/mount -o remount,ro /media/share/Images/
/usr/bin/mount -o remount,ro /media/share/Music/
/usr/bin/mount -o remount,ro /media/share/Pictures/
/usr/bin/mount -o remount,ro /media/share/Videos/

# sync the drives
/usr/bin/sync

# switch of smbd
/usr/sbin/service smbd stop

# umount the share folders
/usr/bin/umount /media/share/*

# disable the volume group
/usr/sbin/vgchange -a n share

# set the raid to read only
/usr/sbin/mdadm --readonly /dev/md127

# finally power down the system
/sbin/shutdown -h +0

Slave setup

If another machine is supposed to listen to the UPS aswell, install NUT on that machine and set the mode to netclient. Edit the upsmon.conf and add corresponding MONITOR directive:

MONITOR upsname@server 1 slaveusername password slave

In case of the EATON, this was supplied on the NAS system that runs as a slave:

MONITOR eaton@pve.local 1 monslave pass slave

Final notes

After the setup is finished, a shutdown sequence test should be done. After all servers have shut down, the UPS should recognise the load dropping and launch a power cycle. This should restart all servers (if set up correctly in the BIOS).

Testing and debugging

To access the UPS and query information, upsc <upsname>@<server> can be used.

To control the driver, a utility called upsdrvctrl is supplied. Launching it as upsdrvctl start should tell you more information about the connected UPS.

To test the full shutdown sequence, upsmon -c fsd will trigger a shutdown as if the power would’ve failed. Careful: This will shut down the servers.

upsdrvctl -t shutdown will give information about the shutdown sequence without actually triggering it.

Helpful links

Configuration notes Archwiki Setup Guide Compatibility List