Network UPS Tools (NUT)

NUT is an UPS (UPS) monitoring system that allows the sharing of one (or more) UPS systems between several computers. It has a 'server' component, which monitors the UPS status and notifies a 'client' component when the UPS has a low battery. There can be multiple computers running the client component and each can be configured to shut down cleanly in a power failure (before the UPS batteries run out of charge).

  • The IPFire NUT package contains the core system as well as the serial and USB UPS drivers. It allows a complete UPS monitoring system.
  • NUT supports a large number of UPS devices. These are listed in the NUT Hardware compatibility list.
  • NUT itself is split in to multiple modules. These make it appear complicated but allow it to be highly customizable.

There are two ways to monitor a UPS with NUT:

  • A direct, local connection (USB or Serial)
  • Using another network device (computer or NAS) which itself is direct connected and is running NUT in Network-Server configuration.
Note!
There are also detailed instructions here which cover additional options, such as notifying other servers when a UPS is about to run out of power, email status notifications and more detail about the whole process.

Simple NUT configuration using official documentation

Note!
This procedure is based on the official NUT user manual for an IPFire system connected to a single UPS with no other network-based clients. Although you can configure a UPS without testing, it is best that you prepare for a controlled outage of IPFire at the end of this procedure to test that your configuration works.

Configure a nutmon user and group

While nut can run entirely as root, it is best to run the "upsmon" monitoring process without root privileges. To do this we must create a new user and group.

  • Connect to your IPFire system as root through SSH.
  • Create a "nutmon" user, who should not have a login shell:
    • useradd nutmon -g nut -s /sbin/nologin

Monitor a locally connected UPS

  • Identify your UPS in the NUT Hardware Compatibility List and take a note of the Driver listed:

  • Connect to IPFire using ssh (or log in to the console) as "root"

  • Make a copy of the ups.conf sample file:
    • cp /etc/nut/ups.conf.sample /etc/nut/ups.conf
  • Modify ups.conf to add an entry for your UPS:
    • Follow the instructions in section 6.2 of the NUT documentation: http://www.networkupstools.org/docs/user-manual.chunked/ar01s06.html
    • Your configuration should look similar to this:
[eaton3s]
    driver = usbhid-ups
    port = auto
    desc = "UPS"
  • Make a copy of the upsd.conf sample file:
    • cp /etc/nut/upsd.conf.sample /etc/nut/upsd.conf
  • Edit the file and uncomment the localhost entry, so that NUT will listen only on the local interface. The file should only have one line uncommented (one line which does not begin with "#")
    • LISTEN 127.0.0.1 3493
  • Make a copy of the upsd.users sample file (you do not need to configure this file yet):
    • cp /etc/nut/upsd.users.sample /etc/nut/upsd.users
  • Change permissions on these two configuration files so only root can read them:
    • chown root:root upsd.conf upsd.users
    • chmod 0640 upsd.conf upsd.users
  • Start the driver(s) for your UPS
    • /usr/sbin/upsdrvctl start
    • Which should produce output similar to this:
Network UPS Tools - UPS driver controller 2.7.2
Network UPS Tools - Generic HID driver 0.38 (2.7.2)
USB communication driver 0.32
Using subdriver: MGE HID 1.33
Note!
If the previous command returns an error, saying that it cannot connect to a UPS, or it reports that the data is stale you must resolve the problem before continuing: either your ups.conf file is incorrect or you may have not chosen the correct driver for your UPS.
  • Before starting the 'upsd' UPS server, tighten security by removing world read access from a special state directory:
    • chmod 0750 /var/state/ups
  • Start the 'upsd' daemon:
    • /usr/sbin/upsd
    • Ensure that it connects to the driver on your IPFire system (ignore any warnings about a .pid file):
Network UPS Tools upsd 2.7.2
fopen /var/state/ups/upsd.pid: No such file or directory
listening on 127.0.0.1 port 3493
Connected to UPS [eaton3s]: usbhid-ups-eaton3s
Note!
If there are any errors (except for the warning about the .pid file) they must be resolved before the rest of these instructions can be followed
  • Check that the configuration is working and your UPS is providing good status data:
    • upsc <myupsname>@localhost ups.status
    • OR: upsc <myupsname>@localhost
    • For example:
      • upsc eaton3s@localhost ups.status
    • produces: OL (Online) or OL CHRG (Online Charging)

Configure automatic shutdown at low battery

  • Edit /etc/nut/upsd.users and create a upsd user with a strong password of your own:
[admin]
    password = "PLZset@strongpassw0rdh3r3!"
    actions = SET
    instcmds = ALL
  • Reload upsd: /usr/sbin/upsd -c reload
  • Make a copy of the upsmon.conf sample file:
    • cp /etc/nut/upsmon.conf.sample /etc/nut/upsmon.conf
  • Configure a "flag" file which is created to indicate that UPS needs to be powered off during a power failure, when low battery is reached:
    • Edit /etc/nut/upsmon.conf
    • Check that that an entry for POWERDOWNFLAG /etc/killpower exists and is not commented out with a '#'
  • Create MONITOR directive in upsmon:
    • Edit /etc/nut/upsmon.conf again
    • Uncomment one of the examples and change it to match your use, just update the username and password to match the one which you set in step 1.
    • MONITOR eaton3s@localhost 1 admin "PLZset@strongpassw0rdh3r3!" master
  • Un-comment the SHUTDOWNCMD directive
    • While still editing /etc/nut/upsmon.conf, remove the "#" before SHUTDOWNCMD. It should look like this:
    • SHUTDOWNCMD "/sbin/shutdown -h +0"
  • Secure all the /etc/nut configuration files:
chown root:nut /etc/nut/*
chmod 640 /etc/nut/*
  • Secure the special "state path" directory:
chown root:nut /var/state/ups
chmod 0770 /var/state/ups
  • Start upsmon:
    • /usr/sbin/upsmon
  • Check the 'messages' log for errors:
    • grep upsmon /var/log/messages
Note!
'upsmon' may display a confusing error "[ERR ACCESS-DENIED]" in the messages log. This may not indicate an actual failure. If this occurs, follow the instructions below.
  • If you see the error message Login on UPS [your_ups@localhost] failed - got [ERR ACCESS-DENIED] stop upsmon and start it again with debug output enabled:
for i in $( ps aux | grep [u]psmon | awk '{print $2}' ); do kill $i ; done
/usr/sbin/upsmon -DD
  • The error will still be displayed, but after a few seconds you should see the upsmon process connect anyway. The evidence is that the UPS status will be shown correctly, for example OL CHRG
  • Configure which mode NUT will use, in this case "standalone".
    • cp /etc/nut/nut.conf.sample /etc/nut/nut.conf
    • edit /etc/nut/nut.conf
    • Add the following text after the last line. All other lines should be commented out with a "#"
    • MODE=standalone
  • Start NUT
    • /etc/init.d/nut start
    • There should be no errors on the command line.
    • Check the messages log to ensure the three NUT components start (usbhid-ups, upsd and upsmon)
      • grep ups /var/log/messages
  • Check the Web User Interface
    • Log in to the IPFire WUI using a browser
    • In the Status > Services screen you should see the nut service RUNNING. It will be visible in the "Addon -Services" section.
    • 'nut' will automatically start when IPFire starts up. You can now also start and stop the service from the "Services" screen in the WUI.
Note!
You should now arrange a Change so that you can to test your configuration by shutting down IPFire on low battery.

Quick test

Before doing a test with low battery, you can verify that the NUT components are working by switching off the power to your UPS.

  • Turn off the power to the UPS
    • If you are logged in to IPFire using SSH you should see a broadcast message from nutmon@your_ipfire_server:
      • Broadcast message from nutmon[Michael Jackson](//users/ipfire) (Sat Aug 22 15:43:55 2015): UPS eaton3s@localhost on battery'
    • If you missed the broadcast message, check the "messages" log:
      • grep upsmon /var/log/messages
    • For example:
      • Aug 22 15:43:55 ipfire upsmon[7532]: UPS eaton3s@localhost on battery
  • Turn power back on to the UPS
    • You should see another broadcast message from nutmon@your_ipfire_server:
      • Broadcast message from nutmon[Michael Jackson](//users/ipfire) (Sat Aug 22 15:45:31 2015): UPS eaton3s@localhost on line power
    • If you missed the broadcast message, check the "messages" log:
      • grep upsmon /var/log/messages
    • For example:
      • Aug 22 15:45:45 ipfire upsmon[7532]: UPS eaton3s@localhost on line power
Edit Page ‐ Yes, you can edit!
Last changed by Stu, August 8, 2021 View Older Revisions