Provided by: upsd_2.6-4.1_i386 bug

NAME

       upsd, rc.upsd -- UPS monitor daemon.

SYNOPSIS

       /sbin/upsd  [options] serial-device | host-name
       /etc/rc.d/rc.upsd [ -r -w sec -v ]

DESCRIPTION

   upsd
       Upsd  is  a daemon process that sits in the background and monitors the
       state of the DCD and CTS lines of the specified serial  device.   These
       lines  are  to  be connected to a UPS (Uninterruptible Power Supply) so
       that the computer can monitor the state  of  the  UPS.   The  DCD  line
       monitors  for  a  power  fail  condition,  while CTS monitors for a low
       battery condition.  RTS may be optionally used to shut down the UPS, if
       that  feature  is  supported  by  the  UPS.   CTS  and  RTS may be left
       unconnected if the UPS does not support the corresponding features.

       Upsd can also run in slave mode.  In this mode, upsd polls another copy
       of  itself  running  on  a  remote  host.   This  can be used to give a
       controlled shutdown capability to all of the hosts on a  network,  even
       ones which do not have a hardwired monitor connection to a UPS.

       When  upsd senses that the power is failing, it notifies init(8), which
       will execute the powerwait and powerfail  entries  in  /etc/inittab  as
       well  as  the  powerfailnow  entries  if  sysinit  2.52  or  higher  is
       installed.  If upsd  senses  that  the  power  has  been  restored,  it
       notifies init again and init will execute the powerokwait entry.

       Upsd uses the syslog(2) facility for status reporting when running as a
       daemon.

ARGUMENTS

   upsd
       serial-device
              Some serial port that is not being used by another  device,  and
              does  not  share  an  interrupt with any other serial port.  Not
              valid with -s.

       host-name
              A host name or IP address.  Only valid if the -s option is used.

OPTIONS

   upsd
       -c count
              Wait  count  poll  intervals before shutdown.  The default is 2.
              This option is intended to prevent  users  on  the  system  from
              being  bothered  by  alerts  caused by short power glitches.  It
              should probably be  set  to  0  (signal  right  away)  on  slave
              machines.

       -d master | local
              Simulate  operation  with  dummy  status  by  taking  UPS status
              information from the file /tmp/upsds.  In  master  mode,  simply
              report  this  status to any slave interrogating via the network,
              no other action is taken. In local  mode,  operate  exactly  the
              same  as  without  this  option  except the status is taken from
              /tmp/upsds rather than either the UPS or the net.

       -e     Enhanced support for the init powerfailnow action. This  is  not
              documented  in  man  init  as  of  sysvinit-2.74  but  has  been
              incorporated  since  sysvinit-2.52  several  years  ago.   Older
              versions  of  init  will  default to powerfail if this option is
              turned on. Versions of init from 2.52 onward must have an  entry
              of the form:

              id:runlevels:powerfailnow:process

              See the installation README file for additional details

              Use  of  the  -e option for slaves is not recommended unless the
              slave shares the same UPS as the master.

       Man page info for init action powerfailnow is as follows:

              The process will be  executed  when  init  receives  the  SIGPWR
              signal, indicating that battery is low, provided that there is a
              file  called etc/powerstatus containing the word LOW. Init  will
              wait  for  the process to finish before continuing. NOTE: if the
              process started is shutdown, it will not be aborted by  a  power
              OK.

       -h     Print a short usage message and exit.

       -i time
              Set  the  poll interval to time seconds.  Default is 10 seconds.
              This should probably be shorter on the master machine and longer
              on  the  slaves.  Times less than 0 are interpreted to mean that
              upsd should get the UPS status and  exit  immediately  (this  is
              useful  in  a "halt" script).  The UPS status is returned in the
              exit code.

       -k     Kill the UPS power.  Most brands of UPS will honor  this  signal
              only  if  they  are  running on battery power.  Causes RTS to go
              high for 5 seconds.

       -l     Don’t shut down until a low battery indication appears.   Should
              only  be  used on standalone machines, and only with init set up
              for immediate shutdown.  On battery indications  will  still  be
              logged,  but won’t cause a shutdown. Init signal powerfailnow is
              disabled and replaced with a powerfail  signal.  Recommend  only
              for older systems that do not have sysinit 2.52 or higher.

       -m     Disable  master  mode.   Do  not  respond  to  polls  from slave
              machines.  Do not listen on a TCP port.  Do monitor the UPS  and
              signal  power  failures  to  init.   This  mode  is intended for
              standalone machines.

       -p port
              Listen on port in master mode, try to contact port  for  updates
              in slave mode.  Default is port 401.

       -r     Do  a recall of the previous UPS status from file /etc/upstatus.
              This mode prevents upsd from restarting  another  shutdown  when
              invoked  from runlevel 1 after a power failure has been detected
              and shutdown has run to completion. upsd will only  do  a  power
              recovery  when  started with this option. DO NOT use this option
              when invoking upsd on initial system boot.

       -s     Run in slave mode.  Poll a master host for UPS status.  The host
              name  or IP replaces the device name on the command line if this
              flag is specified.

       -t     Test mode.  Do not become a daemon, do not send SIGPWR to  init.
              This mode is intended for testing your setup.

       -w time
              Quietly  wait  in the foreground for the power to return. Do not
              become a daemon, do not send SIGPWR to init. If a master,  check
              the  UPS  status  every  time seconds. If a slave, poll a master
              host every  time  seconds.  This  mode  is  intended  for  power
              recovery  on  a  READ  ONLY file system such as software RAID, a
              slave or  master  host  using  a  UPS  system  without  shutdown
              capability.

RETURN CODES

   upsd
       Normally,  upsd does not return status codes, because it does not exit.
       If upsd does exit abnormally, it will return a status of 1.  If  killed
       by  SIGTERM,  it will return a status of 0.  If upsd is run with a poll
       interval (-i) value less than zero, it will  get  the  UPS  status  and
       exit.

   no -recall option
       With no -recall option, upsd returns it’s status as follows:

       99     Status  is  unknown. For slaves, this usually indicates that the
              connecton to the master host could not be established.

       100    Power is OK.

       101    UPS is on battery, but the battery is ok.

       102    UPS is on battery, and the battery is low.

       103    There was a UPS connection error.  Connecton  to  the  host  (in
              slave   mode)   was   interrupted,   or  the  monitor  cable  is
              disconnected (in master mode).

   with -recall option
       With -recall enabled, upsd will only  reports  status  codes  that  are
       known.  Potentially bogus status codes are not returned. Status unknown
       (99) and lost connection (103) from a remote master are  not  reported.
       For  hosts  slaved  to  a  remote  master,  failure to connect, dropped
       connections, and remote master cable failures are ignored.   Upsd  will
       instead  return the last valid status that was determined based on both
       the last valid current status (including  the  recall  value  retrieved
       from /etc/upstatus at startup).  This set of codes is useful in scripts
       that are used in the shutdown/reboot sequence. If you want  the  actual
       status,  do not use the -recall option. The valid codes returned are as
       follows:

       100    Power is OK or was at last valid status.

       101    UPS is on battery, the battery  is  ok  or  was  at  last  valid
              status.

       102    UPS  is  on  battery,  the  battery  is low or was at last valid
              status.

       103    There was a UPS cable failure. NOT reported for slaves.

DIAGNOSTICS

   upsd
       Upsd regularly checks the DSR line to see if it is high.  DSR should be
       directly  connected  to DTR and upsd keeps that line high, so if DSR is
       low then something is wrong with the connection.  Upsd will notify  you
       about this fact.  When it sees that the connection has been restored it
       will say so.

DESCRIPTION

   rc.upsd
       The rc.upsd script is used to simplify  the  setup,  configuration  and
       debug of upsd.  The configuration arguments for upsd are entered in the
       first portion of the rc.upsd script file and then  it  is  called  with
       simple  option  flags.   If  the  parameter  DEBUG is set to yes in the
       script, it will echo the upsd command string and options  to  the  main
       console rather than executing them.

OPTIONS

   rc.upsd
       only examines the first character of each option

       -h ?   Display this help

       -r*    Recall  previous  UPS  status from /etc/upstatus at startup.  Do
              NOT specify at system boot, that will cause SIGPWR failures that
              are dependent on your inittab.

       -v*    Verbose  forground  reporting  (ignored  unless  -w  specified).
              Continuously report daemon return codes (i.e.  status CODE,  UPS
              status  message,  user message). This mode is not debounced with
              the upsd -c n option, recommended only for  DEBUG  mode  or  for
              slaves where -c 0 is normal.

       -w*    Quietly   wait   in  forground  unless  the  verbose  option  is
              specified.

              Called from the command line in the form:

                   rc.upsd -wait -verbose

              rc.upsd will echo the battery status or remote host status, if a
              slave,  to the console screen until the UPS power signal returns
              to OK.

HOWTO

       It’s pretty simple to connect your UPS to a Linux  machine.  The  steps
       are as follows:

       1.     Make  sure you have an UPS with a simple relay output; it should
              close its connections (make) if the power is gone, and it should
              open its connections (break) if the power is good.

       2.     Buy  a  serial  plug.  Connect  the  DTR  line  to  the DSR line
              directly.  Connect the DTR line and the DCD line with a 10  kOhm
              resistor.  Connect the CTS line and the DTR line with another 10
              kOhm resistor.  Now connect the (normally open) ON BATTERY relay
              of  the  UPS to the DCD line and the (normally open) LOW BATTERY
              relay to the CTS line.  Connect the RTS  line  to  the  SHUTDOWN
              input  on  the  UPS.   Connect  the return side of the relays to
              GROUND or TD as appropriate. Connect  the  return  side  of  the
              SHUTDOWN  signal  to  GROUND. For a more detailed description of
              cable  construction  and  pinouts,  see  the  README   file   in
              /usr/share/doc/upsd.

       3.     You’re  all  set.   It is also safe to use this setup with a UPS
              having open collector outputs, like  the  APC  SmartUPS  v/s  or
              Tripp Lite LAN 2.1 series, but be very careful to not exceed the
              current limit of the output transistors.  It is possible, though
              unlikely,  that you may need to increase the resistor values for
              some units.

FILES

       /etc/inittab
              Control file for init(8).

       /etc/powerstatus
              Power status file read by init(8) after  receiving  SIGPWR.  The
              file contents are as follows:

                        init action
                   OK   powerokwait
                   LOW  powerfailnow (Sysvinit 2.52 and up)
                   FAIL powerfail, powerwait

       /etc/upstatus
              UPS  status  file  read by upsd when invoked with the -r option.
              The file contents are as follows:

                   a:b message a:message b

              Where the a digit corresponds to the last  valid  status  and  b
              digit  corresponds  to  the  current  status.  The  text message
              correspond to the a and b digit status respectively.  The  codes
              and related messages are as follows:

                   0 Power = OK
                   1 On Battery
                   2 Lo Battery
                   3 No Connect
                   ? Don’t Know

              The  first digit and text is the last valid status used by upsd,
              and when invoked with the -r option it is  used  to  preset  the
              contents  of  upsd’s last valid status. Thus when upsd is killed
              and re-invoked by init when changing run levels, upsd  will  not
              generate  spurious SIGPWR signals and can determine if power has
              been restored in the event it was kill with power down  and  re-
              invoked   with   power  up.   The  second  digit  and  text  are
              informational for a human reader to show the most recent  status
              read from power information source.

       /tmp/upsds
              File read for status in dummy simulation mode.

CREDITS

       Miquel  van  Smoorenburg  developed  the  original  powerd program that
       inspired upsd.  Some of his words are still  in  this  man  page.   Jan
       Vilhuber’s  version  of  powerd  for  the APC Back-UPS contributed some
       ideas for the automatic power-down and network monitor features.

BUGS

       No way to specify the polarity of the SHUTDOWN signal (always goes high
       for   shutdown).   Could  probably  handle  connection  errors  better.
       There’s probably a standard for UPS monitoring on a network  somewhere,
       but if so I don’t know about it.

SEE ALSO

       shutdown(8), init(8), inittab(5).

AUTHOR

       Bob Hauck, bobh@wasatch.com

                                 May 12, 1998                          UPSD(8)