<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<HTML>
<HEAD>
<TITLE>Apcupsd EVENTS</TITLE>
<meta name="Author" content="Kern Sibbald">
<link rel=stylesheet href="apcupsd-styles.css" type="text/css">
</HEAD>
<BODY>
<H1>Apcupsd EVENTS</H1>
<P>When <B>apcupsd</B> detects anomalies from your UPS device, it
will make some decisions that usually result in one or more calls to
the script located in <B>/etc/apcupsd/apccontrol</B>. The <B>apccontrol</B>
file is a shell script that acts on the first argument that <B>apcupsd</B>
passes to it. These actions are set up by default to sane behaviour
for all possible situations <B>apcupsd</B> is likely to detect from
the UPS. Nevertheless you can change the <B>apccontrol</B> behaviour
for every single action. To do so create a file with the same name as
the action, which is passed as a command line argument. Put your
script in the <B>/etc/apcupsd </B>directory.
</P>
<P>These events are sent to the system log, optionally sent to the
temporary events file (<B>/etc/apcupsd/apcupsd.events</B>), and they
also generate a call to <B>/etc/apcupsd/apccontrol</B> which in turn
will call any scripts you have placed in the <B>/etc/apcupsd
</B>directory.
</P>
<P>Normally, <B>/etc/apcupsd/acpcontrol</B> is called only by
<B>apcupsd</B>. 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 <B>wall</B>.
We recommend that you do so by writing your own script to be invoked
by <B>apccontrol</B> rather than by modifying <B>apccontrol</B>
directly. This makes it easier for you to upgrade to the next version
of <b>apcupsd</b>
</P>
<P>In other case, you may want to write your own shell scripts that
will be invoked by <B>apccontrol</B>. For example, when a power fail
occurs, you may want to send an email message to root. At present the
arguments that <B>apccontrol</B> recognizes are:
</P>
<H2>How apcupsd calls apccontrol</H2>
When <b>apcupsd</b> detects an event, it calls the <b>apccontrol</b> script
with four arguments as:
<p class="tty">apccontrol <event> <ups-name> <connected> <powered></p>
where:
<dl> <dt>event</dt> <dd>is the event that occurred and it may be
any one of the values described in the next section.</dd>
<dt>ups-name</dt> <dd>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 <b>Default</b></dd>
<dt>connected</dt><dd>is 1 if <b>apcupsd</b> 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
<b>apcupsd</b> is not directly connected to the UPS, this value
will be 0.</dd>
<dt>powered</dt><dd></dd>is 1 if <b>apcupsd</b> is powered by the
UPS and 0 if not. In version 3.8.2, this value is always 1.</dd>
</dl>
<h2>apccontrol Command Line Options</h2>
<P><B>apccontrol</B> accepts the following command line options:
</P>
<DL>
<DT>annoyme<DD>Does a <B>printf "Power problems please logoff."
| wall </B> then exits.
<DT>changeme<DD>Does a <B>printf "Emergency! UPS batteries have
failed\nChange them NOW" | wall </B> then exits.
<DT>commfailure<DD>Does a <B>printf "Warning serial port
communications with UPS lost." | wall</B> then
exits.
<DT>commok<DD>Does a <B>printf "Serial communciations with UPS
restored." | wall</B> then exits.
<DT>doreboot<DD>Does a reboot of the system by calling <B>shutdown -r
now</B>
<DT>doshutdown<DD>Does a shutdown of the system by calling <B>shutdown -h
now</B>
<DT>emergency<DD>Does an emergency shutdown of the system by calling
<B>shutdown -h now</B>
<DT>failing<DD>Does a <B>printf "UPS battery power exhaused. Doing
shutdown.\n" | wall</B> then exits.
<DT>loadlimit<DD>Does a <B> printf "UPS battery discharge limit
reached. Doing shutdown.\n" | wall</B> then exits.
After completeting this event, <B>apcupsd</B> will immediately
initiate a <B> doshutdown </B>event.
<DT>mainsback<dd>Attempts to cancel the shutdown with a
<B>shutdown -c</B>
<DT>onbattery<DD>Does a <B>printf "Power failure. Running on UPS
batteries." | wall</B> then exits.
<DT>powerout<DD>Does a <B>printf "Warning power loss detected."
| wall</B> then exits. </dd>
<DT>remotedown<DD>Does a <B>shutdown -h now</B> </dd>
<DT>restartme<DD>Terminates the currently running <B>apcupsd</B> and then restarts
it.</dd>
<DT>runlimit<DD>Does a <B>printf "UPS battery runtime percent
reached. Doing shutdown.\n" | wall</B> then exits.
After completeting this event, <B>apcupsd</B> will immediately
initiate a <B>doshutdown</B> event.</dd>
<DT>timeout<DD STYLE="margin-bottom: 0.2in">Does a <B>printf "UPS battery runtime limit
exceded. Doing shutdown.\n" | wall</B> then exits.
After completeting this event, <B>apcupsd</B> will immediately
initiate a <B>doshutdown</B> event.</dd>
<dt>startselftest</dt><dd>This is called when <b>apcupsd</b> detects that the
UPS is doing a self test. No action is taken.</dd>
<dt>endselftest</dt><dd>This is called when <b>apcupsd</b> determines that
a self test has been completed. No action is taken.</dd>
</DL>
<P>
To write your own routine for the <B>powerout</B> action, you create
shell script named <B>powerout</B> and put it in the lib directory
(normally <B>/etc/apcupsd</B>). When the <B>powerout</B> action is
invoked by <B>apcupsd</B>, <B>apccontrol</B> will first give control
to your script. If you want <B>apccontrol</B> to continue with the
default action, simply exit your script with an exit status of zero.
If you do not want <B>apccontrol</B> to continue with the default
action, your script should exit with the special exit code of <B>99</B>.
However, in this case, please be aware that you must ensure proper
shutdown of your machine if necessary.</P>
<p>Some sample scripts (onbattery and mainsback) that email power failure messages can be
found in the <b>examples</b> directory of the source code.
<P><BR><BR>
</P>
<hr>
<a href="eprom.html" target="_self"><img src="back.gif" border=0 alt="Back"></a>
<a href="faq.html" target="_self"><img src="next.gif" border=0 alt="Next"></a>
<a href="index.html"><img src="home.gif" border=0 alt="Home"></a>
</BODY>
</HTML>
