*** Rewritten 2 Feb 2002 - this is the old version

Desc: How to set up automatic shutdowns
File: shutdown.txt
Date: 19 October 2001
Auth: Russell Kroll <rkroll@exploits.org>

The basic idea here is to allow all other systems to shut down safely,
then have the master take care of itself.  Finally, the master will start
the shutdown which eventually tells the UPS to power off after the
disks have been synced and remounted read-only.  This ensures a reboot
when the utility power returns.  Without this step, it's possible to have
halted systems just sitting there if the power comes back at the worst
possible time.

Shutdown steps
--------------

Using this method, the master goes through the following steps when the
overall power situation gets critical (on battery + low battery).

1. Slave systems are given up to <HOSTSYNC> seconds to log out.
   If any are still connected after that time, the master assumes it
   is hung and proceeds with the shutdown anyway.

2. upsmon generates a NOTIFY_SHUTDOWN event.

3. upsmon waits <FINALDELAY> seconds - default 15.

4. upsmon creates the <POWERDOWNFLAG> file

5. upsmon calls your <SHUTDOWNCMD>

6. init takes over, kills all processes, syncs your disks, then remounts
   them readonly.

7. The shutdown script checks for the <POWERDOWNFLAG>, finds it, and
   tells your UPS driver to kill the power immediately.

8. The system loses power.

How you set it up
-----------------

1. Add "POWERDOWNFLAG /some/path" to your upsmon.conf.  Exactly where you
   put it doesn't matter much, assuming it's not accessible to the users.
   Otherwise some clever user might create it and your system(s) will
   power off the next time the script runs, like for a reboot.  Ouch.

   This defaults to /etc/killpower.  If you like that filename, there's
   no need to change anything in the config file.
   
2. Edit your shutdown scripts to check for that flag file and then call
   your UPS support program to do the dirty work.  Something like this
   should work on most systems.  Change the paths to suit your setup:

	if (test -f /etc/powerdown)
	then
	  echo "Killing the power, bye!"
	  /usr/local/ups/bin/apcsmart -k /dev/ttyS0
	fi

   Replace apcsmart with the driver(s) you use, of course.  If you're 
   using FreeBSD, you may also need to do "-x nolock" as the drivers
   attempt and fail to uu_lock() serial ports on a read-only filesystem.

   This file may be /etc/rc.d/rc.0, /etc/shutdown, or something else.
   Consult a guru for your OS/distribution if you're not sure.

   Note: this only works if your driver supports the -k option.  If it
   doesn't, report it as a bug, since it is.


3. Start up upsmon, pull the plug, and wait.

Other issues
------------

Q: Should I rm the flag file at startup?

A: You can, but it's not essential.  upsmon will check for it when
   starting up and will remove it for you.  So, if upsmon runs when the
   system boots (why wouldn't it?) then you don't have to worry about it.
  
   This means that lazy admins like me only have to modify their shutdown
   scripts for this feature and don't have to change the startup files.

Q: Why can't my system find the model program when it's time to do
   the -k command to turn the power off?

A: Your shutdown scripts may totally unmount the filesystem that has
   the UPS software.  If this happens, either change the scripts to 
   leave them mounted (read-only, of course), or make sure that the driver
   exists on a partition which is still mounted like /bin.

Q: What happens if the power comes back on during the shutdown phase?

A: "Smart" UPSes should force a power down for at least a few seconds,
   no matter what happens.  That is the best way to be sure that every
   attached system forcibly reboots back into a usable state.

   On most contact closure units, it gets messy.  You can get around
   this by adding a reboot command after the "module -k ..." command so
   that it reboots and comes back up if the shutdown fails.

   Note that if you have multiple systems on a simple contact closure UPS,
   you're asking for trouble.  The slaves will have no way to know when
   the shutdown fails, short of a timer elapsing.  If you really have to
   run more than one system on one of these models, be sure to have a
   sleep followed by a reboot rather than just a halt.  Otherwise you may
   come back to find the master up and all the slaves halted after an
   event like this.
