NUT (Network UPS Tools)

The NUT package can be useful if you have an UPS connected to the router. For example, you have multiple devices connected to the UPS (PC, NAS ...), but your router is the only device that runs 24/7 (or at least it runs most of the time). In this case you run NUT in netserver mode, where other devices connect to router to see UPS status and be able to shut down correctly if power fails. NUT must be installed on every machine using this feature.

NUT can be installed from packages feed.

NUT was updated with more UCI in commit a23c4e85, which appears in the 18.06 release.

NOTE: configuration has changed: It's now all done through UCI (see below) (and the UCI is changed).

There was a Pull Request (#936) for a LuCI app for the new configuration that sadly never made into 18.06, for complicated reasons that are non-technical, but is merged in a modified form into master.

There can be more than one of each section (as appropriate)

NB: From 18.06

The config section name (e.g. 'upsname' above) will be used a the ups name.

config override 'override_[variable_name]'

e.g. config override 'override_battery_charge_low' creates ups.conf entry for override.battery.charge.low =

config default 'default_[variable_name]'

e.g. config default 'default_battery_charge_low' creates ups.conf entry for default.battery.charge.low =

config override 'other_[parameter]'

e.g. config other 'other_parameter' creates ups.conf entry for parameter =

config override 'otherflag_[parameter]'

e.g. config override 'otherflag_extraflag' creates ups.conf entry for extraflag

NB From 18.06

There should only be on 'upsd' section and it should be named 'upsd'

#config driver 'upsname'
#	option driver usbhid-ups
#	option port auto
#	option other other-value
#	option runas root

#config user
#	option username upsuser
#	option password upspassword
#	option actions optional-action
#	list instcmd optional-instant-command
#	option upsmon slave|master

#config listen_address
#	option address ::1
#	option port 3493

#config upsd 'upsd'
#	option maxage 15
#	option statepath /var/run/nut
#	option maxconn 1024
# NB: certificates only apply to SSL-enabled version
#       option certfile /usr/local/etc/upsd.pem

config driver 'eaton5p'
  option driver usbhid-ups
  option port auto
  
config user
   option username upsuser
   option password somepassword
   option upsmon master
   # For a netserver, otherwise the default ::1 (localhost) is fine

config listen_address
   option 0.0.0.0

config upsd upsd

There should be only one upsmon section and should be named 'upsmon'

For each of (lowercased):

• COMOK
• COMBAD
• SHUTDOWN
• REPLBATTERY
• NOCOMMS
• NOPARENT
• ONLINE
• ONBATT
• LOWBATT
• FSD

There are 'XXXmsg' and 'XXXnotifyflag' options (e.g. 'comokmsg' and 'comoknotifyflag').

This are all optional. The 'msg' options are strings and are messages to emit instead of the default on one of the above conditions (see upsmon.conf man page (official)).

The 'notifyflag' options are boolean (default true) and indicate whether to emit the message using the 'defaultnotify' setting or to not emit a message (IGNORE) setting for that message.

From 'UPS TYPES' in upsmon manpage (official)

upsmon and upsd(8) don’t always run on the same system. When they do, any UPSes that are directly attached to the upsmon host should be monitored in “master” mode. This makes upsmon take charge of that equipment, and it will wait for slaves to disconnect before shutting down the local system. This allows the distant systems (monitoring over the network) to shut down cleanly before upsdrvctl shutdown runs and turns them all off.

When upsmon runs as a slave, it is relying on the distant system to tell it about the state of the UPS. When that UPS goes critical (on battery and low battery), it immediately invokes the local shutdown command. This needs to happen quickly. Once it disconnects from the distant upsd(8) server, the master upsmon will start its own shutdown process. Your slaves must all shut down before the master turns off the power or filesystem damage may result.

upsmon deals with slaves that get wedged, hang, or otherwise fail to disconnect from upsd(8) in a timely manner with the HOSTSYNC timer. During a shutdown situation, the master upsmon will give up after this interval and it will shut down anyway. This keeps the master from sitting there forever (which would endanger that host) if a slave should break somehow. This defaults to 15 seconds.

If your master system is shutting down too quickly, set the FINALDELAY interval to something greater than the default 15 seconds. Don’t set this too high, or your UPS battery may run out of power before the master upsmon process shuts down that system

#config upsmon 'upsmon'
#	option runas run-as-user
#	option minsupplies 1
#	option shutdowncmd /sbin/halt
#	option notifycmd /path/to/cmd
#	list defaultnotify SYSLOG
#	option pollfreq 5
#	option pollfreqalert 5
# 	option hostsync 15
#	option deadtime 15
#	option powerdownflags /var/run/killpower
#	option onlinemsg "online message"
#	option onbattmsg "on battery message"
#	option lowbattmsg "low battery message"
#	option fsdmsg "forced shutdown message"
#	option comokmsg "communications restored message"
#	option combadmsg "communications bad message"
#	option shutdowmsg "shutdown message"
#	option replbattmsg "replace battery message"
#	option nocommmsg "no communications message"
#	option noparentmsg "no parent message"
#	option onlinenotify "online notify flag 1|0"
#	option onbattnotify "on battery notify flag 1|0"
#	option lowbattnotify "low battery notify flag 1|0"
#	option fsdnotify "forced shutdown notify flag 1|0"
#	option comoknotify "communications restored notify flag 1|0"
#	option combadnotify "communications bad notify flag 1|0"
#	option shutdownotify "shutdown notify flag 1|0"
#	option replbattnotify "replace battery notify flag 1|0"
#	option nocommnotify "no communications notify flag 1|0"
#	option noparentnotify "no parent notify flag 1|0"
#	option rbwarntime 4200 # replace battery warn time
#	option nocommwarntime 300 # no communications warn time
#	option finaldelay 5 # final delay
#	option certpath /path/to/ca/dir
#	option certverify 0
#	option forcessl 0

#config master
#	option upsname upsname
#	option hostname localhost
#	option port # optional port number
#	option powervalue 1
#	option username upsuser
#	option password upspassword

#config slave
#	option upsname upsname
#	option hostname localhost
#	option port # optional port number
#	option powervalue 1
#	option username upsuser
#	option password upspassword

config 'upsmon' upsmon

config master
  option upsname eaton5p
  option hostname localhost
  option username upsuser
  option password somepassword

#config host
#	option upsname upsname
#	option hostname localhost
#	option port # optional port number
#	option displayname "Display Name"

config host
  option uspsname eaton5p
  option hostname localhost
  option displayname "Eaton 5P"

In older release(s) there's problem with some USB UPSes (e.g. EATON) that are not recognized by usbhid-ups. This is apparently a bug in libusb-compat, since libusb (0.1.4) can recognize them. You can work around this by installing Attitude Adjustment, manually installing packages libusb-compat and nut-driver-usbhid-ups, then manualy remove libusb-compat and install libusb istead (packages in trunk may break on having manually installed libusb)

You will want to have packages nut, nut-server and nut-client packages installed to have main functionality.

NOTE UCI configuration has changed for 18.06 (as of the commit above).

You may want to have nut-monitor installed, if you want to shutdown your router when UPS power goes critical and your device can turn itself off. Otherwise, the UPS will only provide information for you and clients.

NUT expects configuration by UCI, by putting the following into /etc/config/ups:

config driver 'eaton'
        option driver 'usbhid-ups'
        option port 'auto'

config user
        option username 'guest'
        option password 'guest'
        option upsmon 'slave'

For the NUT to run at all, you must change the MODE in /etc/nut/nut.conf to e.g. netserver:

MODE=netserver

If you want the upsd be acccessible from network (why otherwise would you want to run nut on router?), you must put a LISTEN directive to /etc/nut/upsd.conf:

LISTEN 0.0.0.0

You may want to change options according to the type of UPS you have and options you want to use.

After you installed and configured NUT, you may want to setup your router for monitoring UPS. You need to install nut-monitor package and add your config to /etc/config/upsmon

Sample upsmon config

config upsmon
        option 'shutdowncmd' '/lib/nut/upsdrvctl shutdown'
        option 'notifycmd' '/etc/nut/notify.sh'
        option 'onlinemsg' 'UPS %s on line power'
        option 'onbattmsg' 'UPS %s on battery'
        option 'lowbattmsg' 'UPS %s battery is low'
        option 'fsdmsg' 'UPS %s: forced shutdown in progress'
        option 'commokmsg' 'Communications with UPS %s established'
        option 'commbadmsg' 'Communications with UPS %s lost'
        option 'shutdownmsg' 'Auto logout and shutdown proceeding'
        option 'replbattmsg' 'UPS %s battery needs to be replaced'
        option 'nocommmsg' 'UPS %s is unavailable'
        option 'noparentmsg' 'upsmon parent process died - shutdown impossible'
        option 'onlinenotify' 'EXEC+SYSLOG'
        option 'onbattnotify' 'EXEC+SYSLOG'
        option 'lowbattnotify' 'EXEC+SYSLOG'
        option 'fsdnotify' 'EXEC+SYSLOG'
        option 'commoknotify' 'EXEC+SYSLOG'
        option 'commbadnotify' 'EXEC+SYSLOG'
        option 'shutdownnotify' 'EXEC+SYSLOG'
        option 'replbattnotify' 'EXEC+SYSLOG'
        option 'nocommnotify' 'EXEC+SYSLOG'
        option 'noparentnotify' 'EXEC+SYSLOG'
config master
        option 'upsname' 'UPS'
        option 'user' 'guest'
        option 'password' 'guest'

Upsmon will send to notifycmd script some environment strings:

$UPSNAME - will contain the name of UPS specified in /etc/config/ups
$NOTIFYTYPE - will contain the type string of whatever caused this event to happen.