next up previous contents index
Next: Controlling Multiple UPSes on Up: Apcupsd User's Guide Previous: Advanced topics   Contents   Index

Subsections


Customizing Event Handling

When apcupsd detects anomalies from your UPS device, it will make some decisions that usually result in one or more calls to the script located in /etc/apcupsd/apccontrol. The apccontrol file is a shell script that acts on the first argument that apcupsd passes to it. These actions are set up by default to sane behavior for all psituations apcupsd is likely to detect from the UPS. However, you can change the apccontrol behavior for every single action.

To customize, so create a file with the same name as the action, which is passed as a command line argument. Put your script in the /etc/apcupsd directory.

These events are sent to the system log, optionally sent to the temporary events file (/etc/apcupsd/apcupsd.events), and they also generate a call to /etc/apcupsd/apccontrol which in turn will call any scripts you have placed in the /etc/apcupsd directory.

Normally, /etc/apcupsd/acpcontrol is called only by apcupsd. Consequently, you should not invoke it directly. However, it is important to understand how it functions, and in some cases, you may want to change the messages that it prints using wall. We recommend that you do so by writing your own script to be invoked by apccontrol rather than by modifying apccontrol directly. This makes it easier for you to upgrade to the next version of apcupsd

In other case, you may want to write your own shell scripts that will be invoked by apccontrol. For example, when a power fail occurs, you may want to send an email message to root. At present the arguments that apccontrol recognizes are:

When apcupsd detects an event, it calls the apccontrol script with four arguments as:

apccontrol <event> <ups-name> <connected> <powered>

where:

event
is the event that occurred and it may be any one of the values described in the next section.

ups-name
is the name of the UPS as specified in the configuration file (not the name in the EEPROM). For version 3.8.2, this is always set to Default

connected
is 1 if apcupsd is connected to the UPS via a serial port (or a USB port). In most configurations, this will be the case. In the case of a Slave machine where apcupsd is not directly connected to the UPS, this value will be 0.

powered
is 1 if the computer on which apcupsd is running is powered by the UPS and 0 if not. At the moment, this value is unimplemented and always 0.


apccontrol Command Line Options

apccontrol accepts the following command line options:

annoyme
When a shutdown is scheduled, and the time specified on the ANNOYME directive in the apcupsd.conf file expires, this event is generated.

Default -- does a printf ``Power problems please logoff.'' | wall then exits.

changeme
When apcupsd detects that the mains are on, but the battery is not functioning correctly, this event is generated. It is repeated every x hours.

Default -- does a printf ``Emergency! UPS batteries have failed\nChange them NOW'' | wall then exits.

commfailure
This event is generated each time the communications line with the computer is severed. This event is not detected on dumb signaling UPSes.

Default -does a printf ``Warning serial port communications with UPS lost.'' | wall then exits.

commok
After a commfailure event is issued, when the communications to the computer is re-established, this event will be generated.

Default -- does a printf ``Serial communications with UPS restored.'' | wall then exits.

doreboot
This event is depreciated and should not be used.

Default - does a reboot of the system by calling shutdown -h now

doshutdown
When the UPS is running on batteries and one of the limits expires (time, run, load), this event is generated to cause the machine to shutdown.

Default does a shutdown of the system by calling shutdown -h now

emergency
Does an emergency shutdown of the system by calling shutdown -h now

failing
This event is generated when the UPS is running on batteries and the battery power is exhausted. The event following this one will be a shutdown.

Default -- does a printf ``UPS battery power exhausted. Doing shutdown.\n'' | wall then exits.

loadlimit
This event is generated when the battery charge is below the low limit specified in the apcupsd.conf file.

Default -- does a printf ``UPS battery discharge limit reached. Doing shutdown.\n'' | wall then exits. After completing this event, apcupsd will immediately initiate a doshutdown event.

mainsback
This event is generated when the mains power returns after a powerout condition. The shutdown event may or may not have been generated depending on the paramaters you have defined and the length of the power outage. A cancel of a shutdown should never be attempted as it is very unlikely to succeed and will almost surely leave your machine in a indeterminate state.

Default -- attempts to cancel the shutdown with a shutdown -c (not sure about that!!!!)

onbattery
This event is generated 5 or 6 seconds after an initial powerfailure is detected. It means that apcupsd definitely considers the UPS to be on batteries. The onset of this event can be delayed by the ONBATTERYDELAY apcupsd.conf configuration directive.

Default -- does a printf ``Power failure. Running on UPS batteries.'' | wall then exits.

offbattery
This event is generated when the mains return only if the onbattery event has been generated.

Default -- does nothing.

powerout
This event is generated immediately when apcupsd detects that the UPS has switched to batteries. It may be due to a short powerfailure, an automatic selftest of the UPS, or a longer powerfailure. In many cases, you may want to inhibit the normal message sent/emailed by this event to avoid being annoyed by short power failures.

Default -- does a printf ``Warning power loss detected.'' | wall then exits.

remotedown
This event is generated on a slave machine when it detects either that the master has shutdown, or that a onbattery situation exists and the communications line has been severed.

Does a shutdown -h now

runlimit
This event is generated when the MINUTES value defined in the apcupsd.conf file expires while in a power fail condition. The MINUTES is the remaining runtime as internally calculated by the UPS and monitored by apcuspd.

Does a printf ``UPS battery runtime percent reached. Doing shutdown.\n'' | wall then exits. After completing this event, apcupsd will immediately initiate a doshutdown event.

timeout
This event is generated when the TIMOUT value defined in the apcupsd.conf file expires while in a power fail condition. It indicates that the total time in a power failure has been exeeded and the machine should be shutdown. Normally, with smart UPSes, this value is not used, but rather one relies on the remaining runtime (MINUTES) or the battery level (BATTERYLEVEL) values specified in the conf file.

Does a printf ``UPS battery runtime limit exceeded. Doing shutdown.\n'' | wall then exits. After completing this event, apcupsd will immediately initiate a doshutdown event.

startselftest
This event is generated when apcupsd detects a self test by the UPS. Normally due to the 6 second onbattery delay default time, self test events are not detected.

This is called when apcupsd detects that the UPS is doing a self test. No action is taken.

endselftest
This event is generated when the end of a self test is detected.

This is called when apcupsd determines that a self test has been completed. No action is taken.

battdetach
This event is generated when apcupsd detects that the UPS battery has been disconnected.

battattach
This event is generated when apcupsd detects that the UPS battery has been reconnected after a battdetach event.

To write your own routine for the powerout action, you create shell script named powerout and put it in the lib directory (normally /etc/apcupsd). When the powerout action is invoked by apcupsd, apccontrol will first give control to your script. If you want apccontrol to continue with the default action, simply exit your script with an exit status of zero. If you do not want apccontrol to continue with the default action, your script should exit with the special exit code of 99. However, in this case, please be aware that you must ensure proper shutdown of your machine if necessary.

Some sample scripts (onbattery and mainsback) that email power failure messages can be found in /etc/apcupsd after an install or in the platforms/etc directory of the source code.


next up previous contents index
Next: Controlling Multiple UPSes on Up: Apcupsd User's Guide Previous: Advanced topics   Contents   Index
2009-03-11