NOTE: I abbandoned this project few months ago since I found the very good apcupsd port in FreeBSD ports tree, which works great with my APC RS 1000 ups.
A few months ago I purchased an APC
RS 1000 UPS device.
It comes with a USB cable to attach it to your PC, and with an APC software
bundle to check UPS status.
Bundled software is for MS Windows only, and since I had to attach a FreeBSD
server to this UPS, it was totally useless for me.
So I started searching FreeBSD ports tree to find a daemon that could listen
to UPS messages, and simply start commands on critical events, such as starting
a backup of important files on power failures, and shutting down the server
when battery level is too low.
I tried a few things but none of them worked with this UPS model, or they were
just too complex to install or use (I think that installing a 10 Megabytes package
just to start a command when the power fails is wast of space/time/resurces!).
Finally I found a C source that does some of the simple things I needed, but
it was an unfinished prototype, so I decided to develop my own daemon: apcusbd.
apcusbd is a daemon, written in Perl, that lets your FreeBSD box, listen in on an APC UPS attached via a USB cable, and react to the following three events, launching commands you specify in configuration:
OnBattery: utility power failure, UPS started using battery power
OnUtility: utility power restored, UPS stopped using batteries
OnShutdown: UPS on battery and battery charge level is low (under a specified threshold)
There are three main files for apcusbd (see INSTALL document in distribution package to know how to install these files on your system):
apcusbd: this is the main Perl script. It requires Perl 5 or better. You should copy it in /usr/local/sbin .
apcusbd.sh: this is the daemon control script, used to start/stop/restart the daemon. You should copy it in /usr/local/etc/rc.d .
apcusbd.conf: this contains daemon configuration. Usually you will copy it in /usr/local/etc (or in /etc).
Once you have installed these files, you will need to configure apcusbd.
Please see INSTALL document for a detailed installation procedure and hints
about configuration.
The most difficult part of the configuration process is finding the device file
that your system used for the APC monitor usb unit.
Explore dmesg results to find it.
Example:
on my FreeBSD box, dmesg reports following device:
%dmesg | grep -i ups
uhid0: American Power Conversion Back-UPS RS 1000 FW:7.g8 .I USB FW:g8, rev 1.10/1.06, addr 2, iclass 3/0
This means that /dev/uhid0 is the UPS device on my system, and that I had to put the following line in apcusbd.conf file:
upsdev "/dev/uhid0"
Also you can specify a commqnd to run for each the three events apcusbd can track. Example: to send root user a message on power failure, you can add the following to apcusbd.conf file:
onbatterycmd "echo power failure | mail -E -s apcusbd root"
You can keep track of UPS related events with syslog. Default apcusbd syslog facility is local6 but you can change it in apcusbd.conf.
You can also add a safe-shutdown command to run when UPS is on battery and battery charge level runs under a defined threshold. Example: following lines let apcusbd start a system shutdown when battery level goes under 5%:
shutdownthreshold 5
shutdowncmd "shutdown -h now"
apcusbd had been tested on a FreeBSD 5.3 with a APC RS 1000 (firmware 7.g8) UPS unit. It will likely work on different configuration but I had not personally tried it. If you tried a different configuration, please write it to me, so that I can add your comments here.
I released apcusbd as open source software with the following license:
Redistribution and use, with or without modification, are permitted
provided that the following conditions are met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. The name of the author may not be used to endorse or promote products
derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Download release 0.02 (5Kb - 2005-07-04): apcusbd.tgz
For any suggestions or question, please write to maurizio@mauriziogiunti.it.
