<!doctype html public "-//W3C//DTD HTML 4.0//EN">
<html>
<head>
<title>Shutdown Sequence</title>
<meta name="Author" content="Kern Sibbald">
<link rel=stylesheet href="apcupsd-styles.css" type="text/css">
</head>
<body>
<h1><a name="ShutdownSequence"></a>Shutdown Sequence</h1>
If you experienced so problems with the testing procedures,
or if you are porting <b>apcupsd</b> to another system, or you
are simply curious, you may want to know exactly what is going on
during the shutdown process.
<p>The shutdown sequence is as follows:
<ul>
<li>Apcupsd detects that there is a power problem and
it calls <b>/etc/apcupsd/apccontrol powerout</b>,
which normally sends a message to all users informing
them of a potential problem.
<p>
<li>After approximately 5 seconds in the power problem
mode, Apcupsd calls <b>/etc/apcupsd/apccontrol onbattery</b>,
which normally sends a message to all users informing
them that the UPS is on batteries.
<p>
<li>When one of the conditions listed below occurs, <b>apcupsd</b> issues
a shutdown command by calling <b>/etc/apcupsd/apccontrol doshutdown</b>,
which should perform a shutdown of your system using the
system <b>shutdown</b> command. You can modify the behavior
by editing the /etc/apcupsd/apccontrol script, but doing so
will make it more complicated to upgrade to the next <b>apcupsd</b>
version.
<p>
The conditions that trigger the shutdown can be: running time on
batteries have expired (TIMEOUT), the battery runtime remaining is
below the configured value (BATTERYLEVEL), the estimated remaining
runtime is below the configured value (MINUTES), or the UPS signals
that the batteries are exhausted.
<p>A shutdown could also be initiated if <b>apcupsd</b> detects that the
batteries are no longer functioning correctly. This case, though very
unusual, can happen at any time even if there is proper mains voltage,
and <b>/etc/apcupsd/apccontrol emergency</b> is called.
<p>Just before initiating any shutdown through the apccontrol script,
<b>apcupsd</b> will create the file
<b>/etc/apcupsd/powerfail</b>. This file will be used
later in the shutdown sequence to recall <b>apcupsd</b>
after syncing of the disks to initiate a power off of
the UPS. <p>If the <b>/etc/nologin</b>
file has not already been created, it will normally be
created during the shutdown sequence to prevent additional
users from logging in (see the NOLOGIN configuration
directive).
<p>Even though <b>apcupsd</b> has requested the system to
perform a shutdown, it continues running. If it is a
master with slaves, it will inform the slaves to do
a shutdown. They perform their shutdown by calling
<b>/etc/apcupsd/apccontrol remotedown</b>.
<p>
<li>When the system signals <b>apcupsd</b> to do exit,
it does so. This is part of the normal system
shutdown (at least on Unix and Linux systems) and the exact time
that <b>apcupsd</b> receives the termination signal depends on how
the shutdown links (usually in /etc/rc.d) are set.
<p>Note that on Windows NT systems, <b>apcupsd</b> apparently
continues to run as a Service even though the machine is
"shutdown".
<p>
<li>During the shutdown of the system after <b>apcupsd</b>
has been forced to exit, one of
the last things done by the system shutdown is to call the
halt script, which is usually in /etc/rc.d/halt or
/etc/rc.d/init.d/halt, or possibly in /sbin/init.d/rc.0 depending on
your system. If apcupsd was properly installed, this standard halt
script was modified to include a bit of new logic just before the
final halt of the system. It first tests if the file
<b>/etc/apcupsd/powerfail</b> exists, and if it does, it executes
<b>/etc/apcupsd/apccontrol killpower</b>. It is this last step that
will cause <b>apcupsd</b> to be re-executed with the
<b>--killpower</b> option on the command line. This option tells
<b>apcupsd</b> to inform the UPS to kill the power.
<p>This final
step is important if you want to ensure that your system will
automatically reboot when the power comes back on. The actual code
used on the RedHat version is:
<pre>
# See if this is a powerfail situation. # ***apcupsd***
if [ -f /etc/apcupsd/powerfail ]; then # ***apcupsd***
echo # ***apcupsd***
echo "APCUPSD will now power off the UPS" # ***apcupsd***
echo # ***apcupsd***
/etc/apcupsd/apccontrol killpower # ***apcupsd***
echo # ***apcupsd***
echo "Please ensure that the UPS has powered off before rebooting" # ***apcupsd***
echo "Otherwise, the UPS may cut the power during the reboot!!!" # ***apcupsd***
echo # ***apcupsd***
fi # ***apcupsd***
</pre>
</li>
</ul>
<p>The above code must be inserted as late as
possible in the halt script. On many systems, such as RedHat, all the
disk drives were unmounted, then remounted read-only, thus permitting
access to the /etc files and the <b>apcupsd</b> executable. If your
system does not explicitly remount the disks, you must remount them in
read-only mode in the code that you add. Examples of code fragments
that do this can be found in the distributions/suse subdirectory of the
source.
<p>If you are not able to insert the above code in your halt script
because there is no halt script, or because your halt script calls the
<b>init</b> program as some Unix systems do, you can either just forget
about powering off the UPS, which means that your machine will not
automatically reboot after a power failure, or there is yet another
alternative, though not at all as satisfying as inserting code in the
halt script.
<p>Only if you cannot insert the appropriate code in the halt script,
when you start <b>apcupsd</b>, normally from the
/etc/rc.d/init.d/apcupsd script, use the <b>--kill-on-powerfail</b>
option. This will cause <b>apcupsd</b> to program the UPS to shutoff
the power just before it (<b>apcupsd</b>) does the system shutdown.
Please note that this is not the most ideal solution. Read on to
understand why.
<p>A very important consideration is that you must set the EEPROM in
your UPS so that it waits a sufficient time for the system to halt
before it shuts off the UPS power. The current value as well as the
permitted values for your UPS can be determined by executing:
<p class="tty">apcaccess eeprom</p> The output should look something like
the following:
<pre>
apcaccess eeprom
Valid EPROM values for the SMART-UPS 1000
Config Current Permitted
Description Directive Value Values
===================================================================
Upper transfer voltage HITRANSFER 253 253 264 271 280
Lower transfer voltage LOTRANSFER 196 196 188 208 204
Return threshold RETURNCHARGE 0 00 15 50 90
Output voltage on batts OUTPUTVOLTS 230 230 240 220 225
Sensitivity SENSITIVITY H H M L L
Low battery warning LOWBATT 2 02 05 07 10
Shutdown grace delay SLEEP 20 020 180 300 600
Alarm delay BEEPSTATE 0 0 T L N
Wakeup delay WAKEUP 0 000 060 180 300
Self test interval SELFTEST 336 336 168 ON OFF
</pre>
The line of interest for you is the <b>Shutdown grace delay</b>, which can
be changed using the <a href=configure.html#SLEEP>SLEEP</a> directive in your
<b>apcupsd.conf</b> file. The default value is 20 seconds, but generally, you
can set it to 180, 300, or 600 seconds depending on your UPS.
See the <a href="eprom.html">EEPROM programming section</a>
of this manual for further details on how to change this EPROM value.
<pIf you use the <b>--kill-on-powerfail</b> option,
you run the risk of having the computer power cut before the system
has shutdown. Even if the grace period is rather long, if something
goes wrong in the shutdown, well, it is up to you to decide.
<h2>Automatic Reboot of your Computer after a Power Shutdown</h2>
If <b>apcupsd</b> has successfully shutdown your computer and powered off the
UPS during a power outage, you can control whether or not your computer
is automatically rebooted when the power returns.
<p>The UPS contains two internal EPROM values that determine when it
will restore power to your computer after a full power shutdown. They
are the <a href=configure.html#RETURNCHARGE>RETURNCHARGE</a> percentage
and the <a href=configure.html#WAKEUP>WAKEUP</a> delay. Briefly, the
<b>RETURNCHARGE</b> specifies what percentage charge the battery must
have before the power is restored. Higher values are recommended in
regions where the power goes up and down frequently. The <b>WAKEUP</b>
delay is a simple time delay. Most sites will have both of these at
zero, or perhaps the <b>RETURNCHARGE</b> set to 15. Please follow the
links to the <b>Configuration</b> section of this manual for more
information. See the <a href="eprom.html">EEPROM programming
section</a> of this manual for further details on how to change these
EPROM values.
<p>The final consideration for a automatic reboot after a full power
down is to ensure that your computer will automatically reboot when the
power is restored. This is not the normal behavior of most computers as
shipped from the factory. Normally after the power is cut and restored,
you must explicitly press a button for the power to actually be turned
on. You can test your computer by powering it down; shutting off the
power (pull the plug); then plugging the cord back in. If your computer
immediately starts up, good. There is nothing more to do. If your
computer does not start up, manually turn on the power (by pressing the
power on button) and enter your computer's SETUP program (often by
pressing DEL during the power up sequence; sometimes by pressing F10).
You must then find and change the appropriate configuration parameter to
permit instant power on. Normally, this is located under the
<b>BOOT</b> menu item, and will be called something such as <b>Restore
on AC/Power Loss</b> or <b>Full-On</b>. The exact words will vary
according to the ROM BIOS provider. Generally you will have three
options: <b>Last State</b>, <b>Power On</b>, and <b>Power Off</b>.
Although <b>Last State</b> should normally work, I set my computers to
<b>Power On</b>. This means that whenever the power is applied they are
on. The only way to shut them off is to pull the plug or to have a
special program that powers them off (<b>/sbin/poweroff</b> on Linux
systems).
<h2>Shutdown Problems</h2>
Obviously if your halt script is not properly modified,
<b>apcupsd</b> will not be able to shut off the power to
the UPS, and if the power returns before the batteries are
exhausted your system will not automatically reboot. In any
case, your machine should have been cleanly shutdown.
<a name="MasterSlaveShutdown"></a>
<h2>Master/Slave Shutdown</h2>
In master/slave configurations, however, the master cannot be 100
percent sure that the slaves have all shutdown before it performs the
power off. As a consequence, it is possible that the master will shut
off the power before the slave has finished shutdown. If this is the
case, the best procedure is to put an appropriate sleep command in the
<b>/etc/apcupsd/apccontrol</b> file on the master. For example to give
the slaves 30 additional seconds to shutdown, one would add:
<p class="tty">sleep 30</p>
just after the line that reads
<p class="tty">doshutdown)</p>
in the apccontrol
file (approximately line 79 - depending on your system version).
<p>Also, on a slave machine, you do not want to use the modified
halt script since it will recall <b>apcupsd</b>, which will detect
that it is a slave (i.e. no connection to the UPS) and will complain
that it cannot do the killpower. This situation is not harmful just
annoying and possibly confusing.
<p>One possible problem during shutdown can be caused by remnants
of old versions. Please be sure to delete or rename all prior
versions (/usr/local/sbin/apcupsd or /sbin/powersc).
<h2>Startup</h2>
Normally, <b>apcupsd</b> is automatically started when your
system is rebooted. This normally occurs because the startup
script <b>apcupsd</b> is linked into the appropriate places in
<b>/etc/rc.d</b>. On most Linux systems, there is a program
called <b>chkconfig</b> that will automatically link the
startup script. This program is invoked by the <b>make install</b>
scripts, or it is explicitly done for those systems that do not
have <b>chkconfig</b>. If this is not the case, you can either
link it in appropriately yourself or explicitly call it from
your rc.local file. The appropriate manual way to startup <b>apcupsd</b>
is by executing:
<p class="tty"> <path>/apcupsd start</p>
where <path> is normally <b>/etc/rc.d</b> or <b>/etc/rc.d/init.d</b>
depending on your system (isn't Unix wonderful? :-)). Using this script
is important so that any files remaining around after a power failure
are removed. Likewise, shutting down <b>apcupsd</b> should be done
with the same script:
<p class="tty"> <path>/apcupsd stop</p>
<h2>Windows Considerations</h2>
Please see the end of <a href="win32.html">Apcupsd Under Windows</a>
chapter of this manual for conderations pertaining to shutdown and
killpower on Windows.
<hr>
<a href="troubles.html" target="_self"><img src="back.gif" border=0 alt="Back"></a>
<a href="apcaccess.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>
