Apcupsd

From Gentoo Linux Wiki

Wikipedia has an article on:

Apcupsd

[edit] Objectives

By the time you’ve gone through all this, you should have:

• USB support for your APC UPS.
• Power management support allowing apcupsd to completely poweroff the system (rather than simply halting it, requiring a manual poweroff at the mains).
• Functionality allowing apcupsd to control and monitor multiple systems over Ethernet in a master/slave configuration.
• The ability to monitor the status of your UPS with apcupsd via your favorite browser.

[edit] Prerequisites

This HOWTO assumes the following:

• You own an APC UPS attached via the supplied USB cable to a Gentoo installation. I don’t know anything about other cables, non-APC products, other Linux distributions, the UPS with the bad smell your brother found in the parking lot, etc. La-la-la, I can’t hear you… (<---ROLF)

-works with APC-UPS with seriall cable too.. tested on a SMART-UPS 3000 RM and a SMART-UPS 2200 RM, also master slave setup and web..

• You will be performing these operations on an x86-based system…however, I have at least one report of this HOWTO functioning for AMD64 systems. (Note: You got another: AMD Athlon(tm) 64 Processor 3000+ running with gentoo 2005.1 AMD64, with apcupsd 3.10.18-r1, ups is APC Back-UPS CS 650 - code bk650ei)
• Your master and slave machines will both be running some version of Gentoo. If you’re mixing your operating systems, I’d be interested to hear what was necessary to adapt these procedures.
• You are familiar with the procedures and potential consequences of recompiling your own kernel.
• You already have Apache configured and running on the system that will act as the master for apcupsd (namely the one the USB cable’s plugged into). If you’re not interested in the browser status aspect of this HOWTO, feel free to ignore this.
• You understand enough about networking protocols (and your own network) to be dangerous.
• You can use a text editor.

If any of the above is not true, you’re either in the wrong place or have bigger problems to worry about than playing with your UPS.

[edit] Known Working UPS

(Please add your working model number, links would be nice too )

[edit] Kernel Configuration

The first thing we’ll need to do is recompile our kernel to support both USB and ACPI or APM on the system that will act as the master installation. If you don’t know whether your machine supports APM or ACPI, reboot and go root around in your BIOS options (usually under “Power Management” oddly enough). If you see something like “Enable ACPI [y/n]?” you know what you’ve got and what the response to that [y/n] should be. The rule seems to be that pre-millennium boards use APM, more recent hardware uses ACPI. Just make a note of which you’re using for now; we’ll come back to it momentarily.

One more thing: if you’re using ACPI, you may want to add it to your USE settings in /etc/make.conf. I didn’t and lived to tell the tale, but it’s up to you.

Now, drop into a console, su to root, and grab your favorite kernel sources:

cd /usr/src/linux; make menuconfig

First, let’s get the power management squared away. Make sure the following are enabled in your kernel...for 2.4 kernels, yours might want to look like this:

General setup  --->
   [*] Power Management support
   < >   Advanced Power Management BIOS support
   ACPI Support  --->
      [*] ACPI Support
      < >   AC Adapter
      < >   Battery
      <M>   Button
      < >   Fan
      <M>   Processor
      < >   Thermal Zone
      < >   ASUS Laptop Extras
      < >   Toshiba Laptop Extras
      [ ]   Debug Statements
      [ ]   Relaxed AML Checking

For 2.6 kernels, try this:

Power management options (ACPI, APM)  --->
    [*] Power Management support
    [ ]   Software Suspend (EXPERIMENTAL)
    [ ]   Suspend-to-Disk Support
         ACPI (Advanced Configuration and Power Interface) Support  --->
         [*] ACPI Support
         [ ]   Sleep States (EXPERIMENTAL)
         <*>   AC Adapter
         <*>   Battery
         <*>   Button
         < >   Fan
         <*>   Processor
         < >   Thermal Zone
         < >   ASUS/Medion Laptop Extras
         < >   Toshiba Laptop Extras
         [ ]   Debug Statements
         [ ]   Power Management Timer Support

Obviously, my master machine uses ACPI. I found these options to be the minimum I was comfortable with; you may want more, and you’re welcome to try less.

If you’re using APM, you’ll probably want to disable ACPI support and try something like this for your 2.4 kernel:

General setup  --->
   [*] Power Management support
   <*>   Advanced Power Management BIOS support
   [ ]     Ignore USER SUSPEND
   [*]     Enable PM at boot time
   [ ]     Make CPU Idle calls when idle
   [ ]     Enable console blanking using APM
   [ ]     RTC stores time in GMT
   [*]     Allow interrupts during APM BIOS calls
   [*]     Use real mode APM BIOS call to power off
   ACPI Support  --->

...or this, for your 2.6 kernel:

Power management options (ACPI, APM)  --->
    [*] Power Management support
    [ ]   Software Suspend (EXPERIMENTAL)
    [ ]   Suspend-to-Disk Support
       APM (Advanced Power Management) BIOS Support  --->
       <M> APM (Advanced Power Management) BIOS support
       [*]   Ignore USER SUSPEND (NEW)
       [ ]   Enable PM at boot time (NEW)
       [ ]   Make CPU Idle calls when idle (NEW)
       [ ]   Enable console blanking using APM (NEW)
       [ ]   RTC stores time in GMT (NEW)
       [*]   Allow interrupts during APM BIOS calls (NEW)
       [*]   Use real mode APM BIOS call to power off (NEW)

With these options enabled in the kernel, your machine should power itself off on a halt without you having to stab the power button.

As a side note, I’ve read that ACPI and SMP do not play well together. There are several threads about this on the forums, so I won’t go into it…just be advised that if you’re running multiple processors or one of those new-fangled Pentiums with HT technology, this may be an issue for you.

Next, we’ll get USB support set for our UPS (2.4 kernels first):

USB support  --->
   <M> Support for USB
   [ ]   USB verbose debug messages
   --- Miscellaneous USB options
   [*]   Preliminary USB device filesystem
   [ ]   Enforce USB bandwidth allocation (EXPERIMENTAL)
   --- USB Host Controller Drivers
   ...
   <M>   OHCI (Compaq, iMacs, OPTi, SiS, ALi, ...) support
   < >   SL811HS Alternate (x86, StrongARM, isosynchronous mode)
   ...
   <M>   USB Human Interface Device (full HID) support
   ---     Input core support is needed for USB HID input layer or HIDBP
   [*]     /dev/hiddev raw HID device support
   < >   USB HIDBP Keyboard (basic) support
   < >   USB HIDBP Mouse (basic) support

Now, for 2.6 kernels:

Device Drivers  --->
    USB support  --->
         <*> Support for Host-side USB
         [ ]   USB verbose debug messages
         ---   Miscellaneous USB options
         [*]   USB device filesystem
         [ ]   Enforce USB bandwidth allocation (EXPERIMENTAL)
         [ ]   Dynamic USB minor allocation (EXPERIMENTAL)
         ---   USB Host Controller Drivers
         < >   EHCI HCD (USB 2.0) support
         <*>   OHCI HCD support
         ...
         ---   USB Human Interface Devices (HID)
         <*>   USB Human Interface Device (full HID) support
         [*] HID input layer support
         [ ]   Force feedback support (EXPERIMENTAL)
         [*] /dev/hiddev raw HID device support
         ...
         USB Gadget Support  --->

The hiddev option has moved in 2.6.23:

Device Drivers  --->
    HID Devices  --->
         ...
         [*] /dev/hiddev raw HID device support
         ...

There are a couple things to note here. First, make sure you build support for USB as a module in 2.4 kernels only; builtin is preferable for 2.6 kernels.

Second, the Preliminary USB device filesystem is very important (as I found when I took my first swing at this project). I had neglected to build this in; the result gave me a seemingly functional installation with full communication between apcupsd and the UPS. I just couldn’t get apcupsd to shutdown the machine, which I viewed as a rather important piece of functionality. Make sure it’s there.

Next, be sure to build the appropriate driver for your chipset. Mine is made by SiS, hence I use the OHCI driver…if you use Intel or VIA, you need the UHCI driver. If you don’t know what you use, do an Alt-F2 (or open a new console window, or whatever) and run:

/sbin/lsusb –v

This will list all the USB devices; you should find your answer somewhere in there. (Please note that lsusb is included as part of the sys-apps/usbutils package in Portage.)

Note that I don’t have anything else enabled in the way of printers, audio, Bluetooth…that’s because the UPS is the only USB device plugged into this system. Your needs may be different.

That’s it for the kernel. Hit Esc twice, and do the usual for 2.4 kernels:

# make dep && make bzImage modules modules_install
# mount /boot/
# cp arch/i386/boot/bzImage /boot/kernel-<your-kernel-version-goes-here>
# cp System.map /boot/System.map-<your-kernel-version-goes-here>
# cp .config /boot/config-<your-kernel-version-goes-here>

...or, if you have a 2.6 kernel:

# make && make modules_install
# mount /boot/
# cp arch/i386/boot/bzImage /boot/kernel-<your-kernel-version-goes-here>
# cp System.map /boot/System.map-<your-kernel-version-goes-here>
# cp .config /boot/config-<your-kernel-version-goes-here>

Remember to update bootloader configuration if necessary.

Finally, this would be a good time to <-- old school you probably don't need this unless you have an old setup

if it’s not already running on your installation.

EDIT: "[F]unctionality previously provided by coldplug is integrated in recent versions of udev. Unmerge coldplug if it is installed, then upgrade to a version of udev > 089".

As long as you have a newer version of udev, you do NOT need to install hotplug/coldplug.

Remember that whole “master/slave” thing about controlling two machines with one UPS? If you’ve got a standalone machine (one UPS controlling one machine) you’re done…if, however, you’ve got multiple machines on the same UPS you’ll want to head over to your slave machine at this point and make sure that it also has the appropriate power management built into its kernel. Whether you compile with USB support on the slave is up to you…it’s not necessary for our purposes here, though.

If everything looks good, make sure your UPS is plugged in at both ends and reboot into your new kernel.

[edit] Checking your USB subsystem

For a more detailed explanation, see the document from which this was shamelessly cribbed.

Basically, you just run:

# cat /proc/bus/usb/devices

You should see something analogous to the following:

T:  Bus=01 Lev=01 Prnt=01 Port=00 Cnt=01 Dev#=  2 Spd=1.5 MxCh= 0
D:  Ver= 1.10 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs=  1
P:  Vendor=051d ProdID=0002 Rev= 1.00
S:  Manufacturer=American Power Conversion
S:  Product=Back-UPS 350 FW: 5.2.I USB FW: c1
S:  SerialNumber=BB0115017954
C:* #Ifs= 1 Cfg#= 1 Atr=a0 MxPwr= 30mA
I:  If#= 0 Alt= 0 #EPs= 1 Cls=03(HID  ) Sub=00 Prot=00 Driver=hid
E:  Ad=81(I) Atr=03(Int.) MxPS=   8 Ivl= 10ms

To quote the apcupsd User’s Manual, “In general, if you see your UPS model in the S field, you're done.” If you don’t, you have a problem. You also need to check the I field: if driver is set to none you have a problem (missing HID device in kernel configuration?). Double-check your kernel configuration, try unplugging and re-plugging the USB cable, make sure the cable is firmly seated at both ends, and see the link above for more troubleshooting tips. If none of this helps, you’re unfortunately now outside the scope of this HOWTO. Seek help from your local guru.

Assuming that went according to plan, now would also be a good time to make sure our power management is working properly.

# shutdown –h now

Your system should power itself down without any manual assistance from you…if it doesn’t, you’ve got some more homework to do. Don’t forget to check your slave machine for this functionality as well.

Good so far? Then let’s get apcupsd installed on our master machine.

[edit] Installing and configuring APCUPSD

As usual, this is an absolutely painless process in Gentoo. Emerge apcupsd and set it to start automatically. You might need to enable the "usb" USE-flag. Check with: emerge -pv apcupsd
If usb is disabled: add this to /etc/portage/package.use: sys-power/apcupsd usb

# emerge sync; emerge apcupsd; rc-update add apcupsd default

Now it’s time to start configuring our master installation:

# nano -w /etc/apcupsd/apcupsd.conf

As you can see, there’s quite a bit in here. Feel free to consult the apcupsd User’s Manual for some sample configurations and advice; I’ll provide mine below and try to hit the important stuff, but it’s extremely beneficial to understand what’s happening within this file.

## apcupsd.conf v1.1 ##
#
#  for apcupsd release 3.10.9 (31 December 2003) – gentoo
#  “sample master” configuration file
UPSNAME                              <some-unique-string>
UPSCABLE                             usb
UPSTYPE                              usb
LOCKFILE                             /var/lock
ONBATTERYDELAY                       6
BATTERYLEVEL                         5
MINUTES                              3
TIMEOUT                              0
ANNOY                                300
ANNOYDELAY                           60
NOLOGON                              disable
KILLDELAY                            0
NETSERVER                            on
NISPORT                              3551
EVENTSFILE                           /var/log/apcupsd.events
EVENTSFILEMAX                        10
UPSCLASS                             netmaster
UPSMODE                              net
NETTIME                              10
NETPORT                              6666
SLAVE                                <your-slave-machine’s-IP-address>
USERMAGIC                            <some-unique-string>
STATTIME                             0
STATFILE                             /var/log/apcupsd.status
LOGSTATS                             off
DATATIME                             0

##  for apcupsd release 3.14.1 (04 May 2007) - gentoo
#
# "apcupsd" POSIX config file
UPSNAME <some-unique-string>
UPSCABLE smart
UPSTYPE apcsmart
DEVICE /dev/ttyS0
LOCKFILE /var/lock
SCRIPTDIR /etc/apcupsd
PWRFAILDIR /etc/apcupsd
NOLOGINDIR /etc/apcupsd
ONBATTERYDELAY 15
BATTERYLEVEL 10
MINUTES 10
TIMEOUT 0
ANNOY 300
ANNOYDELAY 60
NOLOGON disable
KILLDELAY 0
NETSERVER on
NISIP <ip address>
NISPORT 3551
EVENTSFILE /var/log/apcupsd.events
EVENTSFILEMAX 50
STATTIME 0
STATFILE /var/log/apcupsd.status
LOGSTATS off
DATATIME 0
FACILITY DAEMON
UPSCLASS standalone
UPSMODE disable

There are several things to note here.

[edit] Version 3.1.9

• For our purposes, both UPSCABLE and UPSTYPE must be set to usb in order to establish communication with the UPS.
• You’ll notice that the DEVICE parameter does not appear here. That’s because it’s been commented out of my apcupsd.conf file. See this for the reason why.
• You’ll also notice that NISIP does not appear here, as it has also been commented out. See this thread (again) for the reason why.
• The NETSERVER and NISPORT settings are crucial to obtaining status information from apcupsd. Make sure they appear as listed in the above file.
• UPSCLASS must be set to netmaster and UPSMODE must be set to net in order for this installation to act as the master. If you’ll be running the standalone configuration without a slave, see below.
• SLAVE is the IP address or FQDN of your slave machine.
• USERMAGIC is a basic form of authentication between the master and slave. Break out your favorite password generator and enter the results here. Make sure you’ve got it handy somewhere; you’ll need it again for the slave machine’s configuration file.

[edit] Version >3.14.1

• NISIP is IP-address of your ups connected server which starts at NISPORT.
• UPSCLASS is used only when APC ShareUPS card is used to share UPS else you have to set it to standalone.

*UPCMODE disable until APC ShareUPS card is used.

• in version 3.14.1 SLAVE ip-addresses are not listed everyone who connects to the NISIP:NISPORT can use apcupsd ups data.
• BATTERYLEVEL and MINUTES if you have more servers connected to your UPS, increase these values because much more power and time is needed to properly shutdown 3-4 servers.
• FACILITY is logging level which is used to log messages to system logger daemon

For those of you planning on running with one UPS powering one machine, you’ll want something like the following:

## apcupsd.conf v1.1 ##
#
#  for apcupsd release 3.10.9 (31 December 2003) – gentoo
#  “sample standalone” configuration file
UPSNAME                              <some-unique-string>
UPSCABLE                             usb
UPSTYPE                              usb
LOCKFILE                             /var/lock
ONBATTERYDELAY                       6
BATTERYLEVEL                         5
MINUTES                              3
TIMEOUT                              0
ANNOY                                300
ANNOYDELAY                           60
NOLOGON                              disable
KILLDELAY                            0
NETSERVER                            on
NISPORT                              3551
EVENTSFILE                           /var/log/apcupsd.events
EVENTSFILEMAX                        10
UPSCLASS                             standalone
UPSMODE                              disable
STATTIME                             0
STATFILE                             /var/log/apcupsd.status
LOGSTATS                             off
DATATIME                             0

## apcupsd.conf v1.1 ##
# 
#  for apcupsd release 3.14.1 (04 May 2007) - gentoo
#
# "apcupsd" POSIX config file
UPSNAME                      <some-unique-string>
UPSCABLE                      ether
UPSTYPE                        net
DEVICE                          <NIS server ip address:port>
LOCKFILE                       /var/lock
SCRIPTDIR                     /etc/apcupsd
PWRFAILDIR                  /etc/apcupsd
NOLOGINDIR                /etc/apcupsd
UPSCLASS                     standalone
UPSMODE                     disable
EVENTSFILE                  /var/log/apcupsd.events
EVENTSFILEMAX          50
STATTIME                    0
STATFILE                     /var/log/apcupsd.status
LOGSTATS                   off
FACILITY                      DAEMON

Note the differences between the files:

[edit] Version 3.1.9

• NETTIME, NETPORT, SLAVE, and USERMAGIC are no longer relevant and have been removed.
• UPSCLASS must be set to standalone and UPSMODE must be set to disable.

[edit] Version 3.14.1

• UPSCABLE must be set to ether to use ethernet cable to connect more apcupsd daemons to NIS server.
• UPSTYPE can be net or pcnet
  • net is used for classic apcupsd NIS services
  • pcnet is used for PowerChute Network Shutdown Driver
• DEVICE specify ip address of master server.

Once you’re satisfied with your apcupsd.conf file, save it and proceed to...

[edit] Starting APCUPSD

It’s time to kick this thing in the guts and see if it runs. Start apcupsd manually with:

# /etc/init.d/apcupsd start

If you’ve followed the configuration guidelines above, you should get a clean start from apcupsd.

 * Starting APC UPS daemon...                                   [ ok ]

If you don't get a clean start, you need to double-check your previous work. Check your log with

# tail -f /var/log/apcupsd.events

to see what went wrong.

# /etc/init.d/apcupsd zap

This will allow you a clean start (after you’ve changed something, presumably) rather than forcing a reboot of the system to clear the process.

ANOTHER NOTE ON BAD STARTS: You may get an error message similar to the following:

apcupsd FATAL ERROR in linux-usb.c at line 684
Cannot open UPS device:

Before ransacking your kernel configuration or the apcupsd.conf file, try the following procedure. Make sure apcupsd is stopped and do a running tail of your log:

# /etc/init.d/apcupsd zap
# tail -f /var/log/apcupsd.events

Now unplug your USB cable from your machine and plug it back in. You should see the stats for your UPS pop up in the tail you've got running. Cancel the tail and attempt to start apcupsd again; it should start with no problems if everything else is in order. If you don't see your UPS in the tail after a few unplug/replug attempts, you probably do need to go back and check your kernel configuration and apcupsd.conf file.

Now it's time to test apcupsd for full functionality. We'll run through each of these tests in brief; for more detailed testing information, please refer to the invaluable-and-frequently-cited apcupsd User's Manual section on this subject.

A FURTHER NOTE: During these tests, you may not get wall messages to your console; instead, you may see things like the following in /var/log/apcupsd.events:

Feb 10 15:36:17 <your-host-here> sSMTP[2626]: Unable to locate mail
Feb 10 15:36:17 <your-host-here> sSMTP[2626]: Cannot open mail:25
Feb 10 15:36:17 <your-host-here> wall[2630]: wall: user root broadcasted 1 lines (42 chars)

These have to do with system configurations that I'm not particularly interested in. See the man pages or your local guru if this bothers you.

ectospasm notes that you can drop the wall messages entirely (if they annoy you) by commenting out the “WALL=wall” variable in /etc/apcupsd/apccontrol, like so:

#
# These variables are needed for set up the autoconf other variables.
#
prefix=/usr
exec_prefix=${prefix}

APCPID=/var/run/apcupsd.pid
APCUPSD=/usr/sbin/apcupsd
SHUTDOWN=/sbin/shutdown
SCRIPTSHELL=/bin/sh
SCRIPTDIR=/etc/apcupsd
# WALL=wall

Note that you'll have to do this each time you upgrade apcupsd.

[edit] Testing APCUPSD

[edit] Testing APCUPSD – Process-Status Test

Once you've got apupsd started, execute the following command:

# ps fax

You should see something similar to the following in the output:

 9870 ?        Ss     0:00 apcmain
 9887 ?        S      0:00  \_ apcnis
 9888 ?        S      0:00  \_ apcdev

If you only see one instance of apcupsd running, don't sweat it unless the communication test fails. If there are no instances of apcupsd, go back and check /var/log/apcupsd.events...

[edit] Testing APCUPSD – Logging Test

Now that we know the apcupsd processes are running, do a tail of your system log file:

# tail -f /var/log/apcupsd.events

You should see something similar to the following:

Feb 11 11:07:37 <your-host-here> apcupsd[2411]: apcupsd 3.10.9 (31 December 2003) gentoo startup succeeded
Feb 11 11:07:37 <your-host-here> apcupsd[2431]: NIS server startup succeeded
Feb 11 11:08:07 <your-host-here> apcupsd[2430]: Slave connection failed Connection refused! Down slave 0

Don't worry about the failed slave connection; we haven't set our slave up yet. If you don't see the message about the NIS server successfully starting, check your apcupsd.conf file and make sure you enabled the proper options (as outlined above).

[edit] Testing APCUPSD – apcaccess Test

Run the following:

# apcaccess status

Your output should resemble the following:

APC      : 001,027,0653
DATE     : Wed Feb 11 11:12:37 EST 2004
HOSTNAME : <your-host-here>
RELEASE  : 3.10.9
VERSION  : 3.10.9 (31 December 2003) gentoo
UPSNAME  : APC
CABLE    : USB Cable
MODEL    : Back-UPS 350
UPSMODE  : Net Master
STARTTIME: Wed Feb 11 11:07:37 EST 2004
SHARE    : NetworkUPS
STATUS   : ONLINE
BCHARGE  : 100.0 Percent
TIMELEFT :  43.0 Minutes
MBATTCHG : 5 Percent
MINTIMEL : 3 Minutes
MAXTIME  : 30 Seconds
NUMXFERS : 0
TONBATT  : 0 seconds
CUMONBATT: 0 seconds
XOFFBATT : N/A
STATFLAG : 0x02000008 Status Flag
MANDATE  : 2003-05-15
BATTDATE : 2003-05-15
NOMBATTV :  12.0
FIRMWARE : 5.4.D USB FW: c1
APCMODEL : Back-UPS 350
END APC  : Wed Feb 11 11:13:36 EST 2004

There may be more; there may be less. It will depend on your UPS. Again, you must have NETSERVER and NISPORT defined in your apcupsd.conf file in order for this test to succeed. Check this first if there's a problem.

If you see something resembling:

attach_shmarea: shared memory version mismatch (or UPS not yet ready to report)

or if all the status values come back zero, give apcupsd another minute to initiate communication with the UPS, then try running the apcaccess command again.

[edit] Testing APCUPSD – Communications Test

If everything's gone smoothly, we now need to ascertain whether the UPS and apcupsd are communicating properly. Do a running tail of the apcupsd events file:

# tail -f /var/log/apcupsd.events

Now disconnect the USB cable from the UPS or from your machine. You should see the following appear in the apcupsd.events file:

Wed Feb 11 11:15:59 EST 2004  Communications with UPS lost.
Wed Feb 11 11:16:07 EST 2004  Slave connection failed Connection refused! Down slave 0

Again, ignore the messages about the slave.

ectospasm notes that it may take some time for this message to appear. Remember, patience is a virtue.

Reconnect the USB cable. You should see:

Wed Feb 11 11:16:20 EST 2004  Communications with UPS restored.
Wed Feb 11 11:16:37 EST 2004  Slave connection failed Connection refused! Down slave 0

All set? Cancel the tail and move to the next test.

If you don't see these messages, you need to correct the problem before proceeding. Did you emerge hotplug? Kernel compiled correctly?

[edit] Testing APCUPSD – Simulated Power Fail Test

First we'll need to reconfigure a few things to make sure apcupsd doesn't actually shutdown our system. Somewhat counterintuitive, I know, but we're still testing the installation. Do the following:

# cp /etc/apcupsd/apccontrol /etc/apcupsd/apccontrol.save
# cp /etc/apcupsd/safe.apccontrol /etc/apcupsd/apccontrol

This substitutes the “safe” version of apccontrol for our operational version.

We're about to pull the plug. Do I need to tell you to make sure your system is properly backed up? Do another running tail of the apcupsd events file:

# tail -f /var/log/apcupsd.events

...and disconnect your UPS from its outlet. You should see something like the following appear in your apcupsd.events file:

Wed Feb 11 11:19:52 EST 2004  Power failure.
Wed Feb 11 11:19:58 EST 2004  Running on UPS batteries.

Give this whole process about fifteen seconds for the messages to appear; after the second message, reconnect the power. You should see:

Wed Feb 11 11:20:06 EST 2004  Power is back. UPS running on mains.
Wed Feb 11 11:20:08 EST 2004  Slave connection failed Connection refused! Down slave 0

If all's well here, cancel the tail and we'll do a simulated power down of the system. Keep the “safe” version of apccontrol where it is, and backup your apcupsd.conf file:

# cp /etc/apcupsd/apcupsd.conf /etc/apcupsd/apcupsd.save

Now edit your apcupsd.conf file's TIMEOUT value to read 30 instead of zero. This will cause apcupsd to attempt a shutdown of the system thirty seconds after it detects a power failure. Save your new configuration file. You'll need to restart apcupsd for the changes to take effect:

# /etc/init.d/apcupsd restart

Start another running tail of /var/log/apcupsd.events, and pull the plug. Your output should resemble the following:

Wed Feb 11 11:35:27 EST 2004  Power failure.
Wed Feb 11 11:35:33 EST 2004  Running on UPS batteries.

If you've done everything right, the following will appear after roughly thirty seconds:

Wed Feb 11 11:36:04 EST 2004  Reached run time limit on batteries.
Wed Feb 11 11:36:04 EST 2004  Initiating system shutdown!
Wed Feb 11 11:36:04 EST 2004  User logins prohibited

When you see this message, reconnect the power. The following should appear:

Wed Feb 11 11:36:07 EST 2004  Cancelling shutdown
Wed Feb 11 11:36:07 EST 2004  Power is back. UPS running on mains.
Wed Feb 11 11:36:07 EST 2004  Allowing logins

apcupsd should acknowledge that power has been restored and cancel the shutdown.

Replace your apccontrol and apcupsd.conf files, restart apcupsd and we'll move on to the final test...

# cp /etc/apcupsd/apccontrol.save /etc/apcupsd/apccontrol
# cp /etc/apcupsd/apcupsd.save /etc/apcupsd/apcupsd.conf
# /etc/init.d/apcupsd restart

[edit] Testing APCUPSD – Full Power Down Test

System still properly prepared for catastrophic failure? Then let's do it for real.

You have two options here: simulate a complete loss of power by yanking the plug and waiting for the batteries to exhaust themselves, or set a low TIMEOUT value (e.g. 60) in apcupsd.conf. Remember to restart apcupsd if you choose the latter option. Either way, your system should power itself off once it has reached the appropriate parameter: roughly sixty seconds after unplugging if you chose to modify the TIMEOUT value as above, or when the battery reaches either 5% or has only three minutes of runtime remaining (whichever comes first, assuming you used the values from my sample apcupsd.conf files). These values are set (where else?) in your apcupsd.conf file, and can be modified to taste. You can run a tail of /var/log/apcupsd.events if you're into watching that sort of thing while your UPS bleats at you incessantly.

[edit] Testing APCUPSD – The Aftermath

If everything went flawlessly, congratulations. You now have a functional master (or standalone) installation of apcupsd. If you altered the TIMEOUT value in apcupsd.conf, remember to set it back to 0 and restart apcupsd before you continue.

If something didn't go as planned, double-check your configuration file; check that you restored the original version of apccontrol after the Simulated Power Fail Test; make sure your UPS is still communicating successfully with apcupsd, and so on.

Now that we've got that sorted, let's set up our slave. If you're running apcupsd in standalone mode, you can skip this section and move on to Obtaining UPS status via your browser. If you're not interested in that either, you're done. Smoke 'em if you got 'em.

[edit] Installing, Configuring and Starting the APCUPSD Slave:

Now it's time to get our slave up and running. This is much less involved as we're already familiar with the basic principles, right?

# emerge --sync; emerge apcupsd; rc-update add apcupsd default

Now edit your slave's apcupsd.conf file. Mine looks like this:

## apcupsd.conf v1.1 ##
#
#  for apcupsd release 3.10.9 (31 December 2003) – gentoo
#  “sample slave” configuration file
UPSCABLE                             ether
UPSTYPE                              smartups
LOCKFILE                             /var/lock
NOLOGON                              disable
NETSERVER                            on
NISPORT                              3551
EVENTSFILE                           /var/log/apcupsd.events
EVENTSFILEMAX                        10
UPSCLASS                             netslave
UPSMODE                              net
NETPORT                              6666
MASTER                               <your-master-machine’s-IP-address>
USERMAGIC                            <some-unique-string>

While I retain the original form and content of the apcupsd.conf file on my master installation (i.e. I just change values and comment lines in/out) my slave file literally looks like what you see above. Very simple, very easy; feel free to just copy it into your favorite text editor and change what you need.

A few (very important) notes on the above:

• UPSCABLE must be set to ether.
• UPSTYPE must be set to smartups. I'm not kidding. This was worth twenty-four hours of aggravation when I was attempting to set my first slave. I've read documentation suggesting that the master and slave must have the same UPSTYPE. I've read documentation stating that UPSTYPE must be set to net just like UPSMODE. Neither of these settings worked on my installation. Just take my word for it: set UPSTYPE to smartups and don't look back.
• Unless you want to be locked out of your slave machine the moment your UPS switches to battery, I'd set the NOLOGON value to disable.
• Neither EVENTSFILE nor EVENTSFILEMAX are necessary, but I like to see what my slave's been up to even though the master calls all the shots. It's your decision to include or omit this.
• Remember when I told you to make a note about your master installation's USERMAGIC setting? Enter the same thing here or you'll be sorry.

Save your file, and start apcupsd manually. You should get a clean start:

# /etc/init.d/apcupsd start
 * Starting APC UPS daemon...                                   [ ok ]

If you look in /var/log/apcupsd.events, you should see something like the following:

Wed Feb 11 15:39:08 EST 2004  apcupsd 3.10.9 (31 December 2003) gentoo startup succeeded
Wed Feb 11 15:39:38 EST 2004  Connect from master <your-master-machine’s-IP-address> succeeded

Likewise, you can run back to your master machine (it is still running apcupsd, right?) and check its apcupsd.events file for a similar message:

Wed Feb 11 15:39:38 EST 2004  Connect to slave <your-slave-machine’s-IP-address> succeeded

Note that it may take a minute or more for the master and slave to contact each other. Be patient. If errors occur, check your apcupsd.conf files. Also, check to make sure your master is listed in your /etc/hosts file; apcupsd will wait for networking before starting, but better safe than sorry. If everything is in order there, it's time to start troubleshooting your network connectivity. Good luck.

[edit] Testing the APCUPSD Slave

This goes just like it did for the master; just remember, your slave takes its orders from the master, so all file reconfiguration for testing should be done on the master, not on the slave. If you're lazy, overconfident, or just don't care by this point you can do what I did: once you've established the master and slave are communicating, pull the plug and see if the slave powers down with the master.

Remember to reset any configuration files to their operational states after testing and to restart apcupsd if you made any changes.

That's it. You now have a slave that will shutdown when its master tells it. Note that you can add BATTERYLEVEL, MINUTES, and TIMEOUT settings to the above slave configuration file to have the slave shutdown before the master, thereby conserving more battery for the master's use.

[edit] Obtaining UPS status via your browser

First, you'll need to edit the /etc/apcupsd/hosts.conf file on your master installation to tell apcupsd which machines to monitor. Mine looks like this:

MONITOR <your-master-machine’s-IP-address> “<your-master-machine’s-name>”
MONITOR <your-slave-machine’s-IP-address> “<your-slave-machine’s-name>”

When emerged, apcupsd automatically creates these files and directories in your /var/www directory (assuming a default Apache configuration and that you enabled the cgi flag and disabled the vhosts flag when compiling apcupsd).

Apache's configuration files are not touched when enabling apcupsd (at least not in my installation), so you will have to add some lines to httpd.conf.

  Alias /apcupsd/ "/var/www/apcupsd/"
  ...
  <Directory /var/www/apcupsd>
      Options ExecCGI
      SetHandler cgi-script
  </Directory>

This will make your main monitor accessible through http://<ServerName>/apcupsd/multimon.cgi

Of course, this is a sample/simple configuration. You can enclose the Alias directive in a virtual host, rename the alias to whatever you feel like, authenticate users so that only an admin can monitor the UPS, etc. After all, Open Source is all about creativity and some spare time :).

I'd restart apcupsd and Apache just to be safe. Or, better yet, reload Apache rather than restarting it, it's faster and safer.

You should see something like this. If you click on the name of the master or the slave in this display, you should see something like this.

Your stats may or may not be as extensive as those noted in the above links; it will depend on your UPS.

[edit] Finishing up

Did you replace all your test configuration files with the proper ones? Are all your TIMEOUT values set to 0? Did you plug the UPS back in?

Stellar. I'd reboot both machines for good measure; bring the master online first, then the slave. Make sure apcupsd starts automatically (and properly) on both machines, check your logs, and relax. You're now running your UPS in “smart” mode...

[edit] Calibration

Note that the following procedure could damage your battery. Lead-acid batteries do not like to be deep discharged. To do it for mere calibration might not be a very good idea. Caveat emptor.

Oh, and one last thing. This is as good a place as any to talk about calibration of the UPS unit. It has recently become apparent that some (if not all) of the UPS units need to be calibrated in order to achieve their proper runtime while operating under load during a power failure. This has been confirmed as a necessity for the Back-UPS RS 1500; it can't hurt to follow this procedure for other APC UPS units as well.

First, if you're reading this prior to purchasing or installing a new APC UPS, I strongly recommend following the manufacturer's advice on charging the battery for the first time. For those without their manuals handy, that's usually a minimum of eight hours without anything else being plugged into the unit.

Once your unit has been properly charged, place the unit under at least a 50% load (you can monitor this either with your browser or apcaccess). Now disable apcupsd and yank the plug, letting the battery run until it is completely dead.

Plug the UPS unit back into the wall and allow it to recharge completely. This should greatly improve the accuracy of the TIMELEFT estimate (and consequently, your actual runtime with apcupsd).

Thanks go to ectospasm for finding this issue and chasing it down, as well as Adam Kropelin for the providing the answer.

[edit] Notes on Miscellaneous Functionality

• Currently, apcupsd on USB UPS units does not send the UPS into “hibernation” when it powers down the system(s) it supports. This means that while apcupsd will monitor the status of the UPS and shutdown its supported system(s) as appropriate, it will not automatically bring the UPS and its supported systems(s) back online when power returns, as the UPS itself is never “shut down” (unless, of course, you’re without power long enough that the UPS actually exhausts itself). Please see this section of the Troubleshooting apcupsd with USB thread for more details, but this functionality should be enabled sometime in the near future. Once apcupsd includes this feature for USB UPS units, I’ll update this document with general guidelines regarding the procedure for making sure your system(s) come back to life automatically following a UPS-induced shutdown.

UPDATE: mark_lagace has developed a temporary workaround for this lack of functionality. Please see this section of this thread for his solution. If you're going to implement it, please read it carefully and take all the necessary precautions. Thanks, Mark!

UPDATE [bis]: `apccontrol killpower` is now called by the Gentoo halt script since early may 2005 (ref).

• As noted in the Obtaining UPS status via your browser section, the amount of information your UPS reports will vary depending on your model…for example, my Back-UPS RS 1000 reports line voltage, while my two Back-UPS XS 800’s do not. I may eventually include a separate section detailing the vagaries of the individual APC models, but for the time being this HOWTO will only encompass what I consider to be the primary functions of apcupsd, i.e. basic monitoring of the UPS unit itself and controlled shutdown of its supported system(s) according to user-defined parameters.

[edit] Resources

Text taken directly from HOWTO: apcupsd with USB (at Gentoo Forums) so that the HOWTO would be in Gentoo-wiki. -- Some updates done to reflect new operation on apcupsd within Gentoo. Mainly the current use of /var/log/apcupsd.events instead of /var/log/messages.

[edit] See Also

• Related Forum Article
• Apcupsd Website