Search:  
Gentoo Wiki

Apcupsd


This article is part of the HOWTO series.
Installation Kernel & Hardware Networks Portage Software System X Server Gaming Non-x86 Emulators Misc


Please improve it in any way that you see fit, and remove this notice {{Cleanup}} from the article. For tips on cleaning and formatting see Cleanup process


Wikipedia has an article on:
Apcupsd

Contents

Objectives

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

Prerequisites

This HOWTO assumes the following:

-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..

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.

Known Working UPS

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

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.

Note: Power Management: Since this guide’s inception, I’ve received several reports indicating that neither APM nor ACPI is necessary for some systems to successfully perform an unassisted shutdown. If your system already handles its power management needs to your satisfaction, I’d advise not changing anything; if you run into problems you can always come back here and follow the steps below. If it isn’t broken…

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

Code: Configuration of the Kernel
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:

Linux Kernel Configuration: Power management using ACPI in 2.4
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:

Linux Kernel Configuration: Power management using ACPI in 2.6
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:

Linux Kernel Configuration: Power management using APM in 2.4
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:

Linux Kernel Configuration: Power management using APM in 2.6
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):

Linux Kernel Configuration: USB in 2.4
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:

Linux Kernel Configuration: USB in 2.6
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:

Linux Kernel Configuration: raw hiddev USB 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:

Code: Finding out what type of chipset you have
/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:

Code: Build 2.4 Kernel
# 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:

Code: Build 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

Code: Install Necessary Packages

# emerge --sync; emerge hotplug; rc-update add hotplug default ...and if you have a new version of hotplug it may need coldplug: # emerge coldplug; rc-update add coldplug default

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.

Checking your USB subsystem

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

Basically, you just run:

Code:
# cat /proc/bus/usb/devices

You should see something analogous to the following:

Code: Output of cat /proc/bus/usb/devices
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.

Code: Shut down
# 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.

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

Note: Version apcupsd-3.14.1 changed their configuration file so be careful !!
Code: Install APCUPSD
# emerge sync; emerge apcupsd; rc-update add apcupsd default

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


Code:
# 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.


File: /etc/apcupsd/apcupsd.conf
## 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
File: /etc/apcupsd/apcupsd.conf --version 3.14.1
##  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.


Version 3.1.9

Version >3.14.1

*UPCMODE disable until APC ShareUPS card is used.

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


File: /etc/apcupsd/apcupsd.conf
## 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
File: /etc/apcupsd/apcupsd.conf
## 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:

Version 3.1.9

Version 3.14.1


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

Starting APCUPSD

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

Code:
# /etc/init.d/apcupsd start

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

Code:
 * 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

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

to see what went wrong.

Note: I’ve experienced problems with the apcupsd process going undead on me when it gets a bad start; attempts to stop it, kill it, or restart it are futile. If you get a bad start, you’ll need to do:
# /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:

Code: Error message
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:

Code:
# /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.

Note: These tests are applicable for installations running apcupsd in both master and standalone modes. Standalone users should not see messages about apcupsd being unable to connect to its slave, but I doubt this will bother them much.

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:

File: /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:

File: /etc/apcupsd/apccontrol
#
# 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.

Testing APCUPSD

Testing APCUPSD – Process-Status Test

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

Code:
# ps fax

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

Code:
 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...

Testing APCUPSD – Logging Test

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

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

You should see something similar to the following:

File: /var/log/apcupsd.events
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).

Testing APCUPSD – apcaccess Test

Run the following:

Code:
# apcaccess status

Your output should resemble the following:

Code:
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:

File: /var/log/apcupsd.events
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.

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:

Code:
# 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:

File: /var/log/apcupsd.events
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:

File: /var/log/apcupsd.events
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?

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:

Code:
# 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:

Code:
# 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:

File: /var/log/apcupsd.events
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:

File: /var/log/apcupsd.events
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:

Code:
# 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:

Code:
# /etc/init.d/apcupsd restart

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

File: /var/log/apcupsd.events
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:

File: /var/log/apcupsd.events
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:

File: /var/log/apcupsd.events
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...

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

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.

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.

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?

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

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

File: /etc/apcupsd/apcupsd.conf
## 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:

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

Code:
# /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:

File: /var/log/apcupsd.events
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:

File: /var/log/apcupsd.events
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.

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.

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:

File: /etc/apcupsd/hosts.conf
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.

File: /etc/apache2/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.

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...

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.

Note: It probably goes without saying, but you may not want to use your expensive server or gaming rig to run the battery into the ground (especially since we're disabling apcupsd). I'd think about loading the UPS unit with another (less valuable) appliance and simply using your system to ascertain the actual load. I'm not going to make any recommendations about what to load the UPS with, but please, use common sense.

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.

Notes on Miscellaneous Functionality

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).

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.

See Also

Retrieved from "http://www.gentoo-wiki.info/Apcupsd"

Last modified: Fri, 03 Oct 2008 14:04:00 +0000 Hits: 29,433