<!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 behavior for all possible situations <B>apcupsd</B> is likely to detect from the UPS. Nevertheless you can change the <B>apccontrol</B> behavior 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 communications 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 exhausted. 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 completing 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 completing 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 exceeded. Doing shutdown.\n" | wall</B> then exits. After completing 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>