man upsd (Administration système) - upsd, rc.upsd -- UPS monitor daemon.

NAME

upsd, rc.upsd -- UPS monitor daemon.

SYNOPSIS

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.

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.

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

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

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.

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.

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

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