ntp.keys

title: ntp.keys(5)

summary: NTP symmetric key file format

text:
# ntp.keys(5)

## NAME
ntp.keys - NTP symmetric key file format configuration file

## SYNOPSIS
[--option-name] [--option-name value]

All arguments must be options.

## DESCRIPTION
This document describes the format of an NTP symmetric key file. For a description of the use of this type of file, see the "Authentication Support" section of the ntp.conf(5) page.

ntpd(8) reads its keys from a file specified using the -k command line option or the keys statement in the configuration file. While key number 0 is fixed by the NTP standard (as 56 zero bits) and may not be changed, one or more keys numbered between 1 and 65535 may be arbitrarily set in the keys file.

The key file uses the same comment conventions as the configuration file. Key entries use a fixed format of the form

keyno type key opt_IP_list

where keyno is a positive integer (between 1 and 65535), type is the message digest algorithm, key is the key itself, and opt_IP_list is an optional comma-separated list of IPs where the keyno should be trusted. that are allowed to serve time. Each IP in opt_IP_list may contain an optional /subnetbits specification which identifies the number of bits for the desired subnet of trust. If opt_IP_list is empty, any properly-authenticated message will be accepted.

The key may be given in a format controlled by the type field. The type MD5 is always supported. If ntpd was built with the OpenSSL library then any digest library supported by that library may be specified. However, if compliance with FIPS 140-2 is required the type must be either SHA or SHA1.

What follows are some key types, and corresponding formats:

MD5

The key is 1 to 16 printable characters terminated by an EOL, whitespace, or a # (which is the "start of comment" character).

SHA

SHA1

RMD160

The key is a hex-encoded ASCII string of 40 characters, which is truncated as necessary.

Note that the keys used by the ntpq(8) and ntpdc(8) programs are checked against passwords requested by the programs and entered by hand, so it is generally appropriate to specify these keys in ASCII format.

## FILES
/etc/ntp.keys

the default name of the configuration file

## SEE ALSO
ntp.conf(5), ntpd(1), ntpdate(1), ntpdc(1), sntp(1)

## AUTHORS
The University of Delaware and Network Time Foundation

## COPYRIGHT
Copyright (C) 1992-2024 The University of Delaware and Network Time Foundation all rights reserved. This program is released under the terms of the NTP license, <http://ntp.org/license>.

## BUGS
Please send bug reports to: https://bugs.ntp.org, bugs@ntp.org

## NOTES
This document was derived from FreeBSD.

This manual page was AutoGen-erated from the ntp.keys option definitions.


nut.conf

package: nut

title: nut.conf(5)

summary: UPS definitions for Network UPS Tools

text:
# nut.conf(5)

## NAME
nut.conf - UPS definitions for Network UPS Tools

## DESCRIPTION
This file attempts to standardize the various files being found in different installations, like /etc/default/nut on Debian based systems and /etc/sysconfig/ups on RedHat based systems.

An init (or service method) script provided by an OS distribution should source this file in order to determine which components have to be started; it may also be consulted by nutshutdown integration hook script and others.

Blank lines are ignored. Lines with a hash (#) character at the first position of the line are ignored, too. They can be used to add comments.

## IMPORTANT NOTES
•This file is intended to be sourced by shell scripts as well as by service management frameworks like systemd on Linux:

•There is no guaranteed export VAR=VAL syntax

•No guaranteed expansion of variables like VAR1="$VAR2-something" — only verbatim assignments

•You may need to export VAR when sourcing it into init-scripts or other scripts, for eventual propagation of certain settings to NUT programs. Not-exported variables can only be consumed by the script which "sourced" the file (and may choose to export them independently).

•You MUST NOT use spaces around the equal sign!

•Practical support for this file and its settings currently varies between different OS packages and NUT sample scripts, but should converge over time.

•Contents of this file should be pure ASCII (character codes not in range would be ignored with a warning message).

Refer to the EXAMPLE section for illustrations.

## DIRECTIVES
MODE

Required. Recognized values are none, standalone, netserver and netclient. Defaults to none. none

Indicates that NUT should not get started automatically, possibly because it is not configured or that an Integrated Power Management or some external system, is used to startup the NUT components.

standalone

Addresses a local only configuration, with 1 UPS protecting the local system. This implies to start the 3 NUT layers (driver, upsd and upsmon), with the related configuration files. This mode can also address UPS redundancy.

netserver

Like the standalone configuration, but also possibly need one or more specific LISTEN directive(s) in upsd.conf. Since this MODE is open to the network, a special care should be applied to security concerns.

netclient

When only upsmon is required, possibly because there are other hosts that are more closely attached to the UPS, the MODE should be set to netclient.

ALLOW_NO_DEVICE

Optional, defaults to false. Set this to true to allow starting the upsd NUT data server service even if ups.conf has no device sections configured at the moment. This environment variable overrides the built-in "false" flag value in the upsd program, and an optional same-named default flag that can be set in upsd.conf. If you want a data server always running and responding on the network, even if it initially has nothing to serve (may be live-reloaded later, when devices become configured), this option is for you.

ALLOW_NOT_ALL_LISTENERS

Optional, defaults to false. Set this to true to allow starting the upsd NUT data server even if not all LISTEN directives can be honoured at the moment. This environment variable overrides the built-in "false" flag in the upsd program, and an optional same-named default flag that can be set in upsd.conf. If you want a data server always running, even if it would potentially not serve all clients on every uptime, this option is for you (note you would have to restart upsd to pick up the `LISTEN`ed IP address if it appears later).

Probably configuring LISTEN * is a better choice in such cases.

UPSD_OPTIONS

Optional. Set upsd specific options. See upsd(8) for more details. It is ignored when MODE above indicates that no upsd should be running.

UPSMON_OPTIONS

Optional. Set upsmon specific options. See upsmon(8) for more details. It is ignored when MODE above indicates that no upsmon should be running.

POWEROFF_WAIT

Optional. At the end of an emergency system halt, the upsmon primary will signal the UPS to switch off. This may fail for a number of reasons. Most notably is the case that mains power returns during the shutdown process. See the section "Power races" in /usr/share/doc/nut/FAQ.txt.gz. The system will wait this long for the UPS to cut power, and then reboot. It should be long enough to exhaust the batteries, in case line power continues to be unavailable. On the other hand, it should not be so long that the system remains offline for an unreasonable amount of time if line power has returned. See sleep(1) for compatible time syntax. If you specify the time in seconds, use the "s" suffix.

Warning

This workaround might be dangerous under some circumstances. Please read http://bugs.debian.org/358696 for more details.

POWEROFF_QUIET

Optional, defaults to false. This setting controls if the NUT shutdown integration scripts or service units would emit messages about their activity (or lack thereof). By default they may be verbose, to aid in post-mortem troubleshooting via logs or console captures. Set to true to avoid that trove of information, if you consider it noise.

NUT_DEBUG_LEVEL

Optional, defaults to 0. This setting controls the default debugging message verbosity passed to NUT daemons. As an environment variable, its priority sits between that of DEBUG_MIN setting of a driver and the command-line options.

NUT_DEBUG_PID

Optionally add current process ID to tags with debug-level identifiers. This may be useful when many NUT daemons write to the same console or log file, such as in containers/plugins for Home Assistant, storage appliances...

NUT_DEBUG_PROCNAME

Optionally log process name (or however the program chose to identify itself). This may be useful when multiple NUT daemons log into the same file or console, without syslog to prefix the name into each line (e.g. in tests, single init script systems like Home Assistant, etc.)

NUT_DEBUG_SYSLOG

Optional, unset by default. Normally NUT can (attempt to) use the syslog or Event Log (WIN32), but the environment variable NUT_DEBUG_SYSLOG allows to bypass it, and perhaps keep the daemons logging to stderr (useful e.g. in NUT Integration Test suite to not pollute the OS logs, or in systemd where stderr and syslog both go into the same journal). Recognized values: Value

Description

stderr

Disabled and `background()` keeps `stderr` attached

```

```

none

Disabled and `background()` detaches `stderr` as usual

```

```

default

Not disabled

```

```

unset/other

Not disabled

```

```

NUT_IGNORE_CHECKPROCNAME

Optional, defaults to false. Normally NUT can (attempt to) verify that the program file name matches the name associated with a running process, when using PID files to send signals. The NUT_IGNORE_CHECKPROCNAME boolean toggle allows to quickly skip such verification, in case it causes problems (e.g. NUT programs were renamed and do not match built-in expectations).

This environment variable can also be optionally set in init-scripts or service methods for upsd, upsmon and NUT drivers/upsdrvctl.

NUT_QUIET_INIT_UPSNOTIFY

Optional flag to prevent daemons which can notify service management frameworks (such as systemd) about passing their lifecycle milestones, to not report loudly if they could NOT do so (e.g. running on a system without a framework, or misconfigured so they could not report and the OS could eventually restart the false-positively identified "unresponsive" service. Currently such reports, done by default, help troubleshoot service start-up and highlight that NUT sources (or package build) did not take advantage of tighter OS service management framework integration (if one exists, so that developers could focus on adding that). Reasons to set this flag could include platforms without such a framework and not expecting one, although nagging your favourite OS or contributing development to make it better is also a way.

## EXAMPLE

```
   # /etc/nut/nut.conf.  See nut.conf(5)

   MODE=none

   UPSD_OPTIONS=""

   UPSMON_OPTIONS=""

   # POWEROFF_WAIT=15m
```

## INTEGRATION
An init script, such as /etc/init.d/nut, is expected to source this file in order to determine which components have to be started.

## SEE ALSO
ups.conf(5), upsd.conf(5), upsd.users(5), upsmon.conf(5)

### Internet resources:
The NUT (Network UPS Tools) home page: https://www.networkupstools.org/historic/v2.8.5/


upsmon.conf

title: upsmon.conf(5)

text:
# upsmon.conf(5)

## NAME
upsmon.conf - Configuration for Network UPS Tools upsmon client

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

A minimal configuration should include at least one MONITOR instruction, MINSUPPLIES (may be 0 if this system is only monitoring other NUT servers), and a POWERDOWNFLAG if this machine is a "primary" system connected to the UPS and drives its late-shutdown power-off command in case of an emergency.

Additionally, other optional configuration values can be set in this file.

## IMPORTANT NOTES
•Contents of this file should be pure ASCII (character codes not in range would be ignored with a warning message).

•Balance the run-time user permissions to access the file (and perhaps the directory it is in) for only upsmon to be able to read it; write access is not needed. It is common to use chown root:nut and chmod 640 to set up acceptable file permissions.

•Packages (and build recipes) typically prepare one set of user and group accounts for NUT. Custom builds with minimal configuration might even use nobody:nogroup or similar, which is inherently insecure.

•On systems with extra security concerns, NUT drivers, data server, and any other monitoring, logging, etc. clients, should run as separate user accounts. This would need some daemons to use customized user, group, RUN_AS_USER and/or RUN_AS_GROUP settings to override the single built-in value.

•Keep in mind the security of also any backup copies of this file, e.g. the archive files it might end up in.

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

FINALDELAY seconds

When handling a forced shutdown (FSD) due to a critical UPS state or explicit user signal, upsmon waits this long after sending the NOTIFY_SHUTDOWN message to warn the users. After the timer elapses, it then runs your SHUTDOWNCMD. By default this is set to 5 seconds. If you need to let your users (or the NOTIFYCMD script) 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.

Note

If FINALDELAY on the secondary is greater than HOSTSYNC on the primary, the primary will give up waiting for that secondary upsmon to disconnect.

HOSTSYNC seconds

upsmon will wait up to this many seconds in primary mode for the secondaries 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 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.

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 username 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 upsmon.conf.

•system is a UPS identifier. It is in this form: <upsname>[@<hostname>[:<port>]]

The default hostname is "localhost". Some examples:

•"su700@mybox" means a UPS called "su700" on a system called "mybox". This is the normal form.

•"fenton@bigbox:5678" is a UPS called "fenton" on a system called "bigbox" which runs upsd(8) on port "5678".

•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 username and password on this line must match an entry in the upsd server system’s upsd.users(5) file. If your username is "observer" and your password is "abcd", the MONITOR line might look like this (likely on a remote secondary system):

```
MONITOR myups@bigserver 1 observer abcd secondary
```

Meanwhile, the upsd.users on bigserver would look like this:

```
[observer]

        password = abcd

        upsmon secondary
[upswired]

        password = blah

        upsmon primary
```

And the copy of upsmon on that bigserver would run with the primary configuration:

```
MONITOR myups@bigserver 1 upswired blah primary
```

•The type refers to the relationship with upsd(8). It can be either "primary" or "secondary". See upsmon(8) for more information on the meaning of these modes. The mode you pick here also goes in the upsd.users file, as seen in the example above.

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.

POLLFAIL_LOG_THROTTLE_MAX count

upsmon normally reports polling failures for each device that are in place for each POLLFREQ loop (e.g. "Data stale" or "Driver not connected") to system log as configured. If your devices are expected to be AWOL for an extended timeframe, you can use this throttle to reduce the stress on syslog traffic and storage, by posting these messages only once in every several loop cycles, and when the error condition has changed or cleared. 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.

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

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.

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"
```

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 primary (FSD = "Forced Shutdown")

COMMOK

Communications established with the UPS

COMMBAD

Communications lost to the UPS

SHUTDOWN

The system is being shutdown

SHUTDOWN_HOSTSYNC

This primary system began the shutdown, and is waiting for secondaries

REPLBATT

The UPS battery is bad and needs to be replaced

NOCOMM

A UPS is unavailable (can’t be contacted for monitoring)

NOPARENT

upsmon parent process died - shutdown impossible

CAL

UPS calibration in progress

NOTCAL

UPS calibration finished

OFF

UPS administratively OFF or asleep

NOTOFF

UPS no longer administratively OFF or asleep

BYPASS

UPS on bypass (powered, not protecting)

NOTBYPASS

UPS no longer on bypass

ECO

UPS in ECO or similar mode (as defined and named by vendor); for more details see upsmon(8).

NOTECO

UPS no longer in ECO mode (see above)

ALARM

UPS has one or more active alarms (check ups.alarm); for this notification, the message can contain a second %s placeholder to substitute the current value of ups.alarm.

NOTALARM

UPS is no longer in an alarm state (no active alarms)

OVER

UPS is overloaded

NOTOVER

UPS is no longer overloaded

TRIM

UPS is trimming incoming voltage

NOTTRIM

UPS is no longer trimming incoming voltage

BOOST

UPS is boosting incoming voltage

NOTBOOST

UPS is no longer boosting incoming voltage

OTHER

UPS has at least one unclassified ups.status token; for this notification, the message can contain a second %s placeholder to substitute the current collection of such tokens.

NOTOTHER

UPS has no unclassified status tokens anymore

SUSPEND_STARTING

OS is entering sleep/suspend/hibernate mode

SUSPEND_FINISHED

OS just finished sleep/suspend/hibernate mode, de-activating obsolete UPS readings to avoid an unfortunate shutdown

NOTIFYFLAG type 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. Except for Windows where upsmon only writes to the Event Log by default. 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.

Note

This setting is different from a pollfreq supported by some of the NUT driver programs, such as usbhid-ups(8) (about how often the driver polls a particular device).

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 warnings from the POLLFREQ entry about too-high and too-low values also apply here.

POWERDOWNFLAG filename

upsmon creates this file when running in primary mode when the UPS needs to be powered off. You should check for this file in your late shutdown scripts and call upsdrvctl shutdown if it exists; note that upsmon -K may be called for this effect, if NUT configuration files remain readable at that point (file systems mostly unmounted or changed to read-only). Historically it was often /etc/killpower but nowadays you may want it in a temporary filesystem (e.g. under (/var)/run or even a dedicated (/var)/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.

Warning

The upsmon binary program does not have a built-in default, so this setting MUST be specified in the configuration, in order for the late shutdown integration to work on the particular primary-mode system!

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.

OFFDURATION seconds

NUT supports an "administrative OFF" for power devices which can be managed to turn off their application workload, while the UPS or ePDU remains accessible for monitoring and management. This toggle allows to delay propagation of such state into a known loss of a feed (possibly triggering FSD on upsmon clients which MONITOR the device and are in fact still alive — e.g. with multiple power sources or because they as the load are not really turned off), because when some devices begin battery calibration, they report "OFF" for a few seconds and only then they might report "CAL" after switching all the power relays — thus causing false-positives for upsmon FSD trigger. 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.

Note

So far we support the device reporting an "OFF" state which usually means completely un-powering the load; a bug-tracker issue was logged to design similar support for just some manageable outlets or outlet groups.

OVERDURATION seconds

This setting handles how a UPS that is overloaded should be treated in situations when it is not fully communicating. Because such a UPS may be in a potentially severe state, some users may want their systems to be shutdown either immediately or after a set timeout has elapsed. The OVERDURATION setting defines this timeout (in seconds), after which an overloaded UPS that is not communicating will be considered critical. A negative value means an overloaded UPS will never be considered critical (at least not because of the overload itself). A value of zero means the UPS will instantly be considered critical when overloaded and not communicating. Built-in default value is -1 (seconds).

Note

This setting only affects the behavior when a UPS is both overloaded and not communicating. When the UPS is communicating normally, an overload condition may raise notifications but won’t trigger a system shutdown on its own.

OBLBDURATION seconds

NUT normally raises alarms for immediate shutdown (FSD) for consumers of an UPS known to be on battery ("OB") and achieving the low battery status ("LB"), if that is their last remaining power source to satisfy their MINSUPPLIES setting. In some special cases, users may want to delay raising the alarm (using the OBLBDURATION option) at their discretion and risk of an ungraceful shutdown. 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).

Note

If both OBLBDURATION and HOSTSYNC options are set on the same (secondary) upsmon client system, and HOSTSYNC is shorter, it would be effectively ignored: upsmon would wait for up to OBLBDURATION seconds for the "OB LB" state to clear, and then the secondary client logic would fall through to immediate shutdown. If the primary system issues an FSD on this UPS, that would take an even higher-priority effect as soon as seen.

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.

ALARMCRITICAL 0 | 1

NUT normally considers UPS with active alarms as volatile, meaning they are observed more closely and may be considered critical/dead earlier than in other regular UPS statuses. This is especially true for no-communication situations, where UPS in an ALARM status will be considered lost and system shutdowns may be triggered as a product. As there is no common standard for what constitutes an alarm, such alarm states may in fact be mundane in nature and the behavior above unwanted due to possibly resulting in unwarranted system shutdowns.

When this setting is disabled, upsmon will consider a UPS in an alarm state as not volatile and make it treat the ALARM status as any other.

RUN_AS_USER username

upsmon normally splits into two processes, keeping a small part which remains owned by root to initiate the system shutdown by calling SHUTDOWNCMD when/if the time comes, and runs the bulk of the monitoring duties under another user ID after dropping root privileges. On most custom-built systems this means it runs as "nobody", since that’s the default from compile-time; packages often deliver a "nut" or "ups" user to run NUT service daemons. The catch is that the system-default "nobody" can’t read your upsmon.conf file, since by default it is installed so that only root can open it (because this file can contain sensitive data like remote NUT data server credentials). This means you won’t be able to reload the configuration file, since it will be unavailable to the unprivileged part of the upsmon daemon.

The solution is to create a new user just for upsmon, then make it run as that user. It may be the same account as that used for the NUT drivers or data server, but does not have to be. On systems with higher concerns about security and privilege separation we 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. So typically you would also create a group for NUT daemons (which the user would be a member of) and allow that group read-only access to root-owned configuration files.

That said, other variants may be possible — e.g. run all of upsmon as a single process initially started and owned by nut and call a shutdown script prefixed by sudo, pfexec or other RBAC tools. This however adds more "moving parts" and fragility (e.g. the sudoers settings may live in LDAP, and that server could be unavailable at shutdown when the rack is half powered off, at just the time you need it here), and is not available on all platforms — so such setups are something users explore on their own so far (we would welcome posts on NUT Wiki or links to blogs though).

SHUTDOWNCMD command

upsmon runs this command when the system needs to be brought down. If it is a secondary, it will do that immediately whenever the current overall power value drops below the MINSUPPLIES value above. 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.:

```
SHUTDOWNCMD "/sbin/shutdown -h +0"
```

SHUTDOWNEXIT boolean|number

After initiating shutdown, should this upsmon daemon itself exit? By doing so NUT secondary systems can tell the NUT primary that it can proceed with its own shutdown and eventually tell the UPS to cut power for the load. ("Yes" by default) 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.

CERTPATH certificate file or database

When compiled with SSL support, you can enter the certificate path here. With NSS:

Certificates are stored in a dedicated database (data split in 3 files). Specify the path of the database directory.

With OpenSSL:

Directory containing CA certificates in PEM format, used to verify the server certificate presented by the upsd server. The files each contain one CA certificate. The files are looked up by the CA subject name hash value, which must hence be available.

CERTIDENT certificate name database password

When compiled with SSL support with NSS, you can specify the certificate name to retrieve from database to authenticate itself and the password required to access certificate related private key. Currently no-op when built with OpenSSL.

Note

Be sure to enclose "certificate name" in double-quotes if you are using a value with spaces in it.

CERTHOST hostname certificate name certverify forcessl

When compiled with SSL support with NSS, you can specify security directive for each server you can contact. 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.

Currently no-op when built with OpenSSL.

Note

Be sure to enclose "certificate name" in double-quotes if you are using a value with spaces in it.

CERTVERIFY 0 | 1

When compiled with SSL support, make upsmon verify all connections with certificates. 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.

FORCESSL 0 | 1

When compiled with SSL, specify that a secured connection must be used to communicate with upsd. 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.

DEBUG_MIN INTEGER

Optionally specify a minimum debug level for upsmon daemon, e.g. for troubleshooting a deployment, without impacting foreground or background running mode directly. Command-line option -D can only increase this verbosity level.

Note

If the running daemon receives a reload command, presence of the DEBUG_MIN NUMBER value in the configuration file can be used to tune debugging verbosity in the running service daemon (it is recommended to comment it away or set the minimum to explicit zero when done, to avoid huge journals and I/O system abuse). Keep in mind that for this run-time tuning, the DEBUG_MIN value present in reloaded configuration files is applied instantly and overrides any previously set value, from file or CLI options, regardless of older logging level being higher or lower than the newly found number; a missing (or commented away) value however does not change the previously active logging verbosity.

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

### Internet resources:
The NUT (Network UPS Tools) home page: https://www.networkupstools.org/historic/v2.8.5/


upssched.conf

title: upssched.conf(5)

text:
# upssched.conf(5)

## NAME
upssched.conf - Configuration for upssched timer program

## DESCRIPTION
This file controls the operations of upssched(8), the timer-based helper program for upsmon(8).

## IMPORTANT NOTES
•Contents of this file should be pure ASCII (character codes not in range would be ignored with a warning message).

•Command execution is synchronous (with the called tool process in case of EXECUTE directive, or with the timer process). Consider using your system shell abilities like & to send long-duration handling to the background and let upssched timer daemon continue. This should not impact upsmon daemon, which handles each notification in a separate sub-process (and so not a problem for immediate EXECUTE events).

## CONFIGURATION DIRECTIVES
DEBUG_MIN number

Optional. Specify minimal debugging level for upssched daemon or client, e.g. for troubleshooting a deployment without a need to edit consumer configuration. Note that command-line option -D can only increase this verbosity level.

Also note that the configuration file is processed line by line, so you may want to set this option early on.

Example:

```
DEBUG_MIN 6
```

CMDSCRIPT scriptname

Required. This must be above any AT lines. This script is used to invoke commands when your timers are triggered. It receives a single argument which is the name of the timer that caused it to trigger.

PIPEFN filename

Required. This sets the file name of the socket which will be used for interprocess communications. This should be in a directory where normal users can’t create the file, due to the possibility of symlinking and other evil.

Caution

If you are running Solaris or similar, the permissions that upssched sets on this file are not enough to keep you safe. If your OS ignores the permissions on a FIFO, then you MUST put this in a protected directory!

Note

By default, upsmon(8) will run upssched as whatever user you have defined with RUN_AS_USER; in upsmon.conf(5). Make sure that user can create files and write to files in the path you use for PIPEFN and LOCKFN.

My recommendation: create a special directory for upssched, make it owned by your upsmon user, then use it for both. The stock version of the upssched.conf ships with PIPEFN disabled to make you visit this portion of the documentation and think about how your system works before potentially opening a security hole.

LOCKFN filename

Required. upssched attempts to create this file in order to avoid a race condition when two events are dispatched from upsmon at nearly the same time. This file will only exist briefly. It must not be created by any other process. You should put this in the same directory as PIPEFN.

AT notifytype upsname command

Define a handler for a specific event notifytype on UPS upsname. upsname can be the special value * to apply this handler to every UPS. This will perform the command command when the notifytype and upsname match the current activity. Possible values for command are:

START-TIMER timername interval

Start a timer of interval seconds. When it triggers, it will pass the argument timername as an argument to your CMDSCRIPT. Each invocation starts an independent timer, even if the timername was already registered and started (note this can mess up subsequent CANCEL-TIMER operations). Example:

Start a timer that will execute when any UPS (*) has been gone for 10 seconds

```
AT COMMBAD * START-TIMER upsgone 10
```

START-TIMER-SHARED timername interval

Start a timer of interval seconds. When it triggers, it will pass the argument timername as an argument to your CMDSCRIPT. Each invocation checks if the timername was already started, and if so — appends the current event’s UPSNAME, NOTIFYTYPE and NOTIFYMSG to the list of unique values it would report via environment variables (as a comma-separated string for UPSNAME and NOTIFYTYPE, and tab-separated sentences for NOTIFYMSG) when the timer does execute.

Note

Currently this updates the first seen instance with the timername (in case you managed to start many).

Example: Start a timer that will execute when any UPS (*) has been gone for 10 seconds

```
AT COMMBAD * START-TIMER upsgone 10
```

CANCEL-TIMER timername [cmd]

Cancel a running timer called timername, if possible. If the timer has passed then pass the optional argument cmd to CMDSCRIPT.

Note

This removes the all seen instances with the timername (in case you managed to start many).

Example: If a specific UPS (myups@localhost) comes back online, then stop the timer before it triggers

```
AT COMMOK myups@localhost CANCEL-TIMER upsgone
```

CANCEL-TIMER-MATCHED timername [cmd]

Similar to the above, but tries to only cancel the timername if it refers to the UPSNAME and NOTIFYTYPE values passed by caller. The NOTIFYMSG is ignored in this context. Example:

If any UPS (*) reverts to utility power, then stop the timer before it triggers ONLY if that UPS is associated with the already scheduled timer:

```
AT ONLINE * CANCEL-TIMER-MATCHED onbattwarn
```

EXECUTE command

Immediately pass command as an argument to CMDSCRIPT. Example:

If any UPS (*) reverts to utility power, then execute ups-back-on-line via CMDSCRIPT.

```
AT ONLINE * EXECUTE ups-back-on-line
```

Note that any AT that matches both the notifytype and the upsname for the current event will be used.

For a complete list of notifytype possible values, refer to the section NOTIFY EVENTS in upsmon(8).

## SEE ALSO
upssched(8), upsmon(8)

### Internet resources:
The NUT (Network UPS Tools) home page: https://www.networkupstools.org/historic/v2.8.5/


hosts.conf

package: nut-cgi

title: hosts.conf(5)

text:
# hosts.conf(5)

## NAME
hosts.conf - Access control for Network UPS Tools CGI programs

## DESCRIPTION
The CGI programs (upsset.cgi(8), upsstats.cgi(8), upsimage.cgi(8)) use this file to determine if they are allowed to talk to a host. This keeps random visitors from using your web server to annoy others by creating outgoing connections.

## IMPORTANT NOTES
•Contents of this file should be pure ASCII (character codes not in range would be ignored with a warning message).

•This file does not contain passwords. Read-only monitoring in NUT is anonymous, and the upsset(8) program asks for credentials in the browser session when commanding a particular UPS (web-server should be secured, as reported to the program by upsset.conf(5) file).

## DIRECTIVES
MONITOR ups description

The ups element is in the form upsname[@hostname[:port]]. To allow connections to an UPS called "snoopy" on a system called "doghouse" that runs upsd on port 7877, it would look like this:

```
MONITOR snoopy@doghouse:7877 "Joe Cool"
```

The description must be one element, so if it has spaces, then it must be wrapped with quotes as shown above. The default hostname is "localhost".

CUSTOM_TEMPLATE_LIST filename, CUSTOM_TEMPLATE_SINGLE filename

upsstats(8) allows to use custom HTML template files for some of its outputs (JSON and "treemode" mark-ups are currently hard-coded in the binary), which you can specify in the query string part of the URI (in your index.html and/or added cells of header.html) as e.g.

```
.../cgi-bin/upsstats.cgi?template_single=custom-s.htm&template_list=custom-l.htm
```

+ Specific file names for a specific role must be permitted with these directives (can be repeated). File names must contain the .htm sub-string and must be located directly in the NUT configuration directory (same as default templates). If custom templates are used in the original request URI, they will be automatically suffixed to generated links (primarily HOSTLINK, but also just in case added to TREELINK and TREELINK_JSON, see upsstats.html(5) for more details).

## SEE ALSO
upsset.cgi(8), upsstats.cgi(8), upsimage.cgi(8)

### Internet resources:
The NUT (Network UPS Tools) home page: https://www.networkupstools.org/historic/v2.8.5/


upsset.conf

title: upsset.conf(5)

text:
# upsset.conf(5)

## NAME
upsset.conf - Configuration for Network UPS Tools upsset.cgi and general description of web server setup for NUT CGI programs

## DESCRIPTION
This file only does one job — it lets you convince upsset.cgi(8) that your system’s CGI directory is secure. The program will not run until this file has been properly defined.

Note If you custom-build NUT for Windows, keep in mind the --with-cgi-uri configuration option. It defaults to /cgi-bin/nut for POSIX builds and to plain /cgi-nut for Windows builds, to make them easier to integrate as part of existing web sites or as a dedicated web site, respectively. If there is a mismatch of this value for your particular deployment, check the html/header.html file to adjust the a href links to CGI programs to be opened in the bottom section (called target=mainFrame).

## IMPORTANT NOTES
•Contents of this file should be pure ASCII (character codes not in range would be ignored with a warning message).

## SECURITY REQUIREMENTS
upsset.cgi(8) allows you to try login name and password combinations. There is no rate limiting, as the program shuts down between every request. Such is the nature of CGI programs.

Credentials are provided to upsset.cgi as part of your browsing session, so it is highly recommended to set up HTTPS on the web server. You may also want to generally use web-server based authentication (whether basic user name and password, or LDAP, or client certificate, etc.), or set up virtual host listeners with unpublished host names ("security by obscurity"), to restrict access to NUT CGI programs generally. Ways to do so are specific to your chosen web server implementation and are beyond the scope of this document.

Normally, attackers would not be able to access your upsd(8) NUT data server directly, as it would be protected by the LISTEN directives in your upsd.conf(5) file, tcp-wrappers (if available when NUT was built), and hopefully local firewall settings in your OS.

upsset runs on your web server, so upsd will see it as a connection from a host on an internal network. It does not know that the connection is actually initiated by someone further outside. This is why you must secure it.

### Apache Web Server
On Apache, you can use the .htaccess file or put the directives in your httpd.conf. It looks something like this, assuming the .htaccess method for older Apache releases:

```
<Files upsset.cgi>

        deny from all

        allow from your.network.addresses
</Files>
```

You will probably have to set AllowOverride Limit for this directory in your server-level configuration file as well.

Modern Apache enjoys a more detailed syntax, like this:

```
ScriptAlias /upsstats.cgi /usr/share/nut/cgi/upsstats.cgi
ScriptAlias /upsset.cgi /usr/share/nut/cgi/upsset.cgi
<Directory "/usr/share/nut/cgi">

      Options +Includes +ExecCGI

      AllowOverride Limit

      <RequireAny>

          Require local

          Require ip aa.bb.cc.dd/nn

      </RequireAny>
</Directory>
```

### Microsoft IIS
With NUT for Windows builds, the Microsoft Internet Information Server (IIS) can be used as the platform’s native web server to host the NUT CGI programs.

Warning Like other aspects of NUT for Windows, this configuration should be considered experimental; feedback and pull requests to improve the code and documentation like this page are very welcome.

One aspect that may simplify or complicate things is that these builds aim to be relocatable, so the archive (eventually package) can be unpacked into any directory of the end-user’s choosing and "just work", and this relies on defaulting to use configuration and program location relative to the currently executed NUT program, rather than hard-coded paths as in POSIX builds tailored to a particular deployment or package.

The click-through setup below was verified on a Windows 10 workstation. Names and layering of referenced concepts are known to be different in other releases of the operating system. For more details see docs like https://learn.microsoft.com/en-us/iis/configuration/system.webserver/cgi or blogs like https://dotnetblog.asphostportal.com/5-steps-to-run-cgi-program-on-your-iis/

In Windows, open Control Panel and go to "Programs / Programs and Features", there to the "Turn Windows features on or off" section. Scroll down to the "Internet Information Services" and check its box to enable the default set of options (e.g. some services, some tools, no FTP). Then drill into its "World Wide Web Services / Application Development Features" and select "CGI" and "ISAPI Extensions". A reboot may be needed to install these.

Note The IIS Manager application needs to be restarted if you add features later (after you start it), otherwise they do not show up in the UI to be configured.

Open IIS Manager, check that the main panel includes icons for "CGI" and for "ISAPI and CGI Restrictions".

In IIS configuration, you can edit the Default Web Site or create a new one (would need a host name to be known either in DNS or at least via local %SystemRoot%\system32\drivers\etc\hosts file), and set the website root to the NUT installation location (the directory with etc and cgi-bin subdirectories, among other things).

Note It may be more secure to copy the cgi-bin and html subdirectories into a separate location (e.g. under c:\inetpub\wwwroot or the non-default website root), and then either populate a dedicated etc directory with configuration files and templates for the CGI programs, or somehow export NUT_CONFPATH environment variable from the web server to point to a location not "near" the executable programs. Alternately, explore using an empty root and "virtual directories" in IIS to reference just the cgi-bin and html in the NUT installation location — and so minimize exposure of any other files.

Once you have a web-site defined one way or another, select its root in the "Connections" panel, and double-click the "ISAPI and CGI Restrictions" icon. There "Actions / Add" and specify full paths (3 times overall) to the upsimage.cgi.exe, upsset.cgi.exe and upsstats.cgi.exe programs, all with the checkbox to "Allow extension path to execute".

Revise "Handler Mappings" for the cgi-bin subdirectory, that it includes "CGI-exe" with "Path *.exe" and "State Enabled" (if not, edit the entry, press "Request Restrictions", and tick "Access/Execute" there).

If the (virtual) server is dedicated to NUT CGI programs, you may also want to visit the "CGI" icon, and change Behavior/Timeout to a few minutes or even seconds (and Apply the change), so in case of any breakage in the NUT CGI programs, you would not stare at a blank page and not know if the server is alive. The IIS default is 15 minutes.

•You may want to allow for a series of NUT upscli_tryconnect() timeouts (10 seconds each, by default), however, e.g. to get the error messages when NUT data servers are down. While there may be one connection for each run of upsset or upsimage CGI clients, there may be more for upsstats depending on the number of devices you MONITOR in hosts.conf(5).

•This recommendation may change later if support for "tracking" of device-side completion of posted commands or settings would be implemented; currently the upsset(8) CGI client only gets and relays confirmation that the NUT data server upsd(8) received the request.

In the NUT configuration directory, update the hosts.conf(5) and upsset.conf files as appropriate, (optionally adapt) and rename the upsstats.html.sample and upsstates-single.html.sample files to not include the .sample extension.

Finally, assuming default website configuration, go to http://localhost/html/ and you should be served with a two-panel page, with a NUT banner and links to the two tools on top, and tables of data in the bottom. If you have device monitoring set up already, check the details pages: if they do not render, make sure the upsstats.html and upsstats-single.html files define UPSSTATSPATH and UPSIMAGEPATH program URI names with the .exe extension.

### Completing the CGI setup
If this doesn’t make sense, then stop reading and leave this program alone. It’s not something you absolutely need to have anyway.

Assuming you have all the above steps done, and it actually works (test it!), congratulations — you have a read-only web server to report information from NUT in a convenient form.

If you further want to manage the devices (and again, if you did set up appropriate security constraints), then you may add the following directive to this file and so unlock the potentially dangerous access through the server:

```
I_HAVE_SECURED_MY_CGI_DIRECTORY
```

If you lie to the program and someone beats on your upsd through your web server, don’t blame me.

## SEE ALSO
upsset.cgi(8)

### Internet resources:
The NUT (Network UPS Tools) home page: https://www.networkupstools.org/historic/v2.8.5/


upsstats.html

title: upsstats.html(5)

summary: HTML template for web\-based Network UPS Tools upsstats

text:
# upsstats.html(5)

## NAME
upsstats.html - HTML template for web-based Network UPS Tools upsstats

## DESCRIPTION
This file, and a similarly structured upsstats-single.html for certain use-cases, are used by upsstats.cgi(8) to generate NUT CGI status pages. Certain commands are recognized, and will be replaced with various status elements on the fly.

As a bit of a safety check, the file must start with @NUT_UPSSTATS_TEMPLATE@ command.

For details about configuring some popular web servers to run NUT CGI programs, please see the upsset.conf(5) page.

Note This template file should be placed in the NUT configuration location. If you use a dedicated copy of that directory or one not discovered by the binaries relocated into your web server’s cgi-bin locations (such as with NUT for Windows builds, defaulting to seek in locations relative to each binary), consider exporting the NUT_CONFPATH environment variable from the web server.

Note On platforms with required program file name extensions, like Windows, you may have to use e.g. a *.cgi.exe extension for the programs in HTML template files (UPSSTATSPATH, UPSIMAGEPATH).

## FORMATTING
Commands can be placed anywhere on a line, but must start and end with @.

Any extra characters before or after the commands will be passed through unchanged.

It is allowed to use more than one command on a single line, as long as each command has its own start and end character.

If you need to use the @ sign, use HTML entity @ to prevent it from being treated as a start character.

## BLOCK CONTROL
Some commands begin blocks — sections of the template that will be included, excluded, or repeated depending on certain parameters.

### BLOCK CONTROL - ITERATION
@FOREACHUPS@

Starts a block that will be repeated for each MONITOR directive in the hosts.conf(5). This is how you can generate pages that monitor all of your systems simultaneously.

@ENDFOR@

Ends a FOREACHUPS block.

### BLOCK CONTROL - MATCHING SPECIFIC CASES
@IFSUPP var@*

Starts a block that will only be printed if the variable var is supported by the current UPS. This is generally used to suppress "not supported" messages by avoiding the label and variable call entirely.

@IFEQ var value@

Starts a block if the value returned from the variable var matches value.

Note

You can use @IFEQ upsstats.use_celsius (0|1)@ to check for the current setting of @TEMPC@ or @TEMPF@ toggle.

@IFBETWEEN varlow varhigh varvalue@

Starts a block if the value returned by the variable varvalue is between the values returned by the variables varlow and varhigh.

@ELSE@

If the previous IF-command did not match, perform this instead.

@ENDIF@

Ends an IF/ELSE-block.

### BLOCK CONTROL - ADVANCED EXPRESSIONS
Even though the parser is pretty limited, it’s still possible to create rather advanced expressions. The key to this is the fact that multiple block control commands are AND:ed. This is illustrated with an example (more examples are available in upsstats.html).

```
@IFSUPP ambient.humidity@
@IFSUPP ambient.temperature@
This UPS knows both ambient temperature and humidity.
@ELSE@
@IFSUPP ambient.humidity@
This UPS only knows ambient humidity.
@ELSE@
@IFSUPP ambient.temperature@
This UPS only knows ambient temperature.
@ELSE@
This UPS knows nothing, how annoying.
@ENDIF@
```

## OTHER COMMANDS
@NUT_UPSSTATS_TEMPLATE [args]@

The template file MUST start exactly with @NUT_UPSSTATS_TEMPLATE@ or @NUT_UPSSTATS_TEMPLATE Some text@ so that upsstats.cgi(8) is not coerced into showing arbitrary files. Currently the command and its arguments are otherwise ignored; templates shipped with NUT use the argument values "default" and "single" effectively as a comment for debugging/troubleshooting.

@UPSSTATSPATH filename@

URI to the upsstats.cgi(8) program placed into HTML references. Default is the program’s name, making it a link relative to the currently displayed page in the browser. May have to include the platform-specific program file name extension, like @UPSSTATSPATH upsstats.cgi.exe@

@UPSIMAGEPATH filename@

URI to the upsimage.cgi(8) program placed into HTML references. Default is the program’s name, making it a link relative to the currently displayed page in the browser. May have to include the platform-specific program file name extension, like @UPSIMAGEPATH upsimage.cgi.exe@

@AMBTEMP@

Insert the ambient temperature in the current temperature scale.

@DATE format@

Insert the current date and time. The format string is passed to strftime, so almost anything is possible. See strftime(3) for possible values.

@DEGREES@

Insert the entity for degrees (°) and either C or F depending on the current temperature scale.

@HOST@

Insert the designation of the host being monitored, like myups@localhost.

@HOSTDESC@

Insert the host’s description from hosts.conf(5).

@HOSTLINK@

Insert a HTML link to upsstats.cgi(8) with the "host" variable set to the current UPS. This is only useful within a FOREACHUPS block.

@TREELINK [Link text]@

Insert a HTML link to upsstats.cgi(8) with the "host" variable set to the current UPS and "treemode" enabled to show all data points as an HTML page. This is primarily useful within a FOREACHUPS block, but also as an upsstats-single.html footer. If some "Link text" is not provided, it defaults to "All data".

@TREELINK_JSON [Link text]@

Insert a HTML link to upsstats.cgi(8) with the "host" variable set to the current UPS and "treemode" enabled to show all data points as a JSON document. This is primarily useful within a FOREACHUPS block, but also as an upsstats-single.html footer. If some "Link text" is not provided, it defaults to "JSON".

@IMG varname @

Insert an IMG SRC to upsimage.cgi(8) for one of these status variables: battery.charge

Battery charge — a percentage

battery.voltage

The charge on the battery in volts

input.frequency

Incoming utility frequency (Hz)

input.voltage

Incoming utility voltage

input.L1-L2.voltage

Incoming voltage, L1-L2 (3phase)

input.L2-L3.voltage

Incoming voltage, L2-L3 (3phase)

input.L3-L1.voltage

Incoming voltage, L3-L1 (3phase)

output.frequency

Outgoing utility frequency (Hz)

output.voltage

Outgoing voltage (from the UPS)

output.L1-L2.voltage

Outgoing voltage, L1-L2 (3phase)

output.L2-L3.voltage

Outgoing voltage, L2-L3 (3phase)

output.L3-L1.voltage

Outgoing voltage, L3-L1 (3phase)

output.L1.power.percent

UPS load, L1 (3phase)

output.L2.power.percent

UPS load, L2 (3phase)

output.L3.power.percent

UPS load, L3 (3phase)

ups.load

UPS load — percentage

ups.temperature

UPS temperature

extra is where you can put additional definitions. Right now the valid definitions are colors for various parts of the bars drawn by upsimage.cgi(8). Possible color names are:

back_col

background color

scale_num_col

scale number color

summary_col

summary color (number at the bottom)

ok_zone_maj_col

major scale color for the normal ("ok") zone

ok_zone_min_col

minor scale color for the normal ("ok") zone

neutral_zone_maj_col

major scale color for the neutral zone

neutral_zone_min_col

minor scale color for the neutral zone

warn_zone_maj_col

major scale color for the warning zone

warn_zone_min_col

minor scale color for the warning zone

bar_col

the color of the bar in the middle

All colors are hex triplets — e.g. 0xff0000 is red, 0x00ff00 is green, and 0x0000ff is blue.

Examples:

```
@IMG battery.charge@
@IMG battery.charge back_col=0xff00ff bar_col=0xaabbcc@
@IMG input.voltage ok_zone_maj_col=0x123456@
```

@REFRESH@

Insert the META header magic for refreshing the page if that variable has been set by the browser. This needs to be in the HEAD section of the page.

@STATUS separator@, @STATUS@

Expand the abbreviations in the ups.status variable — OL becomes "On line", OB becomes "On battery", and so on. Reported values are separated by the specified optional separator (<br/> if not specified), which starts at the next character after the "STATUS<space>" (e.g. a @STATUS @ directive might be used to avoid any separation, or @STATUS @ to separate by spaces.

@STATUSCOLOR@

Insert red, green, or yellow color triplets depending on the severity of the current UPS status. Normal operations are green, warnings like voltage trim/boost or "off" are yellow, and other events like being on battery or having a low battery are red.

@VAR varname@

Insert the current value of the status variable varname on the host being monitored, or "Not supported".

@RUNTIME@

Inserts the current runtime, in hh:mm:ss format.

@TEMPC@

Use the Celsius scale for temperature data (default).

@TEMPF@

Use the Fahrenheit scale for temperature data.

@UPSTEMP@

Insert the UPS temperature in the current scale.

@BATTTEMP@

Insert the battery temperature in the current scale.

@UTILITYCOLOR@

Obsoleted. Use IFBETWEEN instead (see example in upsstats.html).

@VERSION@

Insert the version number of the software.

## OTHER TEMPLATES
upsstats.cgi(8) will also open a file called upsstats-single.html if you call it with host= set in the query URL. That file uses the same rules and techniques as documented here.

## SEE ALSO
upsstats.cgi(8), upsimage.cgi(8)

### Internet resources:
The NUT (Network UPS Tools) home page: https://www.networkupstools.org/historic/v2.8.5/


ups.conf

package: nut-server

title: ups.conf(5)

summary: UPS definitions for Network UPS Tools

text:
# ups.conf(5)

## NAME
ups.conf - UPS definitions for Network UPS Tools

## DESCRIPTION
This file is read by the driver controller upsdrvctl(8), the UPS drivers which use the common core (see nutupsdrv(8)), nut-driver-enumerator(8), and the NUT data server upsd(8). The file begins with global directives, and then each UPS has a section which contains a number of directives that set parameters for that UPS.

A UPS section begins with the name of the UPS in brackets, and continues until the next UPS name in brackets or until EOF. The name "default" is used internally in upsd(8), so you can’t use it in this file.

You must define the driver and port elements for each entry. Anything after that in a section is optional. A simple example might look like this:

```
[myups]

        driver = blazer_ser

        port = /dev/ttyS0

        desc = "Web server UPS"
```

A slightly more complicated version includes some extras for the hardware-specific part of the driver:

```
[bigups]

        driver = apcsmart

        port = /dev/cua00

        cable = 940-0095B

        sdtype = 2

        desc = "Database server UPS"
```

In this case, the apcsmart(8) driver will receive variables called "cable" and "sdtype" which have special meanings. See the man pages of your driver(s) to learn which variables are supported and what they do.

Here is another example, when connecting a serial UPS on Windows:

```
[windows-ups]

        driver = mge-shut

        port = "\\\\.\\COM10"

        desc = "UPS on a Windows machine"
```

## IMPORTANT NOTES
•Contents of this file should be pure ASCII (character codes not in range would be ignored with a warning message).

•Balance the run-time user permissions to access the file (and perhaps the directory it is in) for only upsd and the drivers to be able to read it; write access is not needed. It is common to use chown root:nut and chmod 640 to set up acceptable file permissions.

•Packages (and build recipes) typically prepare one set of user and group accounts for NUT. Custom builds with minimal configuration might even use nobody:nogroup or similar, which is inherently insecure.

•On systems with extra security concerns, NUT drivers, data server should run as separate user accounts which would be members of one same group for shared access to local Unix socket files and the directory they are in, as well for reading ups.conf, but different groups for other configuration file access. This would need some daemons to use customized user, group, RUN_AS_USER and/or RUN_AS_GROUP settings to override the single built-in value.

•Note that the monitoring, logging, etc. clients are networked-only. They do not need access to these files and directories, and can run as an independent user and group altogether.

•Keep in mind the security of also any backup copies of this file, e.g. the archive files it might end up in.

## GLOBAL DIRECTIVES
chroot

Optional. The driver will chroot(2) to this directory during initialization. This can be useful when securing systems.

driverpath

Optional. Path name of the directory in which the UPS driver executables reside. If you don’t specify this, the programs look in a built-in default directory, which is often /usr/local/ups/bin.

statepath

Optional. Path name of the directory in which the UPS drivers should place their state sockets for local communication with upsd data server, rather than the default location that was compiled into the program, which is often /var/state/ups. Note that the drivers must use the same path as upsd, so the data server would prefer this setting from ups.conf global section, if present, over its own in upsd.conf.

Environment variable NUT_STATEPATH set by caller can override this setting.

maxstartdelay

Optional. Same as the UPS field of the same name, but this is the default for UPSes that don’t have the field.

maxretry

Optional. Specify the number of attempts to start the driver(s), in case of failure, before giving up. A delay of retrydelay is inserted between each attempt. Caution should be taken when using this option, since it can impact the time taken by your system to start. The default is 1 attempt.

nowait

Optional. Specify to upsdrvctl to not wait at all for the driver(s) to execute the request command. The default (omission) is to wait.

It can be overridden by NUT_IGNORE_NOWAIT environment variable (e.g. used to work around certain issues with systemd otherwise).

retrydelay

Optional. Specify the delay between each restart attempt of the driver(s), as specified by maxretry. Caution should be taken when using this option, since it can impact the time taken by your system to start. The default is 5 seconds.

pollinterval

Optional. The status of the UPS will be refreshed after a maximum delay which is controlled by this setting. This is normally 2 seconds. This setting may be useful if the driver is creating too much of a load on your monitoring system or network. Note that some drivers (such as usbhid-ups(8), snmp-ups(8) and nutdrv_qx(8)) also have an option called pollfreq which controls how frequently some of the less critical parameters are polled. Details are provided in the respective driver man pages.

synchronous

Optional. The drivers work by default in asynchronous mode initially but can fall back to synchronous mode if writes to server socket failed (i.e synchronous=auto). This means that all data are pushed by the driver on the communication socket to upsd (Unix socket on Unix, Named pipe on Windows) without waiting for these data to be actually consumed. With some HW, such as ePDUs, that can produce a lot of data, asynchronous mode may cause some congestion, resulting in the socket to be full, and the driver to appear as not connected. In such case, the driver will provide the following debug message:

```
write XX bytes to socket Y failed
```

By enabling the synchronous flag (value = yes), the driver will wait for data to be consumed by upsd, prior to publishing more. This can be enabled either globally or per driver.

The default of auto acts like no (i.e. asynchronous mode) for backward compatibility of the driver behavior, until communications fail with a "Resource temporarily unavailable" condition, which happens when the driver has many data points to send in a burst, and the server can not handle that quickly enough so the buffer fills up.

user

Optional. Overrides the compiled-in default unprivileged username for all NUT device drivers. See the discussion of the -u option in nutupsdrv(8) for details.

group

Optional. Overrides the compiled-in (and/or global-section) default unprivileged group name for all NUT device drivers, used for the socket file access. See the discussion of the -g option in nutupsdrv(8) for details. This may be specifically useful for ensuring access to dynamic device filesystem nodes, such as USB (or serial-over-USB) hot-plug support, or with device filesystems re-generated by an OS for every reboot.

debug_min INTEGER

Optional. Specify a minimum debug level for all driver daemons and for the upsdrvctl(8) tool, e.g. for troubleshooting a deployment without changing init scripts, without impacting foreground or background running mode directly. Command-line option -D can only increase this verbosity level.

LIBUSB_DEBUG INTEGER

Optional. For run-time troubleshooting of USB-capable NUT drivers, you can specify verbosity of LibUSB specific debugging as a numeric value such as 4 ("All messages are emitted"). Should not have any practical impact on other NUT drivers. For more details, including the currently supported values for your version of the library, see e.g.:

•https://libusb.sourceforge.io/api-1.0/

•https://libusb.sourceforge.io/api-1.0/group__libusb__lib.html

## UPS FIELDS
driver

Required. This specifies which program will be monitoring this UPS. You need to specify the one that is compatible with your hardware. See nutupsdrv(8) for more information on drivers in general and pointers to the man pages of specific drivers.

port

Required. This is the serial port where the UPS is connected. On a Linux system, the first serial port usually is /dev/ttyS0. On FreeBSD and similar systems, it probably will be /dev/cuaa0. On Windows, the first serial port will be "\\\\.\\COM1" (note the escaped slashes).

user

Optional. Overrides the compiled-in (and/or global-section) default unprivileged username for a particular NUT device driver. See the discussion of the -u option in nutupsdrv(8) for details. This may be specifically useful for ensuring access to dynamic device filesystem nodes, such as USB (or serial-over-USB) hot-plug support, or with device filesystems re-generated by an OS for every reboot.

group

Optional. Overrides the compiled-in (and/or global-section) default unprivileged group name for a particular NUT device driver, used for the socket file access. See the discussion of the -g option in nutupsdrv(8) for details. This may be specifically useful for ensuring access to dynamic device filesystem nodes, such as USB (or serial-over-USB) hot-plug support, or with device filesystems re-generated by an OS for every reboot.

sdorder

Optional. When you have multiple UPSes on your system, you usually need to turn them off in a certain order. upsdrvctl shuts down all the 0s, then the 1s, 2s, and so on. To exclude a UPS from the shutdown sequence, set this to -1. The default value for this parameter is 0.

sdcommands

Optional. Comma-separated list of instant command name(s) to send to the UPS when you request its shutdown. Default logic is built into each driver (where supported) and can be referenced here as the shutdown.default value.

The primary use-case is for devices whose drivers "natively" support trying several commands, but the built-in order of those calls a command that is mis-handled by the specific device model (so the handling is reported as successful and the loop stops, but nothing happens as far as the load power-down is concerned).

Another use-case is differentiation of automated power-off scenarios where the UPS and its load should stay "OFF" (e.g. by building emergency power-off) vs. those where the load should return to work automatically when it is safe to do so. NOTE: This would currently need editing of ups.conf for such cases before nutshutdown sees the file; but could be better automated in future NUT releases.

Note

User-provided commands may be something other than actual shutdown, e.g. a beeper to test that the INSTCMD happened such and when expected, and the device was contacted, without impacting the load fed by the UPS.

allow_killpower

Optional. This allows you to request driver.killpower instant command, to immediately call the driver-specific default implementation of upsdrv_shutdown() method, for same effect as when a NUT driver is started with -k command-line flag. This option can be toggled with upsrw(8) as driver.flag.allow_killpower during run-time.

desc

Optional. This allows you to set a brief description that upsd will provide to clients that ask for a list of connected equipment.

nolock

Optional. When you specify this, the driver skips the port locking routines every time it starts. This may allow other processes to seize the port if you start more than one accidentally. You should only use this if your system won’t work without it.

This may be needed on Mac OS X systems.

ignorelb

Optional. When you specify this, the driver ignores a low battery condition flag that is reported by the UPS (some devices will switch off almost immediately after setting this flag, or will report this as soon as the mains fails). Instead it will use either of the following conditions to determine when the battery is low:

```
battery.charge < battery.charge.low
battery.runtime < battery.runtime.low
```

The idea is to set the battery.charge.low and/or battery.runtime.low levels in ups.conf to a value that gives enough time to cleanly shutdown your system:

```
override.battery.charge.low = 30
override.battery.runtime.low = 180
```

In order for this to work, your UPS should be able to (reliably) report charge and/or runtime remaining on battery. Use with caution!

maxstartdelay

Optional. This can be set as a global variable above your first UPS definition and it can also be set in a UPS section. This value controls how long upsdrvctl will wait for the driver to finish starting. This keeps your system from getting stuck due to a broken driver or UPS. Note that after this time upsdrvctl would just move along with its business (whether retrying the same driver if maxretry>1, or trying another driver if starting them all, or just eventually exit); however, each such most recently started "stuck" driver process may be further initializing in the background, and might even succeed eventually.

They would not be actively killed by upsdrvctl after this timeout expires.

The default is 75 seconds.

maxretry

Optional. This can be set as a global variable above your first UPS definition and it can also be set in a UPS section. See explanation above, in the global section.

retrydelay

Optional. This can be set as a global variable above your first UPS definition and it can also be set in a UPS section. See explanation above, in the global section.

synchronous

Optional. Same as the global directive of the same name, but this is for a specific device.

usb_set_altinterface[=altinterface]

Optional. Force the USB code to call usb_set_altinterface(0), as was done in NUT 2.7.2 and earlier. This should not be necessary, since the default for bAlternateSetting (as shown in lsusb) is zero on all USB devices seen to date. However, this redundant call to usb_set_altinterface() prevents certain UPSes from working on Mac OS X. If your UPS requires explicitly setting the alternate interface, include this flag, and email the nut-upsdev list with details about your UPS and operating system.

usb_config_index, usb_hid_rep_index, usb_hid_desc_index, usb_hid_ep_in, usb_hid_ep_out

Optional. Force use of specific interface, endpoint, descriptor index etc. numbers, rather than defaulting to 0 (rarely other values in certain drivers for some devices known to use non-zero numbers). Specified as a hexadecimal number. As a rule of thumb for usb_hid_desc_index discovery, you can see larger wDescriptorLength values (roughly 600+ bytes) in reports of lsusb or similar tools.

default.<variable>

Optional. Set a default value for <variable> which is used in case the UPS doesn’t provide a value, but will be overwritten if a value is available from the UPS:

```
default.input.voltage.nominal = 230
```

The above will report the nominal input voltage to be 230, unless the UPS tells us differently.

override.<variable>

Optional. Set a value for <value> that overrides any value that may be read from the UPS. Used for overriding values from the UPS that are clearly wrong (some devices report wrong values for battery voltage for instance):

```
override.battery.voltage.nominal = 12
```

Use with caution! This will only change the appearance of the variable to the outside world, internally in the UPS the original value is used.

All other fields are passed through to the hardware-specific part of the driver. See those manuals for the list of what is allowed.

debug_min INTEGER

Optional. Specify a minimum debug level for this driver daemon, e.g. for troubleshooting a deployment, without impacting foreground or background running mode directly. If the global debug_min is also set, this driver-level setting overrides it. Command-line option -D can only increase this verbosity level.

LIBUSB_DEBUG INTEGER

Optional. For run-time troubleshooting of USB-capable NUT drivers, you can specify verbosity of LibUSB specific debugging as a numeric value such as 4 ("All messages are emitted"). For more details, including the currently supported values for your version of the library, see e.g.:

•https://libusb.sourceforge.io/api-1.0/

•https://libusb.sourceforge.io/api-1.0/group__libusb__lib.html

## INTEGRATION
upsdrvctl(8) uses this file to start and stop the drivers.

The drivers themselves also obtain configuration data from this file. Each driver looks up its section and uses that to configure itself.

upsd(8) learns about which UPSes are installed on this system by reading this file. If this system is called "doghouse" and you have defined a UPS in your ups.conf called "snoopy", then you can monitor it from upsc(8) or similar as "snoopy@doghouse".

## SEE ALSO
upsd(8), nutupsdrv(8), upsdrvctl(8), upsdrvsvcctl(8)

### Internet resources
The NUT (Network UPS Tools) home page: https://www.networkupstools.org/historic/v2.8.5/


upsd.conf

title: upsd.conf(5)

text:
# upsd.conf(5)

## NAME
upsd.conf - Configuration for Network UPS Tools upsd data server

## DESCRIPTION
upsd(8) uses this file to control access to the server and set some other miscellaneous configuration values. This file contains details on access controls, so keep it secure. Ideally, only the upsd process should be able to read it.

## IMPORTANT NOTES
•Contents of this file should be pure ASCII (character codes not in range would be ignored with a warning message).

•Balance the run-time user permissions to access the file (and perhaps the directory it is in) for only upsd to be able to read it; write access is not needed. It is common to use chown root:nut and chmod 640 to set up acceptable file permissions.

•Packages (and build recipes) typically prepare one set of user and group accounts for NUT. Custom builds with minimal configuration might even use nobody:nogroup or similar, which is inherently insecure.

•On systems with extra security concerns, NUT drivers and data server should run as separate user accounts which would be members of one same group for shared access to local Unix socket files and the directory they are in, but different groups for configuration file access. This would need some daemons to use customized user, group, RUN_AS_USER and/or RUN_AS_GROUP settings to override the single built-in value.

•Note that the monitoring, logging, etc. clients are networked-only. They do not need access to these files and directories, and can run as an independent user and group altogether.

•Keep in mind the security of also any backup copies of this file, e.g. the archive files it might end up in.

## CONFIGURATION DIRECTIVES
MAXAGE seconds

upsd usually allows a driver to stop responding for up to 15 seconds before declaring the data "stale". If your driver takes a very long time to process updates but is otherwise operational, you can use MAXAGE to make upsd wait longer. Most users should leave this at the default value.

TRACKINGDELAY seconds

When instant commands and variables setting status tracking is enabled, status execution information are kept during this amount of time, and then cleaned up. This defaults to 3600 (1 hour).

ALLOW_NO_DEVICE Boolean

Normally upsd requires that at least one device section is defined in ups.conf when the daemon starts, to serve its data. For automatically managed services it may be preferred to have upsd always running, and reload the configuration when power devices become defined. Boolean values true, yes, on and 1 mean that the server would not refuse to start with zero device sections found in ups.conf.

Boolean values false, no, off and 0 mean that the server should refuse to start if zero device sections were found in ups.conf. This is the default, unless the calling environment sets a same-named variable to enforce a value for the current run. One way this can happen is somebody un-commenting it in the nut.conf file used by init-scripts and service unit method scripts.

ALLOW_NOT_ALL_LISTENERS Boolean

Normally upsd requires that all LISTEN directives can be honoured at the moment the daemon starts. If your LAN IP address (or host name) used in one of the LISTEN directives may be not always accessible, and for some reason do not want to just LISTEN * on the wildcard interface, but e.g. you still want to use upsmon on localhost, this option can help. Note you would have to restart upsd to pick up the LISTEN'ed IP address if it appears later. Boolean values true, yes, on and 1 mean that the server would not refuse to start if it can listen on at least one interface.

Boolean values false, no, off and 0 mean that the server should refuse to start if it can not LISTEN on each and every (non-localhost) interface found in upsd.conf. This is the default, unless the calling environment sets a same-named variable to enforce a value for the current run. One way this can happen is somebody un-commenting it in the nut.conf file used by init-scripts and service unit method scripts.

STATEPATH path

Tell upsd to look for the driver state sockets in path rather than the default that was compiled into the program. Note that the drivers must use the same path, so upsd would prefer the same-named setting from ups.conf global section, if present, over its own.

Environment variable NUT_STATEPATH set by caller (e.g. init script or service method) can override this setting.

LISTEN interface port

Bind a listening port to the interface specified by its Internet address or name. This may be useful on hosts with multiple interfaces. You should not rely exclusively on this for security, as it can be subverted on many systems. Optionally listen on TCP port port instead of the default value which was compiled into the code. This overrides any value you may have set with configure --with-port. If you don’t change it with configure or this value, upsd will listen on port 3493 for this interface.

Multiple LISTEN addresses may be specified. The default is to bind to 127.0.0.1 if no LISTEN addresses are specified (and also ::1 if IPv6 support is compiled in).

To listen on all available interfaces and configured IP addresses of your system, you may also use :: for IPv6 and 0.0.0.0 for IPv4, respectively. As a special case, a single LISTEN * <port> directive (with an asterisk) will try to listen on both IPv6 (::0) and IPv4 (0.0.0.0) wild-card IP addresses, subject to upsd command-line arguments or system configuration. Note that if the system supports IPv4-mapped IPv6 addressing per RFC-3493, and does not allow to disable this mode, then there may be one listening socket to handle both address families.

```
LISTEN 127.0.0.1
LISTEN 192.168.50.1
LISTEN myhostname.mydomain
LISTEN ::1
LISTEN 2001:0db8:1234:08d3:1319:8a2e:0370:7344
```

This parameter will only be read at startup. You’ll need to restart (rather than merely reload) upsd to apply any changes made here.

Please note that older NUT releases could have been using the IPv4-mapped IPv6 addressing (sometimes also known as "dual-stack") mode, if provided by the system. Current versions (since NUT v2.8.1 release) explicitly try to restrict their listening sockets to only support one address family on each socket, and so avoid IPv4-mapped mode where possible.

MAXCONN connections

This defaults to maximum number allowed on your system. Each UPS, each LISTEN address and each client count as one connection. If the server runs out of connections, it will no longer accept new incoming client connections. Only set this if you know exactly what you’re doing. Note that on some platforms there may be a smaller amount of file descriptors or handles that can be polled in one operation, the server would then poll several smaller groups until it handles all the connections it tracks. With a large amount of connections this may however impact the delays between processing loops, and time before an incoming message is seen and processed.

CERTFILE certificate file

When compiled with SSL support with OpenSSL backend, you can enter the certificate file here. The certificates must be in PEM format and must be sorted starting with the subject’s certificate (server certificate), followed by intermediate CA certificates (if applicable) and the highest level (root) CA. It should end with the server key. See docs/security.txt in NUT sources, or the Security chapter of NUT user manual, for more information on the SSL support in NUT.

CERTPATH certificate database

When compiled with SSL support with NSS backend, you can enter the certificate path here. Certificates are stored in a dedicated database (data split in 3 files). Specify the path of the database directory.

CERTIDENT certificate name database password

When compiled with SSL support with NSS backend, you can specify the certificate name to retrieve from database to authenticate itself and the password required to access certificate related private key.

Note

Be sure to enclose "certificate name" in double-quotes if you are using a value with spaces in it.

CERTREQUEST certificate request level

When compiled with SSL support with NSS backend and client certificate validation (disabled by default, see ‘docs/security.txt` in NUT sources), you can specify whether upsd requests or requires clients’ certificates.

Warning

Until issue #3329 is solved, not all stock NUT clients may even have a way to present some certain certificate.

Possible values are:

•0 or NO to not request that clients provide any certificate

•1 or REQUEST to require all clients to present some certificate

•2 or REQUIRE to require all clients to present a valid certificate (with auth chain trusted by server database)

DISABLE_WEAK_SSL BOOLEAN

Tell upsd to disable older/weak SSL/TLS protocols and ciphers. With relatively recent versions of OpenSSL or NSS it will be restricted to TLSv1.2 or better. Unless you have really ancient clients, you probably want to enable this. Currently disabled by default to ensure compatibility with existing setups.

DEBUG_MIN INTEGER

Optionally specify a minimum debug level for upsd data daemon, e.g. for troubleshooting a deployment, without impacting foreground or background running mode directly. Command-line option -D can only increase this verbosity level.

Note

If the running daemon receives a reload command, presence of the DEBUG_MIN NUMBER value in the configuration file can be used to tune debugging verbosity in the running service daemon (it is recommended to comment it away or set the minimum to explicit zero when done, to avoid huge journals and I/O system abuse). Keep in mind that for this run-time tuning, the DEBUG_MIN value present in reloaded configuration files is applied instantly and overrides any previously set value, from file or CLI options, regardless of older logging level being higher or lower than the newly found number; a missing (or commented away) value however does not change the previously active logging verbosity.

## SEE ALSO
upsd(8), nutupsdrv(8), upsd.users(5)

### Internet resources:
The NUT (Network UPS Tools) home page: https://www.networkupstools.org/historic/v2.8.5/


upsd.users

title: upsd.users(5)

text:
# upsd.users(5)

## NAME
upsd.users - Administrative user definitions for NUT upsd data server

## DESCRIPTION
Administrative commands such as setting variables and the instant commands are powerful, and access to them needs to be restricted. This file defines who may access them, and what is available.

## IMPORTANT NOTES
•Contents of this file should be pure ASCII (character codes not in range would be ignored with a warning message).

•Balance the run-time user permissions to access the file (and perhaps the directory it is in) for only upsd to be able to read it; write access is not needed. It is common to use chown root:nut and chmod 640 to set up acceptable file permissions.

•Packages (and build recipes) typically prepare one set of user and group accounts for NUT. Custom builds with minimal configuration might even use nobody:nogroup or similar, which is inherently insecure.

•On systems with extra security concerns, NUT drivers and data server should run as separate user accounts which would be members of one same group for shared access to local Unix socket files and the directory they are in, but different groups for configuration file access. This would need some daemons to use customized user, group, RUN_AS_USER and/or RUN_AS_GROUP settings to override the single built-in value.

•Note that the monitoring, logging, etc. clients are networked-only. They do not need access to these files and directories, and can run as an independent user and group altogether.

•Keep in mind the security of also any backup copies of this file, e.g. the archive files it might end up in.

## SECTIONS
Each user gets its own section. The fields in that section set the parameters associated with that user’s privileges. The section begins with the name of the user in brackets, and continues until the next user name in brackets or EOF. These users are independent of /etc/passwd or other OS account databases.

Here are some examples to get you started:

```
[admin]

        password = mypass

        actions = set

        actions = fsd

        instcmds = all
```

```
[pfy]

        password = duh

        instcmds = test.panel.start

        instcmds = test.panel.stop
```

```
[upswired]

        password = blah

        upsmon primary
```

```
[observer]

        password = abcd

        upsmon secondary
```

## FIELDS
password

Set the password for this user.

actions

Allow the user to do certain things with upsd. To specify multiple actions, use multiple instances of the actions field. Valid actions are: SET

change the value of certain variables in the UPS

FSD

set the forced shutdown flag in the UPS. This is equivalent to an "on battery + low battery" situation for the purposes of monitoring.

The list of actions is expected to grow in the future.

instcmds

Let a user initiate specific instant commands. Use "ALL" to grant all commands automatically. To specify multiple commands, use multiple instances of the instcmds field. For the full list of what your UPS supports, use upscmd -l. The cmdvartab file supplied with the NUT distribution contains a list of most of the generally known command names.

upsmon

Add the necessary actions for an upsmon process, and can be viewed as a role of a particular client instance to work with this data server instance. This is either set to primary (may request FSD) or secondary (follows critical situations to shut down when needed). Do not attempt to assign actions to upsmon by hand, as you may miss something important. This method of designating a "upsmon user" was created so internal capabilities could be changed later on without breaking existing installations (potentially using actions that are not exposed for direct assignment).

## SEE ALSO
upsd(8), upsd.conf(5)

### Internet resources:
The NUT (Network UPS Tools) home page: https://www.networkupstools.org/historic/v2.8.5/