apcupsd(8)

NAME
apcupsd - daemon for most APC's UPS for Linux

SYNOPSIS
/usr/local/sbin/apcupsd
/usr/local/etc/apcupsd/apccontrol
/usr/local/etc/apcupsd/apcupsd.conf
/usr/local/sbin/apcaccess
/usr/local/sbin/apcnetd

DESCRIPTION

This daemon can be used for controlling the APC SmartUPS. During a power failure, "apcupsd" will inform the users about the power failure and that a shutdown may occur. If power is not restored, a system shutdown will follow when the battery is exausted, a timeout (seconds) expires, or runtime expires based on internal APC calculations determined by power consumption rates. If the power is restored before one of the above shutdown conditions is met, "apcupsd" will inform users about this fact. The shutdown is made by script calls to "/usr/local/etc/apcupsd/apccontrol", which is called by "apcupsd". Consequently, no changes to /etc/inittab are necessary. There is no communication between "apcupsd" and init(1) process. Apcupsd modifies the halt script so that at the end of the shutdown process, apcupsd will be re-executed in order to power off the UPS.

The "apcupsd" daemon now supports two networking modes that function independently, but if desired at the same time. Most users will probably enable the first network mode, which permits apcupsd to serve status and event information to clients over the network. The second networking mode is for multiple networked machines that are powered by the same UPS. In this mode, one machine is configured as a master with the UPS attached to the serial port. The other machines (max. 20) powered by the same UPS are configured as slaves. The master has a network connection with the slaves and sends them information about the UPS status.

RedHat and S.u.S.E. versions of Linux have direct install support. All other flavors of Linux will need some fussing with to get the install correct.

OPTIONS

-c --configure
    Attempts to configure the UPS EPROM to the values specified in the configuration file "/usr/local/etc/apcupsd/apcupsd.conf".

-d --debug <level>
    Turns on debugging output for a NETSLAVE or a NETMASTER.

-f --config-file <file>
    Specifies the location of the configuration file. The default is: /usr/local/etc/apcupsd/apcupsd.conf

-k --killpower
    Attempt to turn the UPS off. This option is normally only used by the daemon itself to shut the UPS off after a system shutdown has completed.

-n --rename-ups
    Attempts to change the UPS name stored in the UPS EPROM to that specified in your "/usr/local/etc/apcupsd/apcupsd.conf" file.

-u --update-battery-date
    Attempts to update the battery date stored in the UPS EPROM. Normally done after a battery replacement.

-V --version
    Prints the apcupsd version number and the usage.

-? --help
    Prints a brief apcupsd help screen.

CONFIGURATION
It may be necessary to change the configuration information in the file "/usr/local/etc/apcupsd/apcupsd.conf" to meet your needs and to correspond to your configuration. This file is a plain ASCII file and you can use your favorite editor to change it.

Configuration commands in /usr/local/etc/apcupsd/apcupsd.conf are:

  GENERAL CONFIGURATION COMMANDS

UPSCABLE -- <type of cable you are using>
[ simple | 940-0020B | 940-0023A (broken) ]
[ smart | 940-0024B | 940-0024C ]
[ 940-0095A | 940-0095C ]
[ ether ]
[ usb ]

UPSTYPE -- <Type of APCC UPS you have>
[ dumb | apcsmart | net | usb | snmp | test ]

DEVICE -- <name of serial port>
Please specify which device is used for UPS communication. The default is /dev/ttyS[0|1|2|3]. If you have a USB UPS, it is /dev/usb/hid/hiddev[0-9]. On some Red Hat versions you may need to specify /dev/usb/hiddev[0-9]

LOCKFILE -- <path to lockfile>
By supplying this argument, "apcupsd" tries to create a lockfile for the serial or USB port in the specified directory.

  CONFIGURATION COMMANDS USED BY THE NETWORK INFORMATION SERVER

NETSTATUS [on | off]
This configuration command turns the network information server on or off. If it is on, apcupsd will spawn a child process that serves STATUS and EVENTS information over the network. This information is currently used by the Web based CGI programs. The default is on. In some cases, for added security, you may want to invoke a separate information server daemon from the inetd daemon. In this case, NETSTATUS should be off.

STATUSPORT <port>
This configuration command specifies the port to be used by the apcupsd server. The default is 7000. If you change this port, you must manually change the #define SERV_TCP_PORT in cgi/upsfetch.c and rebuild the CGI programs.

EVENTFILE <filename>
If you want the apcupsd network information server to provide the last 10 events via the network, you must specify a file where apcupsd will save these events. The default is: /var/log/apcupsd.events. Currently, apcupsd will save at most the last 50 events. When more than 50 events are recorded and a network request for the events arrives, the network server will truncate the file to the most recent 10 events. Consequently this file will not grow indefinitely as long as the events are checked from time to time.

  CONFIGURATION COMMANDS USED TO CONTROL SYSTEM LOGGING

STATTIME

STATFILE

DATATIME

FACILITY

CONFIGUATION COMMANDS USED DURING POWER FAILURES

ANNOY -- <time in seconds>
Please specify the time in seconds between messages requesting logged in users to get off the system. This timer starts only when the UPS is running on batteries. The default is 300 seconds (5 minutes).

ANNOYDELAY -- <time in seconds>
Please specify delay time in seconds before apcupsd begins requesting logged in users to get off the system. This timer starts only after the UPS is running on batteries. This timer is reset when the power returns. The default is 60 seconds. That is the first warning to log off the system occurs after 60 seconds on batteries.

NOLOGON -- <specifies when apcupsd should create the nologon file>
[ disable | timeout | percent | minutes | always ] are valid types. Based on Ten (10) percent of a setting. This allows one to define the point when the /etc/nologin file is added. This is important for allowing systems with BIG UPSes to run as normally until the system administrator determines the need for dumping users. The feature also allows the system administrator to hold the "ANNOY" factor until the /etc/nologin file is added. disable prevents apcupsd from creating the nologin file. timeout specifies a specific wait time before creating the nologin file. percent specifies the percent battery charge remaining before creating the nologin file. minutes specifies the battery runtime remaining before creating the nologin file. always causes the nologin file to be immediately created on a power failure.

BATTERYLEVEL -- <percent of battery>
If BATTERYLEVEL is specified, during a power failure, apcupsd will shutdown the system when the remaining battery charge falls below the specified percentage. The default is 5.

MINUTES -- <battery runtime in minutes>
If MINUTES is specified, during a power failure, apcupsd will shutdown the system when the remaining remaining runtime on batteries as internally calculated by the UPS falls below the time specified. The default is 3.

TIMEOUT -- <time in seconds>
After a power failure, the system will be shutdown after TIMEOUT seconds have expired. Normally for SMARTUPSes, this should be zero so that the shutdown time will be determined by the battery level or remaining runtime (see above). This command is useful for dumb UPSes that do not report battery level or the remaining runtime. It is also useful for testing apcupsd in that you can force a rapid shutdown by setting a small value (e.g. 60) and pulling the plug to the UPS. The timeout for the master is always 30 seconds longer than slaves. TIMEOUT, BATTERYLEVEL, and MINUTES can be set together without problems. The daemon will react to the first case or test that is valid. Normally SmartUPS users will set TIMEOUT to zero so that the system is shutdown depending on the percentage battery charge remaining (BATTERYLEVEL) or the remaining battery runtime (MINUTES).

  CONFIGURATION COMMANDS USED TO SET THE UPS EPROM
The values specified with the following commands are only used if the --configure option is specified on the apcupsd command line, and the UPS is capable of internal EPROM programming. In that case, apcupsd attempts to set the values into the UPSes EPROM. Under normal operations, the values for these parameters specified in the configuration file are not used. Instead, they are read from the UPS EPROM by apcupsd.

SENSITIVITY -- <sets sensitiviy level>
(H)igh, (M)edium, (L)ow
This value determine how sensitive the UPS is to the mains quality and voltage fluxuations. The more sensitive it is, the quicker the UPS will switch to battery power when the mains line quality is bad. Normally, this should be set to H, but if you find your UPS switching to batteries frequently, you might want to try a less sensitive setting, providing that your computer equipment tolerates the poor quality mains. This value is written to the UPS EPROM when the --configure option is specified. Under normal apcupsd operations (no --configure option), apcupsd will read the value store in the UPS and display it in the STATUS output.

WAKEUP -- <set wakeup delay>
The power restart delay value in [0,60,180,300] in seconds after the UPS shuts down during a power failure. This is to prevent the power from coming back on too quickly after a power down, and is important for those who have high RPM drives that need to spindown before powering them up again. Some older SCSI models are very sensitive to this problem. Default is zero. This value is written to the UPS EPROM when the --configure option is specified. Under normal apcupsd operations (no --configure option), apcupsd will read the value store in the UPS and display it in the STATUS output.

SLEEP -- <set sleep delay>
Delay in [20,180,300,600] seconds before the actual killpower event. The default is 20. This value is written to the UPS EPROM when the --configure option is specified. Under normal apcupsd operations (no --configure option), apcupsd will read the value store in the UPS and display it in the STATUS output.

LOTRANSFER -- <sets lower limit of ups batt. transfer>
This sets the low line voltage point to switch over to batteries. There are four values that can be selected, but they vary based on the UPS model, classification, and manufacture date. Thus a value ranging from 0-3 are assigned the learned and bubble sorted values. This value is written to the UPS EPROM when the --configure option is specified. Under normal apcupsd operations (no --configure option), apcupsd will read the value store in the UPS and display it in the STATUS output.

HITRANSFER -- <sets upper limit of ups batt. transfer>
This sets the high line voltage point to switch over to batteries.
There are four values that can be selected, but they vary based on the UPS model, classification, and manufacture date. Thus a value ranging from 0-3 are assigned the learned and bubble sorted values. This value is written to the UPS EPROM when the --configure option is specified. Under normal apcupsd operations (no --configure option), apcupsd will read the value store in the UPS and display it in the STATUS output.

RETURNCHARGE -- <sets min. batt. charge level>
This parameter specifies what battery percentage charge is necessary before the UPS will supply power to your equipment after a power down. There are four values that can be selected, but they vary based on the UPS model, classification, and manufacture date. Thus a value ranging from 0-3 are assigned the learned and bubble sorted values. This value is written to the UPS EPROM when the --configure option is specified. Under normal apcupsd operations (no --configure option), apcupsd will read the value store in the UPS and display it in the STATUS output.

BEEPSTATE -- <sets alarm beep state>
This parameter tells the UPS when it can sound its audio alarm. These settings are based on discrete events related to the remaining capacity of the UPS. 0 immediately upon power failure T power failure + 30 seconds L low battery power N never

UPSNAME -- <string>
This is normally an eight character string, but it currently only handles seven. This is the UPS name that will be stored in the UPS EPROM. This value is written to the UPS EPROM when the --configure option is specified. Under normal apcupsd operations (no --configure option), apcupsd will read the value store in the UPS and display it in the STATUS output.

  CONFIGURATION COMMANDS FOR SHARING A UPS

UPSCLASS -- <class of operation>
[ standalone | shareslave | sharemaster ] and
[ netslave | netmaster ] are valid types.
[ standalone | netslave | netmaster ] are tested classes.
[ shareslave | sharemaster ] classes are being tested.

The default is "standalone" and should be used for all machines powered by the UPS and having a serial port connection to the UPS, but where there are no other computers dependent power from the same UPS. This is the "normal" case. Use "netmaster", if and only if you have a serial port connection to the UPS and there are other machines deriving power from the same UPS. Use "netslave" if and only if you have no serial port connection to the UPS, but you derive power from it. Use "shareslave" if and only if you are using a ShareUPS and connected to a BASIC Port with Simple Signal. Use "sharemaster", if and only if you are using a ShareUPS and connected to the ADVANCED Port Smart Signal control.

UPSMODE -- [ disable | share | net | sharenet ] are valid types.

[ disable | net ] are the only known and tested classes.
[ share | sharenet ] classes are being tested.

BETA [ share ] For two or seven (2/7) additional simple signal ports on a SmartAccessories(tm) (internal/external box) for SmartUPSes.

NETTIME -- <time in seconds>
The rate in seconds that broadcasts information to Slave machines. This rate is reset if there is a power state change. This value is now passed to the slaves to sync. the openning of a socket by the slave for the master.

NETPORT -- <TCP|UDP port number>
This unix service port number must be set in the /etc/services file as follows:
        tab tab(spacejunk) tab tab
name (stuff)/xxp #
apcupsd NETPORT/tcp #
apcupsd NETPORT/udp #

MASTER -- <name of master> for Slave machine.
The name of the master which is authorized to send commands to this slave.

SLAVE -- <name of slave(s)> for Master machine.
The name of the slave machine attached to the master. There can be max. 20 slaves attached to one master.

USERMAGIC -- < user defined magic> for Slave machine.
The second level of magic security. It must be (17) characters long without spaces. This is passed to the master machine during initialization of sockets. This string should be different for each and every slave on the network.

SMARTUPS
If you start getting the follow message:

Emergency -- Batteries Have Failed!
Change Them NOW! Act upon it quickly. It means what it says. Also, not all "SmartUPS" models are eqaully smart. A non-NET or old class of "SmartUPS" has a subset of the full UPSlink(TM) language, and can not be polled for its control codes.

SHAREUPS
Special note for ShareUPS users, TIMEOUT, BATTERYLEVEL, and MINUTES are disabled or set to default values. Currently, there is not a known way for early signals to be sent to BASIC Ports. MINUTES are set to 0.

FILES
/usr/local/etc/apcupsd/apcupsd.conf - configuration file.
/var/log/apcupsd.status - STATUS file
/var/log/apcupsd.events - where up to the last 50 events are stored for the network information server.

EVENTS
apcupsd generates events when certain conditions occur such as a power failure, batteries exhausted, power return, These events are sent to the system log, optionally sent to the temporary events file (/var/log/apcupsd.events), and they also generate a call to /usr/local/etc/apcupsd/apccontrol which in turn will call any scripts you have placed in the /usr/local/etc/apcupsd directory.

DATA format
If the DATATIME configuration command is set nonzero, apcupsd will log a data record at the interval defined on the DATATIME command. This data record is in a format similar to the PowerChute data file format.

STATUS format
The STATUS output is in ASCII format and generally there is a single piece of information on each line output. The format varies based on the type of UPS that you are using.

DATE : time and date of last update
CABLE : cable type used
UPSMODEL : ups type or signal method
UPSMODE : tells apcupsd what to check
SHARE : if ShareUPS is used, this determines what

SmartUPS and MatrixUPS Smart Signals
ULINE : Current (observed) Input Line Voltage
MLINE : Max (observed) Input Line Voltage
NLINE : Min (observed) Input Line Voltage
FLINE : Line Freq (cycles)
VOUTP : UPS Output Voltage
LOUTP : Percent Load of UPS Capacity
BOUTP : Current Charge Voltage of Batteries
BCHAR : Batteries Current Charge Percent of Capacity
BFAIL : UNSIGNED INT CODE (ups state)
UTEMP : Current UPS Temp. in Degrees Cel.
DIPSW : Current DIP switch settings for UPS.

Newer BackUPS Pro Smart Signals
ULINE : Current (observed) Input Line Voltage
MLINE : Max (observed) Input Line Voltage
NLINE : Min (observed) Input Line Voltage
FLINE : Line Freq (cycles)
VOUTP : UPS Output Voltage
LOUTP : Percent Load of UPS Capacity
BOUTP : Current Charge Voltage of Batteries
BCHAR : Batteries Current Charge Percent of Capacity
BFAIL : UNSIGNED INT CODE (ups state)

BackUPS Pro and SmartUPS v/s Smart Signals
LINEFAIL : OnlineStatus
BATTSTAT : BatteryStatus
MAINS : LineVoltageState
LASTEVNT : LastEventObserved

BackUPS and NetUPS Simple Signals
LINEFAIL : OnlineStatus
BATTSTAT : BatteryStatus

BackUPS Pro and SmartUPS v/s Smart Signals
OnlineStatus BatteryStatus LineVoltageState LastEventObserved

BackUPS and NetUPS Simple Signals
OnlineStatus BatteryStatus

SEE ALSO
apcstatus (8) apcevents (8) apcnetd (8)

AUTHOR
Andre M. Hedrick <hedrick@astro.dyer.vanderbilt.edu>

  Retired Co-AUTHOR
Christopher J. Reimer <reimer@doe.carleton.ca>

  The Brave Unnamed PATCH-WORKS and TESTERS
"Daniel Quinlan" <quinlan@pathname.com>
"Tom Kunicki" <kunicki@surgery.wisc.edu>
"Karsten Wiborg" <4wiborg@informatik.uni-hamburg.de>
"Jean-Michel Rouet" <JM.ROUET@maisel-gw.enst-bretagne.fr>
"Chris Adams" <cadams@ro.com>
"Jason Orendorf" <orendorf@sprintmail.com>
"Neil McAllister" <pcm2@sentient.com>
"Werner Panocha" <WPanocha@t-online.de>
"Lee Maisel" <martian@rt66.com>
"Brian Schau" <bsc@fleggaard.dk>
"Riccardo Facchetti" <riccardo@master.oasi.gpa.it>

  The Information HELPERS and TESTERS.
"Eric S. Raymond" <esr@snark.thyrsus.com>
"Chris Hanson" <cph@martigny.ai.mit.edu>
"Pavel Alex" <pavel@petrolbank.mldnet.com>
"Theo Van Dinter" <felicity@kluge.net>
"Thomas Porter" <txporter@mindspring.com>
"Alan Davis" <davis@ele.uri.edu>
"Oliver Hvrmann" <ollo@compuserve.com>
"Scott Horton" <Scott.Horton1@bridge.bellsouth.com>
"Matt Hyne" <mhyne@tip.CSIRO.AU>
"Chen Shiyuan" <csy@hjc.edu.sg>

  OTHER CREDITS
"Miquel van Smoorenburg" <miquels@drinkel.cistron.nl>
"The Doctor What" <docwhat@itek.net>
"Pavel Korensky" <pavelk@dator3.anet.cz>

BUGS AND LIMITATIONS

Not all network modes are supported as yet. There are no known bugs in the standard stuff. There are possible bugs in all ShareUPS mode types. If anyone has had success at all with any ShareUPS models, please report.

EtherUPS/NetUPS
This is fully functional as of version 3.4.0.