Support FAQ 337 | Custom shutdown script for when a monitored UPS reaches critical power levels

Custom shutdown script for when a monitored UPS reaches critical power levels

The Network UPS Tools (NUT) embedded in the console servers can be configured to manage local UPS and monitor remote UPS power devices. A Managed UPS is a local UPS that is connected to the console server by serial or USB cable, or it is SNMP/HTTP/HTTPS connected over the network (refer faq 301). A Remote UPS is remotely managed (by NUT running in a remote console server) and only monitored locally (refer faq 330). For both situations there is an optional checkbox which enables a custom shutdown script to run when power becomes critical for that UPS.

Check Enable Shutdown Script if in the event of a critical power failure (when the UPS battery runs out) you wish to perform any "last gasp" actions using the console server before power is lost.

Currently the default script that gets run is /etc/scripts/ups-shutdown, which looks as follows:

#!/bin/sh

# If there's a user-configured script, run it instead
script="/etc/config/scripts/$(basename $0)"
if [ -f "$script" ]; then
exec /bin/sh "$scripts" $@
fi

if [ -n "$1" ]; then
upsname=$(echo $1 | sed 's/$.*$@.*/\1/')
[ -z "$upsname" ] || upsdrvctl shutdown "$upsname"
fi

exit 0

This script first checks if a custom user script is available. It looks for the file /etc/config/scripts/ups-shutdown and runs it instead. If no such file exists, the script uses the NUT - UPS driver controller upsdrvctl to shutdown the UPS.

A single parameter is sent to this script when it is run. The parameter is in the form <upsname>@<hostname>. The variable $1 contains this value, and the variable $upsname contains only the <upsname> part. The command upsdrvctl can then be used to power down the specific UPS with name $upsname.

The easiest way to create your own custom shutdown script is to make a copy of the existing script and then add/edit it appropriately:

# mkdir /etc/config/scripts (if the folder does not already exist)
# cp /etc/scripts/ups-shutdown /etc/config/scripts/ups-shutdown
# vi /etc/config/scripts/ups-shutdown

Make sure you remove the first if statement from /etc/config/scripts/ups-shutdown. Otherwise the script will create an infinite loop. The code to remove looks as follows:

# If there's a user-configured script, run it instead
script="/etc/config/scripts/$(basename $0)"
if [ -f "$script" ]; then
exec /bin/sh "$script" $@
fi

Note: Only a Managed (local) UPS can be shutdown from the script. Remote UPS's cannot. See the file /etc/config/ups.conf. UPS entries in this file only exist if the UPS is local.

If a single server monitors more than one UPS, the script knows which UPS to run commands on due to the input parameter $1. This means that the script can also be ran manually at any time. For example if we have a local managed UPS with the name "myups", to run the script on this UPS type:
# /etc/scripts/ups-shutdown myups@localhost

"localhost" signifies that this UPS is a managed(local) device.

The final step is to add any additional scripting to the file, or edit the existing content. The main purpose of the script could then be to switch off an RPC outlet which could be powering a server (refer faq 331) or write a log message to a file or shutdown a server gracefully (before its UPS loses power!). Remember, only local UPS's can be shutdown using the upsdrvctl command, but you can still run other commands in the script for remote UPS's if you wish.