UPSMON.CONF(5)

NAME
upsmon.conf - Configuration for Network UPS Tools upsmon

DESCRIPTION
This file's primary job is to define the systems that upsmon(8) will monitor and to tell it how to shut down the system when necessary. It will contain passwords, so keep it secure. Ideally,only the upsmon process should be able to read it. Additionally, other optional configuration values can be set in this file.

CONFIGURATION DIRECTIVES

DEADTIME seconds
    upsmon allows a UPS to go missing for this many seconds before declaring it "dead". The default is 15 seconds. 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. Note 2: if you spend too much time in your NOTIFYCMD, you may cross the DEADTIME interval and trigger an unintended shutdown. If your NOTIFYCMD does anything lengthy that could get stuck, make it kick off a background process to avoid this problem.

FINALDELAY seconds
    When running in master mode, upsmon waits this long after sending the NOTIFY_SHUTDOWN to warn the users. After the timer elapses, it then runs your SHUTDOWNCMD. By default this is set to 15 seconds. 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.

HOSTSYNC seconds
    upsmon will wait up to this many seconds in master mode for the slaves to disconnect during a shutdown situation. By default, this is 15 seconds. When a UPS goes critical (on battery + low battery, or "FSD" - forced shutdown), the slaves are supposed to disconnect and shut down right away. The HOSTSYNC timer keeps the master upsmon from sitting there forever if one of the slaves gets stuck.

MINSUPPLIES num
    Set the number of power supplies that must be receiving power to keep this system running. Normal computers have just one power supply, so the default value of 1 is acceptable. 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).

MONITOR system powervalue password type
    Each UPS that you need to be monitor should have a MONITOR line. Not all of these need supply power to the system that is running upsmon. You may monitor other systems if you want to be able to send notifications about status changes on them. You must have at least one MONITOR directive in this file. system is a UPS identifier. It is in this form:
        [<upsname>@]<hostname>[:<port>] Some examples:
        "localhost" is the first UPS on the local system.
        "su700@mybox" is a UPS called "su700" ([su700] in ups.conf) on a system called "mybox".
        "elvis:1234" is the first UPS on a system called elvis, which is running upsd(8) on port 1234. To use all of the options together:
        "fenton@bigbox:5678" is a UPS called "fenton" on a system called "bigbox" which runs upsd(8) on port 5678. Phew! powervalue is an integer representing the number of power supplies that the UPS feeds on this system. Most normal computers have one power supply, and the UPS feeds it, so this value will be 1. You need a very large or special system to have anything higher here. You can set the powervalue to 0 if you want to monitor a UPS that doesn't actually supply power to this system. This is useful when you want to have upsmon do notifications about status changes on a UPS without shutting down when it goes critical. The password on this line must match the ACCESS definition in your upsd.conf(5). The type refers to the relationship with upsd(8). It can be either "master" or "slave". See upsmon(8) for more information on the meaning of these modes. Remember to grant either LOGIN or MASTER level to this host in your upsd.conf(8) depending on which type you choose here.

NOCOMMWARNTIME seconds
    upsmon will trigger a NOTIFY_NOCOMM after this many seconds if it can't reach any of the UPS entries in this configuration file. It keeps warning you until the situation is fixed. By default this is 300 seconds.

NOTIFYCMD command
    upsmon calls this to send messages when things happen. 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 pager.txt in the docs directory. Remember, this 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"

NOTIFYMSG type message
    upsmon comes with a set of stock messages for various events. You can change them if you like.
        NOTIFYMSG ONLINE "UPS %s is getting line power"
        NOTIFYMSG ONBATT "Someone pulled the plug on %s" Note that %s is replaced with the identifier of the UPS in question. Possible values for type:
        ONLINE - UPS is back online
        ONBATT - UPS is on battery
        LOWBATT - UPS is on battery and has a low battery (is critical)
        FSD - UPS is being shutdown by the master (FSD = "Forced Shutdown")
        COMMOK - Communications established with the UPS
        COMMBAD - Communications lost to the UPS
        SHUTDOWN - The system is being shutdown
        REPLBATT - The UPS battery is bad and needs to be replaced
        NOCOMM - A UPS is unavailable (can't be contacted for monitoring) The message must be one element in the configuration file, so if it contains spaces, you must wrap it in quotes.
        NOTIFYMSG NOCOMM "Someone stole UPS %s"

NOTIFYFLAG type flag[+flag][+flag]...
    By default, upsmon sends walls global messages to all logged in users) via /bin/wall and writes to the syslog when things happen. You can change this. Examples:
        NOTIFYFLAG ONLINE SYSLOG
        NOTIFYFLAG ONBATT SYSLOG+WALL+EXEC Possible values for the flags:
        SYSLOG - Write the message to the syslog
        WALL - Write the message to all users with /bin/wall
        EXEC - Execute NOTIFYCMD (see above) with the message
        IGNORE - Don't do anything If you use IGNORE, don't use any other flags on the same line.

POLLFREQ seconds
    Normally upsmon polls the upsd(8) server every 5 seconds. If this is flooding your network with activity, you can make it higher. You can also make it lower to get faster updates in some cases. 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.

POLLFREQALERT seconds
    This is the interval that upsmon waits between polls if any of its UPSes are on battery. You can use this along with POLLFREQ above to slow down polls during normal behavior, but get quicker updates when something bad happens. This should always be equal to or lower than the POLLFREQ value. By default it is also set 5 seconds. The catches about POLLFREQ about too-high and too-low values also apply here.

POWERDOWNFLAG filename
    upsmon creates this file when running in master mode when the UPS needs to be powered off. You should check for this file in your shutdown scripts and call the shutdown sequence (-k) in your UPS model driver if it exists. This is done to forcibly reset the slaves, so they don't get stuck at the "halted" stage even fi the power returns during the shutdown process. This usually does not work well on contact-closure UPSes that use the genericups driver. See the shutdown.txt file in the docs subdirectory for more information.

RBWARNTIME seconds
    When a UPS says that it needs to have its battery replaced, upsmon will generate a NOTIFY_REPLBATT event. By default this happens every 43200 seconds - 12 hours. If you need another value, set it here.

SHUTDOWNCMD command
    upsmon runs this command when the system needs to be brought down. If it is a slave, it will do that immediately whenever the current overall power value drops below the MINSUPPLIES value above. When upsmon is a master, it will allow any slaves 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.:
        SHUTDOWNCMD "/sbin/shutdown -h +0"

SEE ALSO
upsmon(8), upsd(8), nutupsdrv(8).

  Internet resources:
The NUT (Network UPS Tools) home page: http://www.exploits.org/nut/ The user mailing list: ups@lists.exploits.org