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 /usr/local/ups/etc/ups.conf

To find out which driver to use, check the Hardware Compatibility List, or data/driver.list.

Once you have picked a driver, create a section for your UPS in ups.conf. You must supply values 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 your UPS is supporting.

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), richcomm_usb(8), tripplite_usb(8), usbhid-ups(8)

Start the driver(s) for your hardware:

/usr/local/ups/sbin/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:

# /usr/local/ups/sbin/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.

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

References: man pages: nutupsdrv(8), upsdrvctl(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:

/usr/local/ups/sbin/upsd

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

# /usr/local/ups/sbin/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.

Reference: man page: upsd(8)

Edit your startup scripts, and make sure upsdrvctl and upsd are run every time your system starts.

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.

Here are the steps that occur when a critical power event happens:

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.

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 UPSs will require re-initialization, so it’s best not to keep this running either.

After stopping 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 sending upsdrvctl shutdown since the system will still have to take a snapshot of itself after that. Not all drivers 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 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.

Two UPS, Alpha and Beta, are each driving two of the power supplies. This means that either Alpha or Beta can totally shut down and the server will be able to keep running.

The upsmon.conf configuration that reflect this is the following:

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

With that configuration, upsmon will only shut down when both UPS reaches a critical (on battery + low battery) condition, since Alpha and Beta 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 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.

[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.