Custom shut-down 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 a script is run when power becomes critical for that UPS. This script can be customized so, in the event of a critical power failure (when the UPS battery runs out) you can perform program the console server to perform "last gasp" actions using before power is lost! 

Note: With firmware 2.8.1 and later this script is always run, even when it's configured to do nothing (i.e. "Run until failure") so any custom script will still be run. Pre 2.8.1 you needed to select check Enable Shutdown Script on the Serial & Network: UPS Connection menu. 

Note: With firmware 3.5.1 and later it is simpler to perform "last gasp" actions by triggering Auto Response on the UPS hitting 'batt' or 'lowbatt'. 

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.