failover.c - UPS Failover Driver

NEWS.adoc

@@ -165,6 +165,12 @@ https://github.com/networkupstools/nut/milestone/9
      support for end-to-end tracked instant commands and also variable updating.
      [#2962]
 
+ - The `nut-driver-enumerator.sh` script (NDE) now internally tracks dependency
+   of one driver on another one that should be locally running to serve the
+   "original" data points (`clone`, `clone-outlet`, `dummy-ups`, `failover`).
+   It should create soft dependencies between respective service instances
+   to order their start-up sequence. [#2962]
+
  - NUT Monitor GUI:
    * Ported Python 3 version to Qt6, now shipped alongside Qt5 for systems
      with either or both, maximizing compatibility with old and new setups.

docs/man/failover.txt

@@ -112,6 +112,24 @@ itself. This mode is for setups where immediate shutdown is warranted,
 regardless of anything else, and getting `FSD` out to the clients as fast as
 just possible.
 
+*checkruntime*='0|1|2|3'::
+Optional. Controls how `battery.runtime` values are used to break ties between
+non-fully-online UPS devices **at priority 3 or lower**. Has no effect on
+initial priority selection or when `strictfiltering` is enabled. Defaults to 1.
+
+- `0`: *Disabled.* No runtime comparison is done. The first candidate with the
+best priority is selected according to the order of the port argument.
+
+- `1`: *Compare `battery.runtime`.* The UPS with the higher value is preferred.
+If the value is missing or invalid, the UPS cannot win the tie-break.
+
+- `2`: *Compare `battery.runtime.low`.* The UPS with the higher value is
+preferred. If the value is missing or invalid, the UPS cannot win the tie-break.
+
+- `3`: *Compare both variables strictly.* The UPS is preferred only if it has
+both a higher `battery.runtime` and `battery.runtime.low` value. If either is
+missing or invalid, the UPS cannot win the tie-break.
+
 *strictfiltering*='0|1':: Optional. If set to 1, only UPS drivers matching the
 configured status filters are considered for promotion to primary. If set to 0,
 the hard-coded default logic is also considered when no status filters match
@@ -250,6 +268,11 @@ When using `failover` for redundancy between multiple UPS drivers connected to
 the same underlying UPS device, data is not multiplexed between the drivers. As
 a result, some data points may be available in some drivers but not in others.
 
+For `checkruntime` considerations, the unit of both `battery.runtime` and
+`battery.runtime.low` is assumed to be **seconds**. UPS drivers that report
+these values using different units are considered non-compliant with the NUT
+variable standards and should be reported to the NUT developers as faulty.
+
 AUTHOR
 ------
 

docs/man/nut-driver-enumerator.txt

@@ -19,16 +19,24 @@ SYNOPSIS
 DESCRIPTION
 -----------
 
-*nut-driver-enumerator.sh* implements the set-up and querying of the
-mapping between NUT driver configuration sections for each individual
-monitored device, and the operating system service management framework
-service instances into which such drivers are wrapped for independent
-execution and management (on platforms where NUT currently 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). It may be not installed in packaging for
-other operating systems.
+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
@@ -42,6 +50,15 @@ 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
 --------
 

docs/nut.dict

@@ -1,4 +1,4 @@
-personal_ws-1.1 en 3517 utf-8
+personal_ws-1.1 en 3518 utf-8
 AAC
 AAS
 ABI
@@ -1756,6 +1756,7 @@ cgroup
 cgroupsv
 chargetime
 charset
+checkruntime
 checksum
 checksums
 chgrp