NUT-DRIVER-ENUMERATOR(8)
========================

NAME
----

nut-driver-enumerator - Tool to map NUT device entries to service instances

SYNOPSIS
--------

*nut-driver-enumerator.sh* -h

*nut-driver-enumerator.sh*  (no args)

*nut-driver-enumerator.sh*  [--COMMAND]


DESCRIPTION
-----------

The *nut-driver-enumerator.sh* (also known as "NDE") script implements the
set-up and querying of the mapping between NUT driver configuration sections
for each individual monitored device, and the service instances of an
operating system service management framework (on platforms where NUT already
supports this integration -- currently this covers Linux distributions with
systemd and systems derived from Solaris 10 codebase, including proprietary
Sun/Oracle Solaris and numerous open-source illumos distributions with SMF),
into which such drivers are wrapped for independent execution and management.
It may be not installed in packaging for other operating systems.

With each NUT driver represented as a separate service instance, dependencies
can be defined (e.g. networked drivers must start after the network ability
appears in the OS, but USB/Serial drivers should not wait for that), and they
can fail or be brought into maintenance independently (unlike a monolithic
service based on linkman:upsdrvctl[8] requiring everything configured to be
started). For a few special drivers like linkman:dummy-ups[8], linkman:clone[8],
linkman:clone-outlet[8], and linkman:failover[8] this may also involve a
dependency between service instances of different NUT drivers themselves.

This script provides a uniform interface for further NUT tools
such as linkman:upsdrvsvcctl[8] to implement their logic as
platform-independently as was possible and practical. It is not
currently intended for end-user consumption (and so is located in
the 'libexec' directory), with *upsdrvsvcctl* exposing the most
useful data and actions with its 'list' and 'resync' arguments.

One part of the platform complexity that *nut-driver-enumerator.sh*
hides is the difference of rules for valid service instance names
in various frameworks, as well as system tools and naming patterns
involved.

Depending on the platform, the script may also be wrapped by different service
unit types to run automatically (e.g. upon system start-up, or regularly to
pick up changes of linkman:ups.conf[5] soon after it is edited, or integrated
with a file system monitor to be triggered when the configuration is changed).
Some of these modes make sense for use-cases with a rarely (if ever) changing
population of power devices, e.g. a home or small-office UPS monitored same
way for years at a time; others can help automate a data-center monitoring
system where device deployments (or discovery) can be much more dynamic.

COMMANDS
--------

*nut-driver-enumerator.sh  (no args)*::
Update wrapping of devices into services

*nut-driver-enumerator.sh --daemon(=freq)*::
Update wrapping of devices into services in an infinite loop;
Default freq is 60 sec.

*nut-driver-enumerator.sh --daemon-after(=freq)*::
Update wrapping of devices into services in an infinite loop;
first do one run of the loop though, then daemonize (this way
service unit is deemed started only when NUT config and driver
instances are in sync). Default freq is 60 sec.

*nut-driver-enumerator.sh --reconfigure*::
Stop and un-register all service instances and recreate them
(e.g. if new dependency template was defined in a new
version of the script or package)

*nut-driver-enumerator.sh  --get-service-framework*::
Print the detected service management framework in this OS

*nut-driver-enumerator.sh  --list-devices*::
Print list of devices in NUT config

*nut-driver-enumerator.sh  --list-services*::
Print list of service instances which wrap registered
NUT devices (full name of service unit)

*nut-driver-enumerator.sh  --list-instances*::
Print list of service instances which wrap registered
NUT devices (just instance suffix)

*nut-driver-enumerator.sh  --get-service-for-device DEV*::
Print the full name of service unit which wraps a NUT
device named `DEV`

*nut-driver-enumerator.sh  --get-device-for-service SVC*::
Print the NUT device name for full or instance-suffix name of
a service unit `SVC` which wraps it

*nut-driver-enumerator.sh  --list-services-for-devices*::
Print a TAB-separated list of service units and corresponding
NUT device names which each such unit wraps

*nut-driver-enumerator.sh --show-all-configs*::
Show the complete normalized list of device configuration blocks
(same as used later by the parser in the script to make decisions)

*nut-driver-enumerator.sh --show-device-config DEV*::
Show configuration block of the specified NUT device

*nut-driver-enumerator.sh --show-device-config-value DEV KEY*::
Show single configuration key of the specified NUT device

ENVIRONMENT VARIABLES
---------------------

By default *nut-driver-enumerator.sh* executed without arguments would
automatically start any newly registered service instances wrapping the
NUT devices, and would also restart the `nut-server` service if the
configuration was changed. Environment variable `AUTO_START=no` disables
this default part of the action.

Also see below for environment variable `REPORT_RESTART_42=no` value.

DIAGNOSTICS
-----------

*nut-driver-enumerator.sh* will return a zero exit code if it had nothing
to do (all currently defined drivers match all of the currently defined
service instances, one-to-one) and if it had no errors in its operation.

Other codes can be returned as a result of re-synchronization of mappings:

*42*::
NUT device sections and system service instances differed before, but
now match up -- so now the caller should likely restart some services.
Note that the drivers' service instances may have been started or stopped
as required (by `AUTO_START=yes`) -- but maybe the upsmon or upssched
services should restart.
If you pass environment variable `REPORT_RESTART_42=no` then
this codepath would return 0 (as a non-error exit code).
In default mode, such non-null reconfiguration should cause
the nut-driver-enumerator service to restart and this would
propagate to other NUT services that depend on it.

*13*::
Sections and services differed, and still do not match up

*1*::
Bad inputs, e.g. unrecognized service management framework

*2*::
Absent or unreadable `ups.conf` file

AUTHOR
------

Jim Klimov <jimklimov+nut@gmail.com>

SEE ALSO
--------

linkman:upsdrvsvcctl[8], linkman:ups.conf[5]

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

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