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 linkman: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 linkman: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 linkmanext: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:
+
[options="header",cols="1,3a"]
|===========================================================================
| 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
--------

linkman:ups.conf[5], linkman:upsd.conf[5], linkman:upsd.users[5],
linkman:upsmon.conf[5]

Internet resources:
~~~~~~~~~~~~~~~~~~~

The NUT (Network UPS Tools) home page: https://www.networkupstools.org/
