Wednesday, 10 April 2013

Using a raspberry-pi as a UPS server with nut

In this post we will try to install the Network UPS tools on a Raspberry-Pi device, attach a USB connected UPS and use it as a UPS server that will allow all machines sharing the same UPS to shut-down correctly when the UPS runs out of power. Our server will look after two clients; one running EL5 and the other openSUSE 11.4.

At the end of the post we will demonstrate how easy it is to set up your clients once the server is up and running and provide additional instructions for setting up the client software on Fedora 18 and EL6.

Update 2014-02-02: Meanwhile things here at the office have changed. The openSUSE machine is now gone and has been replaced by one running Debian 7. I have now revised the client setup guides for Fedora and EL5, 6 and I also have added one for Debian. The openSUSE "howto" is left as is but I can no longer verify if it works or not :) ..

Server Setup

Before we begin I would like to confess that my first attempt to install a no-name made in China UPS resulted to total failure, so eventually I got an expensive APC BackUPS Pro, that worked without any problems from the beginning, so unless your UPS is one supported by the UPS network tools project drivers, don't even try to follow the tutorial.

A second remark, is that if you are following the tutorial as the standard pi user you will need to prefix almost all commands with sudo. To become root on a standard Raspbian and follow along, you will need to issue sudo su-. (Thanks Derek for pointing it out)

root@raspbx:~# apt-get install nut-client nut-server
Reading package lists... Done
Building dependency tree       
Reading state information... Done
The following extra packages will be installed:
  libupsclient1
Suggested packages:
  nut-cgi nut-snmp nut-dev nut-xml
The following NEW packages will be installed:
  libupsclient1 nut-client nut-server
0 upgraded, 3 newly installed, 0 to remove and 0 not upgraded.
Need to get 1,583 kB of archives.
After this operation, 3,217 kB of additional disk space will be used.
Do you want to continue [Y/n]? y
Get:1 http://archive.raspbian.org/raspbian/ wheezy/main libupsclient1 armhf 2.6.4-2.3 [106 kB]
Get:2 http://archive.raspbian.org/raspbian/ wheezy/main nut-client armhf 2.6.4-2.3 [191 kB]
Get:3 http://archive.raspbian.org/raspbian/ wheezy/main nut-server armhf 2.6.4-2.3 [1,286 kB]
Fetched 1,583 kB in 2s (562 kB/s)     
debconf: delaying package configuration, since apt-utils is not installed
Selecting previously unselected package libupsclient1.
(Reading database ... 37855 files and directories currently installed.)
Unpacking libupsclient1 (from .../libupsclient1_2.6.4-2.3_armhf.deb) ...
Selecting previously unselected package nut-client.
Unpacking nut-client (from .../nut-client_2.6.4-2.3_armhf.deb) ...
Selecting previously unselected package nut-server.
Unpacking nut-server (from .../nut-server_2.6.4-2.3_armhf.deb) ...
Processing triggers for man-db ...
Setting up libupsclient1 (2.6.4-2.3) ...
Setting up nut-client (2.6.4-2.3) ...
[info] nut-client disabled, please adjust the configuration to your needs.
[info] Then set MODE to a suitable value in /etc/nut/nut.conf to enable it.
Setting up nut-server (2.6.4-2.3) ...
[info] nut-server disabled, please adjust the configuration to your needs.
[info] Then set MODE to a suitable value in /etc/nut/nut.conf to enable it.
root@raspbx:~# 

Don't worry about the nut-server information we shall deal with it later on. Now an optional step that will allow us to to use the lsusb utility will be to install the usbutils package, assuming that it is not already there. So:

root@raspbx:~# apt-get install usbutils

.. and then -- blame me for my Windows habits, I firmly suggest a reboot. When the system is back on, we will make sure that out USB device is nιcely plugged in...

root@raspbx:~# lsusb
Bus 001 Device 002: ID 0424:9512 Standard Microsystems Corp. 
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 001 Device 003: ID 0424:ec00 Standard Microsystems Corp. 
Bus 001 Device 004: ID 051d:0002 American Power Conversion Uninterruptible Power Supply
root@raspbx:~# 

Our UPS is there so let's set up the driver for the nut server. Open file /etc/nut/ups.conf and append the following lines at the end.

[apc1200]
        driver = usbhid-ups
        port = auto
        desc = "APC Back UPS Pro 1200VA supporting the two network servers"

You can name your ups anything you like, as far as the driver is concerned my advice is to browse through the official Network UPS Tools drivers list.

Setting up the UPS name and driver is not enough. I have not tested this on any other Debian box, but on raspberry-pi we need an extra step in order to create the /var/run/nut folder and set correct permissions to it.

root@raspbx:~# mkdir /var/run/nut
root@raspbx:~# chown root.nut /var/run/nut/
root@raspbx:~# chmod 770 /var/run/nut/

Now we are ready to test the UPS driver.

root@raspbx:~# upsdrvctl start
Network UPS Tools - UPS driver controller 2.6.4
Network UPS Tools - Generic HID driver 0.37 (2.6.4)
USB communication driver 0.31
Using subdriver: APC HID 0.95
root@raspbx:~# 

Our next step will be to configure upsd and upsmon. The network UPS tools design dictates that upsd communicates with the UPS driver that we just started and upsmon communicates with upsd and actually shuts down the machine in the event of a power failure. By providing this extra level of indirection, nut allows for multiple instances of upsmon to run on different machines. That way they can allow share the same physical UPS and this is what we said that we are going to demonstrate in this posting.

So to enable accessing the upsd via the network, edit the file /etc/nut/upsd.conf and place the following LISTEN directives.

LISTEN 127.0.0.1 3493
LISTEN 192.168.1.137 3493

192.168.1.137, is my pi's IP address -- replace that with your own. Next, we will need to add some kind of security and the next file that we will need to tamper with will be the /etc/nut/upsd.users. Edit it with your text editor and set up the following users

[admin]
        password = myadmpass
        actions = SET
        instcmds = ALL

#
# --- Configuring for a user who can execute tests only
#
[testuser]
        password  = pass  
        instcmds  = test.battery.start
        instcmds  = test.battery.stop

#
# --- Configuring for upsmon
#
# To add a user for your upsmon, use this example:
#
[upsmon_local]
        password  = local_pass
        upsmon master
[upsmon_remote]
        password  = remote_pass
        upsmon slave

Finally the local UPS monitor daemon will need to specify the UPS to monitor and the user credentials from upsd.users file. Open the /etc/nut/upsmon.conf file, locate the monitor section and add the following line:

MONITOR apc1200@localhost 1 upsmon_local local_pass master 

The number 1 after the ups name and host is the power value. The man page for upsd states clearly that:

The "current overall power value" is the sum of all UPSes that are currently able to supply power to the system hosting upsmon. Any UPS that is either on line or just on battery contributes to this number. If a UPS is critical (on battery and low battery) or has been put into "forced shutdown" mode, it no longer contributes.
A "power value" on a MONITOR line in the config file is the number of power supplies that the UPS runs on the current system.

Final steps: Open the /etc/nut/nut.conf file and change the value of Mode to netserver -- making sure that there are no spaces between each side of the = sign. (See NOTE at end of file) and issue the following commands:

root@raspbx:/etc/nut# service nut-server start
[ ok ] Starting NUT - power devices information server and drivers:  driver(s). upsd.
root@raspbx:/etc/nut# service nut-client start
[ ok ] Starting NUT - power device monitor and shutdown controller: nut-client.
root@raspbx:/etc/nut# 

As a last check, verify that both services will start automatically on system (using the update-rc.d command) reboot and yes, our server is ready! ...

root@raspbx:~# ps -ef | grep ups
nut       3275     1  0 Apr09 ?        00:08:24 /lib/nut/usbhid-ups -a apc1200
nut       3278     1  0 Apr09 ?        00:00:19 /sbin/upsd
root      3312     1  0 Apr09 ?        00:00:00 /sbin/upsmon
nut       3314  3312  0 Apr09 ?        00:00:09 /sbin/upsmon
root      4721  4711  0 18:44 pts/1    00:00:00 grep ups
root@raspbx:~#

Clients

Client setup requires more or less three things: One will be to edit the nut.conf file and set the mode variable value to netclient. Next will be to place the correct MONITOR line in the upsmon.conf file and the third will be to start the upsmon daemon.

openSUSE

Our first client is an openSUSE 11.4 machine that I keep saying that I must upgrade. To install nut on openSUSE we need to issue the following command as root.

zypper install nut

openSUSE nut stores the configuration files /etc/ups. By the way the file /usr/share/doc/packages/nut/README.SUSE offer excellent detailed and precise information on how to do things right. So to get things started:

  • Add the line MODE=netclient at the end of the /etc/ups/nut.conf file
  • Add MONITOR apc1200@asterisk "UPS supporting the main Servers" to /etc/hosts.conf
  • Comment out any reference to any UPS at the end of /etc/ups/ups.conf
  • Add MONITOR apc1200@asterisk 1 upsom_remote remote_pass slave
  • Start the service with etc/init.d/upsd start. (The reload option can be used to reread updated configuration files
  • Finally change the system config so that the service starts every time you start your system using the following command: chkconfig upsd on

Reboot and verify :

atlas:~ # ps -ef | grep ups
root      2958     1  0 18:06 ?        00:00:00 /usr/sbin/cupsd -C /etc/cups/cupsd.conf
root      3374     1  0 18:06 ?        00:00:00 /usr/sbin/upsmon
upsd      3376  3374  0 18:06 ?        00:00:00 /usr/sbin/upsmon
root      4776  4732  0 18:13 pts/0    00:00:00 grep ups

You might probably want to test the configuration and whether the upsmon daemon can shut-down your server, so go ahead and ...

atlas:~ # upsmon -c fsd
Network UPS Tools upsmon 2.6.0
                                                                               
Broadcast Message from upsd@atlas                                              
        (somewhere) at 13:57 ...                                               
                                                                               
Executing automatic power-fail shutdown                                        
                                                                               
                                                                              

Broadcast message from root@atlas (Wed Apr 10 13:57:06 2013):

The system is going down for system halt NOW!

Debian/Ubuntu

Perhaps the easiest setup is on a Debian system. You only need four steps:

  1. Install just the client: sudo apt-get install nut-client.
  2. Edit the file/etc/nut/nut.conf and set the mode to netclient. MODE=netclient (mind that there must be no spaces around the equals sign).
  3. Add the monitor MONITOR apc900@xena 1 upsom_remote remote_pass slave command in the /etc/nut/upsmon.conf.
  4. Restart the nut-client service
    service nut-client restart
  5. Update the system to start the service automatically update-rc.d nut-client defaults

Fedora and CentOS versions 5 & 6

Fedora also stores the nut related data in /etc/ups. Again here we need to perform the three steps we mentioned before, but this time we will need to start the upsmon daemon by hand. So to set up our fedora box as a network client:

  • Install the software using yum install nut-client
  • Add MONITOR apc1200@asterisk 1 upsom_remote remote_pass slave
  • Add /usr/sbin/upsmon start in /etc/rc.d/rc.local to verify that the monitor program will start again after reboot.
    Note: On my Fedora 20 system the file was not present so I had to create it, turn it into a shell script by adding !/bin/sh at the first line and make it executable.

Verify:

[thanassis@skymnos ~]$ ps -ef | grep upsmon
root      1898     1  0 17:37 ?        00:00:00 /usr/sbin/upsmon start
nut       1900  1898  0 17:37 ?        00:00:00 /usr/sbin/upsmon start
500       2142  2118  0 17:38 pts/0    00:00:00 grep upsmon

NUT Monitor

A very good GUI based tool to help test the ups servers. It can be easily installed using the package manager of your distribution -- just search for the nut-monitor package and after you install and run it, it looks like this:

Windows

Winnut is a Windows client, that runs as a 32bit service on Windows 7. The project has not been updated since February 24, 2011. I did install the software on a Windows machine but have not been able to do any serious testing. The program's configuration follows the same rules as the Linux clients. The only thing you have to is click the edit configuration file button

and then add the correct MONITOR Line in the upsmon.conf file that will appear loaded into notepad. On 64bit systems you will also need to change the line

NOTIFYCMD "\"c:\\Program Files\\WinNUT\\alertPopup.exe\""

to

NOTIFYCMD "\"c:\\Program Files (x86)\\WinNUT\\alertPopup.exe\""

12 comments :

KeithDW said...

This is excellent. I've been wanting to enable my Raspberry Pi to monitor a UPS Server on my network and this seems to do the trick!

I've set up the client on my Raspberry Pi (using Raspbian) and used the NUT Monitor GUI to check everything is talking on.

The issue I have is that when I restart the nut-client I get info saying nut-client disabled, please adjust the configuration to your needs. Then set MODE to suitable value in /etc/nut/nut.conf to enable it.

I've added the line MODE=netclient to the end of the nut.conf file, and to the upsmon.con file added the line

MONITOR ups@192.168.123.251 1 monuser secret slave

(these are the same credentials used in the NUT Monitor GUI, and work!

So, I don't know if this is actually working or not, can you suggest anything I may be doing wrong!

Athanassios Bakalidis said...

The only thing that can go wrong in a setup like this is to leave a space between either side of the = character in nut.conf.

The way to test if everything works is to pull the power plug out of your UPS. You should immediately see a notification on the title bar.

KeithDW said...

If I do

sodo service nut-client restart

it seems to work, I get the message

[ ok ] Restarting NUT - power device monitor and shutdown controller: nut-client.

Does this mean I should change the start at boot instructions to

update-rc.d sudo nut-client defaults

Athanassios Bakalidis said...

Check step 5 of the Debian client setup
and make sure that nut client is started when the system starts.

KeithDW said...

I've done step 5 in the debian setup, but had to add sudo to the beginning

sudo update-rc.d nut-client defaults

If I do

service --status-all

nut-client is there on the list, with a + next to it, so that is good.

If I do

sudo service nut-client status

I get

Checking status of NUT - power device monitor and shutdown controller
[FAIL] upsmon is not running ... failed!

Which obviously isn't so good. Trying

sudo upsmon

I get

Network UPS Tools upsmon 2.6.4
fopen /var/run/nut/upsmon.pid: No such file or directory
UPS: ups@192.168.123.251 (slave) (power value 1)
Using power down flag file /etc/killpower

What is this pid file? Have I done something wrong, you don't mention anything to do with pid files in your tutorial.

Thanks for your help so far. I've had my Raspberry Pi for a few weeks now and feel I'm starting to pick up a few things - it's steep learning curve though...

Athanassios Bakalidis said...

My Debian clients /var looks like this

# ls -ld nut
drwxrwx--- 2 root nut 60 Jun 11 09:03 nut


If you do not see the nut folder in your /var/run, or if the permissions are different.

sudo mkdir /var/run/nut
sudo chgrp nut /var/run/nut
sudo chmod g+w /var/run/nut

I believe that this will make your service start.

Derek said...

I followed this guide to the letter (almost - had to sudo near everything) and the nut-server service would not start AT BOOT for love nor money.

i could happily start the service after login - it would work without issue.

I thought it might have been a service order thing because I'm using wifi, so as a quick hack I created a xxxnutstart.sh in /etc/init.d that would literally JUST TRY AND START THE SERVICE AGAIN (sudo service nut-server start), gave it execute permissions (chmod +x xxxnutstart.sh) and it STILL would not work even as it was the last in order.

there was nothing relevant in /var/log/messages so I just decided to go screw it and put in my newly created xxxnutstart.sh "sleep 60".

and then it worked. I really don't have any idea why, but it does.

I'm going to clean it up a little (find the optimum time to wait and start/stop correctly) but I'm leaving it because it works.

Proof: http://instagram.com/p/vdEoc3Kmiz/

Athanassios Bakalidis said...

@Derek. My opinion is also that the problem is related to your WI-fi setup. The nut server does not find the IP address to bind itself, so the service fails.

One suggestion is to set the nut-server service to start manually and then create a script that sleeps until your wlan0 is up and then fires the service nut-server start command.

If you need help on how to check if your network interface is up, then perhaps this link from Debian might give you a clue.

János Gerzson said...

Thank for the great article, it saved me a lot of time!
Now I don't worry about my server.

Raffaele Macrì said...

@Derek @Athanassios I think the problem is the network. I set 'wait the network' option in raspi-config, now during the boot pi wits for ip from dhcp, no more problems...

Unknown said...

Almost got it to work...

This:

root@raspbx:/etc/nut# service nut-server start
[ ok ] Starting NUT - power devices information server and drivers: driver(s). upsd.
root@raspbx:/etc/nut# service nut-client start
[ ok ] Starting NUT - power device monitor and shutdown controller: nut-client.
root@raspbx:/etc/nut#

Actually just shows me this:

root@raspbx:/etc/nut# service nut-server start
root@raspbx:/etc/nut# service nut-client start

Running "update-rc.d" as is, does nothing.


And running "ps -ef | grep ups" :

root@nutserver:~# ps -ef | grep ups
root 648 1 0 20:33 ? 00:00:00 /lib/nut/upsmon
nut 650 648 0 20:33 ? 00:00:00 /lib/nut/upsmon
nut 1277 1 0 20:35 ? 00:00:00 /lib/nut/usbhid-ups -a cyberpower
nut 1280 1 0 20:35 ? 00:00:00 /lib/nut/upsd
root 1482 1227 0 20:36 pts/0 00:00:00 grep ups
root@nutserver:~#



Athanassios Bakalidis said...

@Unknown
I think that you are probably using the latest Raspbian image that is based on Debian Jessie, which uses systemd. This how-to was written for the previous version based on Wheezy that used tc.d scripts. As soon as I can get some free time, I promise to update this how to or even write a new one that explains how to do it for Jessie.