Apcupsd is a UPS control system that permits
orderly shutdown of your
computer in the event of a power failure.
Kern Sibbald
May 25, 2008
This manual documents apcupsd version 3.14.x
Copyright (C) 1999-2005 Kern Sibbald
Copying and distribution of this file, with or without modification, are permitted in any medium without royalty provided the name Apcupsd, the copyright notice, and this notice are preserved.
Apcupsd source code is released under the GNU General Public License version 2. Please see the file COPYING in the main source directory.
For more information on the project, please visit the main web site at http://www.apcupsd.com
This is the manual for apcupsd, a daemon for communicating with UPSes (Uninterruptible Power Supplies) made by American Power Corporation (APC). If you have an APC-made UPS, whether sold under the APC nameplate or OEMed (The HP PowerTrust 2997A UPS has been tested as a ``smartups'' with cable Hewlett Packard part number 5061-2575 equivalent to a custom-smart cable), and you want you get it working with a computer running Linux, Unix, or Windows NT, you are reading the right document.
This manual is divided into parts which increase in technical depth as they go. If you have just bought a state-of-the-art smart UPS with a USB or Ethernet interface, and you are running a current version of Red Hat or SUSE Linux (8.0 or later), then apcupsd is very nearly plug-and-play and you will have to read only the Basic User's Guide (see Basic User's Guide).
If your operating system is older, or if you have an old-fashioned serial-line UPS, you'll have to read about serial installation (see Installation on Serial-Line UPSes). If you need more details about administration for unusual situations (such as a master/slave or multi-UPS setup) you'll need to read the section on advanced topics (see Advanced topics). Finally, there is a Technical Reference (see Technical Reference) section which gives full details on things like configuration file directives and event-logging formats.
You should begin by reading the Quick Start (see Quick Start for Beginners) instructions.
apcupsd is a complex piece of software, but most of its complexities are meant for dealing with older hardware and operating systems. On current hardware and software getting it running should not be very complicated.
The following is a help guide to the steps needed to get apcupsd set up and running as painlessly as possible.
Please note that due to the lack of Unix USB API standards, the USB code in apcupsd works only on Linux and *BSD systems. In addition, at the current release (3.10.17) the USB support for *BSD systems can at best be considered BETA due to fragile kernel drivers. Drivers for other OSes can be written, but it requires someone with a knowledge of the OS and the USB to do so. (This lack of a Unix USB API interface is one of the big failings of Unix. It occurs in other areas such as the GUI. Many people tout the diversity as an advantage, but it is in fact a weakness.)
The apcupsd maintainers develop it under Fedora (Red Hat); that port is, accordingly, the most up to date and best tested. There are enough Debian Linux users that that port is also generally pretty fresh. Slackware Linux is also fully supported.
apcupsd has also been ported to FreeBSD, NetBSD, OpenBSD, HP/UX, Solaris, Alpha Unix and the Cygwin Unix emulation under Windows. It is quite likely to work on those systems, though the port may occasionally get stale and require minor tweaking. apcupsd can also work on Unix-like systems, but without USB mode. apcupsd has been ported to OS X/darwin with this limitation.
In Operating System Specifics you'll find operating-system-specific tips for building and configuring apcupsd.
You can generally count on your UPS being supported if it has either an Ethernet-connected SNMP interface or a USB interface with an APC-supplied cable.
The ``UPSTYPE Keyword'' field is the value you will put in your /etc/apcupsd/apcupd.conf file to tell apcupsd what type of UPS you have. We'll describe the possible values here, because they're a good way to explain your UPS's single most important interface property - the kind of protocol it uses to talk with its computer.
The table shown below lists the APC model supported, and the possible kewords that you would use in the configuration with the listed cables. See below for more details on the keywords. Some of the models, particularly USB enabled models, can be run in multiple modes, so they may appear more than once in the table. APC is putting out new models at a furious rate, and so it is very likely that your model is not listed in the table. If it is USB enabled, it will probably work in USB mode. Please note that some of these new models are extremely inexpensive, so they are stripped down versions of more expensive units, and as such they do not offer as many features, so some of the example output you see elsewhere in this manual may not be available with your unit.
| APC Model | UPSTYPE Keyword | UPSCABLE keywords for Cables Supported | Status |
| BackUPS CS/ES (serial mode) | apcsmart | smart (note: using Smart Custom RJ45) the new Back-UPS RS 500 models are reported NOT to work with this cable. | Supported |
| BackUPS Pro, Smarter BackUPS Pro | apcsmart | 940-0095A | Supported |
| SmartUPS, SmartUPS VS (It has not been confirmed that the cable shipped with the VS is a 940-0095.), PowerStack 450, Matrix UPS, ShareUPS Advanced Port | apcsmart | smart (note: using Smart-Custom), 940-0024C | Supported |
| BackUPS CS USB, Pro USB, ES USB, RS/XS 1000, RS/XS 1500, and probably other USB models | usb | usb (note: using APC cables 940-0127A/B/C) | Supported in version >=3.9.8 |
| SmartUPS USB, BackUPS Office USB, and any other USB UPS | usb | usb (note: using APC cable, no number) | Supported, version >=3.9.8 |
| All SNMP-capable models | snmp | ether | Supported |
| BackUPS | dumb | simple (note: using Simple-Custom (This cable is not an APC product. You have to build it yourself using the instructions in Cables.), 940-0020B, 940-0020C, 940-0119A, 940-0023A | Supported |
| BackUPS Office, BackUPS ES | dumb | 940-0119A | Supported |
| BackUPS CS and possibly ES models (serial mode) | dumb | 940-0128A | Supported |
| ShareUPS Basic Port | dumb | 940-0020B, 940-0020C, 940-0023A | Supported |
Your choices become more interesting if you are running a small cluster or a big server farm. Under those circumstances, it may not be possible or even desirable to pair a UPS with every single machine. apcupsd supports some alternate arrangements.
The second type of configuration is the NIS (Network Information Server) server and client. In this configuration, where one UPS powers several computers, a copy of apcupsd running one one computer will act as a server while the other(s) will act as network clients which poll the server for information about the UPS. Note that ``NIS" is not related to Sun's directory service also called ``NIS" or ``Yellow Pages''.
The third configuration (new with version 3.8.3), is where a single computer controls multiple UPSes. In this case, there are several copies of apcupsd on the same computer, each controlling a different UPS. One copy of apcupsd will run in standalone mode, and the other copy or copies will normally run in master/slave mode. This type of configuration may be appropriate for large server farms that use one dedicated machine for monitoring and diagnostics
Here is a diagram that summarizes the possibilities:
Configuration types.
If you decide to set up one of these more complex configurations, see the Advanced Topics (see Advanced topics) section for details.
Apcupsd supports USB connections on all major operating systems: Linux, FreeBSD, OpenBSD, NetBSD, Windows, Solaris, and Mac OS X Darwin. If you plan to use a USB conenction, please read the appropriate subsection in its entirety. You can skip this section if your UPS has a serial (RS232-C) or Ethernet interface or if you are not running one of the platforms listed above.
mount -t usbdevfs none /proc/bus/usb
KERNEL="hiddev*", NAME="usb/hiddev%n"
More details are provided in the following section ...
You need to check three things:
To make sure that your USB subsystem can see the UPS, just do this from a shell prompt:
cat /proc/bus/usb/devices
This information is updated by the kernel whenever a device is plugged in or unplugged, irrespective of whether apcupsd is running or not. It contains details on all the USB devices in your system including hubs (internal and external), input devices, and UPSes.
You should get some output back that includes something like this, featuring a BackUPS RS 1000:
T: Bus=02 Lev=01 Prnt=01 Port=00 Cnt=01 Dev#= 3 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.06
S: Manufacturer=American Power Conversion
S: Product=Back-UPS RS 1000 FW:7.g3 .D USB FW:g3
S: SerialNumber=JB0308036505
C:* #Ifs= 1 Cfg#= 1 Atr=a0 MxPwr= 24mA
I: If#= 0 Alt= 0 #EPs= 1 Cls=03(HID ) Sub=00 Prot=00 Driver=hid
The important things to check for are the S: lines describing your UPS and and the I: line showing what driver is handling it. If on the I: line, Driver is listed as Driver=none then you do not have the HID driver loaded or the driver did not attach to the UPS. One common cause is having a Linux kernel older than 2.4.22 (such as a stock RedHat 9 or RHEL 3 kernel). If this is the case for your system, please upgrade to at least kernel version 2.4.22 and try again. If you are already running a 2.4.22 or higher kernel, please read further for instructions for other possible courses of action.
For a detailed description of the contents of the /proc/bus/usb files, see Interpreting /proc/bus/usb (linux-2.4) or Interpreting /proc/bus/usb (linux-2.6) as appropriate for your kernel version.
Here is another example, this time featuring a Back-UPS 350:
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
In general, if you see your UPS model in the S: field, which means Manufacturer=, Product=, and SerialNumber=, and you see Driver=hid in the I: field, you know the UPS has been recognized and is bound to the correct driver.
If your UPS doesn't appear in the list at all, check the obvious things: The UPS must be powered on, and a cable must be properly seated in both the data port of the UPS and one of your machine's USB ports. Many UPSes have phone ports to provide surge protection for phones or modems - make sure you haven't plugged your USB cable into one of those rather than the data port (which will usually be near the top edge of the case.)
Also, ensure that the correct drivers are loaded. Under Linux-2.4.x, you can check this out easily by examining the /proc/bus/usb/drivers file. Here's how you can do that:
cat /proc/bus/usb/drivers
...and you should get:
usbdevfs
hub
96-111: hiddev
hid
On Linux-2.6.x, make sure the sysfs filesystem is mounted on /sys and do:
ls -l /sys/bus/usb/drivers/
...where you should get:
total 0
drwxr-xr-x 2 root root 0 May 1 18:55 hid
drwxr-xr-x 2 root root 0 May 1 18:55 hiddev
drwxr-xr-x 2 root root 0 May 1 18:55 hub
drwxr-xr-x 2 root root 0 May 1 18:55 usb
drwxr-xr-x 2 root root 0 May 1 18:55 usbfs
...or perhaps something like:
total 0
drwxr-xr-x 2 root root 0 Jan 6 15:27 hiddev
drwxr-xr-x 2 root root 0 Jan 6 15:28 hub
drwxr-xr-x 2 root root 0 Jan 6 15:28 usb
drwxr-xr-x 2 root root 0 Jan 6 15:27 usbfs
drwxr-xr-x 2 root root 0 Jan 6 15:28 usbhid
If your 2.6.x system does not have the /sys/bus/usb directory, either you do not have sysfs mounted on /sys or the USB module(s) have not been loaded. (Check /proc/mounts to make sure sysfs is mounted.)
A USB UPS needs all of these drivers - the USB device filesystem, the USB hub, the Human Interface Device subsystem driver, and the Human Interface Device driver. If you are compiling your own kernel, you want to enable
CONFIG_USB
CONFIG_USB_HID
CONFIG_USB_HIDDEV
CONFIG_USB_DEVICEFS
...as well as at least one USB Host Controller Driver...
CONFIG_USB_UHCI_HCD (linux-2.6.x)
CONFIG_USB_OHCI_HCD (linux-2.6.x)
CONFIG_USB_UHCI (linux-2.4.x)
CONFIG_USB_OHCI (linux-2.4.x)
For a typical USB section of a kernel .config file, please see Typical Linux Kernel Config
Apcupsd accesses USB UPSes via the hiddev device nodes. Typically these are located in /dev/hiddevN, /dev/usb/hiddevN or /dev/usb/hiddev/hiddevN (where N is a digit 0 thru 9). Some distributions (some Debian releases, possibly others) do not provides these device nodes for you, so you will have to make them yourself. Check /dev, /dev/usb, and /dev/usb/hiddev and if you cannot find the hiddevN nodes, run (as root) the examples/make-hiddev script from the apcupsd source distribution.
Modern Linux distributions using the 2.6 kernel create device nodes dynamically on the fly as they are needed. It is basically a hotplug system, giving a lot more power to the user to determine what happens when a device is probed or opened. It is also a lot more complicated.
Some early 2.6 distributions (Fedora Core 3, for one) do not include hiddev rules in their default udev rule set. The bottom line for apcupsd on such a system is that if the hiddevN is not created when you plug in your UPS, apcupsd will terminate with an error. The solution to the problem is to add a rule to the udev rules file. On Fedora FC3, this file is found in /etc/udev/rules.d/50-udev.rules. Start by adding the following line:
BUS="usb", SYSFS{idVendor}="051d", NAME="usb/hiddev%n"
(Note that this rule uses obsolete udev syntax and is specific to FC3 and other distributions of similar vintage.)
Then either reboot your system, or unplug and replug your UPS and then restart apcupsd. At that point a /dev/usb/hiddevN node should appear and apcupsd should work fine.
If you have several UPSes or you just want to give your UPS a fixed name, you can use rules like the following:
KERNEL=="hiddev*", SYSFS{serial}=="JB0319033692", SYMLINK="ups0"
KERNEL=="hiddev*", SYSFS{serial}=="JB0320004845", SYMLINK="ups1"
(Note that this rule uses modern udev syntax and is appropriate only for more recent distros such as RHEL4 and FC4.)
Replace the serial number in quotes with the one that corresponds to your UPS. Then whenever you plug in your UPS a symlink called ups0, ups1, etc. will be created pointing to the correct hiddev node. This technique is highly recommended if you have more than one UPS connected to the same server since rearranging your USB cables or even upgrading the kernel can affect the order in which devices are detected and thus change which hiddev node corresponds to which UPS. If you use the symlink-by-serial-number approach the link will always point to the correct device node.
You can use...
udevinfo -a -p /sys/class/usb/hiddev0/
...to get more information on the fields that can be matched besides serial number.
An additional device-node-related problem is the use of dynamic minors. Some distributions, such as Mandrake 10, ship with a kernel having CONFIG_USB_DYNAMIC_MINORS turned on. This is not ideal for running with apcupsd, and the easiest solution is to turn CONFIG_USB_DYNAMIC_MINORS off and rebuild your kernel, or find a pre-built kernel with it off. For a kernel with CONFIG_USB_DYNAMIC_MINORS turned on to work with apcupsd, you must enable devfs. The following will tell you if devfs is enabled:
$ ps ax | grep devs
...which should give something like the following:
533 ? S 0:00 devfsd /dev
What complicates the situation much more on Mandrake kernels is their security level since CONFIG_DYNAMIC_USB_MINORS is turned on, but on higher security levels devfs is turned off. The net result, is that in those situations hiddev is completely unusable so apcupsd will not work. So, in these cases, the choices are:
If all these things check out and you still can't see the UPS, something is more seriously wrong than this manual can cover - find expert help. If you are unable to list USB devices or drivers, you kernel may not be USB-capable and that needs to be fixed.
The BSD USB driver supports FreeBSD, OpenBSD and NetBSD. (Thanks go to the BSD developers who kept a nearly identical interface across all three platforms.)
Users of OpenBSD, NetBSD, and some versions of FreeBSD will need to rebuild the kernel in order to enable the ugen driver and disable the uhid driver. uhid is not sufficient for apcupsd at this time and we need to prevent it from grabbing the UPS device. You should make the following changes to your kernel config file:
This is the default configuration for a GENERIC kernel on many platforms so you most likely will not need to recompile.
First, decide which hub and port you wish to use. You can find out the hub and port numbers for any particular physical connector by plugging a USB device into it and looking at the messages printed by the kernel; you should messages something like this:
uxx0 at uhub0 port 1
uxx0: <some device name>
To use your APC UPS on this port, configure the kernel to prefer attachment of the ugen driver over other drivers on this hub and port only, by adding a line like this to your kernel config file:
ugen* at uhub0 port 1 flags 1
(The "flags 1" forces the ugen to attach instead of anything else detected there.)
Configure and build that kernel as per the references below, and your UPS will now attach as a ugen device when plugged into that port.
Don't forget to cd to /dev and "./MAKEDEV ugen1" (and 2 and so on) if you have more than one generic usb device on your system.
For detailed information on rebuilding your kernel, consult these references:
After building a properly configured kernel, reboot into that kernel and plug in your UPS USB cable. You should see a dmesg log message like the following:
ugen0: American Power Conversion Back-UPS RS 1500 FW:8.g6 .D USB FW:g6, rev 1.10/1.06, addr 2
Note that the ugen driver is called out. If you see uhid instead, it probably means you did not properly disable the uhid driver when you compiled your kernel or perhaps you're not running the new kernel.
You can also check with 'usbdevs -d' to get a list of USB devices recognized by the system as well as the drivers they are associated with. For example:
# usbdevs -d
addr 1: UHCI root hub, VIA
uhub0
addr 2: Back-UPS RS 1500 FW:8.g6 .D USB FW:g6, American Power Conversion
ugen0
Apcupsd communicates with the UPS through the USB generic device, ugen. You may or may not need to manually make ugen device nodes in /dev, depending on what OS you are using.
Apcupsd supports USB UPSes on Windows 98, Windows ME (untested, but expected to work), Windows NT 4.0, Windows 2000, Windows XP, and Windows Server 2003. Windows Vista is untested at this time. 64-bit platforms (x64) are also supported.
USB connected UPSes on Windows require a special driver. In most cases, this driver is automatically installed when you install Apcupsd. However, if you unchecked the "USB Driver" package during installation or if you're running Windows 98 or ME, you will need to install the driver manually.
For detailed instructions, please see the install.txt file located in
the driver
folder of your Apcupsd install.
After installing Apcupsd (and the Apcupsd USB driver, if necessary), plug in your UPS USB cable and open the Windows Device Manager. You should see a "LibUSB-Win32 Devices" section, under which is listed "American Power Conversion USB UPS (Apcupsd)". You should NOT see "HID UPS Battery" under the "Batteries" section.
If the "LibUSB-Win32 Devices" section does not appear, check that your UPS is powered on and that the USB cable is connected at both ends. Reinstall the driver as directed above if needed.
Apcupsd supports USB UPSes on Solaris 10 and higher. Both x86 and SPARC platforms are supported.
Some specific packages are necessary when building Apcupsd with USB support on Solaris. You must install the SUNWlibusb and SUNWlibusbugen packages BEFORE attempting to build Apcupsd. These packages can be found on the Solaris installation CDROMs and should be installed with the pkgadd utility.
You also should build using the gcc compiler and ccs make, not Sun's compiler. The appropriate make utility can be found in /usr/ccs/bin. gcc can be installed from packages included on the Solaris installation CDROMs.
Configure and build Apcupsd normally, as described in Building and Installing Apcupsd. Be sure to include the --enable-usb flag to configure.
After building, install Apcupsd as root using 'make install', then perform a reconfigure boot ('reboot -- -r'). During installation, Apcupsd will automatically configure your USB subsystem to attach APC USB devices to the ugen driver. This is a critical step and must be completed by a reconfigure boot. Note that the USB config changes will be reversed if you remove Apcupsd using 'make uninstall'.
After installing Apcupsd as described above and performing a reconfigure boot, plug in your UPS USB cable. You should see a series of dmesg log messages similar to the following:
Dec 5 17:50:50 sunblade usba: [ID 912658 kern.info] USB 1.10 device (usb51d,2) operating at low speed (USB 1.x) on USB 1.10 root hub: input@4, ugen0 at bus address 3 Dec 5 17:50:50 sunblade usba: [ID 349649 kern.info] American Power Conversion Smart-UPS 1000 FW:600.1.D USB FW:1.2 AS0127232356 Dec 5 17:50:50 sunblade genunix: [ID 936769 kern.info] ugen0 is /pci@1f,0/usb@c,3/input@4 Dec 5 17:50:50 sunblade genunix: [ID 408114 kern.info] /pci@1f,0/usb@c,3/input@4 (ugen0) online
Note that the ugen driver is called out. If you do not see any dmesg entries related to your UPS, ensure that it is turned on and that the USB cable is connected at both ends. Also verify that you installed Apcupsd as root using the 'make install' command and that you performed a reconfigure boot afterward.
Apcupsd communicates with the UPS through the USB generic device, ugen. The reconfigure boot performed after Apcupsd installation will ensure the correct device nodes are created. Once your UPS has been recognized in dmesg as shown above, you can check /dev/usb to see if the device nodes have appeared:
[user@sunblade /]$ ls /dev/usb/51d.2/* cntrl0 cntrl0stat devstat if0in1 if0in1stat
(51d.2 is the vendor/product id for APC UPSes.)
Apcupsd supports USB UPSes on Mac OS X (Darwin) 10.3.x and higher. Both Intel and PowerPC platforms are supported.
Some specific packages are necessary when building Apcupsd with USB support on Darwin. You must install libusb-0.1.12 or higher which can be obtained from MacPorts (formerly DarwinPorts) or Fink. Note that Apcupsd is sensitive to the install location of libusb, so beware if you change it from the default.
Apcupsd should be built using gcc, preferably from the XCode development tools. Currently the maintainer is using gcc-4.0.1 from XCode 2.4. Other version of gcc from other sources may also work.
Configure and build Apcupsd normally, as described in Building and Installing Apcupsd. Be sure to include the --enable-usb flag to configure.
After building, install Apcupsd as root using 'make install' and then reboot. During installation, Apcupsd will automatically install a simple dummy kext driver designed to prevent Apple's monitoring software from taking over the UPS. It is necessary to reboot in order to activate the kext. Note that this kext will be automatically removed if you uninstall Apcupsd using 'make uninstall', allowing Apple's monitoring tool to once again access the UPS.
After installing Apcupsd as described above and rebooting, plug in your UPS USB cable. You should notice that Darwin does NOT display the battery monitor tool in the menu bar. You can also check Apple Menu -> About This Mac -> More Info... -> USB to ensure that your UPS appears in the list of USB devices.
For Red Hat systems, apcupsd is available in binary RPM format. This is the simplest way to install. If you have no previous version of apcupsd on your machine and are creating a standalone configuration, simply install the RPM with a normal rpm -ihv command. You're done, and can now skip the rest of this chapter and go straight to tweaking your run-time configuration file. (see After Installation)
If you have a previous installation, you can upgrade with a normal rpm -Uhv, but this may not upgrade the halt script. It may be better to do the upgrade as a remove (rpm -e) foll;owed by a fresh install (rpm -ihv).
After installation of the binary RPM, please verify carefully that /etc/rc.d/init.d/halt was properly updated and contains new script lines flagged with ***APCUPSD***.
Since there is no standard location for cgi-bin, the rpm will place the binary CGI programs in the directory /etc/apcupsd/cgi. To actually use them, you must copy or move them to your actual cgi-bin directory, which on many systems is located in /home/httpd/cgi-bin.
If you have a binary release of the Win32 apcupsd, please see the section describing the Windows version of Apcupsd.
Installation from source might have to be be done different ways depending on what system you are running. The basic procedure involves getting a source distribution, running the configuration, rebuilding, and installing.
The basic installation from a tar source file is rather simple:
If all goes well, the ./configure will correctly determine which operating system you are running and configure the source code appropriately. configure currently recognizes the systems listed below in the Operating System Specifics section of this chapter and adapts the configuration appropriately. Check that the configuration report printed at the end of the configure process corresponds to your choice of directories, options, and that it has correctly detected your operating system. If not, redo the configure with the appropriate options until your configuration is correct.
Please note that a number of the configure options preset apcupsd.conf directive values in an attempt to automatically adapt apcupsd as best possible to your system. You can change the values in apcupsd.conf at a later time without redoing the configuration process by simply editing the apcupsd.conf file.
Other configuration options can be used to set up the installation of HTML documentation and optional modules, notably the CGI interface that enables the UPS state to be queried via the Web. You will find a complete reference later in this chapter.
In general, you will probably want to supply a more elaborate configure statement to ensure that the modules you want are built and that everything is placed into the correct directories.
On Red Hat, a fairly typical configuration command would look like the following:
CFLAGS="-g -O2" LDFLAGS="-g" ./configure \
--enable-usb \
--with-upstype=usb \
--with-upscable=usb \
--prefix=/usr \
--sbindir=/sbin \
--with-cgi-bin=/var/www/cgi-bin \
--enable-cgi \
--with-css-dir=/var/www/docs/css \
--with-log-dir=/etc/apcupsd
By default, make install will install the executable files in /sbin, the manuals in /usr/man, and the configuration and script files in /etc/apcupsd. In addition, if your system is recognized, certain files such as the startup script and the system halt script will be placed in appropriate system directories (usually subdirectories of /etc/rc.d).
On OS X (Darwin), apcupsd can be built with configure defaults. The USB driver can be enabled, as per the directions on Darwin USB Configuration. Apcupsd may be usable on OS X with a smart serial device, but certainly does work as a NIS client or using a USB interface.
The startup information will be installed in /Library/StartupItems/apcupsd which is part of darwin's SystemStartup.
There are a number of things that you can do to check if the installation (make install) went well. The fist is to check where the system has installed apcupsd using which and whereis. On my Red Hat system, you should get the following (lines preceded with a $ indicate what you type):
$ which apcupsd
/sbin/apcupsd
$ whereis apcupsd
apcupsd: /sbin/apcupsd /etc/apcupsd /etc/apcupsd.conf
/etc/apcupsd.status /usr/man/man8/apcupsd.8.gz
/usr/man/man8/apcupsd.8
If you find an apcupsd in /usr/sbin, /usr/local/sbin, /usr/lib, or another such directory, it is probably a piece of an old version of apcupsd that you can delete. If you are in doubt, delete it, then rerun the make install to ensure that you haven't deleted anything needed by the new apcupsd. Please note that the files specified above assume the default installation locations.
As a final check that the make install went well, you should check your halt script (in /etc/rc.d on SUSE systems, and in /etc/rc.d/init.d on Red Hat systems) to see that the appropriate lines have been inserted in the correct place. Modification of the halt script is important so that at the end of the shutdown procedure, apcupsd will be called again to command the UPS to turn off the power. This should only be done in a power failure situation as indicated by the presence of the /etc/powerfail file, and is necessary if you want your machine to automatically be restarted when the power returns. On a Red Hat system, the lines containing the # ***apcupsd*** should be inserted just before the final halt command:
# Remount read only anything that's left mounted.
#echo "Remounting remaining filesystems (if any) readonly"
mount | awk '/ext2/ { print $3 }' | while read line; do
mount -n -o ro,remount $line
done
# See if this is a powerfail situation. # ***apcupsd***
if [ -f /etc/apcupsd/powerfail ]; then # ***apcupsd***
echo # ***apcupsd***
echo "APCUPSD will now power off the UPS" # ***apcupsd***
echo # ***apcupsd***
/etc/apcupsd/apccontrol killpower # ***apcupsd***
echo # ***apcupsd***
echo "Please ensure that the UPS has powered off before rebooting" # ***apcupsd***
echo "Otherwise, the UPS may cut the power during the reboot!!!" # ***apcupsd***
echo # ***apcupsd***
fi # ***apcupsd***
# Now halt or reboot.
echo "$message"
if [ -f /fastboot ]; then
echo "On the next boot fsck will be skipped."
elif [ -f /forcefsck ]; then
echo "On the next boot fsck will be forced."
fi
The purpose of modifying the system halt files is so that apcupsd will be recalled after the system is in a stable state. At that point, apcupsd will instruct the UPS to shut off the power. This is necessary if you wish your system to automatically reboot when the mains power is restored. If you prefer to manually reboot your system, you can skip this final system dependent installation step by specifying the disable-install-distdir option on the ./configure command (see below for more details).
The above pertains to Red Hat systems only. There are significant differences in the procedures on each system, as well as the location of the halt script. Also, the information that is inserted in your halt script varies from system to system. Other systems such as Solaris require you the make the changes manually, which has the advantage that you won't have any unpleasant surprises in your halt script should things go wrong. Please consult the specific system dependent README files for more details.
Please note that if you install from RPMs for a slave machine, you will need to remove the changes that the RPM install script made (similar to what is noted above) to the halt script. This is because on a slave machine there is no connection to the UPS, so there is no need to attempt to power off the UPS. That will be done by the master.
All the available configure options can be printed by entering:
./configure --help
When specifying options for ./configure, if in doubt, don't put anything, since normally the configuration process will determine the proper settings for your system. The advantage of these options is that it permits you to customize your version of apcupsd. If you save the ./configure command that you use to create apcupsd, you can quickly reset the same customization in the next version of apcupsd by simply re-using the same ./configure command.
The following command line options are available for configure to customize your installation.
For most systems, we recommend the following options:
./configure --prefix=/usr --sbindir=/sbin --enable-usb
and you can optionally build and install the CGI programs as follows:
./configure --prefix=/usr --sbindir=/sbin --enable-usb \
--enable-cgi --with-cgi-bin=/home/httpd/cgi-bin
Some systems require unusual options for compilation or linking that the ./configure script does not know about. You can specify initial values for variables by setting them in the environment. Using a Bourne-compatible shell, you can do that on the command line like this:
CFLAGS="-O2 -Wall" LDFLAGS= ./configure
Or on systems that have the env program, you can do it like this:
env CPPFLAGS=-I/usr/local/include LDFLAGS=-s ./configure
Or for example on the Sun Solaris system, you can use:
setenv CFLAGS -O2
setenv LDFLAGS -O
./configure
You can get a listing of all available options by doing:
./configure --help
or simply see the previous section of this manual.
With the exception of Linux SUSE and Linux Red Hat systems used by the developers, we rely on users to help create installation scripts and instructions as well as to test that apcupsd runs correctly on their system. As you can imagine, most of these people are system administrators rather than developers so they are very busy and don't always have time to test the latest releases. With that in mind, we believe that you will find that a lot of very valuable work has been already done to make your installation much easier (and probably totally automatic).
Below, you will find a list of operating systems for which we have received installation files:
The Alpha V4.0 version of apcupsd builds without compiler errors with gcc version 2.95.2. It is unlikely that the native Alpha compiler will work because of varargs differences. Unless you are a system guru, we recommend that you connect your UPS to the second serial port /dev/tty01 to avoid conflicts with the console device.
DEVICE /dev/tty01
In addition, you should ensure serial port lock file in apcupsd.conf is defined as:
LOCKFILE /var/spool/locks
Unlike the Linux systems, the system halt routine is located in /sbin/rc0, so after the make install, please check that this file has been correctly updated.
The start/stop script can be found in:
/sbin/init.d/apcupsd
This port is complete and is operation by several users. Since Debian build and install procedures are somewhat particular, we have put the extra Debian information into the following two subdirectories: <src>/distributions/debian/examples/ and <src>/distributions/debian/packageinfo
You can also find the official Debian packages on the Debian site at:
This port is complete and is being used by several users.
On the FreeBSD OS, there is no known way for a user program to get control when all the disks are synced. This is needed for apcupsd to be able to issue the killpower command to the UPS so that the UPS shuts off the power. To accomplish the same thing on FreeBSD systems, make sure you have a SmartUPS and that your UPS shutdown grace period is set sufficiently long so that you system will power down (usually 2 minutes), the use the kill-on-powerfail option on the apcupsd command line.
We have no reports from testing this yet on version 3.8.4, but worked fine on 3.8.1
Submitted during development of 3.8.2, this should be a complete distribution.
Ensure that you read the distributions/openbsd/README file before running apcupsd. There are some critical differences in how the OpenBSD implementation operates when the UPS batteries are exhausted. Failure to take this into account may result in the system not being fully halted when power is lost.
Red Hat systems are fully supported, and by following the standard installation instructions given above, you should experience few or no problems.
Slackware systems are fully supported, and by following the standard installation instructions given above, you should experience few or no problems.
SUSE systems are fully supported, and by following the standard installation instructions given above, you should experience few or no problems.
Please read this before attempting to compile or install the beta software. It contains important information that will make your efforts easier.
If you find bugs, or run into problems that seem to be related to the version of Solaris that you run, please feel free to contact the maintainers by email, or through the development mailing list. We'll attempt to help with problems getting the beta running, although we can't promise a quick response.
As always, remember testing UPSes can be hazardous to you system, and, apcupsd may contain bugs that can damage your system and data files! You must accept all responsibility for running this software. An unexpected power-off of a running system can be a disaster. As always, make backups of any critical information before you install this software.
Remember, we told you. we'll listen sympathetically if you lose data, but there will be nothing we can do to help you.
Please read the general installation instructions given above before continuing on with these Solaris-specific instructions. Then come back and read this section before attempting to build the package.
For building the system, we suggest that you run the configure and make processes as your normal UNIX user ID. The make install must be run as root. But if your normal ID has an environment setup for using the C compiler, it's simpler to do that than to set up root to have the correct environment.
Normally, we support the GCC compiler, but we have also attempted to support the Solaris workshop compilers and EGCS compilers. Please be aware that if you do not use GCC, you may experience a few problems.
Whichever compiler you do have, please insure that you can execute the compiler from the command line before running configure. If you do not have an environment setup to run the compiler first, configure will fail.
Before running ./configure, please be sure that you do not have /usr/ucb on your path. This may cause the ./configure to choose the wrong shutdown program. If ./configure detects that /usr/usb is on your path, it will print a warning message. Please follow the advice to avoid shutdown problems.
Your normal UNIX user ID must own the source tree directories, and you must have the normal development tools in your path. This includes make, the compiler, the M4 preprocessor, the linker, and ar or ranlib. If the user you are logged in as can compile and link a C program from a source file, then you have all the required tools available.
You will want to install the executables in a directory that remains mounted during the shutdown. Solaris will unmount almost everything except the root directories. Since the ability to power the UPS off requires access to the executable programs, they need to be in a directory that will never be unmounted. And since they should also be in a directory that normal users cannot get into, /sbin is the default. However, please be aware that if you want to follow Sun's filesystem conventions you would use the following:
./configure \
--prefix=/opt/apcupsd \
--sbindir=/etc/opt/apcupsd/sbin \
--sysconfdir=/etc/opt/apcupsd \
--with-cgi-bin=/opt/apcupsd/cgi-bin
The way to setup the /sbin directory as the executables directory is to pass configure the sbindir=/sbin option. No other arguments should be required, and your setup and platform should be detected automatically by configure.
Once you have run configure, you will need to do a make. Once the make has completed with no errors, you must su to root to complete the install. After the su, you may not have a path to the make program anymore. In that case, you should do the make install step as:
/usr/ccs/bin/make install
Once the install completes, you must edit the /sbin/rc0 script as detailed below, then exit from the su'ed shell.
In order to support unattended operation and shutdown during a power failure, it's important that the UPS remove power after the shutdown completes. This allows the unattended UPS to reboot the system when power returns by re-powering the system. Of course, you need autoboot enabled for your system to do this, but all Solaris systems have this by default. If you have disabled this on your system, please re-enable it.
To get the UPS to remove power from the system at the correct time during shutdown, i.e., after the disks have done their final sync, we need to modify a system script. This script is /sbin/rc0.
We do not have access to every version of Solaris, but we believe this file will be almost identical on every version. Please let us know if this is not true.
At the very end of the /sbin/rc0 script, you should find lines just like the following:
# unmount file systems. /usr, /var and /var/adm are not unmounted by umountall
# because they are mounted by rcS (for single user mode) rather than
# mountall.
# If this is changed, mountall, umountall and rcS should also change.
/sbin/umountall
/sbin/umount /var/adm >/dev/null 2>\&1
/sbin/umount /var >/dev/null 2>\&1
/sbin/umount /usr >/dev/null 2>\&1
echo 'The system is down.'
We need to insert the following lines just before the last 'echo':
#see if this is a powerfail situation
if [ -f /etc/apcupsd/powerfail ]; then
echo
echo "APCUPSD will power off the UPS"
echo
/etc/apcupsd/apccontrol killpower
echo
echo "Please ensure that the UPS has powered off before rebooting"
echo "Otherwise, the UPS may cut the power during the reboot!!!"
echo
fi
We have included these lines in a file called rc0.solaris in the distributions/sun subdirectory of the source tree. You can cut and paste them into the /sbin/rc0 file at the correct place, or yank and put them using vi or any other editor. Note that you must be root to edit this file.
You must be absolutely sure you have them in the right place. If your /sbin/rc0 file does not look like the lines shown above, do not modify the file. Instead, email a copy of the file to the maintainers, and we will attempt to figure out what you should do. If you mess up this file, the system will not shut down cleanly, and you could lose data. Don't take the chance.
This feature has only been tested with APC SmartUPS models. If you do not have a SmartUPS, you will be one of the first testers to try this feature. Please send email to let us know if it works with your UPS model, what model you have, and if possible, the event logs located in /etc/apcupsd. We'd be very interested in your results, and would be glad to work with you to get this feature working correctly with all the APC models. A detailed description of the screen output during the shutdown would be very helpful if you see problems.
You will then need to make the normal changes to the /etc/apcupsd/apcupsd.conf file. This file contains the configuration settings for the package. It is important that you set the values to match your UPS model and cable type, and the serial port that you have attached the UPS to. People have used both /dev/ttya and /dev/ttyb with no problems. You should be sure that logins are disabled on the port you are going to use, otherwise you will not be able to communicate with the UPS. If you are not sure that logins are disabled for the port, run the 'admintool' program as root, and disable the port. The 'admintool' program is a GUI administration program, and required that you are running CDE, OpenWindows, or another XWindows program such as KDE.
Solaris probes the serial ports during boot, and during this process, it toggles some handshaking lines used by dumb UPSes. As a result, particularly for simple signalling ``dumb'' UPSes it seems to kick it into a mode that makes the UPS think it's either in a calibration run, or some self-test mode. Since at this point we are really not communicating with the UPS, it's pretty hard to tell what happened. But it's easy to prevent this, and you should. Disconnect the UPS, and boot the system. When you get to a login prompt, log in as root. Type the following command:
eeprom com1-noprobe=true
or
eeprom com2-noprobe=true
depending on which com port your UPS is attached to. Then sync and shutdown the system normally, reattach the UPS, and reboot. This should solve the problem. However, we have some reports that recent versions of Solaris (7 & 8) appear to have removed this eeprom option and there seems to be no way to suppress the serial port probing during boot.
At this point, you should have a complete installation. The daemon will load automatically at the next boot. Watch for any error messages during boot, and check the event logs in /etc/apcupsd. If everything looks OK, you can try testing the package by removing power from the UPS. NOTE! if you have a voltage-signalling UPS, please run the first power tests with your computer plugged into the wall rather than into the UPS. This is because dumb serial-port UPSes have a tendency to power off if your configuration or cable are not correct.
As a user, your input is very helpful in solving problems with the package, and providing suggestions and future directions for the development of the package. We are striving to provide a useful package that works across all platforms, and welcome your feedback.
Best regards, and thanks for your interest and help, The Apcupsd Development Team.
During the ./configure, if apcupsd does not find one of the systems for which it has specific installation programs, it will set the Operating System to unknown and will use the incomplete installation scripts that are in <src>/distributions/unknown/. You will be on your own, or you can ask the developers list (apcupsd-users at lists.sourceforge.net) for installation instructions. This directory also contains a hint file for Linux From Scratch, which could be helpful for other systems as well.
Once you have installed apcupsd, either from a binary package or by building from source, your next step should be to inspect your /etc/apcupsd/apcupsd.conf file to make sure it is valid.
You can read the complete reference on configuration directives (see Configuration Directive Reference), but if you are setting up a normal standalone configuration you should only need to check (and possibly fix) the first three items listed below.
Your UPSTYPE should be the UPS's protocol type: dumb, apcsmart, usb, net, snmp, or ether. Your UPSCABLE should be the type of cable you are using. You should have gotten both from the table of types (see type_table); usually they will both be the string ``usb''.
If you have a USB device, it is better not to specify a DEVICE directive by commenting it out. Apcupsd will automatically search for your device in the standard places. If you specify a DEVICE, it should be the name of the device (or device range) that apcupsd is to use to communicate with the UPS. If you're using a USB UPS under Linux, you may leave the device name field blank and apcupsd will search all the standard locations for the UPS. You may also explicitly specify the device location as either /dev/usb/hid/hiddev[0-15] (on non-Red-Hat systems) or /dev/usb/hiddev[0-15] (on Red Hat systems), but this is not recommended.
Note that you should enter ``/dev/usb/hiddev[0-15]'' literally as shown. The ``[0-15]'' expression tells apcupsd to search all hiddev devices until it finds a UPS. You can restrict the search to a subset of devices by using something like ``[0-4]'', but keep in mind this will limit apcupsd's ability to locate the UPS if the kernel relocates it to a different device node, which happens occasionally during short power failures. Again, it is highly recommended to leave the DEVICE directive blank and let apcupsd find your device automatically.
If the first time you execute apcupsd, you get a message to the effect that the Apcupsd USB driver is missing, it means that you most likely forgot to put --enable-usb on your ./configure command line. If you loaded apcupsd from an rpm file, you may have selected the wrong one -- please ensure that the word usb appears in the rpm package name.
The next chapter (see Configuration Examples) of this manual provides you with the essential characteristics of each main type of configuration file. After those elements are correct, apcupsd should run, and then it is only a matter of customization of your setup.
The final consideration for a automatic reboot after a full power down is to ensure that your computer will automatically reboot when the power is restored.
This is not the normal behavior of most computers as shipped from the factory. Normally after the power is cut and restored, you must explicitly press a button for the power to actually be turned on. You can test your computer by powering it down; shutting off the power (pull the plug); then plugging the cord back in. If your computer immediately starts up, good. There is nothing more to do.
If your computer does not start up, manually turn on the power (by pressing the power on button) and enter your computer's SETUP program (often by pressing DEL during the power up sequence; sometimes by pressing F10). You must then find and change the appropriate configuration parameter to permit instant power on.
Normally, this is located under the BOOT menu item, and will be called something such as Restore on AC/Power Loss or Full-On. The exact words will vary according to the ROM BIOS provider. Generally you will have three options: Last State, Power On, and Power Off. Although Last State should normally work, we recommend setting your computers to Power On. This means that whenever the power is applied they are on. The only way to shut them off is to pull the plug or to have a special program that powers them off (/sbin/poweroff on Linux systems).
If after making all the changes suggested above, you cannot get your computer to automatically reboot, you might examine your halt script (/etc/rc.d/init.d/halt in the case of Red Hat Linux) and see if the final line that performs the halt or reboot contains the -p option for powering down the computer. It should not with the logic used by apcupsd, but if it does, the -p option could cause your computer to power off while the UPS is still suppling power (i.e. before the UPS kills the power). Depending on the setting of your BIOS, it may prevent your computer from restarting when the power returns. As already mentioned, this should not apply, but in case of problems it is worth a try.
The simplest way to invoke apcupsd is from the command line by entering:
/sbin/apcupsd
To do so, you must be root. However, normally, you will want apcupsd started automatically when your system boots. On some systems with installation support (e.g. SUSE and Red Hat), the installation procedure will create a script file that you will be automatically invoked when your system reboots. On other systems, you will have to invoke apcupsd from your rc.local script.
On Red Hat systems, this script file that automatically invokes apcupsd on system start and stops is: /etc/rc.d/init.d/apcupsd
To start apcupsd manually (as you will probably do immediately following the installation), enter the following:
/etc/rc.d/init.d/apcupsd start
To understand how this file is automatically invoked at system startup and shutdown, see the man pages for chkconfig(8).
On SUSE systems, the script file that automatically invokes apcupsd on system start and stops is /etc/rc.d/apcupsd
To start apcupsd manually (as you will probably do immediately following the installation), enter the following:
/etc/rc.d/apcupsd start
Normally, when properly installed, apcupsd will be started and stopped automatically by your system. Unfortunately, the details are different for each system. Below, we give the commands for selected systems. Alternatively, there are simple stopapcupsd and startapcupsd scripts in the examples directory, or you can modify one of the scripts in the distributions directory to meet your needs.
To stop apcupsd you can do the following:
On Red Hat systems:
/etc/rc.d/init.d/apcupsd stop
On SUSE systems:
/etc/rc.d/apcupsd stop
Please see the Testing Apcupsd (see Testing Apcupsd) chapter for more details on insuring that apcupsd is running properly.
If you have a USB UPS, and you have apcupsd version 3.10.7 (3.10.17a for *BSD) or higher, the essential elements of your apcupsd.conf file should look like the following:
## apcupsd.conf v1.1 ##
UPSCABLE usb
UPSTYPE usb
DEVICE
LOCKFILE /var/lock
UPSCLASS standalone
UPSMODE disable
Notice that we have not specified a device. In doing so, apcupsd will try all the well known USB ports. We strongly recommend you use this (empty device address) form unless you have a good reason to do otherwise.
Please use the explicit specifications of a device only if you know exactly what you are doing. In general, it is much easier to let apcupsd find the device itself.
Please see USB Configuration for detailed help on setting up your system to work with a USB UPS.
If you have a Smart UPS using the cable supplied by APC, or you build a CUSTOM SMART cable outlined in the cables chapter, a very simple configuration file would look like the following:
## apcupsd.conf v1.1 ##
UPSCABLE smart
UPSTYPE smartups
DEVICE /dev/ttyS0
LOCKFILE /var/lock
UPSCLASS standalone
UPSMODE disable
Normally you would have many more configuration directives to completely customize your installation, but this example shows you the minimum required.
If you have a simple signaling or dumb UPS such as a BackUPS, you will need to know exactly what cable you have and specify it on the UPSCABLE directive. Please see the list of UPSes versus cables in the beginning of this document for more information. The cable number is normally stamped in the plastic at one end of the cable. If you specify the wrong cable, it is very likely that at the first power failure, your computer will be immediately shutdown. This is an unfortunate consequence of the dumb signaling mode. To avoid this, first replace /etc/apcupsd/apccontrol with safe.apccontrol found in the examples directory, then test until everything works correctly. Once you have the correct cable, be sure to remember to reinstall the correct apccontrol file and test that your computer is correctly shutdown during a power failure.
## apcupsd.conf v1.1 ##
UPSCABLE (number of cable you have)
UPSTYPE dumb
DEVICE /dev/ttyS0
LOCKFILE /var/lock
UPSCLASS standalone
UPSMODE disable
If your cable does not have low battery detection, as is the case with some older models, you will also need to define TIMEOUT nnn where you set nn to be the number of seconds on a power failure after which a shutdown is effected.
Normally you would have many more configuration directives to completely customize your installation, but this example shows you the minimum required.
NIS (Network Information Server) mode allows for communication between instances of apcupsd running on different hosts. Only one of those hosts, the server, needs to talk to the UPS directly. The others, clients, optain information about the state of the UPS by querying the server. NIS is not related to Sun's NIS/YP services.
NIS clients and servers require that apcupsd be compiled with the Net Driver --enable-net. This is typically enabled by default.
The NIS server is connected to the UPS and should be configured exactly as a standalone configuration, but with NETSERVER on. In all other respects, the server should be configured in standalone mode. You may also set the NIS server specific options NISIP to restict which IP address of the server which apcupsd listens on. The default, 0.0.0.0, means to list on all of the server host's IP addresses; NISPORT (default 3551) to set which TCP port the server listens on; and EVENTSFILE and EVENTSFILEMAX to provide information about the last few events to clients. You may also need to modify your firewall rules on the server's host to allow traffic to the NISPORT.
For the NIS client computer, you will have a configuration that looks something like what follows. What is important is that you get the information from an ether UPSCABLE with UPSTYPE set as net over the network and you must specify the address of a NIS server using DEVICE. The client apcupsd will then poll the NIS server specified in DEVICE every POLLTIME seconds (formerly NETTIME).
## apcupsd.conf v1.1 ##
UPSCABLE ether
UPSTYPE net
LOCKFILE /var/lock
DEVICE server-network-address:3551
UPSCLASS standalone
UPSMODE disable
POLLTIME 10
The DEVICE is set to server-address:port, where server-address is the fully qualified domain name or IP address of the apcupsd NIS server, and TCP port is the NISPORT that the server is listening on. The default is 3551, but older versions of apcupsd used port 7000.
If you set POLLTIME too large, your slave may not see the change in state of the NIS server before the server has shutdown. Normally, you have at least 30 seconds of grace time between the time the NIS server decides to shutdown and the time it no longer responds. Your slave must poll during this interval.
Any client run using the Net driver will shutdown when its own timers expire or when the NIS server shuts down, whichever occurs first. This means that if you want the slave to shutdown before the server, you need only set BATTERYLEVEL, MINUTES or TIMEOUT on the client for a faster shutdown than the values defined on the NIS server. This can often be useful if the slave is less important than the master and you wish to reduce battery power consumption so that the master can remain up longer during a power outage.
NIS clients work principally by reading the STATFLAG record that is sent by the NIS server (present in the output of apcaccess). The low 16 bits are the standard APC status flag, and the upper 16 bits represent the internal state of apcupsd, so the slave can see when the power fails and know when to shutdown.
It would be possible to have a client also work as a server, but that would increase the delay of information getting from the UPS to the secondary client.
The difference between the NIS mode and the removed master/slave mode is that the NIS server has no explicit knowledge of the slaves. The NIS server makes its information available via the net (NIS), and the NIS slaves read it. When the NIS server is going to shutdown, it makes the information available to any NIS slave that polls it, but the NIS server does not explicitly call each NIS slave as is the case in the Master/Slave networking described several sections above.
Think of the difference as push (Master/Slave) vs. pull (NIS-based). In the case of M/S, the master makes all the shutdown decisions and notifies the slaves when they are to shut down or when some other interesting event happens. The slaves just do whatever the master says, whenever the master says to. On the other hand, with the NIS-based network config you basically ``publish'' the UPS status from one server and then your clients view that status and make their own decisions.
As of 3.14, Apcupsd supports the PowerChute Network Shutdown protocol. This is an alternative to SNMP for use with APC's AP9617 family of network smartslot modules. Note that the older AP9606 modules do not support PCNET.
To enable PCNET support, configure with the --enable-pcnet flag. This is typically enabled by default.
The required apcupsd.conf settings are straightforward:
## apcupsd.conf v1.1 ##
UPSCABLE ether
UPSTYPE pcnet
LOCKFILE /var/lock
DEVICE ipaddr:user:passphrase
UPSCLASS standalone
UPSMODE disable
The DEVICE setting specifies the IP address of the UPS as well as the username and authentication passphrase to use. Note that the username and passphrase are not the Web/SNMP login credentials. They are separate settings. The default username on a new card is "admin" and the default passphrase is "admin user phrase". To change the passphrase, log in to the Web UI and go to the UPS tab, then to PowerChute -> Configuration. (This assumes firmware v3.3.1. Other versions may place the setting elsewhere.)
Note that you may leave DEVICE blank and Apcupsd will accept information from any PCNET UPS on the network, however it will be very insecure since an attacker could easily send packets crafted to cause your server to shut down. Using the ipaddr, user, and passphrase will prevent this behavior.
You may need to take steps to ensure networking stays active during your OS's shutdown sequence in order for the PCNET driver to power off the UPS (the so-called "killpower" operation). On a Linux distro, you can use commands such as...
chkconfig --level 0 network on chkconfig --level 0 iptables on
...to make sure networking stays up.
The following testing procedures apply for the most part to apcsmart UPSes, whether USB or serial. If you have a dumb voltage-signalling UPS, your testing procedures will be somewhat different, and you should see the section on Testing Serial UPSes (see Testing Serial-Line UPSes).
After you start apcupsd, execute the following command:
ps fax
or the equivalent for your system. You should see something similar to the following output.
632 ? S 0:00 /sbin/apcupsd -f /etc/apcupsd/apcupsd.conf
841 ? S 0:00 \_ /sbin/apcupsd -f /etc/apcupsd/apcupsd.conf
842 ? S 0:00 \_ /sbin/apcupsd -f /etc/apcupsd/apcupsd.conf
This indicates that apcupsd is up and running and has started the two standard threads in addition to the main thread.
If you see only one instance of apcupsd running, don't worry about it as this is normal on most non-Linux systems, and on Linux 2.6.x kernels.
If you do not find that apcupsd is in the above list, the most likely problem is a configuration file glitch. If no messages were printed, you should check your system log (normally /var/log/messages where you will find one or messages indicating the nature of the problem.
There are three threads in apcupsd that serve the following purposes:
Once you have established that the proper processes are running, do a tail of the system log file, normally /var/log/messages:
tail /var/log/messages
You should see output that looks similar to the following:
Dec 5 17:01:05 matou apcupsd[5917]: apcupsd 3.7.2
startup succeeded
And if you have configured the network information server, you should also see:
Dec 5 17:01:05 polymatou apcupsd[5975]: apcserver
startup succeeded
These messages should also appear in the temporary file (/etc/apcupsd/apcupsd.events) if you are using the default configuration file. If you have installed the RPM, they will probably be in /var/log/apcupsd.events.
This test consists of running apcaccess to see if apcupsd is properly updating its internal variables. Please note that you must enable the apcupsd Network Information Server in your configuration file for apcaccess to work. This is done by setting:
NETSERVER on
NISPORT 3551
in your apcupsd.conf file.
To run the apcaccess test, use the following command:
apcaccess status
Depending on the type of UPS you have, you will get slightly different output, but an example For a Smart-UPS is as follows:
APC : 001,048,1088
DATE : Fri Dec 03 16:49:24 EST 1999
HOSTNAME : daughter
RELEASE : 3.7.2
CABLE : APC Cable 940-0024C
MODEL : APC Smart-UPS 600
UPSMODE : Stand Alone
UPSNAME : SU600
LINEV : 122.1 Volts
MAXLINEV : 123.3 Volts
MINLINEV : 122.1 Volts
LINEFREQ : 60.0 Hz
OUTPUTV : 122.1 Volts
LOADPCT : 32.7 Percent Load Capacity
BATTV : 26.6 Volts
BCHARGE : 095.0 Percent
MBATTCHG : 15 Percent
TIMELEFT : 19.0 Minutes
MINTIMEL : 3 Minutes
SENSE : Medium
DWAKE : 000 Seconds
DSHUTD : 020 Seconds
LOTRANS : 106.0 Volts
HITRANS : 129.0 Volts
RETPCT : 010.0 Percent
STATFLAG : 0x08 Status Flag
STATUS : ONLINE
ITEMP : 34.6 C Internal
ALARMDEL : Low Battery
LASTXFER : Unacceptable Utility Voltage Change
SELFTEST : NO
STESTI : 336
DLOWBATT : 05 Minutes
DIPSW : 0x00 Dip Switch
REG1 : N/A
REG2 : N/A
REG3 : 0x00 Register 3
MANDATE : 03/30/95
SERIALNO : 13035861
BATTDATE : 05/05/98
NOMOUTV : 115.0
NOMBATTV : 24.0
HUMIDITY : N/A
AMBTEMP : N/A
EXTBATTS : N/A
BADBATTS : N/A
FIRMWARE : N/A
APCMODEL : 6TD
END APC : Fri Dec 03 16:49:25 EST 1999
For a simple signaling or dumb UPS such as BackUPS, your output will be very minimal as follows:
APC : 001,012,0319
DATE : Mon Feb 18 09:11:50 CST 2002
RELEASE : 3.8.5
UPSNAME : UPS_IDEN
CABLE : APC Cable 940-0128A
MODEL : BackUPS
UPSMODE : Stand Alone
STARTTIME: Mon Feb 18 09:11:45 CST 2002
LINEFAIL : OK
BATTSTAT : OK
STATFLAG : 0x008 Status Flag
END APC : Mon Feb 18 09:15:01 CST 2002
If you see the above output, it is a good sign that apcupsd is working. Assuming that the output looks reasonable, check the following variables:
A very disturbing tendance is for some of the newer (Mar 2004) RS and ES UPSes to have no Voltage information. This is annoying bug not serious. On the other hand, some of those UPSes now have no battery charge information (BCHARGE). If BCHARGE is zero in your listing and you are running a Smart or a USB UPS, then you will have to set the BATTERYLEVEL directive in your apcupsd.conf file to -1.
If you see a message to the effect of:
attach_shmarea: shared memory version mismatch (or UPS not yet ready to report)
or if all the displayed values are zero, you have not waited long enough. Wait a bit longer and then re-execute the apcaccess status command.
If you see a message to the effect of:
APCACCESS FATAL ERROR in apcaccess.c at lin