nut‐driver‐enumerator (NDE)

Intro

The nut-driver-enumerator (NDE) feature is provided since NUT v2.8.0 release to facilitate automatic service unit instance creation for each NUT device driver definition, so that the drivers for each device have independent life-cycles (unlike the singular nut-driver units in earlier releases, or singular init-scripts using upsdrvctl by default without specific device names).

You can see an example unit deployment detailed in NUT systemd service units page.

Pros

Benefits include, for example, that:

• A failed and restarted driver no longer causes a restart of the whole NUT stack and does not impact fellow drivers that did not have any problems.
• Initialization time of one driver (notably snmp-ups can have long first data walks) does not impact other drivers which can start in parallel (caveat: unless such init is CPU-intensive and there are very many drivers - may be a problem on weak appliances with grand plans).
• Dependencies can be defined, whether prerequisites for the drivers (some need networking or similar facilities, others do not), or some further programs of your choice starting because a particular NUT driver runs.
• Edition of ups.conf is automatically applied to the actual set of running NUT driver daemons, each isolated in its nut-driver service unit instance.

This feature is currently supported for Linux systemd and Solaris/illumos SMF service management frameworks. PRs are of course welcome to extend it for more such systems.

Cons (sort of)

Caveat emptor: Many instructions about NUT suggest using upsdrvctl to manage driver lifecycle, or to run driver programs directly when troubleshooting with higher verbosity and/or picking the options for driver configuration. This can conflict with service unit instances created by NDE (which can in turn be automatically enabled as part of NUT packages) and managed by the OS to keep the drivers alive. The new driver program started on command line would typically kill off an older copy (assuming it is stuck), then systemd or SMF would revive the driver wrapped into the service instance and kill off the one started on command line.

• When troubleshooting, remember to either temporarily stop the service units while fiddling with command-line driver instances, or to embrace the automatic reconfiguration and make use of debug_min setting temporarily to collect information into the service logs. See Changing NUT daemon debug verbosity for more details on that.
• When managing driver instances, upsdrvsvcctl (part of NDE) can help.

Technical Details

On the technical side, NDE is primarily a portable shell script which can parse configuration from the ups.conf global and per-device sections, and to discover the service instances for each device (along with saved checksum of last applied configuration), and compares the two lists. If there are any discrepancies (typically device sections appearing, disappearing, or being changed), NDE adds, removes or changes definitions of service units and stops/starts them as applicable, and notifies the upsd data server to reload configuration (or restart).

• See current source code version at https://github.com/networkupstools/nut/blob/master/scripts/upsdrvsvcctl/nut-driver-enumerator.sh.in
• See current man page at https://github.com/networkupstools/nut/blob/master/docs/man/nut-driver-enumerator.txt or https://networkupstools.org/docs/man/nut-driver-enumerator.html

For practical purposes, NDE is a script that people can run manually when they install NUT or change ups.conf definitions, and either a run-once service that takes effect during boot (to refresh current device lists), or a daemon that runs an infinite loop to pick up the changes over time (for monitoring platforms that track a varying population of power devices). Depending on the platform, other triggers may be available, e.g. "path" units which allow the OS to react to filesystem changes and trigger the run-once service (or send a refresh signal to daemon-mode service).

It is accompanied by upsdrvsvcctl which allows to manage service management framework instances wrapping the drivers, while mimicking upsdrvctl (which manages driver daemon binaries directly):

• See current source code version at https://github.com/networkupstools/nut/blob/master/scripts/upsdrvsvcctl/upsdrvsvcctl.in
• See current man page at https://github.com/networkupstools/nut/blob/master/docs/man/upsdrvsvcctl.txt or https://networkupstools.org/docs/man/upsdrvsvcctl.html

Visible deliverables

Depending on the OS and NUT release, you can see some or all of the following:

• The nut-driver-enumerator.sh script which does all the work about parsing ups.conf and managing service units, its libexecdir location depends on packaging.
• The upsdrvsvcctl script which manages service unit instances which each wrap a single NUT driver configuration, its sbindir location depends on packaging.
• Services for single-shot runs (aimed at majority of users with rarely edited configurations):
  • A nut-driver-enumerator.service (systemd) or nut-driver-enumerator:default (SMF) which runs once to add/remove nut-driver service unit instances and exits, typically upon OS boot or when triggered by external callers.
  • A nut-driver-enumerator.path (systemd) to trigger single runs of nut-driver-enumerator.service whenever ups.conf is edited.
• Services for daemonized runs (aimed at larger monitoring systems whose population of known power devices can change frequently):
  • A nut-driver-enumerator-daemon.service (systemd) or nut-driver-enumerator:daemon (SMF) which runs persistently, to pick up editions of ups.conf as it checks the file every minute or so, or instantly on-demand when it receives a signal.
  • A nut-driver-enumerator-daemon-activator.service (systemd) which causes a "reload-or-restart" of the nut-driver-enumerator-daemon.service to cause instant processing (without waiting for a loop delay to expire).
  • A nut-driver-enumerator-daemon-activator.path (systemd) to trigger single runs of nut-driver-enumerator-daemon-activator.service whenever ups.conf is edited.

Obviously, the single-shot and daemon approaches are mutually exclusive. Depending on the OS capabilities (and throttling of those) and on the activated or disabled units, both approaches can result in automatic reconfiguration of nut-driver service instances as you edit the ups.conf file.