The FreeBSD Diary

A UPS is often used to keep systems running despite loss of power. Most of the UPS units you buy in the store will give you at least a few minutes. Around here, that will cover 95% of all power failures. It also protects the equipment from those nasty power spikes. It is the off/on effect that can cause damage. Even slight drops in voltage can cause reboots. I use UPS units mainly to prevent damage and secondly to prevent service interruption for minor power issues.

I use APC UPS units. Nothing else. I have had good experiences with their products and it is now well supported in FreeBSD. Despite having had APC UPS devices for many years, I have never tried apcupsd until relatively recently. There were problems around the USB interface with FreeBSD and APC units. These have recently been fixed. As far back as November 2003, I was trying to get things works. Details have been recorded in my APC library.

In this article, I will show you how I installed and configured apcupsd so that it would politely shutdown my computers should the power go out, and things start to look bad.

Why apcupsd? Because it works. The homepage describes apcupsd as:

Apcupsd can be used for power management and controlling most of APC's UPS models on Unix and Windows machines. Apcupsd works with most of APC's Smart-UPS models as well as most simple signaling models such a Back-UPS, and BackUPS-Office. During a power failure, apcupsd will inform the users about the power failure and that a shutdown may occur. If power is not restored, a system shutdown will follow when the battery is exhausted, a timeout (seconds) expires, or runtime expires based on internal APC calculations determined by power consumption rates. Apcupsd is licensed under the GPL version 2.

I was using FreeBSD 6.1 when I did this. Of course, apcupsd is in the Port tree, so I installed it using these commands:

cd /usr/ports/sysutils/apcupsd
make install clean

For configuration options, I selected CGI, USB, and SNMP.

I then proceeded to the APC UPS Daemon manual. You will notice that the author is Kern Sibbald. I know Kern through his work on backup software. Disclosure: I am a committer on the Bacula project. The documentation is thorough.

At the time of writing, there was a list of FreeBSD kernel configuration issues. These are no longer required. apcupsd now works with a GENERIC kernel on FreeBSD 6.1; there is no longer a need to disable uhid or enable egen. As well, the FreeBSD kernel panics if USB cable is unplugged while apcupsd is running.

In short, apcupsd works out of the box, with the correct configuration items.

Recent APC UPS units come with a USB cable. One end is a USB cable. The other resembles an RJ45 plug. After connecting the USB end of the cable to my server, and the other to the UPS, I saw this in /var/log/message:

Apr  4 12:24:01 myhost kernel: ugen0: American Power Conversion Back-UPS RS 1000 
      FW:7.g8 .D USB FW:g8, rev 1.10/1.06, addr 2

This date precedes that mentioned at the start of this article. At this time, I was testing patches supplied to me by ITetcu, who was working on the port.

You need this entry in /etc/rc.conf to allow apcupsd to start:

apcupsd_enable="YES"

I rushed ahead and started up the daemon with this command:

/usr/local/etc/rc.d/apcupsd start

But it did not start. In /var/log/messages, I found this:

Apr  4 12:45:07 myhost apcupsd[82063]: apcupsd FATAL ERROR in smartsetup.c at line 67 
        Cannot open UPS port /dev/usv: No such file or directory
Apr  4 12:45:07 myhost apcupsd[82063]: apcupsd error shutdown completed

Well, I guess a configuration file would be a good thing.

cd /usr/local/etc/apcupsd
cp apcupsd.conf.sample apcupsd.conf

Experimentation and reading made me select the following values in that file:

UPSTYPE usb
DEVICE /dev/ugen0

I knew the DEVICE value from the entry in /var/log/messages. I guessed the UPSTYPE from the available options. Now when I started the daemon, I saw this entry in /var/log/message

Jun 15 14:59:22 myhost apcupsd[52113]: apcupsd 3.12.3 (26 April 2006) freebsd startup succeeded

NOTE: the above date is more recent, because I decided at a later date that it would be nice to have this entry. It does not date from the original event.

Then I decided it was a good idea to read more of the manual. I went to Testing Apcupsd and decided to run these tests:

 $ apcaccess status
 APC      : 001,034,0868
 DATE     : Tue Apr 04 13:17:13 EDT 2006
 HOSTNAME : myhost.example.org
 RELEASE  : 3.10.18
 VERSION  : 3.10.18 (21 July 2005) freebsd
 UPSNAME  : myhost.example.org
 CABLE    : Custom Cable Smart
 MODEL    : Back-UPS RS 1000
 UPSMODE  : Stand Alone
 STARTTIME: Tue Apr 04 13:07:28 EDT 2006
 STATUS   : ONLINE
 LINEV    : 121.0 Volts
 LOADPCT  :  49.0 Percent Load Capacity
 BCHARGE  : 100.0 Percent
 TIMELEFT :  16.2 Minutes
 MBATTCHG : 5 Percent
 MINTIMEL : 3 Minutes
 MAXTIME  : 0 Seconds
 LOTRANS  : 097.0 Volts
 HITRANS  : 138.0 Volts
 ALARMDEL : Always
 BATTV    : 26.8 Volts
 NUMXFERS : 0
 TONBATT  : 0 seconds
 CUMONBATT: 0 seconds
 XOFFBATT : N/A
 SELFTEST : NO
 STATFLAG : 0x02000008 Status Flag
 MANDATE  : 2003-08-11
 SERIALNO : JB0333002394
 BATTDATE : 2001-09-25
 NOMBATTV :  24.0
 FIRMWARE : .g8 .D USB FW:g8
 APCMODEL : Back-UPS RS 1000
 END APC  : Tue Apr 04 13:17:13 EDT 2006

That looks good. Then I promptly forgot about apcupsd. When I moved the rack from one side of the furnace to another, the USB cable never got reconnected, and I eventually commented out apcupsd from /etc/rc.conf.

Late one night, I saw Scott Long asking about apcupsd. That was when I found my notes for this article and fed him what I had. He got a little further ahead, but we were both stumped by apctest. We were seeing this:

# apctest
2006-06-15 13:04:47 apctest 3.12.3 (26 April 2006) freebsd
Checking configuration ...
Attached to driver: usb
sharenet.type = DISABLE
cable.type = CUSTOM_SMART

You are using a SMART cable type, so I'm entering SMART test mode
mode.type = USB_UPS
Setting up the port ...
Hello, this is the apcupsd Cable Test program.
This part of apctest is for testing Smart UPSes.
Please select the function you want to perform.

1) Query the UPS for all known values
2) Perform a Battery Runtime Calibration
3) Abort Battery Calibration
4) Monitor Battery Calibration progress
5) Program EEPROM
6) Enter TTY mode communicating with UPS
7) Quit

Select function number: 1YWrote: Y Got:
getline failed. Apparently the link is not up.
Giving up.

Select function number: 7

2006-06-15 13:05:36 End apctest.

Then John Baldwin piped in with his configuration settings. Namely:

UPSCABLE usb
UPSTYPE usb

Success! Running apctest now gives us this:

# apctest
2006-06-15 14:49:41 apctest 3.12.3 (26 April 2006) freebsd
Checking configuration ...
Attached to driver: usb
sharenet.type = DISABLE
cable.type = USB_CABLE

You are using a USB cable type, so I'm entering USB test mode
mode.type = USB_UPS
Setting up the port ...
Hello, this is the apcupsd Cable Test program.
This part of apctest is for testing USB UPSes.

Getting UPS capabilities...SUCCESS

Please select the function you want to perform.

1) Test kill UPS power
2) Perform self-test
3) Read last self-test result
4) Change battery date
5) View battery date
6) View manufacturing date
7) Set alarm behavior
8) Quit

Select function number: 2


This test instructs the UPS to perform a self-test
operation and reports the result when the test completes.

Clearing previous self test result...CLEARED
Initiating self test...INITIATED
Waiting for test to complete...COMPLETED
Result of last self test: PASSED

1) Test kill UPS power
2) Perform self-test
3) Read last self-test result
4) Change battery date
5) View battery date
6) View manufacturing date
7) Set alarm behavior
8) Quit

Select function number: 3

Result of last self test: PASSED

1) Test kill UPS power
2) Perform self-test
3) Read last self-test result
4) Change battery date
5) View battery date
6) View manufacturing date
7) Set alarm behavior
8) Quit

Select function number: 8

2006-06-15 14:52:06 End apctest.
#

If you see this:

# apctest


2007-09-16 16:56:28 apctest 3.14.1 (04 May 2007) freebsd
Checking configuration ...
Attached to driver: usb
sharenet.type = DISABLE
cable.type = USB_CABLE

You are using a USB cable type, so I'm entering USB test mode
mode.type = USB_UPS
Setting up the port ...
apctest FATAL ERROR in bsd-usb.c at line 711
Cannot find UPS device --
For a link to detailed USB trouble shooting information,
please see .
apctest error termination completed
#

Then apcupsd is probably running. Stop it and try apctest again. This scenario will also produce an entry like this in /var/log/messages:

apctest: Valid lock file for pid=9838, but not ours pid=9839

I ran the Communications Test, followed by the Simulated Power Fail Test. The Communications Test produced these entries in /var/log/apcupsd.events:

Thu Jun 15 15:25:24 EDT 2006  Communications with UPS lost.
Thu Jun 15 15:25:36 EDT 2006  Communications with UPS restored.

In addition to these entries, emails were also sent to root, one for each event. Then I did a very short simulated power failure test. Be careful here. You might power off your system unexpectedly. Read the details in the Simulated Power Fail Test of the APC UPS Daemon manual (the link is just above). This test produced these log entries:

Jun 15 15:49:47 myhost apcupsd[697]: UPS Self Test switch to battery.
Jun 15 15:50:07 myhost apcupsd[697]: Running on UPS batteries.
Jun 15 15:50:40 myhost apcupsd[697]: Mains returned. No longer on UPS batteries.
Jun 15 15:50:40 myhost apcupsd[697]: Power is back. UPS running on mains.

As with the previous test, two emails were sent out to root, one for the power going off, another for the power coming back on.

These are the entries I saw when apcupsd actually shutdown the box:

Jun 15 16:04:38 myhost apcupsd[909]: Reached run time limit on batteries.
Jun 15 16:04:38 myhost apcupsd[909]: Initiating system shutdown!
Jun 15 16:04:38 myhost apcupsd[909]: User logins prohibited
Jun 15 16:04:38 myhost apcupsd[909]: Attempting to kill the UPS power!
Jun 15 16:04:38 myhost shutdown: halt by dan: apcupsd initiated shutdown
Jun 15 16:04:57 myhost apcupsd[909]: apcupsd exiting, signal 15
Jun 15 16:04:57 myhost apcupsd[909]: apcupsd shutdown succeeded
Jun 15 16:04:59 myhost syslogd: exiting on signal 15

Remember to reset any configuration file changes you did for testing. And then restart apcupsd so it knows about those changes!

Apart from the above mentioned changes, I left everything the way it was installed. The default settings should be enough for me. I will review them when I write the next apcupsd article on the CGI interfaces and Slave configurations.

Time will tell. The next time we get a power outage, it will be interesting to see if everything proceeds as planned. :)