5. Do it yourself guide

This discussion is specifically tailored for dumb UPS control. However, most of the process is about the same for dumb UPSs and smart UPSs. The biggest difference is in the details of how the UPS monitoring daemon (typically powerd) communicates with the UPS.

Before doing anything, I suggest the following algorithm:

• Skim this document.
• Download and investigate all packages which seem specifically tailored to your UPS.
• Download and investigate the more generic packages. Note that some of the more generic packages are actually more powerful, better documented, and easier to use than their more specific counterparts.
• If you still can't get things working, or if points are still unclear, read this document more carefully, and hack away...

5.1 What you need to do (summary)

• Plug the computer into the UPS.
• Connect the computer's serial port to the UPS with a special cable.
• Run powerd (or some sort of equivalent) on the computer.
• Setup your init to do something reasonable on powerfail and powerok events (like start a shutdown and kill any currently running shutdowns, respectively, for example).

5.2 How it's supposed to work

UPS's job

When the power goes out, the UPS continues to power the computer and signals that the power went out by throwing a relay or turning on an opticoupler on it's control port.

Cable's job

The cable is designed so that when the UPS throws said relay, this causes a particular serial port control line (typically DCD) to go high.

Powerd's job

The powerd daemon monitors the serial port. Keeps raised/lowered whatever serial port control lines the UPS needs to have raised/lowered (typically, DTR must be kept high and whatever line shuts off the UPS must be kept low). When powerd sees the UPS control line go high, it writes FAIL to /etc/powerstatus and sends the init process a SIGPWR signal. (Older versions of powerd and initd wrote to /etc/powerfail.) When the control line goes low again, it writes OK to /etc/powerstatus and sends init a SIGPWR signal.

Init's job (aside from everything else it does)

When it receives a SIGPWR, it looks at /etc/powerstatus. If it contains FAIL it runs the powerfail entry from /etc/inittab. If it contains OK it runs the powerokwait entry from inittab.

5.3 How to set things up

The following presupposes that you have a cable that works properly with powerd. If you're not sure that your cable works (or how it works), see section Reverse-engineering cables and hacking powerd.c for information on dealing with poorly described cables and reconfiguring powerd.c. Sections Serial port pin assignments and Ioctl to RS232 correspondence will also be useful.

If you need to make a cable, see section How to make a cable for the overall details, and the subsection of section Info on selected UPSs that refers to your UPS. The latter might also include information on manufacturer supplied cables. You may want to at least skim all of section Info on selected UPSs because each section has a few additional generally helpful details.

• Edit /etc/inittab. Put in something like this:

  # What to do when power fails (Halt system & drain battery :):
  pf::powerfail:/etc/powerfailscript +5
  
  # If power is back before shutdown, cancel the running shutdown.
  pg:0123456:powerokwait:/etc/powerokscript
     
  

• Write scripts /etc/powerfailscript and /etc/powerokscript to shutdown in 5 minutes (or whatever's appropriate) and kill any existing shutdown, respectively. Depending on the version of shutdown that you're using, this will be either so trivial that you'll dispense with the scripts, or be a 1 line bash script, something along the lines of:

      kill `ps -aux | grep "shutdown" | grep -v grep | awk '{print $2}'`
  

  and you'll keep the scripts. (In case it doesn't come out right, the first single quote on the above line is a backquote, the second and third are single quotes, and the last is also a backquote.)
• Tell init to re-process the inittab file with the command:

      telinit q
     
  

• Edit rc.local so that powerd gets run upon startup. The syntax is:

      powerd <line>
      
  

  Replace <line> with the serial port that the UPS is connected, such as /dev/cua1.
• Connect computer's serial port to UPS's serial port. DO NOT PLUG THE COMPUTER INTO UPS YET.
• Plug a light into the UPS.
• Turn on the UPS and the light.
• Run powerd.
• Test the setup:
  • Yank the UPS's plug.
    • Check that the light stays on.
    • Check that /etc/powerfailscript runs.
    • Check that shutdown is running.
  • Plug the UPS back in.
    • Check that the light stays on.
    • Check that /etc/powerokscript runs.
    • Check that /etc/powerfailscript is not running.
    • Check that shutdown is no longer running.
  • Yank the UPS's plug again. Leave it out and make sure that the computer shuts down properly in the proper amount of time.
  • The Dangerous Part. After everything seems to be proper, power down the computer and plug it into the UPS. Run a script that sync's the hard disk every second or so. Simultaneously run a second script that keeps doing a find over your entire hard disk. The first is to make this a little safer and the second is to help draw lots of power. Now, pull the plug on the UPS, check again that shutdown is running and wait. Make sure that the computer shuts down cleanly before the battery on the UPS gives out. This is dangerous because if the power goes out before the computer shuts down, you can end up with a corrupt file system, and maybe even lose all your files. You'll probably want to do a full backup before this test, and set the shutdown time extremely short to begin with.

Congratulations! You now have a Linux computer that's protected by a UPS and will shutdown cleanly when the power goes out!

5.4 User Enhancements

• Hack powerd.c to monitor the line indicating that the batteries are low. When the batteries get low, do an immediate shutdown.
• Modify the shutdown procedure so that if it's shutting down in a powerfail situation, then it turns off the UPS after doing everything necessary.