title: blazer_usb(8)

text:
# blazer_usb(8)

## NAME
blazer_usb - Driver for Megatec/Q1 protocol USB based UPS equipment

## SYNOPSIS
blazer_usb -h

blazer_usb -a UPS_NAME [OPTIONS]

## NOTE
This man page only documents the hardware-specific features of the blazer driver. For information about the core driver, see nutupsdrv(8).

## NOTE
Please note that this driver is deprecated and will not receive new development. If it works for managing your devices — fine, but if you are running it to try setting up a new device, please consider the newer nutdrv_qx(8) instead, which should handle all Q* protocol variants for NUT.

Please do also report if your device works with this driver, but nutdrv_qx(8) would not actually support it with any subdriver!

## SUPPORTED HARDWARE
The blazer driver is known to work with various UPSes from Blazer, Energy Sistem, Fenton Technologies, General Electric, Mustek and many others. The NUT compatibility table lists all the known supported models. Keep in mind, however, that other models not listed there may also be supported, but haven’t been tested.

All devices with a serial interface (use the blazer_ser driver) and many with a USB interface (use the blazer_usb driver) are supported.

## EXTRA ARGUMENTS
You may need to override or provide defaults for some values, depending on the make and model of your UPS. The following are the ones that most likely will need changing (see ups.conf(5)):

default.battery.voltage.high = value

Maximum battery voltage that is reached after about 12 to 24 hours charging. If you want the driver to report a guesstimated battery.charge, you need to specify this (see BATTERY CHARGE GUESSTIMATION).

default.battery.voltage.low = value

Minimum battery voltage just before the UPS automatically shuts down. If you want the driver to report a guesstimated battery.charge, you need to specify this (see BATTERY CHARGE GUESSTIMATION).

default.battery.voltage.nominal = value, override.battery.voltage.nominal = value

Some devices show a wrong nominal battery voltage (or none at all), so you may need to override or set a default value.

override.battery.packs = value

Some devices report a part of the total battery voltage. For instance, if battery.voltage.nominal is 24 V, but it reports a battery.voltage of around 2 V, the number of battery.packs to correct this reading would be 12. The driver will attempt to detect this automatically, but if this fails somehow, you may want to override this value.

ondelay = value

Time to wait before switching on the UPS (minutes). Note that a value below 3 minutes, may cause earlier firmware versions to not switch on automatically, so it defaults to 3 minutes. The acceptable range is 0..9999 minutes.

offdelay = value

Time to wait before shutting down the UPS (seconds). This value is truncated to units of 6 seconds (less than 60 seconds) or 60 seconds (more than 60 seconds). Defaults to 30 seconds. The acceptable range is 12..600 seconds.

norating

Some UPSes will lock up if you attempt to read rating information from them. Setting this flag will make the driver skip this step.

novendor

Some UPSes will lock up if you attempt to read vendor information from them. Setting this flag will make the driver skip this step.

protocol = string

Skip autodetection of the protocol to use and only use the one specified. Supported values are megatec, megatec/old, mustek and zinto.

runtimecal = value,value,value,value

Parameter used in the (optional) runtime estimation. This takes two runtimes at different loads. Typically, this uses the runtime at full load and the runtime at half load. For instance, if your UPS has a rated runtime of 240 seconds at full load and 720 seconds at half load, you would enter

```
runtimecal = 240,100,720,50
```

The first load should always be higher than the second. If you have values available for loads other than 100 and 50 % respectively, you can use those too, but keep them spaced apart as far as reasonably possible. Just don’t get too close to no load (prediction of runtime depends more on idle load for the battery then).

chargetime = value

The time needed to fully recharge the battery after being fully discharged. If not specified, the driver defaults to 43200 seconds (12 hours). Only used if runtimecal is also specified.

idleload = value

Minimum battery load used by the driver to estimate the runtime. If not specified, the driver defaults to 10%. Only used if runtimecal is also specified.

### USB INTERFACE ONLY
port = string

Required option for all NUT drivers. Some value must be set, typically auto for drivers that handle USB connections.

Note

This could be a device filesystem path like /dev/usb/hiddev0 but current use of libusb API precludes knowing and matching by such identifiers. They may also be inherently unreliable (dependent on re-plugging and enumeration order). At this time the actual value is ignored, but syntactically some port configuration must still be there.

It is possible to control multiple UPS units simultaneously by running several instances of this driver, provided they can be uniquely distinguished by setting some combination of the vendor, product, vendorid, productid, serial, bus and/or device options detailed below. For devices or operating systems that do not provide sufficient information, the allow_duplicates option can be of use (limited and risky!)

vendorid = regex, productid = regex, vendor = regex, product = regex, serial = regex

Select a specific UPS, in case there is more than one connected via USB. Each option specifies an extended regular expression (see regex(7) for more information on regular expressions), which must match the UPS’s entire respective vendor/product/serial string values (minus any surrounding whitespace), or the whole 4-digit hexadecimal code for vendorid and productid. Try lsusb(8) or running this NUT driver with -DD command-line argument for finding out the strings to match.

Examples:

•-x vendor="Foo.Corporation.*"

•-x vendorid="051d*" (APC)

•-x product=".*(Smart|Back)-?UPS.*"

bus = regex

OPTIONAL, NOT RECOMMENDED. Select a UPS on a specific USB bus or group of buses. The argument is a regular expression that must match the bus name where the UPS is connected (e.g. bus="002" or bus="00[2-3]") as seen on Linux in /sys/bus/usb/devices or lsusb(8); including leading zeroes.

Note

Bus numbers are not guaranteed by the OS to be stable across re-boots, kernel driver reloads or device re-plugging (e.g. changing visible population of USB hubs).

device = regex

OPTIONAL, NOT RECOMMENDED. Select a UPS on a specific USB device or group of devices. The argument is a regular expression that must match the device name where the UPS is connected (e.g. device="001" or device="00[1-2]") as seen on Linux in /sys/bus/usb/devices or lsusb(8); including leading zeroes.

Note

Device numbers are not guaranteed by the OS to be stable across re-boots or device re-plugging.

busport = regex

OPTIONAL, NOT RECOMMENDED. If supported by the hardware, OS and libusb on the particular deployment, this option should allow to specify physical port numbers on an USB hub, rather than logical device enumeration values, and in turn — this should be less volatile across reboots or re-plugging. The value may be seen in the USB topology output of lsusb -tv on systems with that tool, for example.

Note

This option is not practically supported by some NUT builds (it should be ignored with a warning then), and not by all systems that NUT can run on.

allow_duplicates

OPTIONAL, NOT RECOMMENDED. If you have several UPS devices which may not be uniquely identified by the options above (e.g. only VID:PID can be discovered there), this flag allows each driver instance where it is set to take the first match if available, or proceed to try another.

Normally the driver initialization would abort at this point claiming "Resource busy" or similar error, assuming that the otherwise properly matched device is unique — and some other process already handles it.

Warning

This feature is inherently non-deterministic! The association of driver instance name to actual device may vary between runs! If you only care to know that at least one of your no-name UPSes is online, this option can help.

If you must really know which one, it will not!

usb_set_altinterface = bAlternateSetting

Force redundant call to usb_set_altinterface(), especially if needed for devices serving multiple USB roles where the UPS is not represented by the interface number 0 (default).

usb_config_index, usb_hid_rep_index, usb_hid_desc_index, usb_hid_ep_in, usb_hid_ep_out

Force use of specific interface, endpoint, descriptor index etc. numbers, rather than defaulting to 0 (rarely other values in certain drivers for some devices known to use non-zero numbers). Specified as a hexadecimal number. As a rule of thumb for usb_hid_desc_index discovery, you can see larger wDescriptorLength values (roughly 600+ bytes) in reports of lsusb or similar tools.

LIBUSB_DEBUG = INTEGER

Run-time troubleshooting of USB-capable NUT drivers can involve not only raising the common NUT debug verbosity (e.g. using the DEBUG_MIN setting in ups.conf(5) or protocol commands to change the driver.debug value), but may also benefit from LibUSB specific debugging. For the latter, you can set the LIBUSB_DEBUG driver option; alternatively you can classically export the environment variable LIBUSB_DEBUG before starting a NUT driver program (may be set and "exported" in driver init script or service method, perhaps via nut.conf(5)), to a numeric value such as 4 ("All messages are emitted").

For more details, including the currently supported values for your version of the library, see e.g.:

•https://libusb.sourceforge.io/api-1.0/

•https://libusb.sourceforge.io/api-1.0/group__libusb__lib.html

subdriver = string

Select a serial-over-USB subdriver to use. You have a choice between phoenix, ippon, cypress, and krauler. When using this option, it is mandatory to also specify the vendorid and productid.

langid_fix = value

Apply the language ID workaround to the krauler subdriver. This is mandatory for some devices to work (LDLC, Dynamix and others). You must to provide value (0x409 or 0x4095), according to your device entry in NUT hardware compatibility list (HCL).

## UPS COMMANDS
This driver supports some instant commands (see upscmd(8)):

beeper.toggle

Toggle the UPS beeper. (Not available on some hardware.)

load.on

Turn on the load immediately.

load.off

Turn off the load immediately (see KNOWN PROBLEMS).

shutdown.return

Turn off the load and return when power is back. Uses the timers defined by ondelay and offdelay.

shutdown.stayoff

Turn off the load and remain off (see KNOWN PROBLEMS). Uses the timer defined by offdelay.

shutdown.stop

Stop a shutdown in progress.

test.battery.start.deep

Perform a long battery test (Not available on some hardware.)

test.battery.start.quick

Perform a (10 second) battery test.

test.battery.start value

Perform a battery test for the duration of value minutes.

test.battery.stop

Stop a running battery test (not available on some hardware.)

## BATTERY CHARGE GUESSTIMATION
Due to popular demand, this driver will report a guesstimated battery.charge value and optionally battery.runtime, provided you specified a couple of the EXTRA ARGUMENTS listed above.

If you specify both battery.voltage.high and battery.voltage.low in ups.conf(5), but don’t enter runtimecal, it will guesstimate the state of charge by looking at the battery voltage alone. This is not reliable under load, as this only gives reasonably accurate readings if you disconnect the load, let the battery rest for a couple of minutes and then measure the open cell voltage. This just isn’t practical if the power went out and the UPS is providing power for your systems.

```
                     battery.voltage - battery.voltage.low
battery.charge =  ------------------------------------------ x 100 %

                  battery.voltage.high - battery.voltage.low
```

There is a way to get better readings without disconnecting the load, but this requires one to keep track on how much (and how fast) current is going in- and out of the battery. If you specified the runtimecal, the driver will attempt to do this. Note however, that this heavily relies on the values you enter and that the UPS must be able to report the load as well. There are quite a couple of devices that report 0% (or any other fixed value) at all times, in which case this obviously doesn’t work.

The driver also has no way of determining the degradation of the battery capacity over time, so you’ll have to deal with this yourself (by adjusting the values in runtimecal). Also note that the driver guesses the initial state of charge based on the battery voltage, so this may be less than 100%, even when you are certain that they are full. There is just no way to reliably measure this between 0 and 100% full charge.

This is better than nothing (but not by much). If any of the above calculations are giving you incorrect readings, remember that you are the one who put in the values in ups.conf(5), so don’t complain to the author. If you need something better, consider buy an UPS that reports battery.charge and battery.runtime all by itself without the help of a NUT driver.

## NOTES FOR THE PREVIOUS USER OF MEGATEC DRIVERS
The blazer drivers having replaced the megatec ones, some configuration changes may be required by users switching to blazer.

Part of this, the following megatec options, in ups.conf, have to be changed:

battvolts

You need to use default.battery.voltage.high and default.battery.voltage.low

dtr and rts

You need to use cablepower

ignoreoff

This parameter can simply be discarded, since it was a wrong understanding of the specification.

## KNOWN PROBLEMS
Some UPS commands aren’t supported by all models. In most cases, the driver will send a message to the system log when the user tries to execute an unsupported command. Unfortunately, some models don’t even provide a way for the driver to check for this, so the unsupported commands will silently fail.

Both the load.off and shutdown.stayoff instant commands are meant to turn the load off indefinitely. However, some UPS models don’t allow this.

Some models report a bogus value for the beeper status (will always be enabled or disabled). So, the beeper.toggle command may appear to have no effect in the status reported by the driver when, in fact, it is working fine.

The temperature and load value is known to be bogus in some models.

## AUTHORS
•Arjen de Korte <adkorte-guest at alioth.debian.org>

•Alexander Gordeev <lasaine at lvk.cs.msu.su>

## SEE ALSO
blazer_ser(8), nutupsdrv(8), upsc(8), upscmd(8), upsrw(8)

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

•The NUT HCL: https://www.networkupstools.org/stable-hcl.html


clone

package: nut-server

title: clone(8)

text:
# clone(8)

## NAME
clone - Clone an UPS, treating its outlet as if it were an UPS (with shutdown INSTCMD support)

## SYNOPSIS
clone -h

clone -a UPS_NAME [OPTIONS]

Note This man page only documents the specific features of the clone driver. For information about the core driver, see nutupsdrv(8).

## DESCRIPTION
This driver, which sits on top of another driver’s local UNIX socket file (or Windows named pipe), allows users to group clients to a particular outlet of a device and deal with this output as if it were a normal UPS.

Unlike the clone-outlet(8) driver, this driver represents a manageable device that can be used both for monitoring and for client computer and UPS/ePDU outlet shutdowns (it supports sending relevant instant commands during run time).

Unlike dummy-ups(8), this driver does not require a running upsd data server nor use the networked NUT protocol to talk to the "real" driver (which may be remote in case of dummy-ups repeater mode).

This driver does not create a completely new virtual device, but replaces or extends some of the original readings reported by the "real" driver using information from the specified outlet, and relays all other readings as they were.

Remote clients like upsmon can MONITOR the device entry presented by the data server with this driver (and the "real" driver) running and published.

A larger deployment with one or more lower-priority devices collected on a manageable outlet of an UPS or ePDU would likely see several drivers set up on the system actually capable of interactions with the UPS and running the NUT data server upsd(8) (and likely powered by another outlet):

•a "real" driver talking to the UPS;

•a clone driver talking to the "real" driver and issuing outlet power-off (or power-cycle) based on relatively high thresholds for remaining battery charge and/or runtime of the actual UPS (or explicit instant commands), with such operations first setting the respective timers for the outlet on the "real" driver, and the "FSD" flag among states of the virtual UPS status;

•possibly a clone-outlet driver which is read-only and interprets the outlet timer values as triggers for "FSD" or "OFF" flags reported among states of the virtual UPS status.

With this approach, the lower-priority systems collected on such outlet would run the NUT upsmon(8) client to MONITOR the virtual UPS presented by the read-only clone-outlet driver and shut down as soon as the "FSD" flag is raised (fairly early, based on charge and/or runtime thresholds configured for that driver) allowing the higher-priority devices (likely including the NUT server) to enjoy a longer on-battery life.

The clone driver responsible for outlet power state changes would not normally be monitored directly (e.g. to avoid unfortunate direct shutdown requests from those clients), although it can be (instead of clone-outlet) in sufficiently trusted networks.

## EXTRA ARGUMENTS
This driver supports the following settings:

port=drivername-devicename

Required. The standard NUT driver port setting, here it provides the name of the local Unix socket file (or Windows named pipe) for connection to the "real" device driver.

load.off=command

Recommended. Set the command on the "real" UPS driver that will be used to switch off the outlet. You need both load.off and load.on in order to power cycle the outlet. Otherwise, shutting down the clients powered by an outlet is a one way street (see IMPORTANT).

load.on=command

Recommended. Set the command on the "real" UPS driver that will be used to switch on the outlet. You need both load.off and load.on in order to power cycle the outlet. Otherwise, shutting down the clients powered by an outlet is a one way street (see IMPORTANT).

load.status=value

Recommended. Set the variable on the "real" UPS driver that will be used to indicate the outlet status (i.e. on/off). If not specified, the clone driver will attempt to keep track of the outlet status, but this is less reliable.

offdelay=num

Set the timer (in seconds) before the outlet is turned off after the shutdown condition (OB LB) for this outlet is met or a command to shutdown was issued. Defaults to 120 seconds.

ondelay=num

Set the timer (in seconds) for the outlet to switch on in case the power returns after the outlet has been switched off. Defaults to 30 seconds.

mincharge=value

Set the remaining battery level when the clone UPS switches to LB (percent).

minruntime=value

Set the remaining battery runtime when the clone UPS switches to LB (seconds).

## IMPLEMENTATION
The port specification in the ups.conf(5) should reference the local driver socket (or Windows named pipe) that the "real" UPS driver is using. For example:

```
  [realups]

     driver = usbhid-ups

     port = auto

  [clone-outlet-1]

     driver = clone

     port = usbhid-ups-realups

     load.on = outlet.1.load.on

     load.off = outlet.1.load.off

     load.status = outlet.1.status

     desc = "Outlet 1 of the Real UPS"

     [...]
```

This driver supports instant commands to initiate a forced shutdown for upsmon or similar clients which MONITOR this virtual UPS device, if the outlet status is currently on and no other shutdown was initiated yet (setting the virtual UPS shutdown delay timer to offdelay and issuing an FSD via ups.status):

•shutdown.return — power the outlet back on after ondelay;

•shutdown.stayoff — keep the outlet off.

Such commands are propagated to the "real" driver using the NUT socket protocol (using command names specified in the load.off and load.on driver configuration options), if the shutdown or start timers are set at the moment, or if the "real" device is not "online" and its known battery charge or runtime are below the configured "low" thresholds.

The outlet status is determined using the name specified by the load.status driver option if set, or is just assumed by latest completed shutdown/start operation (using unknown outlet number).

The driver does not support a common NUT device shutdown operation as such (clone -k just prints an error and bails out).

This driver also supports setting certain NUT variables at run-time:

•battery.charge.low — see mincharge in driver options;

•battery.runtime.low — see minruntime in driver options.

Compared to the "real" driver’s readings, this driver also adds (or overrides) the following data points: ups.delay.shutdown, ups.delay.start, ups.timer.shutdown and ups.timer.start. It keeps track of "real" driver’s values of battery.charge and battery.runtime (actual current readings) to decide on automated outlet shutdown later on.

## IMPORTANT
Unlike a real UPS, you should not configure a upsmon primary mode for this driver. When a upsmon(8) primary sees the OB LB flags and tells the upsd(8) data server that it is OK to initiate the shutdown sequence, the server will latch the FSD status, and it will not be possible to restart the systems connected without restarting the upsd server.

This will be a problem if the power returns after the clone UPS initiated the shutdown sequence on its outlet, but returns before the real UPS begins shutting down. The solution is in the clone driver itself, that will insert the FSD flag if needed without the help of an upsmon primary.

## CAVEATS
The clone UPS will follow the status on the real UPS driver. You can only make the clone UPS shutdown earlier than the real UPS driver, not later. If the real UPS driver initiates a shutdown, the clone UPS driver will immediately follow.

Be aware that the commands to shutdown/restart an outlet on the real UPS drivers are not affected, so if you tell the real UPS driver to shutdown the outlet of the clone UPS driver, your clients will lose power without warning.

If you use service management frameworks like systemd or SMF to manage the dependencies between driver instances and other units, then you may have to set up special dependencies (e.g. with systemd "drop-in" snippet files) to queue your clone drivers to start after the "real" device drivers.

## AUTHOR
Arjen de Korte <adkorte-guest@alioth.debian.org>

## SEE ALSO
upscmd(8), upsrw(8), ups.conf(5), clone-outlet(8), nutupsdrv(8)

### Dummy driver:
The "repeater" mode of dummy-ups driver is in some ways similar to the clone and clone-outlet drivers, by relaying information from a locally or remotely running "real" device driver (and NUT data server).

dummy-ups(8)

### Internet Resources:
The NUT (Network UPS Tools) home page: https://www.networkupstools.org/historic/v2.8.5/


clone-outlet

title: clone-outlet(8)

text:
# clone-outlet(8)

## NAME
clone-outlet - Clone an UPS, treating its outlet as if it were an UPS (monitoring only)

## SYNOPSIS
clone-outlet -h

clone-outlet -a UPS_NAME [OPTIONS]

Note This man page only documents the specific features of the clone-outlet driver. For information about the core driver, see nutupsdrv(8).

## DESCRIPTION
This driver, which sits on top of another driver’s local UNIX socket file (or Windows named pipe), allows users to group clients to a particular outlet of a device and deal with this output as if it were a normal UPS.

Unlike the clone(8) driver or dummy-ups(8) driver running in repeater mode, this driver represents a read-only device for monitoring and shutdowns (it does not accept setting any values or sending instant commands during run time).

Unlike dummy-ups(8) generally, this driver does not require a running upsd data server nor use the networked NUT protocol to talk to the "real" driver (which may be remote in case of dummy-ups repeater mode).

This driver does not create a completely new virtual device, but replaces or extends some of the original readings reported by the "real" driver using information from the specified outlet, and relays all other readings as they were.

Remote clients like upsmon can MONITOR the device entry presented by the data server with this driver (and the "real" driver) running and published.

A larger deployment with one or more lower-priority devices collected on a manageable outlet of an UPS or ePDU would likely see several drivers set up on the system actually capable of interactions with the UPS and running the NUT data server upsd(8) (and likely powered by another outlet):

•a "real" driver talking to the UPS;

•a clone driver talking to the "real" driver and issuing outlet power-off (or power-cycle) based on relatively high thresholds for remaining battery charge and/or runtime of the actual UPS (or explicit instant commands), with such operations first setting the respective timers for the outlet on the "real" driver, and the "FSD" flag among states of the virtual UPS status;

•possibly a clone-outlet driver which is read-only and interprets the outlet timer values as triggers for "FSD" or "OFF" flags reported among states of the virtual UPS status.

With this approach, the lower-priority systems collected on such outlet would run the NUT upsmon(8) client to MONITOR the virtual UPS presented by the read-only clone-outlet driver and shut down as soon as the "FSD" flag is raised (fairly early, based on charge and/or runtime thresholds configured for that driver) allowing the higher-priority devices (likely including the NUT server) to enjoy a longer on-battery life.

The clone driver responsible for outlet power state changes would not normally be monitored directly (e.g. to avoid unfortunate direct shutdown requests from those clients), although it can be (instead of clone-outlet) in sufficiently trusted networks.

## EXTRA ARGUMENTS
This driver supports the following settings:

port=drivername-devicename

Required. The standard NUT driver port setting, here it provides the name of the local Unix socket (or named Windows pipe) for connection to the "real" driver.

prefix=outlet.N

Required. Specify the outlet prefix as known on the original driver. The subset of data points reported by the "real" UPS driver for the actual device on this prefix would be reported as data points of the virtual UPS maintained by this driver.

## IMPLEMENTATION
The port specification in the ups.conf(5) should reference the local driver socket (or Windows named pipe) that the "real" UPS driver is using. For example:

```
  [realups]

     driver = usbhid-ups

     port = auto

  [clone-outlet-1]

     driver = clone-outlet

     port = usbhid-ups-realups

     prefix = outlet.1

     desc = "Outlet 1 of the Real UPS"

     [...]
```

The driver internally interprets "real" driver’s information about shutdown delay and shutdown timer, whole UPS status and this outlet’s status, and relays other data points as they were.

If the outlet supports and reports a delayed power-off, the virtual UPS would issue an FSD via ups.status for its clients to shut down safely.

In more detail:

Given the (required) prefix value such as outlet.1, the driver would specifically keep track of <prefix>.status, <prefix>.delay.shutdown, and <prefix>.timer.shutdown data points reported by the "real" driver. Numeric values of the *.shutdown readings would be noted by this driver, and the boolean outlet status ("off" or otherwise) will be remembered. These values will also be re-published by this driver "as is".

The ups.status from the "real" driver would be remembered, but not re-published by this driver immediately. Instead, it would be published during regular "update info" loop cycles either:

•with the "OFF" state added (if <prefix>.status indicates the outlet is "off"),

•or with the "FSD" state prepended (if <prefix>.timer.shutdown is non-negative and does not exceed the <prefix>.delay.shutdown value),

•or "as is" if the outlet power state is "not critical".

## IMPORTANT
Unlike a real UPS, you should not configure a upsmon primary mode for this driver. When a upsmon(8) primary sees the OB LB flags and tells the upsd(8) server it is OK to initiate the shutdown sequence, the server will latch the FSD status, and it will not be possible to restart the systems connected without restarting the upsd server.

This will be a problem if the power returns after the clone UPS initiated the shutdown sequence on its outlet, but returns before the real UPS begins shutting down. The solution is in the clone driver, that will insert the FSD flag if needed without the help of an upsmon primary.

## CAVEATS
The clone UPS will follow the status on the real UPS driver. You can only make the clone UPS shutdown earlier than the real UPS driver, not later. If the real UPS driver initiates a shutdown, the clone-outlet UPS driver will immediately follow.

Be aware that the commands to shutdown/restart an outlet on the real UPS drivers are not affected, so if you tell the real UPS driver to shutdown the outlet of the clone UPS driver immediately, your clients will lose power without warning. A delayed outlet power-off should propagate as FSD, and the delay should be sufficiently long to allow for client shutdowns.

If you use service management frameworks like systemd or SMF to manage the dependencies between driver instances and other units, then you may have to set up special dependencies (e.g. with systemd "drop-in" snippet files) to queue your clone drivers to start after the "real" device drivers.

## AUTHOR
Arjen de Korte <adkorte-guest@alioth.debian.org>

## SEE ALSO
upscmd(8), upsrw(8), ups.conf(5), clone(8), nutupsdrv(8)

### Dummy driver:
The "repeater" mode of dummy-ups driver is in some ways similar to the clone and clone-outlet drivers, by relaying information from a locally or remotely running "real" device driver (and NUT data server).

dummy-ups(8)

### Internet Resources:
The NUT (Network UPS Tools) home page: https://www.networkupstools.org/historic/v2.8.5/


dummy-ups

title: dummy-ups(8)

summary: Driver for multi\-purpose UPS emulation or relay

text:
# dummy-ups(8)

## NAME
dummy-ups - Driver for multi-purpose UPS emulation or relay

## SYNOPSIS
dummy-ups -h

dummy-ups -a UPS_NAME [OPTIONS]

Note This man page only documents the specific features of the dummy-ups driver. For information about the core driver, see nutupsdrv(8).

## DESCRIPTION
This program is a multi-purpose UPS emulation tool. Its general behavior depends on the running mode: "dummy" ("dummy-once" or "dummy-loop"), or "repeater".

### Dummy Mode
In this mode, dummy-ups looks like a standard NUT device driver to upsd(8) and allows one to change any value for testing purposes.

It is both interactive, controllable through the upsrw(8) and upscmd(8) commands (or equivalent graphical tool), and batchable through script files.

It can be configured, launched and used as any other "real" NUT driver. This mode is mostly useful for development and testing purposes.

Note See below about the differences of dummy-once vs. dummy-loop modes — the former may be more suitable for "interactive" uses and tests.

### Repeater Mode
In this mode, dummy-ups acts as a NUT client, simply forwarding data.

This can be useful for supervision purposes. This mode can also allow some load sharing between several upsd instances communicating with ultimate NUT clients, with a "central" one using a point-to-point communication with the actual UPS or ePDU device.

This arrangement can also help with networked UPSes, whose network management cards can be overwhelmed with a whole farm of servers directly polling SNMP or other networked protocols every few seconds.

## IMPLEMENTATION
The port specification in ups.conf depends on the running mode, and allows the driver to select the right mode of operation.

Since NUT v2.8.0, the mode specification in ups.conf allows users to override the mode of operation which would be otherwise guessed by the driver.

### Dummy Mode
In this context, port in the ups.conf block specifies a "definition file" name for the dummy-ups to read data from. This can either be an absolute or a relative path name. In the latter case the NUT sysconfig directory (i.e. /etc/nut, /usr/local/ups/etc, ...) is prepended.

Note The "sysconfig" location is built-in according to configure script arguments, but can be tuned at run time by NUT_CONFPATH environment variable. See the tests/NIT/nit.sh script in NUT sources, which heavily relies on this driver, for more examples.

Since NUT v2.8.0 two aspects of this mode are differentiated:

•dummy-once reads the specified file once to the end (interrupting for TIMER lines, etc.) and does not re-process it until the filesystem timestamp of the data file is changed; this reduces run-time stress if you test with a lot of dummy devices, and allows use/test cases to upsrw variables into the driver instance — and they remain in memory until the driver is restarted (or the file is touched or modified); Since NUT v2.8.0 dummy-once is assigned by default to files with a *.dev naming pattern.

•dummy-loop reads the specified file again and again, with a short sleep between the processing cycles; for sequence files using a TIMER keyword (see below), or for use/test cases which modify file contents with external means, this allows an impression of a device whose state changes over time. Before NUT v2.8.0 this was the only aspect, so a simple dummy mode value maps to this behavior for backwards compatibility.

Since NUT v2.8.0 dummy-loop is assigned by default to files with a *.seq naming pattern, and dummy is assigned by default to files with other naming patterns that the driver could not classify.

Note Said defaulting based on filename pattern can break third-party test scripts which earlier expected *.dev files to work as a looping sequence with a TIMER keywords to change values slowly. Now such files should get processed to the end once.

Specify mode=dummy-loop driver option or rename the data file used in the port option for legacy behavior.

Use/Test-cases which modified such files content externally should not be impacted.

For instance:

```
        [dummy1]

                driver = dummy-ups

                port = evolution500.seq

                desc = "dummy-ups in dummy-loop mode"

        [dummy2]

                driver = dummy-ups

                port = epdu-managed.dev

                desc = "dummy-ups in dummy-once mode"
```

This definition file, specified by the port argument in the example above, is generally named something.dev or something.seq. It contains a list of all valid variables and associated values (you can later use upsrw only to modify values of these variables), and has the same format as an upsc(8) data dump (<varname>: <value>). This means you can easily create definition files from an existing UPS using upsc > file.dev.

Note that the Network UPS project provides an extensive DDL (Devices Dumps Library) with files which can be used for modelling real devices. Entries for the DDL library are best prepared with the tools/nut-ddl-dump.sh script from NUT sources instead of plain upsc, to provide some additional data points from other NUT clients as well.

The file can also be empty, in which case only a basic set of data is available: device.*, driver.*, ups.mfr, ups.model, ups.status as filled by the driver itself.

Some sample definition files are available in the data directory of the NUT source tree, and generally in the "sysconfig" or "share" directory of your system distribution.

Since dummy-ups will usually loop on reading this file, you can dynamically modify it with some external process to "interact" with the driver. This will avoid message spam into your system log files, if you are using NUT default configuration.

Note By default since NUT v2.8.0, it will not loop on files in dummy-once mode, e.g. those with a .dev extension, unless their timestamp changes.

You can also use the TIMER <seconds> instruction to create scheduled event sequences (such files are traditionally named with the .seq extension). For example, the following sequence will loop on switching ups.status between "OL", "OB" and "OB LB" every minute:

```
ups.status: OL
TIMER 60
ups.status: OB
TIMER 60
ups.status: OB LB
TIMER 60
```

It is wise to end the script for dummy-loop mode with a TIMER keyword. Otherwise dummy-ups will directly go back to the beginning of the file and, in particular, forget any values you could have just set with upsrw.

Note that to avoid CPU overload with an infinite loop, the driver "sleeps" a bit between file-reading cycles (currently this delay is hardcoded to one second), independently of (and/or in addition to) any TIMER keywords and possibly the common pollinterval setting.

Another, more recently introduced instruction is ALARM, which allows the simulation of UPS alarms in much the same way they would be raised by real driver implementations. Modern drivers decouple alarm states from the ups.status variable, and raising ALARM by setting it as a status token is discouraged in favor of using modern, common functions for raising alarms within the driver code.

The ALARM instruction is intended to simulate this behavior as closely as possible. The value following an ALARM instruction is treated as the alarm message and is eventually published as the ups.alarm variable, with the ALARM token also set in ups.status by internal driver mechanisms, rather than by directly manipulating the variable. Multiple ALARM instructions will have their messages combined into the ups.alarm variable, just as would happen with real driver logic.

Conversely, any ALARM instruction on its own will clear active alarm states. See below for an example of setting and resetting alarms:

```
ALARM [UPS too warm to charge]
ALARM [UPS circuit is overheating]
TIMER 5
ALARM
TIMER 5
ALARM [UPS too cold to charge]
```

### Repeater Mode
In this context, port in the ups.conf block is the name of the target UPS, using the NUT format, i.e.:

```
<upsname>@<hostname>[:<port>]
```

For instance:

```
[repeater]

        driver = dummy-ups

        port = ups1@remotehost

        desc = "dummy-ups in repeater mode"
```

Unlike UPS specifications in the rest of NUT, the @hostname portion is not optional — it is the @ character which enables Repeater Mode. To refer to an UPS on the same host as dummy-ups, use port = upsname@localhost.

Note that to avoid CPU overload with an infinite loop, the driver "sleeps" a bit between data-requesting cycles (currently this delay is hardcoded to one second), so propagation of data updates available to a remote upsd may lag by this much.

Beware that any error encountered at repeater mode startup (e.g. when not all target UPS to be repeated or their upsd instances are connectable yet) will by default cause the dummy-ups driver to terminate prematurely. This behaviour can be changed by setting the repeater_disable_strict_start flag, making such errors non-fatal.

## INTERACTION
Once the driver is loaded in dummy mode, you can change any variables, except those of the driver.* and server.* collections. You can do this by either editing the definition file, or use the upsrw(8) and upscmd(8) commands.

Note that in simulation mode, new variables can be added on the fly, but only by adding these to the definition file (and waiting for it to be re-read). That is, the driver should not allow to define a new variable via upsrw.

Conversely, if you need to remove a variable (such as transient ones, like ups.alarm), simply update these by setting an empty value. As a result, they will get removed from the data.

In repeater mode, the driver acts according to the capabilities of the UPS, and so supports the same instant commands and settable values.

## BACKGROUND
Dummy Mode was originally written in one evening to replace the previous dummycons testing driver, which was too limited, and required a terminal for interaction.

dummy-ups is useful for NUT client development, and other testing purposes.

It also helps the NUT Quality Assurance effort, by automating some tests on the NUT framework and the NIT (NUT Integration Test suite). See the tests/NIT/nit.sh script in NUT sources, which heavily relies on this driver, for more examples.

It now offers a repeater mode. This will help in building the Meta UPS approach, which allows one to build a virtual device, composed of several other devices (either UPS, PDUs), or perhaps represent the same device which supports several communication protocols and different media (Serial, USB, SNMP...)

## BUGS
Instant commands are not yet supported in Dummy Mode, and data need name/value checking enforcement, as well as boundaries or enumeration definition.

## CAVEATS
If you use service management frameworks like systemd or SMF to manage the dependencies between driver instances and the data server, and some of these drivers are dummy-ups in repeater mode representing data from another driver running on the same system, then you may have to set up special dependencies (e.g. with systemd "drop-in" snippet files) to allow your nut-server to start after the "real" device drivers and before such repeater drivers (without a responding server, they would fail to start anyway). This may also need special care in upsd.conf and/or ups.conf files to not block the system start-up for too long while the repeater driver has not started.

## AUTHOR
Arnaud Quette

## SEE ALSO
upscmd(8), upsrw(8), ups.conf(5), nutupsdrv(8)

### Clone drivers:
The "repeater" mode of dummy-ups driver is in some ways similar to the clone and clone-outlet drivers, which sit on top of another driver socket (or named Windows pipe) locally, and allow users to group clients to a particular outlet of a device and deal with this output as if it were a normal UPS. Notably, in this mode the dummy-ups driver is a client to the networked NUT protocol and can relay information of local or remotely served devices, and requires a running NUT data server upsd to represent the "real" device for this to work.

clone(8), clone-outlet(8)

### Internet Resources:
The NUT (Network UPS Tools) home page: https://www.networkupstools.org/historic/v2.8.5/


etapro

title: etapro(8)

summary: Driver for ETA UPS equipment

text:
# etapro(8)

## NAME
etapro - Driver for ETA UPS equipment

## SYNOPSIS
etapro -h

etapro -a UPS_NAME [OPTIONS]

Note This man page only documents the hardware-specific features of the etapro driver. For information about the core driver, see nutupsdrv(8).

## SUPPORTED HARDWARE
This driver supports ETA UPS equipment with the "PRO" option for smart mode.

## EXTRA ARGUMENTS
This driver does not support any extra settings in the ups.conf(5).

## AUTHOR
Marek Michalkiewicz <marekm@amelek.gda.pl>

## SEE ALSO

### The core driver:
nutupsdrv(8)

### Internet resources:
The NUT (Network UPS Tools) home page: https://www.networkupstools.org/historic/v2.8.5/


everups

title: everups(8)

summary: Driver for Ever UPS models

text:
# everups(8)

## NAME
everups - Driver for Ever UPS models

## SYNOPSIS
everups -h

everups -a UPS_NAME [OPTIONS]

Note This man page only documents the hardware-specific features of the everups driver. For information about the core driver, see nutupsdrv(8).

## SUPPORTED HARDWARE
This driver should recognize the NET *-DPC and AP *-PRO models.

## EXTRA ARGUMENTS
This driver does not support any extra settings in the ups.conf(5).

## BUGS
This UPS can only switch off the load if it’s running on battery. This means you may be vulnerable to power races if your shutdown scripts don’t sleep and force a reboot.

## AUTHOR
Bartek Szady <bszx@bszxdomain.edu.eu.org>

## SEE ALSO

### The core driver:
nutupsdrv(8)

### Internet resources:
The NUT (Network UPS Tools) home page: https://www.networkupstools.org/historic/v2.8.5/


failover

title: failover(8)

summary: UPS Failover Driver

text:
# failover(8)

## NAME
failover - UPS Failover Driver

## SYNOPSIS
failover -h

failover -a UPS_NAME [OPTIONS]

Note This man page only documents the specific features of the failover driver. For information about the core driver, see nutupsdrv(8).

## 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:

•Socket availability and communication status

•Data freshness and UPS online/offline indicators

•User-defined status filters (e.g., presence or absence of OL, LB, ...)

•Administrative override via control commands (force.primary, force.ignore)

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:

•Keep last primary and declare the data as stale

•Raise ALARM and declare the data as stale

•Raise ALARM and set forced shutdown (FSD)

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,...

Required. Specifies the local sockets (or Windows named pipes) of the underlying UPS drivers to be tracked. Entries must either be a path or follow the format drivername-devicename, as used by NUT’s internal socket naming convention (e.g. usbhid-ups-myups). Multiple entries are comma-separated with no spaces.

inittime=seconds

Optional. Sets a grace period after driver startup during which the absence of a primary is tolerated. This allows time for underlying drivers to initialize. For networked connections or drivers that require "lock-picking" their communication protocol, consider increasing this value to accommodate potential longer delays. Defaults to 30 seconds.

deadtime=seconds

Optional. Sets a grace period in seconds after which a non-responsive UPS driver is considered dead. Defaults to 30 seconds.

relogtime=seconds

Optional. Time interval in which repeated connection failure logs are emitted for a UPS, reducing log spam during unstable conditions. Defaults to 5 seconds.

noprimarytime=seconds

Optional. Duration to wait without a suitable primary UPS driver before entering the configured fallback mode (fsdmode). Defaults to 15 seconds.

maxconnfails=count

Optional. Number of consecutive connection failures allowed per UPS driver before entering into the cooldown period (coolofftime). Defaults to 5.

coolofftime=seconds

Optional. Cooldown period during which the driver pauses reconnect attempts after exceeding maxconnfails. Defaults to 15 seconds.

fsdmode=0|1|2

Optional. Defines the behavior when no suitable primary UPS driver is found after noprimarytime has elapsed. Defaults to 0.

•0: Do not demote the last primary, but mark its data as stale. This is similar to how a regular UPS driver would behave when it loses its connection to the target UPS device. upsmon(8) will act on the last known (online or not) status, and decide itself whether that UPS should be considered critical.

•1: Demote the primary, raise ALARM, and mark the data as stale after an additional few seconds have elapsed (ensuring full propagation). This will cause upsmon(8) to detect that a device previously in an alarm state has lost its connection, consider the UPS driver critical, and possibly trigger a forced shutdown (FSD) due to depletion of MINSUPPLIES.

•2: Demote the primary, raise ALARM, and immediately set FSD. This will set FSD from the driver side and preempt upsmon(8) from raising it 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 (read more about this in the section PRIORITIES). Defaults to 0.

status_have_any=OL,CHRG,...

Optional. If any of these comma-separated tokens are present in a UPS driver’s ups.status, it passes this status filtering criteria. Defaults to unset.

status_have_all=OL,CHRG,...

Optional. All listed comma-separated tokens must be present in ups.status for the UPS driver to pass this status filtering criteria. Defaults to unset.

status_nothave_any=OB,OFF,...

Optional. If any of these comma-separated tokens are present in ups.status, the UPS driver does not pass this status filtering criteria. Defaults to unset.

status_nothave_all=OB,LB,...

Optional. If all of these comma-separated tokens are present in ups.status, the UPS driver does not pass this status filtering criteria. Defaults to unset.

Note The status_* arguments are primarily intended to adjust the weighting of UPS drivers, allowing some to be prioritized over others based on their status. For example, a driver reporting OL might be preferred over one reporting ALARM OL. While strictfiltering can be enabled, status filters are most effective when used in combination with the default set of connectivity-based PRIORITIES. For more details, see the respective section further below.

## 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:

•<socketname>.force.ignore [seconds] prevents the specified UPS driver from being selected as primary for the given duration, or permanently if a negative value is used. A value of 0 resets this override and re-enables selection.

•<socketname>.force.primary [seconds] forces the specified UPS driver to be treated with the highest priority for the given duration, or permanently if a negative value is used. A value of 0 resets this override.

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:

•0 (highest): UPS driver was forced to the top by administrative command.

•1: UPS driver has passed the user-defined status filters.

•2: UPS driver has fresh data and is online (in status OL).

•3: UPS driver has fresh data, but may not be fully online.

•4 (lowest): UPS driver is alive, but may not have fresh data.

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:

1.status_nothave_any (first)

2.status_have_all

3.status_nothave_all

4.status_have_any (last)

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.

Note The base requirement for any election is the UPS socket being connectable and the UPS driver having published at least one full batch of data during its lifetime. UPS driver not fulfilling that requirement are always disqualified.

## 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)

### Internet Resources:
The NUT (Network UPS Tools) home page: https://www.networkupstools.org/historic/v2.8.5/


gamatronic

title: gamatronic(8)

summary: Driver for Gamatronic UPS equipment

text:
# gamatronic(8)

## NAME
gamatronic - Driver for Gamatronic UPS equipment

## SYNOPSIS
gamatronic -h

gamatronic -a UPS_NAME [OPTIONS]

Note This man page only documents the hardware-specific features of the gamatronic driver. For information about the core driver, see nutupsdrv(8).

## SUPPORTED HARDWARE
Various — Rebuilt to work with Gamatronic UPS Units, but should recognize any UPS that speaks the SEC protocol at 1200-19200 bps.

## EXTRA ARGUMENTS
This driver does not support any extra settings in the ups.conf(5).

## AUTHOR
Nadav Moskovitch <blutz@walla.com>

## SEE ALSO

### The core driver
nutupsdrv(8)

### Internet resources
The NUT (Network UPS Tools) home page: https://www.networkupstools.org/historic/v2.8.5/


genericups

title: genericups(8)

summary: Driver for contact\-closure UPS equipment

text:
# genericups(8)

## NAME
genericups - Driver for contact-closure UPS equipment

## SYNOPSIS
genericups -h

genericups -a UPS_NAME [OPTIONS]

Note This man page only documents the specific features of the genericups driver. For information about the core driver, see nutupsdrv(8).

## SUPPORTED HARDWARE
This driver supports hardware from many different manufacturers as it only uses the very simplest of signaling schemes. Contact closure refers to a kind of interface where basic high/low signals are provided to indicate status. This kind of UPS can only report line power and battery status.

This means that you will only get the essentials in ups.status: OL, OB, and LB (some UPSes may also support RB and BYPASS). Anything else requires a smarter UPS.

## CABLING
Cabling is different for every kind of UPS. See the table below for information on what is known to work with a given UPS type.

## EXTRA ARGUMENTS
This driver supports the following settings in the ups.conf(5):

upstype=type

Required. Configures the driver for a specific kind of UPS. See the UPS Types section below for more information on which entries are available.

mfr=string

Optional. The very nature of a generic UPS driver sometimes means that the stock manufacturer data has no relation to the actual hardware that is attached. With the mfr setting, you can change the value that is seen by clients that monitor this UPS.

model=string

Optional. This is like mfr above, but it overrides the model string instead.

serial=string

Optional. This is like mfr above and intended to record the identification string of the UPS. It is titled "serial" because usually this string is referred to as the serial number.

sdtime=value

Optional. The driver will sleep for this many seconds after setting the shutdown signal. This is necessary for some hardware which requires a sustained level to activate the shutdown sequence. The default behavior of the driver is to exit immediately. If this doesn’t reliably trigger a shutdown in your UPS hardware, use this setting to give it more time to react.

Note Very large values for sdtime may create warnings from upsdrvctl if it gets tired of waiting for the driver to return.

## CUSTOM CONFIGURATIONS
You may override the values for CP, OL, LB, and SD by defining them in the ups.conf(5) after the upstype setting.

For example, to set the cable power to DTR and the low battery value to DCD, it would look like this:

```
        CP = DTR

        LB = DCD
```

Recognized values for input lines are CTS, DCD, and RNG. Recognized values for output lines are DTR, RTS, and ST. See below for more about what these signals mean.

These values may be negated for active low signals. That is, LB=-DCD recognizes a low battery condition when DCD is not held high.

## TYPE INFORMATION
The essence of a UPS definition in this driver is how it uses the serial lines that are available. These are the abbreviations you will see below:

OL

On line (no power failure) (opposite of OB — on battery)

LB

Low battery

RB

Replace battery

BYPASS

Battery bypass active or no battery installed

SD

Shutdown load

CP

Cable power (must be present for cable to have valid reading)

CTS

Clear to Send. Received from the UPS.

RTS

Ready to Send. Sent by the PC.

DCD

Data Carrier Detect. Received from the UPS.

RNG

Ring indicate. Received from the UPS.

DTR

Data Terminal Ready. Sent by the PC.

DSR

Data Set Ready. Received from the UPS.

ST

Send a BREAK on the transmit data line

NULL

Disable this signal. Disabled signal will always be low except for OL which will always be high.

none

Alias to NULL which matches some other documentation.

A - in front of a signal name (like -RNG) means that the indicated condition is signaled with an active low signal. For example, [LB=-RNG] means the battery is low when the ring indicate line goes low, and that the battery is OK when that line is held high.

## UPS TYPES
0 = UPSonic LAN Saver 600

```
[CP=DTR+RTS] [OL=-CTS] [LB=DCD] [SD=DTR]
```

1 = APC Back-UPS/Back-UPS Pro/Smart-UPS with 940-0095A/C cable

```
[CP=DTR] [OL=-RNG] [LB=DCD] [SD=RTS]
```

2 = APC Back-UPS/Back-UPS Pro/Smart-UPS with 940-0020B cable (Note: Type 2 has also been reported to work with the 940-0020C cable).

```
[CP=RTS] [OL=-CTS] [LB=DCD] [SD=DTR+RTS]
```

3 = PowerTech Comp1000 with DTR cable power

```
[CP=DTR] [OL=CTS] [LB=DCD] [SD=DTR+RTS]
```

4 = Generic RUPS Model

```
[CP=RTS] [OL=CTS] [LB=-DCD] [SD=-RTS]
```

5 = Tripp Lite UPS with Lan2.2 interface (black 73-0844 cable)

```
[CP=DTR] [OL=CTS] [LB=-DCD] [SD=DTR+RTS]
```

6 = Best Patriot with INT51 cable

```
[CP=DTR] [OL=CTS] [LB=-DCD] [SD=RTS]
```

7 = CyberPower Power99 Also Upsonic Power Guardian PG-500, Belkin Belkin Home Office, F6H350-SER, F6H500-SER, F6H650-SER, Eaton Management Card Contact — Config3 with cable 66033 (shutdown does not work)

```
[CP=RTS] [OL=CTS] [LB=-DCD] [SD=DTR]
```

8 = Nitram Elite 500

```
[CP=DTR] [OL=CTS] [LB=-DCD] [SD=???]
```

9 = APC Back-UPS/Back-UPS Pro/Smart-UPS with 940-0023A cable

```
[CP=none] [OL=-DCD] [LB=CTS] [SD=RTS]
```

10 = Victron Lite with crack cable

```
[CP=RTS] [OL=CTS] [LB=-DCD] [SD=DTR]
```

11 = Powerware 3115

```
[CP=DTR] [OL=-CTS] [LB=-DCD] [SD=ST]
```

12 = APC Back-UPS Office with 940-0119A cable

```
[CP=RTS] [OL=-CTS] [LB=DCD] [SD=DTR]
```

13 = RPT Repoteck RPT-800A/RPT-162A

```
[CP=DTR+RTS] [OL=DCD] [LB=-CTS] [SD=ST]
```

14 = Online P-series

```
[CP=DTR] [OL=DCD] [LB=-CTS] [SD=RTS]
```

15 = Powerware 5119, 5125

```
[CP=DTR] [OL=CTS] [LB=-DCD] [SD=ST]
```

16 = Nitram Elite 2002

```
[CP=DTR+RTS] [OL=CTS] [LB=-DCD] [SD=???]
```

17 = PowerKinetics 9001

```
[CP=DTR] [OL=CTS] [LB=-DCD] [SD=???]
```

18 = TrippLite Omni 450LAN with Martin’s cabling

```
[CP=DTR] [OL=CTS] [LB=DCD] [SD=none]
```

19 = Fideltronic Ares Series

```
[CP=DTR] [OL=CTS] [LB=-DCD] [SD=RTS]
```

20 = Powerware 5119 RM (check docs/cables/powerware.txt in NUT sources)

```
[CP=DTR] [OL=-CTS] [LB=DCD] [SD=ST]
```

21 = Generic RUPS 2000 (Megatec M2501 cable)

```
[CP=RTS] [OL=CTS] [LB=-DCD] [SD=RTS+DTR]
```

22 = Gamatronic All models with alarm interface (also CyberPower SL series)

```
[CP=RTS] [OL=CTS] [LB=-DCD] [SD=DTR]
```

23 = Generic FTTx (Fiber to the x) battery backup with 4-wire telemetry interface

```
[CP=RTS] [OL=CTS] [LB=-DCD] [RB=-RNG] [BYPASS=-DSR] [SD=none]
```

## SIMILAR MODELS
Many different UPS companies make models with similar interfaces. The RUPS cable seems to be especially popular in the "power strip" variety of UPS found in office supply stores. If your UPS works with an entry in the table above, but the model or manufacturer information don’t match, don’t despair. You can fix that easily by using the mfr and model variables documented above in your ups.conf(5).

## TESTING COMPATIBILITY
If your UPS isn’t listed above, you can try going through the list until you find one that works. There is a lot of cable and interface reuse in the UPS world, and you may find a match.

To do this, first make sure nothing important is plugged into the outlets on the UPS, as you may inadvertently switch it off. Definitely make sure that the computer you’re using is not plugged into that UPS. Plug in something small like a lamp so you know when power is being supplied to the outlets.

Now, you can either attempt to make an educated guess based on the documentation your manufacturer has provided (if any), or just start going down the list.

### Step 1
Pick a driver to try from the list (run genericups -h) and go to step 2.

### Step 2
Start the driver with the type you want to try, e.g.:

```
genericups -x upstype=n /dev/port
```

Let upsd(8) sync up (watch the syslog), and then run upsc(8) to see what it found. If the STATUS is correct (should be "OL" for online), continue to Step 3, otherwise go back to step 1.

Alternatively, you can run genericups in debug mode, e.g.:

```
genericups -DDDDD -x upstype=n /dev/port
```

In this mode it will be running in the foreground and continuously display the line and battery status of the UPS.

### Step 3
Disconnect the UPS from the wall/mains power. This is easiest if you have a switched outlet in between it and the wall, but you can also just pull the plug to test. The lamp should stay lit, and the status should switch to "OB". If the lamp went out or the status didn’t go to "OB" within about 15 seconds, go to Step 1. Otherwise, continue to Step 4.

### Step 4
At this point, we know that OL and OB work. If nothing else beyond this point works, you at least know what your OL/OB value should be.

Wait for the UPS to start complaining about a low battery. Depending on the size of your UPS battery and the lamp’s bulb, this could take awhile. It should start complaining audibly at some point. When this happens, STATUS should show "OB LB" within 15 seconds. If not, go to Step 1, otherwise continue to Step 5.

### Step 5
So far: OL works, OB works, and LB works.

With the UPS running on battery, run the genericups driver with the -k switch to shut it down.

```
genericups -x upstype=n -k /dev/port
```

If the UPS turns off the lamp, you’re done. At this point, you have verified that the shutdown sequence actually does what you want. You can start using the genericups driver with this type number for normal operations.

You should use your findings to add a section to your ups.conf. Here is a quick example:

```
[myups]

        driver = genericups

        port = /dev/ttyS0

        upstype = 1
```

Change the port and upstype values to match your system.

## NEW SUPPORT
If the above testing sequence fails, you will probably need to create a new entry to support your hardware. All UPS types are determined from the table in the genericups.h file in the source tree.

On a standard 9 pin serial port, there are 6 lines that are used as the standard "high/low" signal levels. 4 of them are incoming (to the PC, from the UPS), and the other 2 are outgoing (to the UPS, from the PC). The other 3 are the receive/transmit lines and the ground.

Be aware that many manufacturers remap pins within the cable. If you have any doubts, a quick check with a multimeter should confirm whether the cable is straight-through or not. Another thing to keep in mind is that some cables have electronics in them to do special things. Some have resistors and transistors on board to change behavior depending on what’s being supplied by the PC.

## SPECIFIC MODEL NOTES
These have been contributed by users of this driver.

The Centralion CL series may power down the load if the driver starts up with the UPS running on battery as the default line settings contain the shutdown sequence. - Neil Muller

The Tripp-Lite Internet Office 700 must be used with the black 73-0844 cable instead of the gray 73-0743 cable. This entry should work with any of their models with the Lan 2.2 interface — see the sticker by the DB9 connector on the UPS. - Stephen Brown

Type 5 should work with the Tripp-Lite Lan 2.1 interface and the 73-0724 cable. This was tested with the OmniSmart 675 PNP on Red Hat 7.2. - Q Giese

Types 7 and 10 should both work with the PhoenixTec A1000.

## BUGS
There is no way to reliably detect a contact-closure UPS. This means the driver will start up happily even if no UPS is detected. It also means that if the connection between the UPS and computer is interrupted, you may not be able to sense this in software.

Most contact-closure UPSes will not power down the load if the line power is present. This can create a race when using secondary upsmon(8) systems. See the upsmon(8) man page for more information.

The solution to both of these problems is to upgrade to a smart protocol UPS of some kind that allows detection and proper load cycling on command.

## SEE ALSO

### The core driver
nutupsdrv(8)

### Internet resources:
The NUT (Network UPS Tools) home page: https://www.networkupstools.org/historic/v2.8.5/


isbmex

title: isbmex(8)

summary: Driver for ISBMEX UPS equipment

text:
# isbmex(8)

## NAME
isbmex - Driver for ISBMEX UPS equipment

## SYNOPSIS
isbmex -h

isbmex -a UPS_NAME [OPTIONS]

Note This man page only documents the hardware-specific features of the isbmex driver. For information about the core driver, see nutupsdrv(8).

## SUPPORTED HARDWARE
This driver supports SOLA/BASIC Mexico ISBMEX protocol UPS equipment.

## EXTRA ARGUMENTS
This driver does not support any extra settings in the ups.conf(5).

## AUTHOR
Edscott Wilson Garcia <edscott@imp.mx>

## SEE ALSO

### The core driver:
nutupsdrv(8)

### Internet resources:
The NUT (Network UPS Tools) home page: https://www.networkupstools.org/historic/v2.8.5/


ivtscd

title: ivtscd(8)

text:
# ivtscd(8)

## NAME
ivtscd - Driver for the IVT Solar Controller Device

## SYNOPSIS
ivtscd -h

ivtscd -a UPS_NAME [OPTIONS]

Note This man page only documents the hardware-specific features of the ivtscd driver. For information about the core driver, see nutupsdrv(8).

## DESCRIPTION
This driver allows to access the IVT SCD-series devices.

## EXTRA ARGUMENTS
This driver does not support any extra argument.

## AUTHOR
Arjen de Korte <adkorte-guest@alioth.debian.org>

## SEE ALSO

### The core driver:
nutupsdrv(8)

### Internet resources:
The NUT (Network UPS Tools) home page: https://www.networkupstools.org/historic/v2.8.5/


liebert

title: liebert(8)

summary: Driver for Liebert contact\-closure UPS equipment

text:
# liebert(8)

## NAME
liebert - Driver for Liebert contact-closure UPS equipment

## SYNOPSIS
liebert -h

liebert -a UPS_NAME [OPTIONS]

Note This man page only documents the hardware-specific features of the liebert driver. For information about the core driver, see nutupsdrv(8).

## SUPPORTED HARDWARE
This driver supports some Liebert UPS equipment with a contact-closure interface. This includes the UPStation GXT2 with their contact-closure cable.

The smart mode ("Multilink") cable is NOT supported by this driver.

## EXTRA ARGUMENTS
This driver does not support any extra settings in the ups.conf(5).

## BUGS
This driver does not yet support shutdowns by raising DTR. Be aware that shutdowns are not possible with the stock contact-closure cable. You may have to build another cable with DTR connected through to the UPS for it to work.

There is no way for this driver to detect the hardware or cable. It will start up successfully even if no UPS is present. This is a fundamental limitation of any contact-closure driver.

## SEE ALSO

### The core driver:
nutupsdrv(8)

### Internet resources:
The NUT (Network UPS Tools) home page: https://www.networkupstools.org/historic/v2.8.5/


title: liebert-esp2(8)

summary: Driver for Liebert UPS, using the ESP\-II serial protocol

text:
# liebert-esp2(8)

## NAME
liebert-esp2 - Driver for Liebert UPS, using the ESP-II serial protocol

## SYNOPSIS
liebert-esp2 -h

liebert-esp2 -a UPS_NAME [OPTIONS]

Note This man page only documents the hardware-specific features of the liebert-esp2 driver. For information about the core driver, see nutupsdrv(8).

## SPECIAL CABLING NOTE
Be aware that an RS-232 cable with ONLY the RX, TX and ground pin must be used when interfacing with GXT2 series UPS units (and possibly others), since the handshaking lines are used for purposes other than RS-232 flow control.

Use of a standard RS-232 cable with full handshaking may result in undesired operation and/or shutdown. It is therefore advisable to confirm the proper cable/wiring with the diagram provided in the manual with your UPS.

## SUPPORTED HARDWARE
Tested to work on the following units:

•Liebert GXT2-6000RT208

This is an experimental driver. You have been warned.

This driver currently does not support modification of configuration parameters, such as the low battery warning time and automatic restart policy.

## EXTRA ARGUMENTS
This driver supports the following optional settings in ups.conf(5):

baudrate=num

Set the speed of the serial connection — 1200, 2400 (default), 4800, 9600 or 19200.

## AUTHORS
•Richard Gregory <R.Gregory at liverpool.ac.uk>

•Arjen de Korte <adkorte-guest at alioth.debian.org>

•Nash Kaminski <nashkaminski at kaminski.io>

## SEE ALSO

### The core driver:
nutupsdrv(8)

### Internet resources:
The NUT (Network UPS Tools) home page: https://www.networkupstools.org/historic/v2.8.5/


liebert-gxe

title: liebert-gxe(8)

text:
# liebert-gxe(8)

## NAME
liebert-gxe - Driver for Liebert GXE series UPS, using the YDN23 serial protocol

## SYNOPSIS
liebert-gxe -h

liebert-gxe -a UPS_NAME [OPTIONS]

Note This man page only documents the hardware-specific features of the liebert-gxe driver. For information about the core driver, see nutupsdrv(8).

## SUPPORTED HARDWARE
Tested to work on the following units:

•Liebert GXE 01k00TS1101C00

Note

This UPS has an RS-232 port and a USB port. The USB port has an ACM interface which functions as a serial port for the host operating system. Both ports can be used managing the device.

This is an experimental driver. You have been warned.

## EXTRA ARGUMENTS
This driver supports the following optional settings in ups.conf(5):

addr=num

Set the address of the UPS — 01 (default) ~ 99.

retry=num

Set the max times of read failures. (UPS sometimes ignores the incoming command and causes driver stales. The driver will ignore retry failures if occurred in a row. However, this does increase the latency if a real stale happened. Default to 3)

## AUTHORS
•Gong Zhile <goodspeed at mailo.cat>

## SEE ALSO

### The core driver:
nutupsdrv(8)

### Internet resources:
The NUT (Network UPS Tools) home page: https://www.networkupstools.org/historic/v2.8.5/


masterguard

title: masterguard(8)

summary: Driver for Masterguard UPS equipment

text:
# masterguard(8)

## NAME
masterguard - Driver for Masterguard UPS equipment

## SYNOPSIS
masterguard -h

masterguard -a UPS_NAME [OPTIONS]

Note This man page only documents the hardware-specific features of the masterguard driver. For information about the core driver, see nutupsdrv(8).

## NOTE
Please note that this driver is deprecated and will not receive new development. If it works for managing your devices — fine, but if you are running it to try setting up a new device, please consider the newer nutdrv_qx(8) instead, which should handle all Q* protocol variants for NUT.

Please do also report if your device works with this driver, but nutdrv_qx(8) would not actually support it with any subdriver!

## SUPPORTED HARDWARE
This driver supports Masterguard UPS equipment (serial connection only).

## EXTRA ARGUMENTS
CS

Cancel the shutdown procedure.

## AUTHOR
Michael Spanier <mail@michael-spanier.de>

## SEE ALSO

### Newer driver:
nutdrv_qx(8)

### The core driver:
nutupsdrv(8)

### Internet resources:
The NUT (Network UPS Tools) home page: https://www.networkupstools.org/historic/v2.8.5/


title: meanwell_ntu(8)

text:
# meanwell_ntu(8)

## NAME
meanwell_ntu - Driver for Mean Well NTU series inverter/UPS units

## SYNOPSIS
meanwell_ntu -h

meanwell_ntu -a UPS_NAME [OPTIONS]

Note This man page documents the hardware-specific features of the meanwell_ntu driver. For general information about NUT drivers, see nutupsdrv(8).

## DESCRIPTION
The meanwell_ntu driver provides support for Mean Well NTU series inverter/UPS units that implement the vendor’s ASCII serial protocol.

This driver is currently experimental and intended for early adopters. Reported variables and behavior may evolve as additional models and firmware revisions are tested.

## SUPPORTED HARDWARE
The driver is known to work with the following NTU models:

•NTU-1200

•NTU-1700

•NTU-2200

•NTU-3200

Supported DC-voltage variants include:

•NTU-1200-112, -124, -148

•NTU-1700-112, -124, -148

•NTU-2200-112, -124, -148

•NTU-3200-212, -224, -248

Other NTU-series devices using the same protocol may also work.

Communication uses a 9600-8-N-1 serial connection via RS-232 or a USB-serial adapter seen by the operating system as a serial port, e.g. /dev/ttyUSB0 (on Linux).

## CABLES
MEAN WELL p/n: RJ11-RS232

A straight-through serial cable (no modem control) is required.

USB-to-RS-232 adapters work as long as they expose a standard TTY device.

## CONFIGURATION
The driver is configured via ups.conf(5).

A minimal configuration:

```
[meanwell-ntu]

    driver = meanwell_ntu

    port   = /dev/ttyUSB0

    desc   = "Mean Well NTU-1200-124"
```

### Required parameters
Example standard parameters:

driver

Must be set to meanwell_ntu.

port

The serial/USB tty device (e.g. /dev/ttyS0, /dev/ttyUSB0).

### Optional parameters
This driver currently relies only on standard NUT parameters:

pollinterval

Interval between status polls (default: 2 seconds).

synchronous

Serial I/O mode as documented in nutupsdrv(8).

## INSTANT COMMANDS
The following instant commands are supported when the connected hardware implements them (see upscmd(8)):

load.off

Request shutdown of inverter output and load power-off (vendor command C100000000000000).

load.on

Request inverter output power-on (vendor command C010000000000000).

Support varies across firmware revisions; test before relying on them.

## STATUS AND VARIABLES
The driver regularly sends the Q (status) and I (info) commands and maps their fields to standard NUT variables.

### Selected read-only variables
battery.voltage

Battery/DC bus voltage (V).

battery.charge

Remaining capacity (%).

battery.alarm.voltage

Low-voltage alarm threshold (V).

battery.shutdown.voltage

Low-voltage shutdown threshold (V).

input.voltage

Utility AC input voltage (non-zero in line or bypass mode).

output.voltage

Inverter output voltage (V).

output.frequency

Output frequency when running on battery (Hz).

ups.temperature

Inverter temperature (°C).

ups.load

Approximate load percentage, derived from PPP bits.

device.mfr

Manufacturer string (typically MEANWELL).

device.model, ups.model

Model descriptor (e.g. NTU-1200-124).

device.serial

Serial number when reported.

device.firmware

Firmware revision string.

### UPS status flags
The NTU protocol exposes a 19-bit status word.

The driver maps selected bits into ups.status keywords:

OB

On battery / inverter mode.

BYPASS

Bypass mode active.

OL

Utility present / online.

LB

Battery low.

OVER

Over-temperature condition.

The raw bit fields are also exported as informational variables such as battery.low, utility.present, bypass.mode, overtemp, etc.

## LIMITATIONS
This driver is marked experimental:

•Protocol interpretation based on limited test samples.

•Some fields in Q/I responses are currently unused.

•Load and capacity reporting may be refined with further testing.

•Shutdown and restart behavior is basic and may not integrate with all NUT power-path logic.

For debugging, run the driver with high verbosity, e.g.:

```
/usr/local/ups/bin/meanwell_ntu -DDDDD -a meanwell-ntu
```

Please include model, firmware version, and operating mode details when reporting issues.

## IMPLEMENTATION
Note the protocol on surface seems related to Megatec Qx, but is sufficiently different to warrant a separate driver and not a sub-driver of e.g. nutdrv_qx(8).

## AUTHOR
The meanwell_ntu driver was contributed by Jonathan Hite.

Additional improvements may be provided by the NUT community. See the project repository for revision history.

## SEE ALSO
ups.conf(5), nutupsdrv(8), upsd(8), upsmon(8), upsc(8), upscmd(8)

### Internet resources:
•The NUT (Network UPS Tools) home page: https://www.networkupstools.org/historic/v2.8.5/

•Vendor documentation: https://www.meanwell.com/Upload/PDF/NTS,NTU-E.pdf


metasys

title: metasys(8)

summary: Driver for Meta System UPS equipment

text:
# metasys(8)

## NAME
metasys - Driver for Meta System UPS equipment

## SYNOPSIS
metasys -h

metasys -a UPS_NAME [OPTIONS]

Note This man page only documents the hardware-specific features of the metasys driver. For information about the core driver, see nutupsdrv(8).

## SUPPORTED HARDWARE
The metasys driver was written with the "Meta System UPS Protocol Rev.1.12" kindly supplied from Meta System.

The driver should support all the common features of the UPS models:

•HF Line (/2) 1-8 boards

•HF Millennium (810, 820)

•HF TOP Line (910, 920, 930, 940, 950, 970, 980)

•ECO Network (750, 1000, 1050, 1500, 1800, 2000, 2100, 2500, 3000)

•ECO (305, 308, 311, 511, 516, 519, 522, SX, SXI)

•ally HF (800, 1000, 1250, 1600, 2000, 2500)

•Megaline (1250, 2500, 3750, 5000, 6250, 7500, 8750, 10000)

## CABLING
The needed cable is a standard pin-to-pin serial cable with at least pins 2, 3, and 5 (on DB9 connector) connected.

## EXTRA ARGUMENTS
This driver supports no extra arguments from ups.conf(5).

## BUGS
This driver has been tested on Meta System HF Millennium 820 and ally HF 1000 only.

Any information about the use of the driver with the other listed UPS are really welcome.

## AUTHOR
Fabio Di Niro <blaxwan@users.sourceforge.net>

## SEE ALSO

### The core driver:
nutupsdrv(8)

### Internet resources:
•The NUT (Network UPS Tools) home page: https://www.networkupstools.org/historic/v2.8.5/

•Meta System UPS protocol: https://networkupstools.org/ups-protocols.html#_legrand


mge-shut

title: mge-shut(8)

summary: Driver for SHUT Protocol UPS equipment

text:
# mge-shut(8)

## NAME
mge-shut - Driver for SHUT Protocol UPS equipment

## SYNOPSIS
mge-shut -h

mge-shut -a UPS_NAME [OPTIONS]

Note This man page only documents the hardware-specific features of the mge-shut driver. For information about the core driver, see nutupsdrv(8).

## SUPPORTED HARDWARE
mge-shut supports all recent Eaton, MGE and Dell UPS models which use the SHUT (Serial HID UPS Transfer) protocol.

Older MGE models, such as Pulsar ESV+, Pulsar EX and Pulsar ES+, use the U-Talk protocol and should use the mge-utalk driver.

## EXTRA ARGUMENTS
This driver also supports the following optional settings:

lowbatt=num

Set the low battery warning threshold at which shutdown is initiated by upsmon(8). The factory default value is 30 (in percent), and can be settable depending on the exact model.

offdelay=num

Set the timer before the UPS is turned off after the kill power command is sent (via the -k switch). The default value is 20 (in seconds). Usually this must be lower than ondelay, but the driver will not warn you upon startup if it isn’t.

ondelay=num

Set the timer for the UPS to switch on in case the power returns after the kill power command had been sent but before the actual switch off. This ensures the machines connected to the UPS are, in all cases, rebooted after a power failure. The default value is 30 (in seconds). Usually this must be greater than offdelay, but the driver will not warn you upon startup if it isn’t. Some UPSes will restart no matter what, even if the power is (still) out at the moment this timer elapses. In that case, you could try if setting ondelay = -1 in ups.conf helps.

Warning

The ondelay parameter was set in ten-seconds unit in the legacy mge-shut(8) driver (e.g. 3 for 30 seconds). It is now set in seconds (30 for 30 seconds). Make sure you use the correct unit in your configuration.

notification=num

Set notification type to 1 (no), 2 (light) or 3 (yes). This argument is ignored. It is only here for backward compatibility.

## KNOWN ISSUES

### Repetitive timeout and staleness
Some models tend to be unresponsive with the default polling frequency. The result is that you have some "data stale" errors in your system log.

In this case, simply modify the general parameter pollinterval to a higher value (like 10 for 10 seconds). This should solve the issue.

Using notification=3 might also help.

## AUTHOR
Arnaud Quette

## SEE ALSO

### The core driver
nutupsdrv(8)

### Internet resources
The NUT (Network UPS Tools) home page: https://www.networkupstools.org/historic/v2.8.5/


mge-utalk

title: mge-utalk(8)

text:
# mge-utalk(8)

## NAME
mge-utalk - Driver for MGE UPS SYSTEMS UTalk protocol equipment

## SYNOPSIS
mge-utalk -h

mge-utalk -a UPS_NAME [OPTIONS]

Note This man page only documents the hardware-specific features of the mge-utalk driver. For information about the core driver, see nutupsdrv(8).

## SUPPORTED HARDWARE
mge-utalk supports the following legacy units, using the MGE UTalk protocol:

•Pulsar ESV+

•Pulsar ES+

•Pulsar EL

•Pulsar EX

•Pulsar EXtreme

•Comet EXtreme

•Comet (Utalk Serial Card, ref 66060)

•Galaxy (Utalk Serial Card, ref 66060)

This driver also support some newer models with backward UTalk compatibility, such as Pulsar Evolution and Pulsar EXtreme C. As these models also support the SHUT protocol, prefer mge-shut(8) for serial communication, or use the USB port, if available, with the usbhid-ups(8)] driver.

## EXTRA ARGUMENTS
This driver supports the following optional settings in the ups.conf(5):

lowbatt=num

Set the low battery warning threshold at which shutdown is initiated by upsmon(8). The factory default value is 30 (in percent), and can be settable depending on the exact model.

offdelay=num

Set the timer before the UPS is turned off after the kill power command is sent (via the -k switch). The default value is 20 (in seconds).

ondelay=num

Set the delay before the UPS is turned on, after the power returns. The default value is 1 (in minutes).

oldmac

Set this flag if you are running Linux on an Oldworld Macintosh box (all beige Apple Macintosh). This might also be needed for other OSs (like *BSD) running on PowerMac.

## KNOWN ISSUES

### Repetitive timeout and staleness
Older models, such as ES/ESV ones, might report repetitive "data stale" errors. This is due to the fact that these models don’t support too much polling. To solve this problem, add pollinterval=20 in ups.conf, and change the value of MAXAGE to 25 in upsd.conf, and DEADTIME to 25 in upsmon.conf.

## AUTHORS
•Hans Ekkehard Plesser

•Arnaud Quette

•Martin Loyer

•Patrick Agrain

•Nicholas Reilly

•Dave Abbott

•Marek Kralewski

## SEE ALSO

### The core driver
nutupsdrv(8)

### Internet resources
The NUT (Network UPS Tools) home page: https://www.networkupstools.org/historic/v2.8.5/


microdowell

title: microdowell(8)

text:
# microdowell(8)

## NAME
microdowell - Driver for Microdowell Enterprise UPS series

## SYNOPSIS
microdowell -h

microdowell -a UPS_NAME [OPTIONS]

Note This man page only documents the hardware-specific features of the Microdowell driver. For information about the core driver, see nutupsdrv(8).

## SUPPORTED HARDWARE
This driver was developed for the Enterprise Nxx and Bxx models. Other Microdowell models may work, too.

## EXTRA ARGUMENTS
This driver does not support any extra settings in the ups.conf(5).

## AUTHOR
Elio Corbolante <eliocor@microdowell.com>

## SEE ALSO

### The core driver:
nutupsdrv(8)

### Internet resources:
The NUT (Network UPS Tools) home page: https://www.networkupstools.org/historic/v2.8.5/


microsol-apc

title: microsol-apc(8)

summary: Driver for APC Back\-UPS BR UPS equipment

text:
# microsol-apc(8)

## NAME
microsol-apc - Driver for APC Back-UPS BR UPS equipment

## SYNOPSIS
microsol-apc -h

microsol-apc -a UPS_NAME [OPTIONS]

Note This man page only documents the hardware-specific features of the microsol-apc driver. For information about the core driver, see nutupsdrv(8).

## SUPPORTED HARDWARE
This driver supports the following UPS models:

•APC Back-UPS BZ1500-BR

•APC Back-UPS BZ2200I-BR

•APC Back-UPS BZ2200BI-BR

In 2009, Schneider Electric acquired Microsol Technologies, and by 2012, the entire Microsol line was being sold under the APC brand. This driver supports these newer, APC-branded models. Older equipment should use solis(8).

## EXTRA ARGUMENTS
This driver support the following extra optional settings in the ups.conf(5).

battext=n

Default = 0, no extra battery, where n = Ampere*hour.

prgshut=n

Default = 0, no programmable shutdown; 1 to enable one.

## COMMANDS
shutdown.return

Shut down in .3 minutes and restart in .3 minutes after that.

shutdown.stayoff

Shut down in .3 minutes and do not return.

## ISSUES
For other APC-Microsol models, the reported voltages, currents and power will be incorrect, as the communication protocol reports unprocessed data instead of real values, needing model-specific post-processing by the driver. Monitoring of UPS state (on-battery/on-line, critical battery) should work for other models, but is untested.

## AUTHORS
•Ygor A. S. Regados <ygorre@tutanota.com>

•Roberto P. Velloso <rvelloso@gmail.com>

•Silvino B. Magalhães <sbm2yk@gmail.com>

## SEE ALSO

### The core driver:
nutupsdrv(8)

### Driver for older devices under same brand:
solis(8)

### Internet resources:
The NUT (Network UPS Tools) home page: https://www.networkupstools.org/historic/v2.8.5/


title: nhs_ser(8)

text:
# nhs_ser(8)

## NAME
nhs_ser - Driver for NHS Nobreaks, senoidal line, with serial port

## SYNOPSIS
nhs_ser -h

nhs_ser -a UPS_NAME [OPTIONS]

Note This man page only documents the hardware-specific features of the nhs_ser driver. For information about the core driver, see nutupsdrv(8).

## SUPPORTED HARDWARE
nhs_ser supports numerous UPS models made by NHS Sistemas Eletronicos LTDA and marketed in Brazil. They feature a serial port and a binary wire protocol.

Note Currently this driver only builds on Linux. This is expected to change in future revisions of the code.

## EXTRA ARGUMENTS
This driver also supports the following optional settings:

baud=num

Set the value of serial port baud rate (default: 2400)

ah=num

Battery discharge capacity in Ampere/hour.

va=num

Nobreak NOMINAL POWER in VA.

pf=num

Power Factor to use in calculations of battery time (default: 0.90).

vin_low_warn_perc=num

Voltage In Percentage to calculate warning low level (default: 2.00).

vin_low_crit_perc=num

Voltage In Percentage to calculate critical low level (default: 2.00).

vin_high_warn_perc=num

Voltage In Percentage to calculate warning high level (default: 2.00).

vin_high_crit_perc=num

Voltage In Percentage to calculate critical high level (default: 2.00).

numbatteries=num

Num Batteries (override value from nobreak).

vbat=num

Battery Voltage (default: 12.00).

debug_pkt_raw

Optional flag to enable debug logging of packet bytes.

debug_pkt_data

Optional flag to enable debug logging of data packet decoding.

debug_pkt_hwinfo

Optional flag to enable debug logging of hwinfo packet decoding.

## AUTHORS
Lucas Willian Bocchi <lucas@lucas.inf.br>

## SEE ALSO

### The core driver:
nutupsdrv(8)

### Internet resources:
The NUT (Network UPS Tools) home page: https://www.networkupstools.org/historic/v2.8.5/


nut-driver-enumerator

title: nut-driver-enumerator(8)

text:
# 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 upsdrvctl(8) requiring everything configured to be started). For a few special drivers like dummy-ups(8), clone(8), clone-outlet(8), and 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 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 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
upsdrvsvcctl(8), ups.conf(5)

### Internet resources:
The NUT (Network UPS Tools) home page: https://www.networkupstools.org/historic/v2.8.5/