Provided by:
upsd_2.6-4.1_i386 
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 moni‐
tors 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 con‐
trolled 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 noti‐
fies 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 infor‐
mation 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 incorpo‐
rated since sysvinit-2.52 several years ago. Older versions of
init will default to powerfail if this option is turned on. Ver‐
sions 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 sig‐
nal, 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 stan‐
dalone 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 recov‐
ery on a READ ONLY file system such as software RAID, a slave or
master host using a UPS system without shutdown capability.
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 discon‐
nected (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 con‐
nections, 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 sta‐
tus.
102 UPS is on battery, the battery is low or was at last valid sta‐
tus.
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). Con‐
tinuously 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 speci‐
fied.
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 corre‐
spond 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 informa‐
tional 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 Vil‐
huber’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.
shutdown(8), init(8), inittab(5).
AUTHOR
Bob Hauck, bobh@wasatch.com
May 12, 1998 UPSD(8)