*** powstatd.man.orig	Sat Apr  3 21:58:22 2004
--- powstatd.man	Sat Apr  3 21:47:05 2004
***************
*** 111,116 ****
--- 111,122 ----
  example, the NTP protocol) or valid status messages may be rejected. 
  
  .SH CONFIGURATION
+ .B Important Note:
+ This section has been modified from the upstream version in order to
+ describe how the software is configured and installed on
+ .B Debian
+ systems.
+ 
  .I powstatd
  is configured via a configuration file, 
  .I /etc/powstatd.conf
***************
*** 119,161 ****
  security option enabled,
  .I powstatd
  will require that file permissions on the configuration file deny rwx
! access to "group" or "other").
! 
! To configure your UPS, follow these steps:
! 
! .B 0.  
! Edit the Makefile to suit your installation. In particular, the secure
! master/slave communication protocol is selected/deselected by making
! the appropriate change to the definition of CFLGS in the
! Makefile. Note that users outside the United States wishing to use the
! secure communication protocol will first need to download the
! public-domain ANSI C implementation of TEA, the
  .I Tiny Encryption Algorithm, 
  from
  .I ftp://vader.eeng.brad.ac.uk/pub/crypto/xtea.c
  
! .B 1. 
! Compile 
! .I powstatd:
! 
! .in +3
! % make 
! .in -3
! 
! or, if you are compiling on a DEC Alpha platform:
! 
! .in +3
! % make alpha
! .in -3
  
! .B 2. 
  Make sure your new UPS is completely charged and is connected to your
  machine via the serial monitoring line provided by the UPS
  manufacturer to your machine (if you did not get such a monitoring
  line with your UPS, see the the UPS-HOWTO for information on how to
  make one).
  
! .B 3. 
  In order to configure 
  .I powstatd,
  make sure your machine 
--- 125,148 ----
  security option enabled,
  .I powstatd
  will require that file permissions on the configuration file deny rwx
! access to "group" or "other").  Note that the
! .B Debian package powstatd
! is compiled with secure cryptography using the public-domain ANSI C
! implementation of TEA, the
  .I Tiny Encryption Algorithm, 
  from
  .I ftp://vader.eeng.brad.ac.uk/pub/crypto/xtea.c
  
! To configure your UPS, follow these steps:
  
! .B 1. 
  Make sure your new UPS is completely charged and is connected to your
  machine via the serial monitoring line provided by the UPS
  manufacturer to your machine (if you did not get such a monitoring
  line with your UPS, see the the UPS-HOWTO for information on how to
  make one).
  
! .B 2. 
  In order to configure 
  .I powstatd,
  make sure your machine 
***************
*** 165,182 ****
  via the serial monitoring line). Instead, plug a desk light or radio
  into the UPS.
  
! .B 4. 
! Determine what serial line is connected to your UPS and create an
! initial copy of 
  .I /etc/powstatd.conf 
  (you can look at the sample powstatd.conf.* files included in the 
! distribution) containing a single line specifying the serial line, e.g.:
  
  .in +3
  watch ttyS0
  .in -3
  
! .B 5. 
  As root, run 
  .I powstatd
  in test mode (you'll have to be root to have
--- 152,173 ----
  via the serial monitoring line). Instead, plug a desk light or radio
  into the UPS.
  
! .B 3. 
! Determine what serial line is connected to your UPS and edit it into
! the configuration file
  .I /etc/powstatd.conf 
  (you can look at the sample powstatd.conf.* files included in the 
! Debian distribution in 
! .I /usr/share/doc/powstatd/
! or
! .I /usr/share/doc/powstatd-crypt/
! ) at the line specifying the serial line, e.g.:
  
  .in +3
  watch ttyS0
  .in -3
  
! .B 4. 
  As root, run 
  .I powstatd
  in test mode (you'll have to be root to have
***************
*** 238,244 ****
  
  until you get the OK status reading.
  
! .B 6. 
  Repeat step 4, but this time pull the plug on the UPS and then
  reinsert it after a few seconds. Observe changes in the values for the
  input lines; it should be easy to determine what line corresponds to
--- 229,235 ----
  
  until you get the OK status reading.
  
! .B 5. 
  Repeat step 4, but this time pull the plug on the UPS and then
  reinsert it after a few seconds. Observe changes in the values for the
  input lines; it should be easy to determine what line corresponds to
***************
*** 280,286 ****
  .TE
  .in -3
  
! .B 7. 
  At this point, you should know the power failure and low battery
  signals.  Now we must determine the appropriate UPS shutdown
  signal. Fortunately, for most UPS systems, there are only 4 possible
--- 271,277 ----
  .TE
  .in -3
  
! .B 6. 
  At this point, you should know the power failure and low battery
  signals.  Now we must determine the appropriate UPS shutdown
  signal. Fortunately, for most UPS systems, there are only 4 possible
***************
*** 311,317 ****
  be too impatient here or you won't know which signal is responsible
  for actually turning the UPS off.
  
! .B 8. 
  At this point configuration should be complete. For example, for
  the Cyberpower Power99 325/385/450/500VA models, a reasonable 
  .I /etc/powstatd.conf 
--- 302,308 ----
  be too impatient here or you won't know which signal is responsible
  for actually turning the UPS off.
  
! .B 7. 
  At this point configuration should be complete. For example, for
  the Cyberpower Power99 325/385/450/500VA models, a reasonable 
  .I /etc/powstatd.conf 
***************
*** 328,334 ****
  .fi
  .in -3
  
! .B 9. 
  If you have other machines running off the same UPS, include one or
  more slave entries specifying their names in the master's configuration file:
  
--- 319,325 ----
  .fi
  .in -3
  
! .B 8. 
  If you have other machines running off the same UPS, include one or
  more slave entries specifying their names in the master's configuration file:
  
***************
*** 350,365 ****
  .fi
  .in -3
  
! If you intend to run more than 2 slaves off a very large UPS, you will
  need to adjust the MAXSLAVES parameter in the source code accordingly
  and then recompile.
  
  If 
  .I powstatd
  is compiled with the appropriate security option enabled, encryption
! is used to protect slaves from malicious shutdown messages. An
! identical password directive should therefore appear in both master
! and slave configuration files:
  
  .in +3
  .nf
--- 341,356 ----
  .fi
  .in -3
  
! If you intend to run more than 20 slaves off a very large UPS, you will
  need to adjust the MAXSLAVES parameter in the source code accordingly
  and then recompile.
  
  If 
  .I powstatd
  is compiled with the appropriate security option enabled, encryption
! is used to protect slaves from malicious shutdown messages (This is true
! on Debian systems).  An identical password directive should therefore
! appear in both master and slave configuration files:
  
  .in +3
  .nf
***************
*** 372,418 ****
  will encrypt generate and check timestamps in order to foil replay
  attacks.
  
! .B 10.
! Make sure your inittab file contains appropriate lines to invoke
! .I powstatd.fail, powstatd.low, 
! and 
! .I powstatd.ok:
! 
! .in +3
! .nf
! # UPS signals a power outage.
! pf:12345:powerfail:/sbin/powstatd.fail
! 
! # UPS signals power restored before the shutdown kicks in.
! pr:12345:powerokwait:/sbin/powstatd.ok
  
! # UPS signals low battery power: emergency shutdown.
! pn:12345:powerfailnow:/sbin/powstatd.low
! .fi
! .in -3
  
! .B 11. 
! Edit scripts 
! .I powstatd.ok, powstatd.fail, 
! and 
! .I powstatd.low
! to adjust time parameters, if desired. 
! 
! .B 12. 
! "make install", then reboot the machine. If you don't want to reboot,
! issue instead:
  
! .in +3
! .nf
! % /etc/rc.d/init.d/powstatd start
! % /sbin/init q
! .fi
! .in -3
  
  .SS How It Works:
  
  .I powstatd 
! is initiated as a daemon in runlevels 3 and 5.  
  
  A UPS can only be in one of three states; OK, FAIL, or LOW. Usually,
  when the main power is on, the UPS is operating in the OK state; when
--- 363,397 ----
  will encrypt generate and check timestamps in order to foil replay
  attacks.
  
! .B 9. 
! Make sure your new /etc/powstatd.conf doesn't have a line like:
! .RS
! #!Unconfigured! Please customize the file as appropriate and remove this line
! .RE
! (all in one line) because the daemon starter script 
! .I /etc/init.d/powstatd 
! inspects 
! .I /etc/powstatd.conf 
! for this line to see if the daemon is properly configured and should be 
! started or not.
  
! .B 10.
! You may also want to edit /etc/init.d/powerfail at the line:
!  failtime=+5 # shutdown delay from initial power failure
  
! It sets the shutdown delay to 5 minutes after power line failure detection.
! You may want to increase that if your UPS has lots of power to spare, or
! reduce it.
  
! .B 11.
! Reboot, or simply start the deamon with the command:
  
+ .B # /etc/init.d/powstatd start
+   
  .SS How It Works:
  
  .I powstatd 
! is initiated as a daemon in runlevels 2 to 5.  
  
  A UPS can only be in one of three states; OK, FAIL, or LOW. Usually,
  when the main power is on, the UPS is operating in the OK state; when
***************
*** 435,449 ****
  .I /etc/powerstatus 
  tells init (which is configured by the
  .I /etc/inittab 
! file) to run one of three scripts: 
! .I powstatd.fail, powstatd.ok, 
! or 
! .I powstatd.low
  The init process then removes
  .I /etc/powerstatus
  so as not to be confused on subsequent interrupts.
  
! .B powstatd.fail
  .RS 
  initiates a timed 
  .I shutdown -h 
--- 414,429 ----
  .I /etc/powerstatus 
  tells init (which is configured by the
  .I /etc/inittab 
! file) to run the script
! .B /etc/init.d/powerfail
! with one of the arguments "start" (shutdown due to power line failure),
! "now" (shutdown NOW due to eminent UPS battery failure) or "stop" (cancel
! shutdown before power is back online).
  The init process then removes
  .I /etc/powerstatus
  so as not to be confused on subsequent interrupts.
  
! .B /etc/init.d/powerfail start
  .RS 
  initiates a timed 
  .I shutdown -h 
***************
*** 451,463 ****
  shutdown can be cancelled.
  .RE
  
! .B powstatd.ok
  .RS 
  cancels the running shutdown and notifies all users that power is restored
  and no shutdown is imminent.
  .RE
  
! .B powstatd.low
  .RS
  cancels the running shutdown and initiates an immediate 
  .I shutdown -h
--- 431,443 ----
  shutdown can be cancelled.
  .RE
  
! .B /etc/init.d/powerfail stop
  .RS 
  cancels the running shutdown and notifies all users that power is restored
  and no shutdown is imminent.
  .RE
  
! .B /etc/init.d/powerfail now
  .RS
  cancels the running shutdown and initiates an immediate 
  .I shutdown -h
***************
*** 465,471 ****
  will indeed shutdown (there is no recovery).
  .RE
  
! Note that as you halt the machine, the shutdown sequence
  invokes 
  .I powstatd
  one last time, but this time with the kill flag (-k), forcing the UPS
--- 445,451 ----
  will indeed shutdown (there is no recovery).
  .RE
  
! Note that as you halt the machine, the shutdown sequence (/etc/init.d/halt)
  invokes 
  .I powstatd
  one last time, but this time with the kill flag (-k), forcing the UPS
***************
*** 478,492 ****
  .SS Troubleshooting:
  
  .B 1. 
- If your machine doesn't seem to notice power status changes even
- when the UPS daemon is signalling them, try adjusting the location of
- the powerstatus file by changing the value of STATUS in the Makefile
- and recompiling. Some versions of the init process look in
- .I /var/log/powerstatus 
- rather than the default 
- .I /etc/powerstatus.
- 
- .B 2. 
  If your machine keeps shutting down even when the power is on, you're
  probably watching the wrong serial line. To recover, try rebooting in single
  user mode (issue "linux 1" at the LILO prompt) and disable 
--- 458,463 ----
***************
*** 504,510 ****
  .\" .I powstatd
  .\" instead.
  
! .B 3.  
  Some older UPS systems as well as some homebuilt cable connections
  (see the UPS HowTo) may require that UPS shutdown signals be sent on
  the transmission line rather than on one of the signaling
--- 475,481 ----
  .\" .I powstatd
  .\" instead.
  
! .B 2.  
  Some older UPS systems as well as some homebuilt cable connections
  (see the UPS HowTo) may require that UPS shutdown signals be sent on
  the transmission line rather than on one of the signaling
***************
*** 542,547 ****
--- 513,519 ----
  .I powstatd.dumb
  included in the distribution for an example of how to go about
  handling this case.
+ (Debian's init is fine in this respect.)
  
  .SH ACKNOWLEDGEMENTS
  .P