NAME¶

failover - UPS Failover Driver

SYNOPSIS¶

failover -h

failover -a UPS_NAME [OPTIONS]

DESCRIPTION¶

The failover driver acts as a smart proxy for multiple "real" UPS drivers. It connects to and monitors these underlying UPS drivers through their local UNIX sockets (or Windows named pipes), continuously evaluating health and suitability for "primary" duty according to a set of user configurable rules and priorities.

At any given time, failover designates one UPS driver as the primary, and presents its commands, variables and status to the outside world as if it were directly talking to that UPS. From the perspective of the clients (such as upsmon(8) or upsc(8)), the failover driver behaves like any single UPS, abstracting away the underlying redundancy, and allowing for seamless transitioning between all monitored UPS drivers and their datasets.

The driver dynamically promotes or demotes the primary UPS driver based on:

If the current primary becomes unavailable or no longer meets the criteria, the driver automatically fails over to a more suitable driver. During transitions, it ensures that any data is switched out instantly, without the upsd(8) considering it as stale or the clients acting on any previously degraded status.

When no suitable primary is available, a configurable fallback state is entered:

Different communication media can be used to connect to individual UPS drivers (e.g., USB, Serial, Ethernet). failover communicates directly at the socket level and therefore does not rely on upsd(8) being active.

EXTRA ARGUMENTS¶

This driver supports the following settings:

port=drivername-devicename,drivername2-devicename2,...

inittime=seconds

deadtime=seconds

relogtime=seconds

noprimarytime=seconds

maxconnfails=count

coolofftime=seconds

fsdmode=0|1|2

checkruntime=0|1|2|3

strictfiltering=0|1

status_have_any=OL,CHRG,...

status_have_all=OL,CHRG,...

status_nothave_any=OB,OFF,...

status_nothave_all=OB,LB,...

IMPLEMENTATION¶

The port argument in the ups.conf(5) should reference the local driver sockets (or Windows named pipes) that the "real" UPS drivers are using. A basic default setup with multiple drivers could look like this:

  [realups]


     driver = usbhid-ups


     port = auto


  [realups2]


     driver = usbhid-ups


     port = auto


  [failover]


     driver = failover


     port = usbhid-ups-realups,usbhid-ups-realups2

Any upsmon(8) clients would be set to monitor the failover UPS.

The driver fully supports setting variables and performing instant commands on the currently elected primary UPS driver, which are proxied and with end-to-end tracking also being possible (upscmd(8) and upsrw(8) -w). You may notice some variables and commands will be prefixed with upstream., this is to clearly separate the upstream commands from those of failover itself.

For your convenience, additional administrative commands are exposed to directly influence and override the primary election process, e.g. for maintenance:

Calling either command without an argument has the same effect as passing 0, but only for that specific override - it does not affect the other.

PRIORITIES¶

As outlined above, primaries are dynamically elected based on their current state and according to a strict set of user influenceable priorities, which are:

The UPS driver with the highest calculated priority is chosen as primary, ties are resolved through order of the socket names given within the port argument.

For the user-defined status filters, the following internal order is respected:

If strictfiltering is enabled, priorities 2 to 4 are not applicable.

If no user-defined status filters are set, the priority 1 is not applicable.

RATIONALE¶

In complex power environments, presenting a single, consistent source of UPS information to upsmon(8) is sometimes preferable to monitoring multiple independent drivers directly. The failover driver serves as a bridge, allowing upsmon(8) to make decisions based on the most suitable available data, without having to interpret conflicting inputs or degraded sources.

Originally designed for use cases such as dual-PSU systems or redundant communication paths to a single UPS, failover also supports more advanced setups - for example, when multiple UPSes feed a shared downstream load (via STS/ATS switches), or when drivers vary in reliability. In these cases, the driver can be combined with external logic or scripting to dynamically adjust primary selection and facilitate graceful degradation. Such setups may also benefit from further integration with the clone family of drivers, such as clone(8) or clone-outlet(8), for greater granularity and monitoring control down to the outlet level.

Additionally, in more niche scenarios, some third-party NUT integrations or graphical interfaces may be limited to monitoring a single UPS device. In such cases, failover can help by exposing only the most relevant or highest-priority data source, allowing those tools to operate within their constraints without missing critical information.

Ultimately, this driver enables more nuanced power monitoring and control than binary online/offline logic alone, allowing administrators to respond to degraded conditions early - before they escalate into critical events or require upsmon(8) to take action.

LIMITATIONS¶

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¶

Sebastian Kuttnig <sebastian.kuttnig@gmail.com>

SEE ALSO¶

upscmd(8), upsrw(8), ups.conf(5), upsc(8), upsmon(8), nutupsdrv(8), clone(8), clone-outlet(8)