1. Nut installation
Here I use Ubuntu Server 22.04 system, the installation can be done directly with one apt command:
2. Nut service components
Before configuring Nut, we need to understand the components of Nut and their roles. Nut mainly contains three core services:
- nut-driver: This service is responsible for communicating with the UPS via a specific driver.
- nut-server: This service uses nut-dirver to communicate with the UPS and to publish the UPS status via web services.
- nut-monitor (nut-client): this service connects to the nut-server and provides specific responses based on the UPS status
Note: nut-client is actually a systemd softlink file, which is still essentially nut-monitor.
A simple diagram is drawn here to make it easier to understand:
3. Nut Basic Configuration
After Nut is installed, a configuration file is automatically created in the
/etc/nut directory, and the next configuration task is to adjust the various configuration files in this directory.
This configuration mainly defines the operation mode of nut, there is only one configuration field
MODE=xxxx, the optional values and meanings of this configuration are as follows:
none: Nut is not configured or uses an external system to start the Nut service, which can be interpreted as “do nothing”.
standalone: Standalone mode, usually used when there is only one UPS and only responsible for the local system (no network services).
netserver: similar to standalone mode, it starts driver, upsd and upsmon services, except that it can provide network services, and nut-monitor on other machines can connect to Nut Server via network.
netclient: client-only mode, only nut-monitor is started, used to connect to remote Nut services.
I’m using the full
netserver schema to facilitate subsequent extensions.
This configuration file defines how the nut-driver connects to the physical UPS, and has the following configuration format.
nutdev1 is the name of the UPS, you can define it as you like;
driver is used to define the driver to be used to connect to the UPS, normally it will be recognized if you use a USB connection like I wrote. If the same USB connection is not recognized, you can use the
nut-scanner command to scan the UPS, which will print out a sample UPS configuration in the console after a successful scan.
Note that if you want Synology or QNAP to be able to connect to the UPS over the network, there are special requirements for the name of the UPS (Synology must be named ups, QNAP has not been tested and may be called qnapups); because both systems are written to death, including the user name and password, which are explained below.
In addition to the USB connection to the UPS, the Nut also supports a variety of drivers to connect to the UPS, such as the APC-specific driver, please refer to the official documentation for details on how to connect the Nut.
This configuration file is used to control the network services of nut-server, such as listening port, maximum number of connections, certificate configuration, etc.; since I am using it on the intranet, I only need to configure the network listening, other parameters can be left as default.
For a complete overview of what configurations are supported, please refer to the official documentation: UPSD.CONF(5)
The upsd.users configuration file is used to define the username and password for connecting to the
nut-server over the network. The sample configuration is as follows.
[xxxx] above represents the user name, the password is specified by the
password field; there are also some special parameters:
actions: specifies which actions the user has access to, with optional values
SET(change UPS variables),
FSD(set UPS force shutdown flag); if you need both, you need to write
instcmds: Immediate command to start the user, the value
ALLmeans all, others can be seen by
upscmd -l; also if you want to specify more than one, you need to write
instcmdsmore than once.
upsmon: adds necessary actions to the upsmon process, optional values
secondary(not normally used)
Note: The version on Ubuntu Server 22.04 may not be as recent, and upsmon actually supports both master and slave parameters.
About Synology and QNAP users: If you expect both NAS to connect directly to Nut Server, you can confirm that Synology needs to ensure the existence of a user with the username monuser and password secret; QNAP I have not verified, but the result of online search is that you need to ensure the existence of a user with the username admin and password 123456.
4. Nut monitoring configuration
Compared with the basic configuration, Nut core processing is how to do a good job of monitoring configuration; Nut for monitoring policy support is roughly two kinds:
- Configured directly by
upsmon.conf, any events are directly handled by user-specified scripts, without advanced features such as timers.
- Configured directly by
- Configure the execution script as
upsmon.conf, any event will be handled by
upsschedfirst, with the help of upssched some advanced features can be implemented, such as selective trigger shutdown, etc.
- Configure the execution script as
This configuration is used to configure how the nut-monitor monitors the UPS and defines what actions are to be taken in the event of a UPS event. The core configuration is explained in detail below.
4.1.1. MONITOR command
MONITOR instruction is used to define the connection address of the UPS to be monitored, in the following format.
<system>: nut-server link address, formatted as “UPS name” + “@” + “nut-server address”, For example
<powervalue>: number of UPS, most of the time you only have one UPS, so just write 1
<username>/<password>: the username and password defined in
mastermeans the system will be shut down last, allowing the slave to shut down first;
slavemeans the system will be shut down immediately
Here is a sample of my configuration:
SHUTDOWNCMD command is used to define the shutdown command when the UPS is low on power or needs to be actively shut down. It is recommended to fill in the full path.
NOTIFYCMD command is a very important command that configures the commands that the
nut-monitor executes in case of a specific event (e.g. utility interruption, UPS low battery, etc.). Simply put,
NOTIFYCMD defines the specific command to be executed, where you can directly configure a script of your own, which will be called whenever an event occurs in the UPS.
There are two ways to configure the NOTIFYCMD command, one is to configure it as your own script, which requires executable permissions, and within the script you can get the event type from the NOTIFY environment variable and process it yourself. This is a bit of a “simple and brutal” approach, and the degree of customization depends on how your script is written. Please test the variables you can use, as the names of the environment variables may vary from version to version.
Another way is to configure NOTIFYCMD to execute the built-in upssched command; upssched is a Nut-provided scheduler with specific policies; in short, it’s an abstraction based on common functions, and upssched has its own individual configuration that allows for an advanced “no shutdown if utility power is restored within 180s”. upssched is an advanced scheduler with a specific policy; in short, it is an abstraction based on common functions.
Here I choose to use the second way, because I am not really good at writing scripts.
NOTIFYFLAG instruction is also a key configuration, and is used in conjunction with
NOTIFYFLAG instruction is responsible for specifying what actions should be triggered by a series of UPS events, the format of the instruction is as follows.
<notify type> indicates the event type, the following types are available:
ONLINE: The UPS is online, i.e. it will be triggered when the utility power is restored.
ONBATT: The UPS is on battery power, i.e. the event will be triggered when the utility power is interrupted.
LOWBATT: Triggered when the UPS is low on power
FSD: UPS is being shut down (Forced Shutdown)
COMMOK: Triggered when connection with nut-server is successfully established
COMMBAD: Triggered when connection with nut-server fails (connection lost)
SHUTDOWN: Triggered when UPS sends a shutdown command
REPLBATT: triggered when the UPS needs to replace the battery
NOCOMM: Triggered when the connection to the UPS cannot be established (UPS is not ready)
flag flag there are usually four types, which are linked by a plus sign (+) for multiple combinations:
SYSLOG: prints syslog only
WALL: pops up a message on the terminal (/bin/wall)
EXEC: Calls the command specified by
NOTIFYCMD, and passes the associated events
IGNORE: does nothing, ignores the event
If NOTIFYCMD uses custom scripts, please configure the events to be handled by the scripts according to your needs; if NOTIFYCMD is configured to use upssched, you can configure all events as EXEC, and then specifically filter them to be handled by upssched.
For example, if you only want the script configured by NOTIFYCMD to handle utility interrupt and recovery events, and to print syslog, you can configure it this way.
NOTIFYCMD is configured with
upssched, I pass all events to
4.1.5. Other configurations
In addition to the above core configuration, other configurations can be left as default if there are no special circumstances; for specific configurations, please refer to the official documentation: UPSMON.CONF(5)
This configuration assumes that the
NOTIFYCMD in the
upsmon.conf configuration points to
upssched, and that
EXEC for the event in question; the main purpose of this configuration is to use some of
upssched’s built-in high-level syntax to control how specific events are handled. The
upssched.conf configuration contains two main parts: the header options and the tail rules.
4.2.1. option configuration
The header options configuration contains only three configurations:
CMDSCRIPT: This configuration should be located on the first line (recommended, actually just before the AT command), this command is used to define the event handling script; the script is usually written by the user,
upsschedwill pass the specified parameters to this script and execute it according to the rules.
PIPEFN: pipeline file for inter-process communication, needs to be located before the AT instruction
LOCKFN: mutually exclusive lock file, used to prevent upsmon from scheduling multiple files at the same time, needs to be located before the AT instruction
For the CMDSCRIPT configuration script, here is a sample:
One thing to note is that the CMDSCRIPT configuration script is run as nut user by default, so you have to deal with the nut user permissions.
For PIPEFN and LOCKFN, the official recommendation is to create a separate directory called upssched and put the files in this directory; however, on some systems such as Ubuntu Server 22.04, /run/nut/ is tmpfs, and rebooting will cause directory loss and permission problems; so it is recommended to configure it directly without creating a separate directory.
4.2.2. rule configuration
The advantage of using
upssched is that there is a built-in rule engine, and we can configure complex rules with some simple syntax; the rule syntax of
upssched is as follows.
The rules start with
notifytype specifies the type of event to follow;
upsname specifies the name of the UPS, you can write
* if there is only one or you don’t want to distinguish;
command is used to specify the action to be performed, there are roughly three types of
START-TIMER: starts a timer
CANCEL-TIMER: cancels a timer
EXECUTE: Execute immediately
This part looks complex but is actually quite simple. For example, the following rule is implemented: when the utility is disconnected (when the UPS is powered by battery) a timer named onbattwarn is started, which after 180s executes the script defined by CMDSCRIPT and passes onbattwarn as the first parameter to the script; at the same time if the utility is restored within 180s of the timer (temporary flash-off), the script is the execution of the script is cancelled.
Of course, there are some events that need to be executed immediately, e.g., immediate notification of a utility outage.