In this page I will describe how to install a NUT server on a router (Asus RT-AC56U) to manage an
UPS - we will use some Entware packages, so please
refer to this page on how to install Entware on a router.
We will use the "Network UPS Tools (NUT)" server (daemon), one of the most used servers
in Linux environments for managing an UPS. To install this server, we need to install several Entware packages, through the following instruction:
opkg install nut-common nut-server nut-upsc nut-upscmd nut-upslog nut-upsmon nut-upsrw nut-upssched nut-web-cgi Installing nut-common (2.7.4-19a) to root... Downloading http://bin.entware.net/armv7sf-k2.6/nut-common_2.7.4-19a_armv7-2.6.ipk Installing nut (2.7.4-19a) to root... Downloading http://bin.entware.net/armv7sf-k2.6/nut_2.7.4-19a_armv7-2.6.ipk Installing libnl-core (3.5.0-1) to root... Downloading http://bin.entware.net/armv7sf-k2.6/libnl-core_3.5.0-1_armv7-2.6.ipk Installing libnl-genl (3.5.0-1) to root... Downloading http://bin.entware.net/armv7sf-k2.6/libnl-genl_3.5.0-1_armv7-2.6.ipk Installing libnl-route (3.5.0-1) to root... Downloading http://bin.entware.net/armv7sf-k2.6/libnl-route_3.5.0-1_armv7-2.6.ipk Installing libnl-nf (3.5.0-1) to root... Downloading http://bin.entware.net/armv7sf-k2.6/libnl-nf_3.5.0-1_armv7-2.6.ipk Installing libnl (3.5.0-1) to root... Downloading http://bin.entware.net/armv7sf-k2.6/libnl_3.5.0-1_armv7-2.6.ipk Installing libpci (3.6.2-4) to root... Downloading http://bin.entware.net/armv7sf-k2.6/libpci_3.6.2-4_armv7-2.6.ipk Installing libnetsnmp (5.8-1) to root... Downloading http://bin.entware.net/armv7sf-k2.6/libnetsnmp_5.8-1_armv7-2.6.ipk Installing libusb-compat (0.1.5-2) to root... Downloading http://bin.entware.net/armv7sf-k2.6/libusb-compat_0.1.5-2_armv7-2.6.ipk Installing nut-server (2.7.4-19a) to root... Downloading http://bin.entware.net/armv7sf-k2.6/nut-server_2.7.4-19a_armv7-2.6.ipk Installing nut-upsc (2.7.4-19a) to root... Downloading http://bin.entware.net/armv7sf-k2.6/nut-upsc_2.7.4-19a_armv7-2.6.ipk Installing nut-upscmd (2.7.4-19a) to root... Downloading http://bin.entware.net/armv7sf-k2.6/nut-upscmd_2.7.4-19a_armv7-2.6.ipk Installing nut-upslog (2.7.4-19a) to root... Downloading http://bin.entware.net/armv7sf-k2.6/nut-upslog_2.7.4-19a_armv7-2.6.ipk Installing nut-upsmon (2.7.4-19a) to root... Downloading http://bin.entware.net/armv7sf-k2.6/nut-upsmon_2.7.4-19a_armv7-2.6.ipk Installing nut-upsrw (2.7.4-19a) to root... Downloading http://bin.entware.net/armv7sf-k2.6/nut-upsrw_2.7.4-19a_armv7-2.6.ipk Installing nut-upssched (2.7.4-19a) to root... Downloading http://bin.entware.net/armv7sf-k2.6/nut-upssched_2.7.4-19a_armv7-2.6.ipk Installing nut-web-cgi (2.7.4-19a) to root... Downloading http://bin.entware.net/armv7sf-k2.6/nut-web-cgi_2.7.4-19a_armv7-2.6.ipk Installing libwebp (1.0.3-2) to root... Downloading http://bin.entware.net/armv7sf-k2.6/libwebp_1.0.3-2_armv7-2.6.ipk Installing libfreetype (2.10.1-1) to root... Downloading http://bin.entware.net/armv7sf-k2.6/libfreetype_2.10.1-1_armv7-2.6.ipk Installing libgd (2.2.5-6) to root... Downloading http://bin.entware.net/armv7sf-k2.6/libgd_2.2.5-6_armv7-2.6.ipk Installing libtiff (4.1.0-1) to root... Downloading http://bin.entware.net/armv7sf-k2.6/libtiff_4.1.0-1_armv7-2.6.ipk Configuring libnl-core. Configuring libnl-route. Configuring libnl-nf. Configuring libpci. Configuring nut. Configuring libnl-genl. Configuring libnl. Configuring libnetsnmp. Configuring libusb-compat. Configuring nut-common. Configuring libwebp. Configuring libfreetype. Configuring libgd. Configuring libtiff. Configuring nut-web-cgi. Configuring nut-upslog. Configuring nut-upsmon. Configuring nut-upsrw. Configuring nut-upssched. Configuring nut-upscmd. Configuring nut-upsc. Configuring nut-server.
Then we have to install the proper driver, that is the software part that will manage our UPS. To choose the proper driver for our UPS, we have to go to the following page, and depending on the manufacturer ("Manufacturer" column) and model ("Model" column), we retrieve the name of the driver that we will have to use. For example, if our UPS is manufactured by APC, we go to the box labeled "Filters" and select the manufacturer "APC" in the "Manufacturer" field, the list below will be filtered to the APC manufacturer only. From there we can choose our model. Most APC models with USB interface are usbhid (USB Human Interface Device) type, as well as many other UPS. So the driver to choose is "usbhid-ups". Let's go back to the router terminal, and look for the driver, either with the "opkg list | grep -i nut-driver" instruction or directly with the "opkg list | grep -i usbhid-ups" instruction. In both cases we note that the driver to download is "nut-driver-usbhid-ups", so we use the "opkg install nut-driver-usbhid-ups" instruction to install the Entware package containing the driver.
Before managing the UPS driver, we need to configure the "/opt/etc/nut/ups.conf" file, with this configuration file we set the UPS
specifications. More information on the above-mentioned configuration file can be found at the
following Internet address.
An example of a "/opt/etc/nut/ups.conf" file is the following one:
[ups1]
driver = usbhid-ups
port = auto
pollinterval = 10
In the above-mentioned file, in the "driver" field we set the name of the "usbhid-ups" driver that we have chosen before for
our UPS. In the "port" field we will put the value "auto", while the "pollinterval" field indicates the value in seconds of interval for
refreshing the UPS data. The "ups1" group will be used by us later, with this name we indicate the first UPS that we manage.
If instead we want to manage two or more UPSes, we can create another section in the above-mentioned file "/opt/etc/nut/ups.conf", as follows:
[ups1]
driver = usbhid-ups
port = auto
pollinterval = 10
[ups2]
driver = usbhid-ups
port = auto
pollinterval = 10
Keep in mind that whenever we have to do with two or more UPSes, even more if these Groups are of the same brand and of the same model, it is better to specify in the file "/opt/etc/nut/ups.conf" the field "serial" (containing the serial number of the product) and the "desc" field (which provides a description of the product), in this way it will be possible to access all the UPSes specified in the above-mentioned file. So the above-mentioned file could become the following one:
[ups1]
driver = usbhid-ups
port = auto
pollinterval = 10
desc = "APC UPS 1"
serial = "ABCDEFGHIJ"
[ups2]
driver = usbhid-ups
port = auto
pollinterval = 10
desc = "APC UPS 2"
serial = "KLMNOPQRST"
The UPS serial number can be retrieved using one of the following methods:
Once the "/opt/etc/nut/ups.conf" file is configured, we can use the "upsdrvctl start" command to start the UPS(es) driver set
on the above-mentioned configuration file. If there are problems starting the drivers, we can run the "upsdrvctl -D start" command to get additional
debugging information. More information on the above-mentioned command can be found at the following Internet address.
The following is an example of the output of the "upsdrvctl start" command with two UPSes set in the above-mentioned configuration file:
Network UPS Tools - UPS driver controller merge-with-ng-626-gdbf3d603 Network UPS Tools - Generic HID driver 0.41 (merge-with-ng-626-gdbf3d603) USB communication driver 0.33 Using subdriver: APC HID 0.96 Network UPS Tools - Generic HID driver 0.41 (merge-with-ng-626-gdbf3d603) USB communication driver 0.33 Using subdriver: APC HID 0.96
After the above-mentioned command, we need to run the "upsd" command to start the daemon of NUT server. If there are problems
launching this command, we can run the "upsd -D" command to get additional debugging information. This command is not in "daemon"
mode, so after executing the command, we must press the keystroke "CTRL+C" to exit the execution mode. More information on the above-mentioned command can be
found at the following Internet address.
The following is an example of the output of the "upsd -D" command with two UPSes set in the above-mentioned configuration file:
Network UPS Tools upsd merge-with-ng-626-gdbf3d603 fopen /opt/var/run/upsd.pid: No such file or directory listening on 127.0.0.1 port 3493 listening on ::1 port 3493 Connected to UPS [ups2]: usbhid-ups-ups2 Connected to UPS [ups1]: usbhid-ups-ups1
If both the "upsdrvctl" and "upsd" commands have been successful, we can now start checking the UPS with the "upsc"
command which allows to view the data of each group inserted, in square brackets, in the above-mentioned configuration file - it is possible to have the list of
available groups using the "upsc -l" command. More information on the above-mentioned command can be found at the
following Internet address.
This is an example of output of the "upsc ups1" command:
battery.charge: 100 battery.charge.low: 10 battery.charge.warning: 50 battery.date: 2001/09/25 battery.mfr.date: 2016/10/05 battery.runtime: 1496 battery.runtime.low: 120 battery.type: PbAc battery.voltage: 27.3 battery.voltage.nominal: 24.0 device.mfr: American Power Conversion device.model: Back-UPS XS 1400U device.serial: ABCDEFGHIJ device.type: ups driver.name: usbhid-ups driver.parameter.pollfreq: 30 driver.parameter.pollinterval: 10 driver.parameter.port: auto driver.parameter.serial: ABCDEFGHIJ driver.parameter.synchronous: no driver.version: merge-with-ng-626-gdbf3d603 driver.version.data: APC HID 0.96 driver.version.internal: 0.41 input.sensitivity: medium input.transfer.high: 280 input.transfer.low: 155 input.voltage: 216.0 input.voltage.nominal: 230 ups.beeper.status: enabled ups.delay.shutdown: 20 ups.firmware: 926.T2 .I ups.firmware.aux: T2 ups.load: 24 ups.mfr: American Power Conversion ups.mfr.date: 2016/10/05 ups.model: Back-UPS XS 1400U ups.productid: 0002 ups.realpower.nominal: 700 ups.serial: ABCDEFGHIJ ups.status: OL ups.test.result: No test initiated ups.timer.reboot: 0 ups.timer.shutdown: -1 ups.vendorid: 051d
Then we can retrieve a list of the Hardware commands that can be executed on each UPS with the "upscmd" command, for example to
retrieve the commands of the first UPS we can use the "upscmd -l ups1" command. More information on the above command can be found at the
following Internet address.
Here is an example of the output of the above-mentioned command - the output shows that there are commands to disable/enable the beeper and to run several
UPS operative tests:
Instant commands supported on UPS [ups1]: beeper.disable - Disable the UPS beeper beeper.enable - Enable the UPS beeper beeper.mute - Temporarily mute the UPS beeper beeper.off - Obsolete (use beeper.disable or beeper.mute) beeper.on - Obsolete (use beeper.enable) load.off - Turn off the load immediately load.off.delay - Turn off the load with a delay (seconds) shutdown.reboot - Shut down the load briefly while rebooting the UPS shutdown.stop - Stop a shutdown in progress test.battery.start.deep - Start a deep battery test test.battery.start.quick - Start a quick battery test test.battery.stop - Stop the battery test test.panel.start - Start testing the UPS panel test.panel.stop - Stop a UPS panel test
Finally we can retrieve a list of the Hardware variables that can be set on each UPS with the "upsrw" command, for example to retrieve
a list of the variables of the first UPS we can use the "upsrw ups1" command. More information on the above command can be found at the
following Internet address.
Here is an example of the output of the above-mentioned command:
[battery.charge.low] Remaining battery level when UPS switches to LB (percent) Type: STRING Maximum length: 10 Value: 10 [battery.runtime.low] Remaining battery runtime when UPS switches to LB (seconds) Type: STRING Maximum length: 10 Value: 120 [input.sensitivity] Input power sensitivity Type: STRING Maximum length: 10 Value: medium [input.transfer.high] High voltage transfer point (V) Type: STRING Maximum length: 10 Value: 280 [input.transfer.low] Low voltage transfer point (V) Type: STRING Maximum length: 10 Value: 155 [ups.delay.shutdown] Interval to wait after shutdown with delay command (seconds) Type: STRING Maximum length: 10 Value: 20
To execute some Hardware commands with the "upscmd" command and to set some Hardware variables with the "upsrw" command it may be necessary to set a user with "root" privileges inside the configuration file "/opt/etc/nut/upsd.users" - an example of the above-mentioned file is the following one:
[admin]
password = [adminpassword]
actions = set
actions = fsd
instcmds = all
[monuser]
password = [password]
upsmon master
In the above-mentioned example we define an user called "admin" that we will have to pass through the "upscmd" and "upsrw" commands. As well as the user, we also set the password in the "password" field, while with the two "actions" lines we define the possibility of changing the UPS variables (using the "upsrw" command) and activating the "forced shutdown" mode , while with the "instcmds" line we let the user run any Hardware command on the UPS. The second "monuser" user will be used later with UPS monitoring. More information on the above configuration file can be found at the following Internet address.
Before managing the UPS monitoring, we must configure the "/opt/etc/nut/upsmon.conf" file, with this configuration file we set the
essential parameters for UPS monitoring. More information on the above-mentioned configuration file can be found at the
following Internet address.
An example of a "/opt/etc/nut/upsmon.conf" file is the following one:
SHUTDOWNCMD "/opt/etc/shutdown.sh" NOTIFYCMD "/opt/etc/upsmon.sh" NOTIFYFLAG ONLINE SYSLOG+WALL+EXEC NOTIFYFLAG ONBATT SYSLOG+WALL+EXEC NOTIFYFLAG LOWBATT SYSLOG+WALL+EXEC NOTIFYFLAG FSD SYSLOG+WALL+EXEC NOTIFYFLAG COMMOK SYSLOG+WALL+EXEC NOTIFYFLAG COMMBAD SYSLOG+WALL+EXEC NOTIFYFLAG SHUTDOWN SYSLOG+WALL+EXEC NOTIFYFLAG REPLBATT SYSLOG+WALL+EXEC NOTIFYFLAG NOCOMM SYSLOG+WALL+EXEC NOTIFYFLAG NOPARENT SYSLOG+WALL+EXEC MONITOR ups1@localhost 1 monuser [password] master MONITOR ups2@localhost 1 monuser [password] master
Now we define the script "/opt/etc/upsmon.sh", an example of the above-mentioned script follows - let's not forget to set the execution permissions of the script with the command "chmod +x /opt/etc/upsmon.sh":
#!/bin/sh now=$(date) OPTVARLOG="/opt/var/log/nutlog.log" # Keep only the last 5000 lines of log file sed -i -e :a -e '$q;N;5001,$D;ba' $OPTVARLOG echo $OPTVARLOG touch $OPTVARLOG echo "$now - $UPSNAME-$NOTIFYTYPE ($*)" >> $OPTVARLOG
The above-mentioned script will write the content of some environment variables (which we will see later) passed by the "UPSMON" daemon to a LOG file "/opt/var/log/nutlog.log", an example of output of this LOG file is the following one:
Fri Mar 13 17:06:21 CET 2020 - ups2@localhost-COMMBAD (Communications with UPS ups2@localhost lost) Fri Mar 13 17:06:21 CET 2020 - ups1@localhost-COMMBAD (Communications with UPS ups1@localhost lost) Fri Mar 13 17:07:31 CET 2020 - ups1@localhost-COMMOK (Communications with UPS ups1@localhost established) Fri Mar 13 17:07:36 CET 2020 - ups2@localhost-COMMOK (Communications with UPS ups2@localhost established)
The above-mentioned script uses the following environment variables:
Once we have the above-mentioned environment variables, we can for example notify the user of the event using a messaging service; for example we can send an email using the "msmtp" command - see this page for more information on how to send an email via router. So we can add the following example lines to the above-mentioned script:
msmtp -v -t << EOF From: [myemail]@hotmail.com Subject: Router - UPS event To: to_address@domain.xxx UPS Name : $UPSNAME Notify Type : $NOTIFYTYPE Notify Message : $* EOF
To create an UPS log, we need to use the "upslog" daemon. More information on the above command can be found at the
following Internet address.
For example we can run the following command inside the router terminal - with the following command we run the "upslog" daemon which creates a log file
"/opt/var/log/ups1.log" for the UPS "ups1", each row will be added every 60 seconds:
upslog -s ups1 -l /opt/var/log/ups1.log -i 60 Network UPS Tools upslog merge-with-ng-626-gdbf3d603 logging status of ups1 to /opt/var/log/ups1.log (60s intervals)
An example output of the log file "/opt/var/log/ups1.log", created with the above-mentioned command, is the following one:
20200313 171823 100 212.0 36 [OL] NA NA 20200313 171923 100 212.0 36 [OL] NA NA 20200313 172023 100 212.0 37 [OL] NA NA 20200313 172123 100 212.0 37 [OL] NA NA
To manage an UPS via the web, we must first use a web server, for convenience and easiness we will use a mini web server as an example, see
this page for more information on how to install a mini web server on a router.
Once the above-mentioned mini web server is installed, we will have two subfolders called "cgi-bin" and "nut" in the "/opt/share/www"
folder.
Since on the above-mentioned page we have configured the web server with the "nobody" user, we must remember to update the user of all
the files just copied with the "chown" command - see the above-mentioned web page for more information on how to use the "chown" command.
Once the two above-mentioned subfolders have been copied, we must configure the configuration file "/opt/etc/nut/hosts.conf". More information on the
above-mentioned configuration file can be found at the following Internet address.
We can add the following two lines to the above-mentioned configuration file - we consider that we have configured two UPSes:
MONITOR ups1@localhost "Local ups1" MONITOR ups2@localhost "Local ups2"
Now we can access the web page using the web address "http://[router address]:[port]/nut". Inside this web page we have two links: