UPSMON.CONF(5)

upsmon requires a UPS to provide status information every few seconds (see POLLFREQ and POLLFREQALERT) to keep things updated. If the status fetch fails, the UPS is marked stale. If it stays stale for more than DEADTIME seconds, the UPS is marked dead.

A dead UPS that was last known to be on battery is assumed to have changed to a low battery condition. This may force a shutdown if it is providing a critical amount of power to your system. This seems disruptive, but the alternative is barreling ahead into oblivion and crashing when you run out of power.

Note: DEADTIME should be a multiple of POLLFREQ and POLLFREQALERT. Otherwise, you’ll have "dead" UPSes simply because upsmon isn’t polling them quickly enough. Rule of thumb: take the larger of the two POLLFREQ values, and multiply by 3.

If you need to let your users do something in between those events, increase this number. Remember, at this point your UPS battery is almost depleted, so don’t make this too big.

Alternatively, you can set this very low so you don’t wait around when it’s time to shut down. Some UPSes don’t give much warning for low battery and will require a value of 0 here for a safe shutdown.

When a UPS goes critical (on battery + low battery, or "FSD": forced shutdown), the secondary systems are supposed to disconnect and shut down right away. The HOSTSYNC timer keeps the primary upsmon from sitting there forever if one of the secondaries gets stuck.

This value is also used to keep secondary systems from getting stuck if the primary fails to respond in time. After a UPS becomes critical, the secondary will wait up to HOSTSYNC seconds for the primary to set the FSD flag. If that timer expires, the secondary upsmon will assume that the primary (or communications path to it) is broken and will shut down anyway.

This keeps the secondaries from shutting down during a short-lived status change to "OB LB" and back that the secondaries see but the primary misses.

Large/expensive server type systems usually have more, and can run with a few missing. The HP NetServer LH4 can run with 2 out of 4, for example, so you’d set it to 2. The idea is to keep the box running as long as possible, right?

Obviously you have to put the redundant supplies on different UPS circuits for this to make sense! See big-servers.txt in the docs subdirectory for more information and ideas on how to use this feature.

Also see the section on "power values" in upsmon(8).

You must have at least one MONITOR directive in upsmon.conf.

A negative value means standard behavior (log on every loop, effectively same as when max=1), and a zero value means to never repeat the message (log only on start and end/change of the failure state).

Note that this throttle only applies to one latest-active error state per monitored device.

This command is called with the full text of the message as one argument. The environment string NOTIFYTYPE will contain the type string of whatever caused this event to happen.

If you need to use upssched(8), then you must make it your NOTIFYCMD by listing it here.

Note that this is only called for NOTIFY events that have EXEC set with NOTIFYFLAG. See NOTIFYFLAG below for more details.

Making this some sort of shell script might not be a bad idea. For more information and ideas, see docs/scheduling.txt

Remember, this command also needs to be one element in the configuration file, so if your command has spaces, then wrap it in quotes.

NOTIFYCMD "/path/to/script --foo --bar"

This script is run in the background—that is, upsmon forks before it calls out to start it. This means that your NOTIFYCMD may have multiple instances running simultaneously if a lot of stuff happens all at once. Keep this in mind when designing complicated notifiers.

Note that %s is replaced with the identifier of the UPS in question.

The message must be one element in the configuration file, so if it contains spaces, you must wrap it in quotes.

Possible values for type:

Examples:

Possible values for the flags:

There are some catches. First, if you set the POLLFREQ too high, you may miss short-lived power events entirely. You also risk triggering the DEADTIME (see above) if you use a very large number.

Second, there is a point of diminishing returns if you set it too low. While upsd normally has all of the data available to it instantly, most drivers only refresh the UPS status once every 2 seconds. Polling any more than that usually doesn’t get you the information any faster.

This should always be equal to or lower than the POLLFREQ value. By default it is also set 5 seconds.

The warnings from the POLLFREQ entry about too-high and too-low values also apply here.

Historically it was often /etc/killpower but nowadays you may want it in a temporary filesystem (e.g. under /run or /run/nut location).

Note that double backslashes must be used for Windows paths, e.g. C:\\Temp\\killpower (modern Windows may also accept forward slashes like C:/Temp/killpower but YMMV).

This is done to forcibly reset the secondary systems, so they don’t get stuck at the "halted" stage even if the power returns during the shutdown process. This usually does not work well on contact-closure UPSes that use the genericups driver.

See the config-notes.txt file in the docs subdirectory for more information. Refer to the section: "Configuring automatic shutdowns for low battery events", or refer to the online version.

A negative value means to disable decreasing the counter of working power supplies in such cases, and a zero makes the effect of detected "OFF" state immediate. Built-in default value is 30 (seconds), to put an "OFF" state into effect (decrease known-fed supplies count) if it persists for this many seconds.

A positive value puts "OB LB" state into effect only if it persists for this many seconds. A non-positive value makes the FSD effect of detected "OB LB" state immediate. Built-in default value is 0 (seconds).

If you need another value, set it here.

The catch is that "nobody" can’t read your upsmon.conf, since by default it is installed so that only root can open it. This means you won’t be able to reload the configuration file, since it will be unavailable.

The solution is to create a new user just for upsmon, then make it run as that user. I suggest "nutmon", but you can use anything that isn’t already taken on your system. Just create a regular user with no special privileges and an impossible password.

Then, tell upsmon to run as that user, and make upsmon.conf readable by it. Your reloads will work, and your config file will stay secure.

This file should not be writable by the upsmon user, as it would be possible to exploit a hole, change the SHUTDOWNCMD to something malicious, then wait for upsmon to be restarted.

When upsmon is a primary, it will allow any secondaries to log out before starting the local shutdown procedure.

Note that the command needs to be one element in the config file. If your shutdown command includes spaces, then put it in quotes to keep it together, i.e.:

Some "secondary" systems with workloads that take considerable time to stop (e.g. virtual machines or large databases) can benefit from reporting (by virtue of logging off the data server) that they are ready for the "primary" system to begin its own shutdown and eventually to tell the UPS to cut the power - not as soon as they have triggered their own shutdown, but at a later point (e.g. when the upsmon service is stopped AFTER the heavier workloads).

Note that the actual ability to complete such shutdown depends on the remaining battery run-time at the moment when UPS power state becomes considered critical and the shutdowns begin. You may also have to tune HOSTSYNC on the NUT primary to be long enough for those secondaries to stop their services. In practice, it may be worthwhile to investigate ways to trigger shutdowns earlier on these systems, e.g. by setting up upssched integration, or dummy-ups driver with overrides for stricter battery.charge or battery.runtime triggers than used by the rest of your servers.

This option supports Boolean-style strings (yes/on/true or no/off/false) or numbers to define a delay (in seconds) between calling SHUTDOWNCMD and exiting the daemon. Zero means immediate exit (default), negative values mean never exiting on its own accord.

Each entry maps server name with the expected certificate name and flags indicating if the server certificate is verified and if the connection must be secure.

Without this, there is no guarantee that the upsd is the right host. Enabling this greatly reduces the risk of man-in-the-middle attacks. This effectively forces the use of SSL, so don’t use this unless all of your upsd hosts are ready for SSL and have their certificates in order.

When compiled with NSS support of SSL, can be overridden for host specified with a CERTHOST directive.

If you don’t use CERTVERIFY 1, then this will at least make sure that nobody can sniff your sessions without a large effort. Setting this will make upsmon drop connections if the remote upsd doesn’t support SSL, so don’t use it unless all of them have it running.

When compiled with NSS support of SSL, can be overridden for host specified with a CERTHOST directive.