--- name: "rc.upsd" section: "8" platform: "linux" package: "upsd" version: "2.5-3" release: "Debian 3.0 (Woody)" platforms: ["linux"] url: "https://new.carta.tech/upsd" --- # rc.upsd(8) Part of [upsd(8)](/upsd/8.md). ## 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)](/init/8.md), 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)](/syslog/2.md) 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)](/init/8.md). - **/etc/powerstatus** Power status file read by [init(8)](/init/8.md) 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)](/shutdown/8.md), [init(8)](/init/8.md), [inittab(5)](/inittab/5.md). ## AUTHOR Bob Hauck, bobh@wasatch.com