All configuration files within this package are parsed with a common state machine, which means they all can use a number of extras described here.

First, most of the programs use an uppercase word to declare a configuration directive. This may be something like MONITOR, NOTIFYCMD, or ACCESS. The case does matter here. "monitor" won’t be recognized.

Next, the parser does not care about whitespace between words. If you like to indent things with tabs or spaces, feel free to do it here.

If you need to set a value to something containing spaces, it has to be contained within "quotes" to keep the parser from splitting up the line. That is, you want to use something like this:

SHUTDOWNCMD "/sbin/shutdown -h +0"

Without the quotes, it would only see the first word on the line.

OK, so let’s say you really need to embed that kind of quote within your configuration directive for some reason. You can do that too.

NOTIFYCMD "/bin/notifyme -foo -bar \"hi there\" -baz"

In other words, \ can be used to escape the ".

Finally, for the situation where you need to put the \ character into your string, you just escape it.

NOTIFYCMD "/bin/notifyme c:\\dos\\style\\path"

The \ can actually be used to escape any character, but you only really need it for \, ", and # as they have special meanings to the parser.

When using file names with space characters, you may end up having tricky things since you need to write them inside "" which must be escaped:

NOTIFYCMD "\"c:\\path with space\\notifyme\" \"c:\\path with space\\name\""

# is the comment character. Anything after an unescaped # is ignored.

Something like this…

identity = my#1ups

will actually turn into identity = my, since the # stops the parsing. If you really need to have a # in your configuration, then escape it.

identity = my\#1ups

Much better.

The = character should be used with care too. There should be only one "simple" = character in a line: between the parameter name and its value. All other = characters should be either escaped or within "quotes".

password = 123=123

is incorrect. You should use:

password = 123\=123

or:

password = "123=123"

You can put a backslash at the end of the line to join it to the next one. This creates one virtual line that is composed of more than one physical line.

Also, if you leave the "" quote container open before a newline, it will keep scanning until it reaches another one. If you see bizarre behavior in your configuration files, check for an unintentional instance of quotes spanning multiple lines.

Create one section per UPS in ups.conf

To find out which driver to use, check the Hardware Compatibility List, or data/driver.list(.in) source file.

Once you have picked a driver, create a section for your UPS in ups.conf. You must supply values at least for "driver" and "port".

Some drivers may require other flags or settings. The "desc" value is optional, but is recommended to provide a better description of what useful load your UPS is feeding.

A typical device without any extra settings looks like this:

[mydevice]
        driver = mydriver
        port = /dev/ttyS1
        desc = "Workstation"

References: ups.conf(5), nutupsdrv(8), bcmxcp_usb(8), blazer(8), nutdrv_qx(8), richcomm_usb(8), riello_usb(8), tripplite_usb(8), usbhid-ups(8)

Generally, you can just start the driver(s) for your hardware (all sections defined in ups.conf) using the following command:

upsdrvctl start

Make sure the driver doesn’t report any errors. It should show a few details about the hardware and then enter the background. You should get back to the command prompt a few seconds later. For reference, a successful start of the usbhid-ups driver looks like this:

# upsdrvctl start
Network UPS Tools - Generic HID driver 0.34 (2.4.1)
USB communication driver 0.31
Using subdriver: MGE HID 1.12
Detected EATON - Ellipse MAX 1100 [ADKK22008]

If the driver doesn’t start cleanly, make sure you have picked the right one for your hardware. You might need to try other drivers by changing the "driver=" value in ups.conf.

Be sure to check the driver’s man page to see if it needs any extra settings in ups.conf to detect your hardware.

If it says can't bind /var/state/ups/... or similar, then your state path probably isn’t writable by the driver. Check the permissions and mode on that directory vs. the user account your driver starts as.

After making changes, try the Ownership and permissions step again.

On operating systems with init-scripts managing life-cycle of the operating environment, the upsdrvctl program is also commonly used in those scripts. It has a few downsides, such as that if the device was not accessible during OS startup and the driver connection timed out, it would remain not-started until an administrator (or some other script) "kicks" the driver to retry startup. Also, startup of the upsd data server daemon and its clients like upsmon is delayed until all the NUT drivers complete their startup (or time out trying).

This can be a big issue on systems which monitor multiple devices, such as big servers with multiple power sources, or administrative workstations which monitor a datacenter full of UPSes.

For this reason, NUT starting with version 2.8.0 supports startup of its drivers as independent instances of a nut-driver service under the Linux systemd and Solaris/illumos SMF service-management frameworks (corresponding files and scripts may be not pre-installed in packaging for other systems).

Such service instances have their own and independent life-cycle, including parallel driver start and stop processing, and retries of startup in case of failure as implemented by the service framework in the OS. The Linux systemd solution also includes a nut-driver.target as a checkpoint that all defined drivers have indeed started up (as well as being a singular way to enable or disable startup of drivers).

In both cases, a service named nut-driver-enumerator is registered, and when it is (re-)started it scans the currently defined device sections in ups.conf and the currently defined instances of nut-driver service, and brings them in sync (adding or removing service instances), and if there were changes — it restarts the corresponding drivers (via service instances) as well as the data server which only reads the list of sections at its startup. This helper service should be triggered whenever your system (re-)starts the nut-server service, so that it runs against an up-to-date list of NUT driver processes.

A service-oriented solution also allows to consider that different drivers have different dependencies — such as that networked drivers should begin startup after IP addresses have been assigned, while directly-connected devices might need nothing beside a mounted filesystem (or an activated USB stack service or device rule, in case of Linux). Likewise, systems administrators can define further local dependencies between services and their instances as needed on particular deployments.

This solution also adds the upsdrvsvcctl script to manage NUT drivers as system service instances, whose CLI mimics that of upsdrvctl program. One addition is the resync argument to trigger nut-driver-enumerator, another is a list argument to display current mappings of service instances to NUT driver sections. Also, original tool’s arguments such as the -u (user to run the driver as) or -D (debug of the driver) do not make sense in the service context — the accounts to use and other arguments to the driver process are part of service setup (and an administrator can manage it there).

Note that while this solution tries to register service instances with same names as NUT configuration sections for the devices, this can not always be possible due to constraints such as syntax supported by a particular service management framework. In this case, the enumerator falls back to MD5 hashes of such section names, and the upsdrvsvcctl script supports this to map the user-friendly NUT configuration section names to actual service names that it would manage.

References: man pages: nutupsdrv(8), upsdrvctl(8), upsdrvsvcctl(8)

Configure upsd, which serves data from the drivers to the clients.

First, edit upsd.conf to allow access to your client systems. By default, upsd will only listen to localhost port 3493/tcp. If you want to connect to it from other machines, you must specify each interface you want upsd to listen on for connections, optionally with a port number.

LISTEN 127.0.0.1 3493
LISTEN ::1 3493

Next, create upsd.users. For now, this can be an empty file. You can come back and add more to it later when it’s time to configure upsmon or run one of the management tools.

Do not make either file world-readable, since they both hold access control data and passwords. They just need to be readable by the user you created in the preparation process.

The suggested configuration is to chown it to root, chgrp it to the group you created, then make it readable by the group.

chown root:nut upsd.conf upsd.users
chmod 0640 upsd.conf upsd.users

References: man pages: upsd.conf(5), upsd.users(5), upsd(8)

Start the network data server:

upsd

Make sure it is able to connect to the driver(s) on your system. A successful run looks like this:

# upsd
Network UPS Tools upsd 2.4.1
listening on 127.0.0.1 port 3493
listening on ::1 port 3493
Connected to UPS [eaton]: usbhid-ups-eaton

upsd prints dots while it waits for the driver to respond. Your system may print more or less depending on how many drivers you have and how fast they are.

On operating systems with service management frameworks, the data server life-cycle is managed by nut-server service.

Reference: man page: upsd(8)

Edit your startup scripts, and make sure upsdrvctl and upsd are run every time your system starts. In newer versions of NUT, you may have a nut.conf file which sets the MODE variable for bundled init-scripts, to facilitate enabling of certain features in the specific end-user deployments.

If you installed from source, check the scripts directory for reference init-scripts, as well as systemd or SMF service methods and manifests.

When your UPS batteries get low, the operating system needs to be brought down cleanly. Also, the UPS load should be turned off so that all devices that are attached to it are forcibly rebooted, and subsequently start in the predictable order and state suitable for your data center.

Here are the steps that occur when a critical power event happens, for the simpler case of one UPS device feeding one or several systems:

Support for suspend to RAM and suspend to disk has been available in the Linux kernel for a while now. For obvious reasons, suspending to RAM isn’t particularly useful when the UPS battery is getting low, but suspend to disk may be an interesting concept.

This approach minimizes the amount of disruption which would be caused by an extended outage. The UPS goes on battery, then reaches low battery, and the system takes a snapshot of itself and halts. Then it is turned off and waits for the power to return.

Once the power is back, the system reboots, pulls the snapshot back in, and keeps going from there. If the user happened to be away when it happened, they may return and have no idea that their system actually shut down completely in the middle (although network connections will drop).

In order for this to work, you need to shutdown NUT (UPS driver, upsd server and upsmon client) in the suspend script and start them again in the resume script. Don’t try to keep them running. The upsd server will latch the FSD state (so it won’t be usable after resuming) and so will the upsmon client. Some drivers may work after resuming, but many don’t and some UPS devices will require re-initialization, so it’s best not to keep them running either.

After stopping NUT driver, server and client you’ll have to send the UPS the command to shutdown only if the POWERDOWNFLAG is present. Note that most likely you’ll have to allow for a grace period after calling upsdrvctl shutdown since the system will still have to take a snapshot of itself after that. Not all drivers and devices support this, so before going down this road, make sure that the one you’re using does.

If you run any sort of RAID equipment, make sure your arrays are either halted (if possible) or switched to "read-only" mode. Otherwise you may suffer a long resync once the system comes back up.

The kernel may not ever run its final shutdown procedure, so you must take care of all array shutdowns in userspace before upsdrvctl shutdown runs.

If you use software RAID (md) on Linux, get mdadm and try using mdadm --readonly to put your arrays in a safe state. This has to happen after your shutdown scripts have remounted the filesystems.

On hardware RAID or other kernels, you have to do some detective work. It may be necessary to contact the vendor or the author of your driver to find out how to put the array in a state where a power loss won’t leave it "dirty".

Our understanding is that most if not all RAID devices on Linux will be fine unless there are pending writes. Make sure your filesystems are remounted read-only and you should be covered.

For the examples in this section, we will use a server with four power supplies installed and locally running the full NUT stack, including upsmon in primary mode — as the UPS manager.

Two UPSes, Alpha and Beta, are each driving two of the power supplies (by adding up, we know about the four power supplies of the current system). This means that either Alpha or Beta can totally shut down and the server will be able to keep running.

The upsmon.conf configuration which reflects this is the following:

MONITOR ups-alpha@myhost 2 monuser mypass primary
MONITOR ups-beta@myhost  2 monuser mypass primary
MINSUPPLIES 2

With such configuration, upsmon on this system will only shut down when both UPS devices reach a critical (on battery + low battery) condition, since Alpha and Beta each provide the same power value.

As an added bonus, this means you can move a running server from one UPS to another (for maintenance purpose for example) without bringing it down since the minimum sufficient power will be provided at all times.

The MINSUPPLIES line tells upsmon that we need at least 2 power supplies to be receiving power from a good UPS (on line or on battery, just not on battery and low battery).

If you have multiple UPSes connected to your system, chances are that you need to shut them down in a specific order. The goal is to shut down everything but the one keeping upsmon alive at first, then you do that one last.

To set the order in which your UPSes receive the shutdown commands, define the sdorder value in your ups.conf device sections.

[bigone]
        driver = usbhid-ups
        port = auto
        sdorder = 2

[littleguy]
        driver = mge-shut
        port = /dev/ttyS0
        sdorder = 1

[misc]
        driver = blazer_ser
        port = /dev/ttyS1
        sdorder = 0

The order runs from 0 to the highest number available. So, for this configuration, the order of shutdowns would be misc, littleguy, and then bigone.

There are a lot of ways to handle redundancy and they all come down to how many power supplies, power cords and independent UPS connections you have. A system with a 1:1 cord:supply ratio has more wires stuffed behind it, but it’s much easier to move things around since any given UPS drives a smaller percentage of the overall power.

More information can be found in the NUT user manual, and the various user manual pages.