apcupsd
APC UPS Daemon (powerful daemon for APC UPS'es)
Controls and monitors the status of an APC UPS under Linux. Allows your computer or server to run for a specified length of time on UPS power, and then executes a controlled shutdown in the case of an extended power failure. Find APC on the Internet at: http://www.apc.com APC also made their PowerChute plus available for download at: http://www.apc.com/tools/download/
USB Configuration
Checking Out Your Linux USB Subsystem
You need to check three things:
1. That your USB subsystem can see the UPS 2. That the kernel has bound the correct driver 3. That the correct device nodes are available in /dev
Verifying Device Detection and Driver
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.
Configuration Examples
A Simple USB Configuration
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.
A Simple Configuration for a SmartUPS
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.
A Simple Configuration for a Simple Signaling or Dumb
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 Server/Client Configuration Using the Net Driver
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 NETTIME seconds.
## apcupsd.conf v1.1 ## UPSCABLE ether UPSTYPE net LOCKFILE /var/lock DEVICE server-network-address:3551 UPSCLASS standalone UPSMODE disable NETTIME 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 NETTIME 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.
Differences between NIS Client/Server and the old (now removed) Master/Slave modes
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 “publishthe UPS status from one server and then your clients view that status and make their own decisions.
PowerChute Network Shutdown Driver (PCNET)
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.