nut-scanner

title: nut-scanner(8)

text:
# nut-scanner(8)

## NAME
nut-scanner - scan communication buses for NUT devices

## SYNOPSIS
nut-scanner -h

nut-scanner [OPTIONS]

## DESCRIPTION
nut-scanner scans available communication buses and displays any NUT-compatible devices it has found.

## INSTALLATION
nut-scanner is only built if libltdl (part of libtool development suite) is available. Available options (USB, SNMP, IPMI, ...) will vary according to the available compile time and runtime dependencies. For example, if Net-SNMP is installed, thus providing libsnmp (.so or .dll) and headers, both during compilation and runtime, then SNMP discovery will be available.

## OPTIONS
-h

Display the help text.

## DISPLAY OPTIONS
-N | --disp_nut_conf

Display result in the ups.conf format.

-P | --disp_parsable

Display result in a parsable format.

## BUS OPTIONS
-C | --complete_scan

Scan all available communication buses (default behavior)

-U | --usb_scan

List all NUT-compatible USB devices currently plugged in.

-S | --snmp_scan

Scan SNMP devices. Requires at least a start IP, and optionally, an end IP. See specific SNMP OPTIONS for community and security settings.

-M | --xml_scan

Scan XML/HTTP devices. Broadcast a network message on the current network interfaces to retrieve XML/HTTP capable devices. No IP required.

-O | --oldnut_scan

Scan NUT devices (i.e. upsd daemon) on IP ranging from start IP to end IP.

-A | --avahi_scan

Scan NUT servers using Avahi request on the current network interfaces. No IP required.

-I | --ipmi_scan

Scan NUT compatible power supplies available via IPMI on the current host, or over the network.

-E | --eaton_serial serial ports

Scan Eaton devices (XCP and SHUT) available via serial bus on the current host. This option must be requested explicitely, even for a complete scan. serial ports can be expressed in various forms:

•auto to scan all serial ports.

•a single charcater indicating a port number (0 (zero) for /dev/ttyS0 and /dev/ttyUSB0 on Linux, 1 for COM1 on Windows, a for /dev/ttya on Solaris...)

•a range of N characters, hyphen separated, describing the range of ports using X-Y, where X and Y are characters refering to the port number.

•a single port name.

•a list of ports name, coma separated, like /dev/ttyS1,/dev/ttyS4.

## NETWORK OPTIONS
-t | --timeout timeout

Set the network timeout in seconds. Default timeout is 5 seconds.

-s | --start_ip start IP

Set the first IP (IPv4 or IPv6) when a range of IP is required (SNMP, old_nut).

-e | --end_ip end IP

Set the last IP (IPv4 or IPv6) when a range of IP is required (SNMP, old_nut). If this parameter is omitted, only the start IP is scanned. If end IP is less than start IP, both parameters are internally permuted.

-m | --mask_cidr IP address/mask

Set a range of IP using CIDR notation.

## NUT DEVICE OPTION
-p | --port port number

Set the port number of scanned NUT devices (default 3493).

## SNMP V1 OPTION
-c | --community community

Set SNMP v1 community name (default = public).

## SNMP V3 OPTIONS
-l | --secLevel security level

Set the security level used for SNMPv3 messages. Allowed values are: noAuthNoPriv, authNoPriv and authPriv.

-u | --secName security name

Set the security name used for authenticated SNMPv3 messages. This parameter is mandatory if you set security level.

-w | --authProtocol authentication protocol

Set the authentication protocol used for authenticated SNMPv3 messages. Allowed values are MD5 or SHA. Default value is MD5.

-W | --authPassword authentication pass phrase

Set the authentication pass phrase used for authenticated SNMPv3 messages. This parameter is mandatory if you set security level to authNoPriv or authPriv.

-x | --privProtocol privacy protocol

Set the privacy protocol used for encrypted SNMPv3 messages. Allowed values are DES or AES. Default value is DES.

-X | --privPassword privacy pass phrase

Set the privacy pass phrase used for encrypted SNMPv3 messages. This parameter is mandatory if you set security level to authPriv.

## IPMI OPTIONS
-b | --username username

Set the username used for authenticating IPMI over LAN connections (mandatory for IPMI over LAN. No default).

-B | --password password

Specify the password to use when authenticating with the remote host (mandatory for IPMI over LAN. No default).

-d | --authType authentication type

Specify the IPMI 1.5 authentication type to use (NONE, STRAIGHT_PASSWORD_KEY, MD2, and MD5) with the remote host (default=MD5). This forces connection through the lan IPMI interface , thus in IPMI 1.5 mode.

-D | --cipher_suite_id cipher suite identifier

Specify the IPMI 2.0 cipher suite ID to use. The Cipher Suite ID identifies a set of authentication, integrity, and confidentiality algorithms to use for IPMI 2.0 communication. The authentication algorithm identifies the algorithm to use for session setup, the integrity algorithm identifies the algorithm to use for session packet signatures, and the confidentiality algorithm identifies the algorithm to use for payload encryption (default=3). The following cipher suite ids are currently supported (Authentication; Integrity; Confidentiality):

•0: None; None; None

•1: HMAC-SHA1; None; None

•2: HMAC-SHA1; HMAC-SHA1-96; None

•3: HMAC-SHA1; HMAC-SHA1-96; AES-CBC-128

•6: HMAC-MD5; None; None

•7: HMAC-MD5; HMAC-MD5-128; None

•8: HMAC-MD5; HMAC-MD5-128; AES-CBC-128

•11: HMAC-MD5; MD5-128; None

•12: HMAC-MD5; MD5-128; AES-CBC-128

•15: HMAC-SHA256; None; None

•16: HMAC-SHA256; HMAC_SHA256_128; None

•17: HMAC-SHA256; HMAC_SHA256_128; AES-CBC-128

## MISCELLANEOUS OPTIONS
-V | --version

Display NUT version.

-a | --available

Display available bus that can be scanned , depending on how the binary has been compiled. (OLDNUT, USB, SNMP, XML, AVAHI, IPMI).

-q | --quiet

Display only scan result. No information on currently scanned bus is displayed.

## EXAMPLES
To scan USB devices only:

nut-scanner -U

To scan SNMP v1 device with public community on address range 192.168.0.0 to 192.168.0.255:

nut-scanner -S -s 192.168.0.0 -e 192.168.0.255

The same using CIDR notation:

nut-scanner -S -m 192.168.0.0/24

To scan NUT servers with a timeout of 10 seconds on IP range 192.168.0.0 to 192.168.0.127 using CIDR notation:

nut-scanner -O -t 10 -m 192.168.0.0/25

To scan for power supplies, through IPMI (1.5 mode) over the network, on address range 192.168.0.0 to 192.168.0.255:

nut-scanner -I -m 192.168.0.0/24 -b username -B password

To scan for Eaton serial devices on ports 0 and 1 (/dev/ttyS0, /dev/ttyUSB0, /dev/ttyS1 and /dev/ttyUSB1 on Linux):

nut-scanner --eaton_serial 0-1

To scan for Eaton serial devices on ports 1 and 2 (COM1 and COM2 on Windows):

nut-scanner --eaton_serial 1-2

## SEE ALSO
ups.conf(5)

## INTERNET RESOURCES
The NUT (Network UPS Tools) home page: http://www.networkupstools.org/


package: nut-server

title: nutdrv_atcl_usb(8)

summary: Driver for \*(AqATCL FOR UPS\*(Aq equipment

text:
# nutdrv_atcl_usb(8)

## NAME
nutdrv_atcl_usb - Driver for 'ATCL FOR UPS' equipment

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

## SUPPORTED HARDWARE
This driver is for UPS hardware which identifies itself as USB idVendor 0001 and idProduct 0000, and iManufacturer ATCL FOR UPS. Known manufacturers include Kanji and Plexus. The UPS interface seems to be a generic USB-to-serial chip, and for hardware manufactured by Kanji and Plexus, the microcontroller appears to emulate a traditional contact-closure interface. This translates into only three states in ups.status: OL, OB and OB LB (similar to genericups(8)), with no other dynamic status values reported. Note that these USB identifiers (including the iManufacturer string) have also been seen on devices that are supported by the fuji subdriver of nutdrv_qx(8).

## EXTRA ARGUMENTS
This driver supports the following optional setting:

vendor=name

In case your iManufacturer (Vendor) string does not exactly match ATCL FOR UPS, you may provide an alternate string here. Note that a more likely case is that your device is handled by another driver for 0001:0000 devices, such as nutdrv_qx(8).

## BUGS
The UPS returns the same code for "load power is off" as for "on line power". This condition will not be observed if the NUT master is powered by the UPS, but may be an issue if the UPS is monitored by a remote system.

The time between the shutdown command and removal of power seems to be fixed at 30 seconds. Ensure that the NUT shutdown script is invoked as late as possible in the shutdown procedure (in case some services take longer than others to clean up).

Most contact-closure UPSes will not power down the load if the line power is present. This can create a race when using slave upsmon(8) systems. See the upsmon(8) man page for more information. The solution to this problem is to upgrade to a smart protocol UPS of some kind that allows detection and proper load cycling on command.

## AUTHORS
Charles Lepple

## SEE ALSO

### The core driver:
nutupsdrv(8)

### The generic serial driver:
genericups(8)

### The Qx driver:
nutdrv_qx(8) (fuji subdriver)

### Internet resources:
The NUT (Network UPS Tools) home page: http://www.networkupstools.org/


title: nutdrv_qx(8)

text:
# nutdrv_qx(8)

## NAME
nutdrv_qx - Driver for Q* protocol serial and USB based UPS equipment

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

## SUPPORTED HARDWARE
The nutdrv_qx driver is known to work with various UPSes from Blazer, Energy Sistem, Fenton Technologies, General Electric, Mustek, Voltronic Power (rebranded by many, many - have I said many? - others.. Long story short: if your UPS came with a software called Viewpower, chances are high that it works with this driver with one of the voltronic* protocols or with the mecer one) 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 and many with a USB interface 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)):

ondelay = value

Time to wait before switching on the UPS (seconds). This value is truncated to units of 60 seconds. Note that a value below 3 minutes, may cause earlier firmware versions to not switch on automatically, so it defaults to 3 minutes (i.e. 180 seconds).

This option provides a default value for ups.delay.start that will then be used by the driver in the automatic shutdown sequence (i.e. calling the driver with the -k option, calling upsdrvctl(8) with the shutdown option or when the FSD flag is set and upsmon(8) enters its shutdown sequence): however you can change this value ‘on the fly’ for the actual session, only for the use with instant commands, setting ups.delay.start with upsrw(8).

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. This option provides a default value for ups.delay.shutdown that will then be used by the driver in the automatic shutdown sequence (i.e. calling the driver with the -k option, calling upsdrvctl(8) with the shutdown option or when the FSD flag is set and upsmon(8) enters its shutdown sequence): however you can change this value ‘on the fly’ for the actual session, only for the use with instant commands, setting ups.delay.shutdown with upsrw(8).

stayoff

If you set stayoff in ups.conf(5) when FSD arises the UPS will call a shutdown.stayoff shutting down after ups.delay.shutdown seconds and won’t return (see KNOWN PROBLEMS), otherwise (standard behaviour) the UPS will call shutdown.return shutting down after ups.delay.shutdown seconds and then turn on after ups.delay.start seconds (if mains meanwhile returned).

protocol = string

Skip autodetection of the protocol to use and only use the one specified. Supported values: bestups, mecer, megatec, megatec/old, mustek, q1, voltronic, voltronic-qs, voltronic-qs-hex and zinto. Note that if you end up using the q1 protocol, you may want to give a try to the mecer, megatec and zinto ones setting the novendor/norating flags (only one, or both).

pollfreq = value

Set polling frequency, in seconds, to reduce the data flow. Between two polling requests the driver will do ‘quick polls’ dealing just with ups.status. The default value is 30 (in seconds).

If your UPS doesn’t report either battery.charge or battery.runtime you may want to add the following ones in order to have guesstimated values:

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

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

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.

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.

### BESTUPS, MECER, MEGATAEC, MEGATEC/OLD, MUSTEK, Q1, VOLTRONIC-QS, VOLTRONIC-QS-HEX, ZINTO PROTOCOLS
ignoresab

Some UPSes incorrectly report the ‘Shutdown Active’ bit as always on, consequently making the driver believe the UPS is nearing a shutdown (and, as a result, ups.status always contains FSD... and you know what this means). Setting this flag will make the driver ignore the ‘Shutdown Active’ bit.

### MECER, MEGATAEC, MEGATEC/OLD, MUSTEK, ZINTO PROTOCOLS
ondelay

The acceptable range is 0..599940 seconds.

offdelay

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.

### BESTUPS PROTOCOL
ondelay

The acceptable range is 60..599940 seconds.

offdelay

The acceptable range is 12..5940 seconds.

pins_shutdown_mode = value

Set shutdown mode functionality of Pin 1 and Pin 7 on the UPS DB9 communication port (Per Best Power’s EPS-0059) to value [0..6].

### Q1 PROTOCOL
ondelay

The acceptable range is 0..599940 seconds.

offdelay

The acceptable range is 12..600 seconds.

### VOLTRONIC-QS, VOLTRONIC-QS-HEX PROTOCOLS
ondelay

The acceptable range is 60..599940 seconds.

offdelay

The acceptable range is 12..540 seconds.

### VOLTRONIC PROTOCOL
The following options are supported only by the voltronic protocol. Not all of them are available on all the UPSes supported by this protocol.

ondelay

The acceptable range is 0..599940 seconds.

offdelay

The acceptable range is 12..5940 seconds.

battery_number = value

Set number of batteries that make a pack to value [1..9]. This setting will change the charge and runtime estimation reported by the UPS.

output_phase_angle = value

Changes output phase angle to the provided value [000, 120, 180, 240]°.

UPS CAPABILITY SETTINGS

reset_to_default

Reset capability options and their voltage and frequency limits to safe default values. (Doable only when the UPS is in Standby Mode) Note that setting this option will reset also ups.start.auto, battery.protection, battery.energysave, ups.start.battery, outlet.0.switchable, input.transfer.high, input.transfer.low, input.frequency.high and input.frequency.low.

These UPSes can be fine-tuned to suit your needs enabling or disabling the following options (the driver should tell you which one the UPS is capable of on startup: the settable ones will be reported either ar enabled or disabled in the logs):

alarm_control = string

Enable or disable alarm (BEEP!) [enabled/disabled]. Settable also ‘on the fly’ with beeper.enable and beeper.disable instant commands.

bypass_alarm = string

Enable or disable alarm (BEEP!) at Bypass Mode [enabled/disabled].

battery_alarm = string

Enable or disable alarm (BEEP!) at Battery Mode [enabled/disabled].

bypass_when_off = string

Enable or disable bypass when the UPS is Off [enabled/disabled]. If enabled, AC will directly provide power to connected devices when the UPS is off.

bypass_forbidding = string

Enable or disable Bypass Forbidding [enabled/disabled]. If enabled, the UPS will not transfer to bypass mode under any condition.

converter_mode = string

Enable or disable Converter Mode [enabled/disabled]. When input frequency is within 40 Hz to 70 Hz, the UPS can be set at a constant output frequency, 50 Hz or 60 Hz. The UPS will still charge battery under this mode.

eco_mode = string

Enable or disable ECO Mode [enabled/disabled]. When input voltage/frequency are within acceptable range, the UPS will bypass voltage to output for energy saving. PFC and INVERTER are still active at this mode. Settable also ‘on the fly’ with bypass.start and bypass.stop instant commands.

advanced_eco_mode = string

Enable or disable Advanced ECO Mode [enabled/disabled]. When input voltage/frequency are within acceptable range, the UPS will bypass voltage to output for energy saving. PFC and INVERTER are off at this mode.

battery_open_status_check = string

Enable or disable Battery Open Status Check [enabled/disabled]. If enabled, when the UPS is turned on, it will check if the battery is connected or not.

site_fault_detection = string

Enable or disable site fault detection [enabled/disabled]. If enabled, the UPS will beep when the input neutral and hot wires are reversed.

constant_phase_angle = string

Enable or disable Constant Phase Angle Function (output and input phase angles are not equal) [enabled/disabled].

limited_runtime_on_battery = string

Enable or disable limited runtime on battery mode [enabled/disabled].

BYPASS MODE VOLTAGE/FREQUENCY LIMITS

Variables to fine-tune voltage and frequency limits for Bypass mode. These limits are reset to safe default values by reset_to_default.

If AC voltage and frequency are within acceptable range, Bypass mode will be used (If the UPS is capable of and it’s enabled).

Since these values are device-specific, if your UPS support them, you will get their settable limits printed in the logs on startup.

max_bypass_volt = value

Maximum voltage for Bypass Mode (V).

min_bypass_volt = value

Minimum voltage for Bypass Mode (V).

max_bypass_freq = value

Maximum frequency for Bypass Mode (Hz).

min_bypass_freq = value

Minimum frequency for Bypass Mode (Hz).

OPTIONS SPECIFIC FOR P31 UPSES

The following options are available only on P31 UPSes.

work_range_type = string

Device grid working range for P31 UPSes [Appliance/UPS].

TESTING

This protocol comes with a couple of functions that are not enabled by default because of the lack of knowledge of some part of the communication protocol used by these UPSes by your friendly neighborhood developer. Since these functions are supposed to be queries to the UPS for some kind of informations, they should not make your UPS go boom. So if you are brave enough to risk your UPS and attached devices' life to help the developers, this will be very appreciated.. Do it at your own risk.

testing

If invoked the driver will exec also commands that still need testing.

### SERIAL INTERFACE ONLY
cablepower = string

By default the driver will set DTR and clear RTS (normal). If you find that your UPS isn’t detected or the communication with the UPS is unreliable, you may try if clear DTR and set RTS (reverse), set DTR and RTS (both) or clear DTR and RTS (none) improves this situation.

### USB INTERFACE ONLY
port = string

You must set value to auto.

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)) that must match the UPS’s entire vendor/product/serial string (minus any surrounding whitespace), or the whole 4-digit hexadecimal code for vendorid and productid. Try -DD for finding out the strings to match. Examples:

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

•-x vendorid=051d* (APC)

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

bus = regex

Select a UPS on a specific USB bus or group of busses. The argument is a regular expression that must match the bus name where the UPS is connected (e.g. bus="002", bus="00[2-3]").

subdriver = string

Select a serial-over-USB subdriver to use. You have a choice between cypress, fabula, fuji, ippon, krauler, phoenix and sgs. 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 provide value (0x409 or 0x4095), according to your device entry in NUT hardware compatibility list (HCL).

IMPLEMENTATION NOTES

fabula subdriver

This subdriver, meant to be used with the megatec protocol, does not support the various test.battery commands. Plus, the shutdown.return command ignores the values set in ups.delay.start/ondelay and makes the UPS turn on the load as soon as power is back.

fuji subdriver

This subdriver, meant to be used with the megatec protocol, does not support the shutdown.stayoff and load.off commands. Plus, the shutdown.return command ignores the values set in ups.delay.start/ondelay and makes the UPS turn on the load as soon as power is back.

krauler subdriver

This subdriver, meant to be used with the megatec protocol, does not support the shutdown commands, i.e.: shutdown.return, shutdown.stayoff and load.off.

## 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. (Not available on some hardware)

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 ups.delay.start and ups.delay.shutdown.

shutdown.stayoff

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

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 quick (10 second) battery test.

test.battery.stop

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

### BESTUPS, MECER, MEGATEC, MEGATEC/OLD, MUSTEK, Q1, ZINTO PROTOCOLS
test.battery.start value

Perform a battery test for the duration of value seconds (truncated to 60 seconds) [60..5940].

VOLTRONIC POWER P98 UNITS (WITH MECER PROTOCOL)

test.battery.start value

Perform a battery test for the duration of value seconds (truncated to 60 seconds) [12..5940]. This value is truncated to units of 6 seconds (less than 60 seconds) or 60 seconds (more than 60 seconds).

### VOLTRONIC PROTOCOL
The following instant commands are available for the voltronic protocol. Not all of them are available on all the UPSes supported by this protocol.

beeper.enable

Enable the UPS beeper.

beeper.disable

Disable the UPS beeper.

test.battery.start value

Perform a battery test for the duration of value seconds [12..5940]. This value is truncated to units of 6 seconds (less than 60 seconds) or 60 seconds (more than 60 seconds).

outlet.1.load.off

Turn off outlet 1 load immediately.

outlet.1.load.on

Turn on outlet 1 load immediately.

outlet.2.load.off

Turn off outlet 2 load immediately.

outlet.2.load.on

Turn on outlet 2 load immediately.

outlet.3.load.off

Turn off outlet 3 load immediately.

outlet.3.load.on

Turn on outlet 3 load immediately.

outlet.4.load.off

Turn off outlet 4 load immediately.

outlet.4.load.on

Turn on outlet 4 load immediately.

bypass.start

Put the UPS in ECO Mode.

bypass.stop

Take the UPS out of ECO Mode.

## BATTERY CHARGE
Due to popular demand, this driver will report a guesstimated battery.charge 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 is giving you incorrect readings, you are the one that put in the values in ups.conf(5), so don’t complain with the author. If you need something better, buy a 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 nutdrv_qx driver having replaced the megatec ones, some configuration changes may be required by users switching to nutdrv_qx.

Part of this, the following megatec options, in ups.conf(5), 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.

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

Part of this, the following blazer options, in ups.conf(5), have to be changed:

ondelay

While the previous blazer drivers expected minutes, the new nutdrv_qx driver wants seconds.

The following instant command has also been changed:

test.battery.start value

While the old blazer drivers expected a value in minutes, the nutdrv_qx driver wants a value in seconds.

## NOTES FOR THE PREVIOUS USER OF BESTUPS DRIVER
The nutdrv_qx driver having replaced the bestups one, some configuration changes may be required by users switching to nutdrv_qx.

Part of this, the following bestups options, in ups.conf(5), are no longer supported by this driver:

nombattvolt, battvoltmult

See BATTERY CHARGE.

ID

Discarded.

## NOTES FOR THE PREVIOUS USER OF VOLTRONIC DRIVERS
The nutdrv_qx driver having replaced the voltronic ones, some configuration changes may be required by users switching to nutdrv_qx.

Part of this, the following voltronic options, in ups.conf(5), have to be changed:

ondelay

While the previous voltronic drivers expected minutes, the new nutdrv_qx driver wants seconds. It no longer defaults to 0 minutes but to 3 minutes (i.e. 180 seconds) for compatibility with the users switching from the old blazer drivers.

battnumb

This option has been renamed to battery_number.

The following options are no longer supported by this driver, you can now change them more conveniently ‘on the fly’ calling upsrw(8) with the appropriate NUT variable - provided that your UPS supports them.

battpacks

→ battery.packs Set number of battery packs in parallel [1..99]. This setting will change the charge and runtime estimation reported by the UPS.

battlow

→ battery.voltage.low Set minimum battery voltage just before the UPS automatically shuts down. This setting will change the charge and runtime estimation reported by the UPS.

auto_reboot

→ ups.start.auto Enable or disable auto reboot [enabled/disabled]. If enabled, the UPS will auto recover when AC power returns.

battery_protection

→ battery.protection Enable or disable battery deep discharge protection [enabled/disabled].

energy_saving

→ battery.energysave Enable or disable Green power function [enabled/disabled]. If enabled, for energy saving, the UPS will auto off when there is no load.

cold_start

→ ups.start.battery Enable or disable Cold Start [enabled/disabled]. If enabled, the UPS can be turned on also if AC is not connected to the UPS.

outlet_control

→ outlet.0.switchable Enable or disable programmable outlets control at battery mode [enabled/disabled]. If enabled, the UPS will cut off programmable outlets after backup time (set through outlet.{1,2,3,4}.delay.shutdown) arrives. If disabled, the UPS will provide continuous power to programmable outlets until the battery is running out.

max_eco_volt

→ input.transfer.high Maximum voltage for ECO Mode (V). If AC voltage is within acceptable range, ECO mode will be used (If the UPS is capable of and it’s enabled).

min_eco_volt

→ input.transfer.low Minimum voltage for ECO Mode (V). If AC voltage is within acceptable range, ECO mode will be used (If the UPS is capable of and it’s enabled).

max_eco_freq

→ input.frequency.high Maximum frequency for ECO Mode (Hz). If AC frequency is within acceptable range, ECO mode will be used (If the UPS is capable of and it’s enabled).

min_eco_freq

→ input.frequency.low Minimum frequency for ECO Mode (Hz). If AC frequency is within acceptable range, ECO mode will be used (If the UPS is capable of and it’s enabled).

outlet1_delay

→ outlet.1.delay.shutdown Delay time before programmable outlet 1 shuts down the load when on battery mode [0..59940] (seconds).

outlet2_delay

→ outlet.2.delay.shutdown Delay time before programmable outlet 2 shuts down the load when on battery mode [0..59940] (seconds).

outlet3_delay

→ outlet.3.delay.shutdown Delay time before programmable outlet 3 shuts down the load when on battery mode [0..59940] (seconds).

outlet4_delay

→ outlet.4.delay.shutdown Delay time before programmable outlet 4 shuts down the load when on battery mode [0..59940] (seconds).

batt_type

→ battery.type Battery type (for P31 UPSes only) [Li/Flooded/AGM].

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

### VOLTRONIC-QS UNITS
Both load.off and shutdown.stayoff instant commands are known to work as expected (i.e. turn the load off indefinitely) only if mains is present, otherwise, as soon as mains returns the load will be powered.

After issuing a shutdown.return instant command, the UPS won’t wait ondelay before powering on the load, provided the following conditions are met:

•if the load has been previously (no matter how long before) powered off through load.off/shutdown.stayoff and powered on through load.on/shutdown.stop and

•if AC wasn’t cut after issuing the load.off/shutdown.stayoff (i.e. the UPS didn’t turn itself off) and

•if there’s a power outage after issuing the shutdown.return command

In this case, as soon as mains returns the load will be powered.

### VOLTRONIC-QS-HEX UNITS
shutdown.return, load.off, and shutdown.stayoff instant commands are known to work as expected only if mains is present, otherwise, as soon as mains returns the load will be powered.

## UPS WARNINGS (VOLTRONIC PROTOCOL)
The UPSes supported by voltronic protocol report warnings through a 64bit flag (bit1bit2...bit63bit64) where 1 means that a warning arose, while 0 means no warning. Since more than one warning at a time can be signaled, and because of the limited space in the ups.alarm variable, if the length of the warnings exceeds that of ups.alarms variable, they will be reported as bits. If you want to know the explanation of that bit you can either watch the log or see the next table (unlisted bits equal to unknown warnings).

Table 1. UPS Warnings for voltronic UPSes

\#

Corresponding Warning

1

Battery disconnected

2

Neutral not connected

3

Site fault

4

Phase sequence incorrect

5

Phase sequence incorrect in bypass

6

Input frequency unstable in bypass

7

Battery overcharged

8

Low battery

9

Overload alarm

10

Fan alarm

11

EPO enabled

12

Unable to turn on UPS

13

Over temperature alarm

14

Charger alarm

15

Remote auto shutdown

16

L1 input fuse not working

17

L2 input fuse not working

18

L3 input fuse not working

19

Positive PFC abnormal in L1

20

Negative PFC abnormal in L1

21

Positive PFC abnormal in L2

22

Negative PFC abnormal in L2

23

Positive PFC abnormal in L3

24

Negative PFC abnormal in L3

25

Abnormal in CAN-bus communication

26

Abnormal in synchronous signal circuit

27

Abnormal in synchronous pulse signal circuit

28

Abnormal in host signal circuit

29

Male connector of parallel cable not connected well

30

Female connector of parallel cable not connected well

31

Parallel cable not connected well

32

Battery connection not consistent in parallel systems

33

AC connection not consistent in parallel systems

34

Bypass connection not consistent in parallel systems

35

UPS model types not consistent in parallel systems

36

Capacity of UPSs not consistent in parallel systems

37

Auto restart setting not consistent in parallel systems

38

Battery cell over charge

39

Battery protection setting not consistent in parallel systems

40

Battery detection setting not consistent in parallel systems

41

Bypass not allowed setting not consistent in parallel systems

42

Converter setting not consistent in parallel systems

43

High loss point for frequency in bypass mode not consistent in parallel systems

44

Low loss point for frequency in bypass mode not consistent in parallel systems

45

High loss point for voltage in bypass mode not consistent in parallel systems

46

Low loss point for voltage in bypass mode not consistent in parallel systems

47

High loss point for frequency in AC mode not consistent in parallel systems

48

Low loss point for frequency in AC mode not consistent in parallel systems

49

High loss point for voltage in AC mode not consistent in parallel systems

50

Low loss point for voltage in AC mode not consistent in parallel systems

51

Warning for locking in bypass mode after 3 consecutive overloads within 30 min

52

Warning for three-phase AC input current unbalance

53

Warning for a three-phase input current unbalance detected in battery mode

54

Warning for Inverter inter-current unbalance

55

Programmable outlets cut off pre-alarm

56

Warning for Battery replace

57

Abnormal warning on input phase angle

58

Warning!! Cover of maintain switch is open

62

EEPROM operation error

## AUTHORS
Daniele Pezzini <hyouko@gmail.com>, Arnaud Quette <arnaud.quette@gmail.com>, John Stamp <kinsayder@hotmail.com>, Peter Selinger <selinger@users.sourceforge.net>, Arjen de Korte <adkorte-guest@alioth.debian.org>, Alexander Gordeev <lasaine@lvk.cs.msu.su>

## SEE ALSO
blazer_ser(8), blazer_usb(8), nutupsdrv(8), ups.conf(5), upsc(8), upscmd(8), upsdrvctl(8), upsmon(8), upsrw(8)

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

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


nutupsdrv

title: nutupsdrv(8)

summary: generic manual for unified NUT drivers

text:
# nutupsdrv(8)

## NAME
nutupsdrv - generic manual for unified NUT drivers

## SYNOPSIS
nutupsdrv -h

nutupsdrv [OPTIONS]

## DESCRIPTION
nutupsdrv is not actually a driver. This is a combined man page for the shared code that is the core of many drivers within the Network UPS Tools package.

For information on the specific drivers, see their individual man pages.

UPS drivers provide a communication channel between the physical UPS hardware and the upsd(8) server. The driver is responsible for translating the native protocol of the UPS to the common format used by the rest of this package.

The core has two modes of operation which are determined by the command line switches. In the normal mode, the driver will periodically poll the UPS for its state and parameters. The results of this command is presented to upsd. The driver will also handle setting variables and instant commands if available.

The driver can also instruct the UPS to shut down the load, possibly after some delay. This mode of operation is intended for cases when it is known that the UPS is running out of battery power and the systems attached must be turned off to ensure a proper reboot when power returns.

Note You probably don’t want to use any of these options directly. You should use upsdrvctl(8) to control your drivers, and ups.conf(5) to configure them. The rest of this manual describes options and parameters that generally are not needed by normal users.

## OPTIONS
-h

Display a help message without doing anything else. This will also list possible values for -x in that driver, and other help text that the driver’s author may have provided.

-a id

Autoconfigure this driver using the id section of ups.conf(5). This argument is mandatory when calling the driver directly.

-D

Raise the debugging level. Use this multiple times to see more details. Running a driver in debug mode will prevent it from backgrounding after startup. It will keep on logging information to the console until it receives a SIGINT (usually Ctrl-C) or SIGTERM signal. The level of debugging needed depends both on the driver and the problem you’re trying to diagnose. Therefore, first explain the problem you have with a driver to a developer/maintainer, before sending them debugging output. More often than not, if you just pick a level, the output may be either too limited or too verbose to be of any use.

-q

Raise log level threshold. Use this multiple times to log more details. The debugging comment above also applies here.

-i interval

Set the poll interval for the device.

-V

Print only version information, then exit.

-L

Print a parseable list of driver variables. Mostly useful for configuration wizard programs.

-k

("Kill" power) Forced shutdown mode. The UPS will power off the attached load, if possible. You should use upsdrvctl shutdown whenever possible instead of calling this directly.

-r directory

The driver will chroot(2) to directory during initialization. This can be useful when securing systems. In addition to the state path, many systems will require /dev/null to exist within directory for this to work. The serial ports are opened before the chroot call, so you do not need to create them inside the jail. In fact, it is somewhat safer if you do not.

-u username

If started as root, the driver will setuid(2) to the user id associated with username. If you do not specify this value and start it as root, the driver will switch to the default value that was compiled into the code. This is typically nobody, and is far from ideal.

-x var=val

Define a variable called var with the value of var in the driver. This varies from driver to driver - see the specific man pages for more information. This is like setting var=val in ups.conf(5), but -x overrides any settings from that file.

## DIAGNOSTICS
Information about the startup process is printed to stdout. Additional messages after that point are available in the syslog. After upsd(8) starts, the UPS clients such as upsc(8) can be used to query the status of an UPS.

## PROGRAM CONTROL
You should always use upsdrvctl(8) to control the drivers. While drivers can be started by hand for testing purposes, it is not recommended for production use.

## FILES
ups.conf

Required configuration file. This contains all details on which drivers to start and where the hardware is attached.

## BUGS
Some of the drivers may have bugs. See their manuals for more information.

## SEE ALSO
Server: upsd(8)

Clients: upsc(8), upscmd(8), upsrw(8), upslog(8), upsmon(8)

CGI programs: upsset.cgi(8), upsstats.cgi(8), upsimage.cgi(8)

Driver control: upsdrvctl(8)

Drivers: al175(8) apcsmart(8), bcmxcp(8), bcmxcp_usb(8), belkin(8), belkinunv(8), bestfcom(8), bestuferrups(8), bestups(8), blazer_ser(8), blazer_usb(8), cyberpower(8), dummy-ups(8), etapro(8), everups(8), gamatronic(8), genericups(8), isbmex(8), liebert(8), masterguard(8), metasys(8), mge-shut(8), mge-utalk(8), mge-xml(8), newmge-shut(8), nitram(8), nutdrv_qx(8), oneac(8), optiups(8), powercom(8), powerman-pdu(8), powerpanel(8), rhino(8), richcomm_usb(8), safenet(8), snmp-ups(8), solis(8), tripplite(8), tripplitesu(8), tripplite_usb(8), usbhid-ups(8), upscode2(8), victronups(8)

Internet resources: The NUT (Network UPS Tools) home page: http://www.networkupstools.org/


oneac

title: oneac(8)

summary: Driver for Oneac UPS equipment

text:
# oneac(8)

## NAME
oneac - Driver for Oneac UPS equipment

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

## SUPPORTED HARDWARE
This driver supports various Oneac UPS families:

•EG (late 80s, early 90s, plug-in serial interface card)

•ON (early and mid-90s, plug-in serial interface card)

•OZ (mid-90s on, DB-25 std., interface slot)

•OB (early 2000’s on, big cabinet, DB-25 std., interface slot)

If your UPS is equipped with the Basic Interface card, use the genericups(8) driver.

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

testtime=num

Change battery test time from the 2 minute default.

offdelay=num

Change shutdown delay time from 0 second default.

## INSTANT COMMANDS
This driver supports the following Instant Commands. (See upscmd(8))

### All UPS units
shutdown.return

Turn off the load possibly after a delay and return when power is back.

shutdown.stop

Stop a shutdown in progress.

shutdown.reboot

Shut down the load briefly while rebooting the UPS.

test.failure.start

Starts a 15 second long simulation of an input power failure.

test.battery.start.quick

Start a "quick" battery test. The default time is 2 minutes. This time can be set in the ups.conf file. See testime above.

test.battery.stop

Stops a battery test that is in progress.

### All ON UPS units
reset.input.minmax

Reset the minimum and maximum input line voltage values seen since the last reset or power on.

### Newer ON UPS units
test.panel.start

Start testing the UPS panel.

test.battery.start.deep

Start a "deep" battery test. This test runs the UPS until the low battery point and then returns to the AC line.

reset.input.minmax

Reset the minimum and maximum input line voltage values seen since the last reset or power on.

beeper.enable

Enable UPS beeper/buzzer.

beeper.disable

Disable UPS beeper/buzzer.

beeper.mute

Mutes the UPS beeper/buzzer for the current alarm condition(s).

## WRITABLE VARIABLES
See upsrw(8) to see what variables are writable for the UPS.

Note If your UPS supports writing battery.runtime.low, the new set value is to be entered in minutes (up to 99) but the reported value is reported in seconds (set value * 60).

Note If your UPS supports input.transfer.low and input.transfer.high, those values are used to create an allowable output range. The UPS will do what it can to keep the output voltage value within the defined range (for example: tap change or switch to inverter).

## AUTHOR
Bill Elliot <bill@wreassoc.com>, Eric Lawson <elawson@inficad.com>

## SEE ALSO

### The core driver:
nutupsdrv(8)

### Internet resources:
The NUT (Network UPS Tools) home page: http://www.networkupstools.org/


optiups

title: optiups(8)

summary: Driver for Opti\-UPS (Viewsonic) UPS and Zinto D (ONLINE\-USV) equipment

text:
# optiups(8)

## NAME
optiups - Driver for Opti-UPS (Viewsonic) UPS and Zinto D (ONLINE-USV) equipment

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

## SUPPORTED HARDWARE
optiups was originally written against a PowerES 280es in nut-0.45. It was revised for nut-2.0.1 and tested against a PowerES 420E. It is expected to work with at least the PowerES, PowerPS, and PowerVS models.

This driver additionally supports a Zinto D from ONLINE USV-Systeme AG because of their very similar commands, but it is unknown if it also works with other UPS from them.

This driver will not work with the PowerES stock serial cable. You will need to construct your own three conductor cable:

```
UPS 6 -> PC 3
UPS 9 -> PC 2
UPS 4 -> PC 5
```

The cable for Online-USV uses pin UPS 7 (not UPS 4) → PC 5.

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

status_only

Only poll for critical status information. Without this, optiups (and all NUT drivers) poll all sorts of information from the UPS fairly often. It is probably not often enough to hurt anything, so this option probably is not very useful, unless you have a flaky serial connection or a highly loaded machine.

nowarn_noimp

Does not print warnings when the UPS reports that a variable is not implemented or not pollable. Without the option you will get a message sent to your system logs each time NUT polls the UPS. If you specify nowarn_noimp, this message will only be logged once.

fake_lowbatt

This forces the low battery flag true. Without it, if you want to test your UPS, you will have to unplug it and wait until the battery drops to a low/critical voltage level before NUT will respond and power down your system. With the flag, NUT should power down the system soon after you pull the plug. When you are done testing, you should remove this flag. For basic shutdown configuration testing, the command upsmon -c fsd is preferred.

powerup

Zinto D from ONLINE-USV cannot be identified when switched to standby. Set this flag to allow the driver to power-up your Zinto UPS. This will also power-up your equipment connected to the UPS!

## BUGS
On the 420E, ups.serial and ups.temperature are unsupported features. This is not a bug in NUT or the NUT driver, just the way things are with this UPS.

## AUTHOR
Russell Kroll, Scott Heavner, Matthias Goebl

## SEE ALSO

### The core driver:
nutupsdrv(8)

### Internet resources:
The NUT (Network UPS Tools) home page: http://www.networkupstools.org/


powercom

title: powercom(8)

text:
# powercom(8)

## NAME
powercom - UPS driver for serial Powercom/Trust/Advice UPS equipment

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

## SUPPORTED HARDWARE
This driver supports many similar kinds of serial UPS hardware (as well as a few USB UPS models with USB-to-serial adapters). The most common ones are the Trust 425/625, Powercom, and Advice Partner/King PR750. Others using the same protocol may also work. For USB connections, you might need usbhid-ups(8).

For more specific guidance on which driver is applicable for a USB connection, see the NUT Hardware Compatibility List (HCL).

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

linevoltage=value

An integer specifying the line voltage. It can’t be auto detected. Acceptable values are in the range of 110-120 or 220-240. The default is 230.

manufacturer=name

Specify the manufacturer name, which also can’t be auto detected. This is a user defined string, so any name is acceptable. The default is PowerCom.

modelname=name

Specify the model name, which also can’t be auto detected. This is a user defined string, so any name is acceptable. The default is Unknown.

serialnumber=value

Like modelname above, but for the serial number. The default is Unknown.

type=name

The exact type of the communication protocol within the powercom family, that will be used to communicate with the UPS. The type is named after the first modelname that was coded with that protocol. The acceptable names are Trust, Egys, KP625AP, IMP, KIN, BNT, BNT-other and OPTI. The default is Trust. BNT-other is a special type for other BNT models (such as the 1500A at 120V and can be used to override ALL models using ALL of the following values.

shutdownArguments={{minutes,seconds},whether_minutes_should_be_used}

The minutes and seconds that the UPS should wait between receiving the shutdown command and actually shutting off. The other argument should be set to the character n only when the minutes value should be skipped and not sent to the UPS. The default is type-dependent and is given below. The braces and commas are mandatory. Note that there should be no whitespace characters.

numOfBytesFromUPS=value

The number of bytes in a UPS frame: 16 is common, 11 for Trust. The default is type-dependent and is given below.

methodOfFlowControl=name

The method of serial communication flow control that is engaged by the UPS. The default is type-dependent and is given below. Acceptable names are dtr0rts1, dtr1 or no_flow_control.

validationSequence={{index1,value1},{index2,value2},{index3,value3}}

(Only for types KP625AP, Trust, Egys.) 3 pairs to be used for validating the UPS by comparing bytes of the raw data with constant values. The index selects the byte from the UPS (see numOfBytesFromUPS) and the value is for matching to the byte. The default is type-dependent and is given below. The braces and commas are mandatory, as the lack of white space characters.

frequency={A,B}

(Only for types KP625AP, Trust, Egys.) A pair to convert the raw frequency data to a human-readable frequency reading using the function 1/(A*x+B). If the raw value x IS the frequency, then set A=1/(x^2) and B=0. The default is type-dependent and is given below. Do note that the braces and commas are mandatory as well, as the lack of whitespace characters.

loadPercentage={BatteryA,BatteryB,LineA,LineB}

(Only for types KP625AP, Trust, Egys.) A quad to convert the raw load data to human readable load percentage reading using the function A*x+B. If the raw value x IS the Load Percent, then set A=1 and B=0. The default is type-dependent and is given below. Do note that the braces and commas are mandatory, as the lack of white space characters.

batteryPercentage={Battery1,Battery2,Battery3,Line4,Line5}

(Only for KP625AP, Trust, Egys.) A 5 tuple to convert the raw battery and line data to a human-readable battery and line percentage reading using the functions (Battery) A*x+B*y+C and (Line) D*x+E. If the raw value x IS the Battery Percent, then set A=1, B=0, C=0, D=1, E=0. The default is type-dependent and is given below. Do note that the braces and commas are mandatory, as the lack of white space characters.

voltage={240A,240B,120A,120B}

(Only for types KP625AP, Trust, Egys.) A quad that is used convert the raw voltage data to a human-readable voltage reading using the function A*x+B. If the raw value x IS HALF the Voltage, then set A=2, B=0. The default is type-dependent and is given below. Do note that the braces and commas are mandatory, as well as the lack of whitespace characters.

## DEFAULT VALUES FOR THE EXTRA ARGUMENTS

```
linevoltage = 230
manufacturer = PowerCom
modelname = Unknown
serialnumber = Unknown
type = Trust
```

The rest of the default values for the extra arguments are type-dependent. However, BNT-other is a special type that can be used to override ALL values for ALL models.

### Trust

```
numOfBytesFromUPS = 11
methodOfFlowControl = dtr0rts1
validationSequence = {{5,0},{7,0},{8,0}}
shutdownArguments = {{0,10},n}
frequency = {0.00020997,0.00020928}
loadPercentage = {6.1343,-0.3808,4.3110,0.1811}
batteryPercentage = {5.0000,0.3268,-825.00,4.5639,-835.82}
voltage = {1.9216,-0.0977,0.9545,0.0000}
```

### KP625AP

```
numOfBytesFromUPS = 16
methodOfFlowControl = dtr0rts1
validationSequence = {{5,0x80},{7,0},{8,0}}
shutdownArguments = {{0,10},n}
frequency = {0.00020997,0.00020928}
loadPercentage = {6.1343,-0.3808,4.3110,0.1811}
batteryPercentage = {5.0000,0.3268,-825.00,4.5639,-835.82}
voltage = {1.9216,-0.0977,0.9545,0.0000}
```

### Egys

```
numOfBytesFromUPS = 16
methodOfFlowControl = no_flow_control
validationSequence = {{5,0x80},{7,0},{8,0}}
shutdownArguments = {{0,10},n}
frequency = {0.00020997,0.00020928}
loadPercentage = {6.1343,-0.3808,1.3333,0.6667}
batteryPercentage = {5.0000,0.3268,-825.00,2.2105,-355.37}
voltage = {1.9216,-0.0977,0.9545,0.0000}
```

### IMP

```
numOfBytesFromUPS = 16
methodOfFlowControl = no_flow_control
validationSequence = {{5,0xFF},{7,0},{8,0}}
shutdownArguments = {{1,30},y}
```

### KIN

```
numOfBytesFromUPS = 16
methodOfFlowControl = no_flow_control
validationSequence = {{11,0x4b},{8,0},{8,0}}
shutdownArguments = {{1,30},y}
```

### BNT

```
numOfBytesFromUPS = 16
methodOfFlowControl = no_flow_control
validationSequence = {{11,0x42},{8,0},{8,0}}
shutdownArguments = {{1,30},y}
```

### BNT-other

```
numOfBytesFromUPS = 16
methodOfFlowControl = no_flow_control
validationSequence = {{8,0},{8,0},{8,0}}
shutdownArguments = {{1,30},y}
frequency = {0.00027778,0.0000}
loadPercentage = {1.0000,0.0,1.0000,0.0}
batteryPercentage = {1.0000,0.0000,0.0000,1.0000,0.0000}
voltage = {2.0000,0.0000,2.0000,0.0000}
```

### OPTI

```
numOfBytesFromUPS = 16
methodOfFlowControl = no_flow_control
validationSequence = {{5,0xFF},{7,0},{8,0}}
shutdownArguments = {{1,30},y}
```

## AUTHOR
Peter Bieringer <pb@bieringer.de>, Alexey Sidorov <alexsid@altlinux.org>, Keven L. Ates <atescomp@gmail.com>

## SEE ALSO

### The core driver:
nutupsdrv(8)

### Internet resources:
The NUT (Network UPS Tools) home page: http://www.networkupstools.org/


powerpanel

title: powerpanel(8)

text:
# powerpanel(8)

## NAME
powerpanel - Driver for PowerPanel Plus compatible UPS equipment

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

## SUPPORTED HARDWARE
This driver supports CyberPower BC1200, PR2200 and many other similar devices, both for the text and binary protocols. The driver will autodetect which protocol is used.

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

protocol=[text,binary]

Override the default autodetection of the protocol.

manufacturer=value

If you don’t like the autodetected value, you can override this by setting it here.

model=value

Like manufacturer above.

serial=value

Like manufacturer above.

ondelay=value

Time to wait before switching on the UPS (1 - 9999 minutes, 0=indefinite). Only available with the text protocol driver (see Support Status).

offdelay=value

Time to wait before shutting down the UPS (6 - 600 seconds). Values below 60 seconds will be truncated to 6 seconds intervals, values above 60 seconds to 60 seconds intervals. Only available with the text protocol driver (see Support Status).

## VARIABLES
Depending on the type of your UPS unit, some of the following variables may be changed with upsrw(8). If the driver can’t read a variable from the UPS, it will not be made available.

input.transfer.high

writable: high transfer voltage point in V

input.transfer.low

writable: low transfer voltage point in V

battery.charge.low

writable: remaining battery charge percentage for low battery warning

output.voltage.nominal

writable: nominal output voltage in V

ups.start.battery

writable: allow cold start from battery

## COMMANDS
Depending on the type of your UPS unit, some of the following commands may be available.

•test.battery.start.quick, test.battery.stop

•beeper.enable, beeper.disable, beeper.toggle

•shutdown.return, shutdown.reboot, shutdown.stayoff

On many devices, these commands are unreliable, so before using them you must verify that these work as expected (see Shutdown Issues).

•shutdown.stop

## SUPPORT STATUS
Vendor support is absent for this driver, so if you need some features that are currently not available, provide ample documentation on what the driver should sent to the UPS in order to make this work. If more information would be available on the binary protocol, it would probably be possible to make ondelay and offdelay configurable. So far, nobody has taken the time to investigate what we should tell the UPS to make this work, and CyberPower isn’t willing to share this with us.

## SHUTDOWN ISSUES
If the shutdown.return command on your UPS doesn’t seem to work, chances are that your UPS is an older model. Try a couple of different settings for offdelay. If no value in the range 6..600 works, your UPS likely doesn’t support this. In order to get the expected behaviour, it requires shutdown.stayoff (when on battery) and shutdown.reboot (when on mains). The driver will automatically fallback to these commands if shutdown.return fails, and tries to detect which one should be used when called with the -k option (or through upsdrvctl shutdown).

This isn’t bullet-proof, however, and you should be prepared that the power will either not be shutdown or that it doesn’t return when the power comes back. All models supported by the binary protocol and many supported through the text protocol are affected by this.

## KNOWN PROBLEMS
The CyberPower OP series don’t offer direct voltage, charge, frequency and temperature readings. Instead, they will return a binary value that needs conversion to the actual value.

The exact conversion needed is unknown at the time of this writing, hence an estimation was made based om readings from actual devices. This may (probably will) be off, possibly a lot. Unless you can tell us the exact mapping between values from the UPS and actual readings, don’t bother to complain. We’ve done the best we can based on the limited information available. Remember, a UPS isn’t a measuring instrument.

## AUTHORS
Arjen de Korte <arjen@de-korte.org>, Doug Reynolds <mav@wastegate.net>

## SEE ALSO

### The core driver:
nutupsdrv(8)

### Internet resources:
The NUT (Network UPS Tools) home page: http://www.networkupstools.org/


rhino

title: rhino(8)

text:
# rhino(8)

## NAME
rhino - Driver for Brazilian Microsol RHINO UPS equipment

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

## SUPPORTED HARDWARE
This driver has been tested with :

•Rhino 6000 VA

•Rhino 7500 VA

•Rhino 10000 VA

•Rhino 20000 VA

All Rhino models are sinusoidal on-line.

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

battext = n - (default = 0, no extra battery, where n = Ampere*hour )

## COMMANDS
•load.on - Turn on the load immediately

•load.off - Turn off the load immediately

•bypass.start - Put the UPS in bypass mode

•bypass.stop - Put the UPS out of bypass mode

•shutdown.stayoff - Shut down in 3 minutes and do not return

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

## SEE ALSO

### The core driver:
nutupsdrv(8)

### Internet resources:
The NUT (Network UPS Tools) home page: http://www.networkupstools.org/


title: richcomm_usb(8)

summary: Driver UPS equipment using Richcomm dry\-contact to USB solution

text:
# richcomm_usb(8)

## NAME
richcomm_usb - Driver UPS equipment using Richcomm dry-contact to USB solution

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

## SUPPORTED HARDWARE
The Richcomm dry-contact to USB solution is a generic interface that is used to upgrade an existing (RS-232) contact closure UPS interface to USB. As such, all the limitations of the underlying contact closure interface apply. This means that you will only get the essentials in ups.status: OL, OB, and LB. See also genericups(8).

## BUGS
Most contact-closure UPSes will not power down the load if the line power is present. This can create a race when using slave 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.

## AUTHORS
Peter van Valderen <p.v.valderen at probu.nl>, Dirk Teurlings <dirk at upexia.nl>

## SEE ALSO

### The core driver:
nutupsdrv(8)

### The generic serial driver:
genericups(8)

### Internet resources:
The NUT (Network UPS Tools) home page: http://www.networkupstools.org/


title: riello_ser(8)

text:
# riello_ser(8)

## NAME
riello_ser - Driver for Riello UPS Protocol UPS equipment

## SYNOPSIS
riello_ser -h

riello_ser -a UPS_NAME [OPTIONS]

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

## SUPPORTED HARDWARE
riello_ser supports all recent Riello UPS, Aros UPS models which use the Riello UPS GPSER and SENTR protocols.

Older Riello UPS products are not supported.

## AUTHOR
Massimo Zampieri

## SEE ALSO

### The core driver
nutupsdrv(8)

### Internet resources
The NUT (Network UPS Tools) home page: http://www.networkupstools.org/


title: riello_usb(8)

text:
# riello_usb(8)

## NAME
riello_usb - Driver for Riello UPS Protocol UPS equipment via USB

## SYNOPSIS
riello_usb -h

riello_usb -a UPS_NAME [OPTIONS]

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

## SUPPORTED HARDWARE
riello_usb supports all recent Riello UPS with USB.

Older Riello UPS products are not supported.

## AUTHOR
Massimo Zampieri

## SEE ALSO

### The core driver
nutupsdrv(8)

### Internet resources
The NUT (Network UPS Tools) home page: http://www.networkupstools.org/


safenet

title: safenet(8)

text:
# safenet(8)

## NAME
safenet - Driver for SafeNet compatible UPS equipment

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

## SUPPORTED HARDWARE
This driver supports UPS equipment which can be controlled via SafeNet v1.0 for Windows (serial interface only).

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

manufacturer=value

Autodetection of this parameter is not possible yet (and it probably never will be). Therefore, this user-defined string accepts any name. The default is unknown.

modelname=value

Like manufacturer above. The default is unknown.

serialnumber=value

Like manufacturer above. The default is unknown.

ondelay=value

Time to wait before switching on the UPS (minutes). Defaults to 1 minute.

offdelay=value

Time to wait before shutting down the UPS (seconds). Defaults to 30 seconds.

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

test.battery.start

Start UPS self test

test.battery.stop

Cancel UPS self test

test.failure.start

Start simulated power failure

test.failure.stop

Cancel simulated power failure

beeper.enable

Enable the UPS beeper

beeper.mute

Temporarily mute the UPS beeper

beeper.toggle

Toggle the UPS beeper

shutdown.return

Turn off the load and wait for the power to return. Uses the timer defined by offdelay.

shutdown.reboot

Turn off the load and return. Uses the timers defined by offdelay and ondelay.

## KNOWN PROBLEMS
If you run the shutdown.return command with mains present, the output may stay on or switch off and not back on again. The shutdown.reboot command will unconditionally switch on the load again (with or without mains present).

If the driver is called with the -k option (or through upsdrvctl shutdown) it tries to detect which command should be used in an attempt to stay off until mains is present again or to cycle the output if the power returned in the mean time. This isn’t bullet-proof, and you should be prepared that the power will either not be shutdown, or that it doesn’t return when the power comes back.

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

## SEE ALSO

### The core driver:
nutupsdrv(8)

### Internet resources:
The NUT (Network UPS Tools) home page: http://www.networkupstools.org/


solis

title: solis(8)

text:
# solis(8)

## NAME
solis - Driver for Brazilian Microsol SOLIS UPS equipment

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

## SUPPORTED HARDWARE
This driver has been tested with :

•Solis 1000 VA

•Solis 1500 VA

•Solis 2000 VA

•Solis 3000 VA

•Back-UPS BZ1200-BR

•Back-UPS BZ2200BI-BR

All Solis models are sinusoidal on-line.

In 2009, Schneider Electric acquired Microsol Technologies, and by 2012, the entire Microsol line of equipment was being sold under the APC brand.

## 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 = 1 - (default = 0, no programable shutdown )

## COMMANDS
•shutdown.return - Shut down in .3 minutes and restart in .3 minutes

•shutdown.stayoff - Shut down in .3 minutes and do not return

## ISSUES
The APC version of the Microsol protocol is slightly incompatible with the solis driver. As of version 0.62 of the solis driver, the driver will connect to the UPS, but some values are read incorrectly.

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

## SEE ALSO

### The core driver:
nutupsdrv(8)

### Internet resources:
The NUT (Network UPS Tools) home page: http://www.networkupstools.org/


tripplite

title: tripplite(8)

summary: Driver for Tripp\-Lite SmartPro UPS equipment

text:
# tripplite(8)

## NAME
tripplite - Driver for Tripp-Lite SmartPro UPS equipment

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

## SUPPORTED HARDWARE
This driver should work on the SmartPro line, including the SMART700 and SMART700SER. It only supports SmartPro models that communicate using the serial port.

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

offdelay=num

Time to wait before the UPS is turned off after the kill power command is sent. The default value is 64 (in seconds).

rebootdelay=num

Set the timer before the UPS is cycled after the reboot command is sent. The default value is 64 (in seconds).

startdelay=num

Set the time that the UPS waits before it turns itself back on after a reboot command. The default value is 60 (in seconds).

## KNOWN ISSUES AND BUGS
Battery charge information may not be correct for all UPSes. It is tuned to be correct for a SMART700SER. Other models may not provide correct information. Information from the manufacturer would be helpful.

## AUTHORS
Rickard E. (Rik) Faith, Nicholas Kain

## SEE ALSO

### The core driver:
nutupsdrv(8)

### Other drivers for Tripp-Lite hardware:
tripplitesu(8), tripplite_usb(8), usbhid-ups(8)

### Internet resources:
The NUT (Network UPS Tools) home page: http://www.networkupstools.org/


title: tripplite_usb(8)

text:
# tripplite_usb(8)

## NAME
tripplite_usb - Driver for older Tripp Lite USB UPSes (not PDC HID)

## SYNOPSIS
tripplite_usb -h

tripplite_usb -a UPS_NAME [OPTIONS]

## SUPPORTED HARDWARE
This driver should work with older Tripp Lite UPSes which are detected as USB HID-class devices, but are not true HID Power-Device Class devices. So far, the devices supported by tripplite_usb have product ID 0001, and the newer units (such as those with "LCD" in the model name) with product ID 2001 require the usbhid-ups(8) driver instead. Please report success or failure to the nut-upsuser mailing list. A key piece of information is the protocol number, returned in ups.debug.0. Also, be sure to turn on debugging (-DDD) for more informative log messages. If your Tripp Lite UPS uses a serial port, you may wish to investigate the tripplite(8) or tripplite_su(8) driver.

This driver has been tested with the following models:

•INTERNETOFFICE700

•OMNIVS1000

•OMNIVS1500XL (some warnings)

•SMART700USB

•SMART1500RM2U

•SMART2200RMXL2U

•SMART3000RM2U

If you have used Tripp Lite’s PowerAlert software to connect to your UPS, there is a good chance that tripplite_usb will work if it uses one of the following protocols:

•Protocol 0004

•Protocol 1001

•Protocol 2001

•Protocol 3003

On the other hand, if the web page for your UPS on the Tripp-Lite website says "HID-compliant USB port also enables direct integration with built-in power management and auto-shutdown features of Windows and MAC OS X", then you should use the usbhid-ups(8) driver instead.

## EXTRA ARGUMENTS
This driver supports the following optional settings in the ups.conf(5) file (or with -x on the command line):

offdelay

This setting controls the delay between receiving the "kill" command (-k) and actually cutting power to the computer.

battery_min, battery_max

These floating-point values correspond to the "empty" (10%) and "full" (100%) voltages of the battery. They are used for an approximation of the battery state-of-charge. The calculated battery.charge value will be clamped to the range of 10% through 100%, so the resting voltage of the charged battery can be used for battery_max, and the higher float charge voltage should not cause problems.

bus

This regular expression is used to match the USB bus (as seen in /proc/bus/usb/devices or lsusb(8); including leading zeroes).

product

A regular expression to match the product string for the UPS. This would be useful if you have two different Tripp Lite UPS models connected to the system, and you want to be sure that you shut them down in the correct order.

Note This regex is matched against the full USB product string as seen in lsusb(8). The ups.model in the upsc(1) output only lists the name after TRIPP LITE, so to match a SMART2200RMXL2U, you could use the regex .*SMART2200.*.

productid

The productid is a regular expression which matches the UPS PID as four hexadecimal digits. So far, the only devices that work with this driver have PID 0001.

serial

It does not appear that these particular Tripp Lite UPSes use the iSerial descriptor field to return a serial number. However, in case your unit does, you may specify it here.

For more information on regular expressions, see regex(7)

## RUNTIME VARIABLES
ups.delay.shutdown

This variable is the same as the offdelay setting, but it can be changed at runtime by upsrw(8).

ups.id

Some SMARTPRO models feature an ID that can be set and retrieved. If your UPS supports this feature, this variable will be listed in the output of upsrw(8).

outlet.1.switch

Some Tripp Lite units have a switchable outlet (usually outlet #1) which can be turned on and off by writing 1 or 0, respectively, to outlet.1.switch with upsrw(8). If your unit has multiple switchable outlets, substitute the outlet number for 1 in the variable name. Be sure to test this first - there is no other way to be certain that the number used by the driver matches the label on the unit.

## KNOWN ISSUES AND BUGS
The driver was not developed with any official documentation from Tripp Lite, so certain events may confuse the driver. If you observe any strange behavior, please re-run the driver with -DDD to increase the verbosity.

So far, the Tripp Lite UPSes do not seem to have a serial number or other globally unique identifier accessible through USB. Thus, when monitoring several Tripp Lite USB UPSes, you should use either the bus or product configuration options to uniquely specify which UPS a given driver instance should control.

For instance, you can easily monitor an OMNIVS1000 and a SMART1500RM2U at the same time, since they have different USB Product ID strings. If you have two SMART1500RM2U units, you would have to find which USB bus number each unit is on (via lsusb(8)), which may result in ambiguities if the available USB ports are on the same bus.

Some of the SMART*2U models have an ID number, but because this ID is not exposed as a USB string descriptor, there is no easy way to use this ID to distinguish between multiple UPS units on a single machine. The UPS would need to be claimed by the driver in order to read this ID.

## AUTHOR
Written by Charles Lepple, based on the tripplite(8) driver by Rickard E. (Rik) Faith and Nicholas Kain. Please do not email the authors directly - use the nut-upsdev mailing list.

A Tripp Lite OMNIVS1000 was graciously donated to the NUT project by Bradley Feldman (http://www.bradleyloritheo.com)

## SEE ALSO

### The core driver:
nutupsdrv(8)

### Other drivers for Tripp-Lite hardware:
tripplite(8), tripplitesu(8), usbhid-ups(8)

### Other tools:
regex(7), lsusb(8)

## INTERNET RESOURCES
The NUT (Network UPS Tools) home page: http://www.networkupstools.org/


tripplitesu

title: tripplitesu(8)

summary: Driver for Tripp\-Lite SmartOnline (SU) UPS equipment

text:
# tripplitesu(8)

## NAME
tripplitesu - Driver for Tripp-Lite SmartOnline (SU) UPS equipment

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

## SUPPORTED HARDWARE
This driver supports the Tripp Lite SmartOnline family (via the serial port).

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

lowbatt=num

Set the low battery warning threshold in percent at which shutdown is initiated by upsmon(8). By default, the UPS may not report low battery until there are only a few seconds left. Common values are around 25—30.

## AUTHOR
Allan N. Hessenflow <allanh@kallisti.com>

## SEE ALSO

### The core driver:
nutupsdrv(8)

### Other drivers for Tripp-Lite hardware:
tripplite(8), tripplite_usb(8), usbhid-ups(8)

### Internet resources:
The NUT (Network UPS Tools) home page: http://www.networkupstools.org/


title: upscode2(8)

text:
# upscode2(8)

## NAME
upscode2 - Driver for UPScode II compatible UPS equipment

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

## SUPPORTED HARDWARE
This driver supports UPS equipment which can be controlled via the UPScode II protocol. This is mainly Fiskars, Powerware equipment, but also some (probably OEM’ed) products from Compaq.

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

manufacturer=value

Autodetection of this parameter is not possible yet (and it probably never will be). Therefore, this user-defined string accepts any name. The default is unknown.

input_timeout=value

The timeout waiting for a response from the UPS. Some UPS models have shown to be rather slow, resulting in frequent messages about empty responses from the UPS. If you see this, try increasing this value.

output_pace=value

Delay between characters sent to the UPS. This was added for completeness with the above parameter. It has not shown to be needed yet.

baudrate=value

The default baudrate is 1200, which is the standard for the UPScode II protocol.

full_update_timer=value

Number of seconds between collection of normative values.

use_crlf

Flag to set if commands towards to UPS need to be terminated with CR-LF, and not just CR.

use_pre_lf

Flag to set if commands towards to UPS need to be introduced with an LF. A Compaq T1500h is known to need this.

## COMMANDS
The driver supports the following commands for those UPSen that support them. The available commands are autodetected during initialization, so you should check availability with upscmd -l.

•test.panel.start - Start UPS self test

•test.battery.start - Start battery self test

•beeper.enable - Enable UPS beeper

•beeper.disable - Disable UPS beeper

•shutdown.return - Shut down in 1 second and wait for power to return

•shutdown.stayoff - Shut down in 1 seconds

•shutdown.reboot - Shut down in 1 seconds and reboot after 1 minute

•shutdown.reboot.graceful - Shut down in 20 seconds and reboot after 1 minute

## NOTES
The Powerware UPS models that this driver has been tested against until now have not returned a value for battery.charge. Therefore, the driver will guestimate a value based on the nominal battery min/max and the current battery voltage.

## AUTHOR
Håvard Lygre <hklygre@online.no>, Niels Baggesen <niels@baggesen.net>

## SEE ALSO

### The core driver:
nutupsdrv(8)

### Internet resources:
The NUT (Network UPS Tools) home page: http://www.networkupstools.org/


upsd

title: upsd(8)

summary: UPS information server

text:
# upsd(8)

## NAME
upsd - UPS information server

## SYNOPSIS
upsd -h

upsd [OPTIONS]

## DESCRIPTION
upsd is responsible for serving the data from the drivers to the clients. It connects to each driver and maintains a local cache of the current state. Queries from the clients are served from this cache, so delays are minimal.

It also conveys administrative messages from the clients back to the drivers, such as starting tests, or setting values.

Communication between upsd and clients is handled on a TCP port. Configuration details for this port are described in upsd.conf(8).

This program is essential, and must be running at all times to actually make any use out of the drivers and clients.

Controls in the configuration files allow you to limit access to the server, but you should also use a firewall for extra protection. Client processes such as upsmon(8) trust upsd for status information about the UPS hardware, so keep it secure.

## OPTIONS
-c command

Send command to the background process as a signal. Valid commands are: reload

reread configuration files

stop

stop process and exit

-D

Raise the debug level. Use this multiple times for additional details.

-h

Display the help text.

-r directory

upsd will chroot(2) to directory shortly after startup and before parsing any configuration files with this option set. You can use this to create a "jail" for greater security. You must coordinate this with your drivers, as upsd must be able to find the state path within directory. See upsdrvctl(8) and nutupsdrv(8).

-u user

Switch to user user after startup if started as root. This overrides whatever you may have compiled in with configure --with-user.

-V

Display the version of the program.

## RELOADING
upsd can reload its configuration files without shutting down the process if you send it a SIGHUP or start it again with -c reload. This only works if the background process is able to read those files.

If you think that upsd can’t reload, check your syslogs for error messages. If it’s complaining about not being able to read the files, then you need to adjust your system to make it possible. Either change the permissions on the files, or run upsd as another user that will be able to read them.

DO NOT make your upsd.conf or upsd.users world-readable, as those files hold important authentication information. In the wrong hands, it could be used by some evil person to spoof your master upsmon and command your systems to shut down.

## DIAGNOSTICS
upsd expects the drivers to either update their status regularly or at least answer periodic queries, called pings. If a driver doesn’t answer, upsd will declare it "stale" and no more information will be provided to the clients.

If upsd complains about staleness when you start it, then either your driver or configuration files are probably broken. Be sure that the driver is actually running, and that the UPS definition in ups.conf(5) is correct. Also make sure that you start your driver(s) before starting upsd.

Data can also be marked stale if the driver can no longer communicate with the UPS. In this case, the driver should also provide diagnostic information in the syslog. If this happens, check the serial or USB cabling, or inspect the network path in the case of a SNMP UPS.

## ACCESS CONTROL
If the server is build with tcp-wrappers support enabled, it will check if the NUT username is allowed to connect from the client address through the /etc/hosts.allow and /etc/hosts.deny files. Note that this will only be done for commands that require to be logged into the server. Further details are described in hosts_access(5).

## FILES
The general upsd configuration file is upsd.conf(5). The administrative functions like SET and INSTCMD for users are defined and controlled in upsd.users(5). UPS definitions are found in ups.conf(5).

## ENVIRONMENT VARIABLES
NUT_CONFPATH is the path name of the directory that contains upsd.conf and other configuration files. If this variable is not set, upsd uses a built-in default, which is often /usr/local/ups/etc.

NUT_STATEPATH is the path name of the directory in which upsd keeps state information. If this variable is not set, upsd uses a built-in default, which is often /var/state/ups. The STATEPATH directive in upsd.conf(5) overrides this variable.

## SEE ALSO

### Clients:
upsc(8), upscmd(8), upsrw(8), upslog(8), upsmon(8)

### CGI programs:
upsset.cgi(8), upsstats.cgi(8), upsimage.cgi(8)

### Drivers:
nutupsdrv(8), apcsmart(8), belkin(8), belkinunv(8), bestuferrups(8), bestups(8), cyberpower(8), energizerups(8), etapro(8), everups(8), genericups(8), isbmex(8), liebert(8), masterguard(8), mge-shut(8), mge-utalk(8), oneac(8), powercom(8), safenet(8), snmp-ups(8), tripplite(8), tripplitesu(8), victronups(8),

### Internet resources:
The NUT (Network UPS Tools) home page: http://www.networkupstools.org/


upsdrvctl

title: upsdrvctl(8)

summary: UPS driver controller

text:
# upsdrvctl(8)

## NAME
upsdrvctl - UPS driver controller

## SYNOPSIS
upsdrvctl -h

upsdrvctl [OPTIONS] {start | stop | shutdown} [ups]

## DESCRIPTION
upsdrvctl provides a uniform interface for controlling your UPS drivers. You should use upsdrvctl instead of direct calls to the drivers whenever possible.

When used properly, upsdrvctl lets you maintain identical startup scripts across multiple systems with different UPS configurations.

## OPTIONS
-h

Display the help text.

-r directory

If starting a driver, this value will direct it to chroot(2) into directory. This can be useful when securing systems.

This may be set in the ups.conf with "chroot" in the global section.

-t

Enable testing mode. This also enables debug mode. Testing mode makes upsdrvctl display the actions it would execute without actually doing them. Use this to test out your configuration without actually doing anything to your UPS drivers. This may be helpful when defining the sdorder directive in your ups.conf(5).

-u username

If starting a driver, this value will direct it to setuid(2) to the user id associated with username.

If the driver is started as root without specifying this value, it will use the username that was compiled into the binary. This defaults to "nobody", and is far from ideal.

This may be set in ups.conf with "user" in the global section.

-D

Raise the debug level. Use this multiple times for additional details.

## COMMANDS
upsdrvctl supports three commands - start, stop and shutdown. They take an optional argument which is a UPS name from ups.conf(5). Without that argument, they operate on every UPS that is currently configured.

start

Start the UPS driver(s). In case of failure, further attempts may be executed by using the maxretry and retrydelay options - see ups.conf(5).

stop

Stop the UPS driver(s).

shutdown

Command the UPS driver(s) to run their shutdown sequence. Drivers are stopped according to their sdorder value - see ups.conf(5).

Warning this will probably power off your computers, so don’t play around with this option. Only use it when your systems are prepared to lose power.

## ENVIRONMENT VARIABLES
NUT_CONFPATH is the path name of the directory that contains upsd.conf and other configuration files. If this variable is not set, upsdrvctl the driver use a built-in default, which is often /usr/local/ups/etc.

## DIAGNOSTICS
upsdrvctl will return a nonzero exit code if it encounters an error while performing the desired operation. This will also happen if a driver takes longer than the maxstartdelay period to enter the background.

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

### Internet resources:
The NUT (Network UPS Tools) home page: http://www.networkupstools.org/


usbhid-ups

title: usbhid-ups(8)

summary: Driver for USB/HID UPS equipment

text:
# usbhid-ups(8)

## NAME
usbhid-ups - Driver for USB/HID UPS equipment

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

This driver, formerly called newhidups, replaces the legacy hidups driver, which only supported Linux systems.

## SUPPORTED HARDWARE
usbhid-ups brings USB/HID UPS monitoring to NUT on all platform supporting USB through libusb. It should detect any UPS that uses the HID power device class, but the amount of data will vary depending on the manufacturer and model.

At the present time, usbhid-ups supports:

•the newer Eaton USB models,

•all MGE USB models,

•all Dell USB models,

•some APC models,

•some Belkin models,

•some Cyber Power Systems models,

•some Powercom models,

•some TrippLite models.

For a more complete list, refer to the NUT hardware compatibility list, available in the source distribution as data/drivers.list, or on the NUT website. You may use the "explore" driver option to gather information from HID UPSes which are not yet supported; see below for details.

This driver is known to work on:

•most Linux systems,

•FreeBSD (beta stage) and maybe other *BSD,

•Darwin / Mac OS X,

•Solaris 10.

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

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 UPS’es 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.

pollfreq=num

Set polling frequency, in seconds, to reduce the USB data flow. Between two polling requests, the driver will wait for interrupts (aka UPS notifications), which are data changes returned by the UPS by itself. This mechanism allow to avoid or reduce staleness message, due to the UPS being temporarily overloaded with too much polling requests. The default value is 30 (in seconds).

pollonly

If this flag is set, the driver will ignore interrupts it receives from the UPS (not recommended, but needed if these reports are broken on your UPS).

vendor=regex, product=regex, serial=regex, vendorid=regex, productid=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)) that must match the UPS’s entire vendor/product/serial string (minus any surrounding whitespace), or the whole 4-digit hexadecimal code for vendorid and productid. Try -DD for finding out the strings to match. Examples:

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

•-x vendorid=051d* (APC)

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

bus=regex

Select a UPS on a specific USB bus or group of busses. The argument is a regular expression that must match the bus name where the UPS is connected (e.g. bus="002", bus="00[2-3]").

explore

With this option, the driver will connect to any device, including ones that are not yet supported. This must always be combined with the "vendorid" option. In this mode, the driver will not do anything useful except for printing debugging information (typically used with -DD).

maxreport

With this option, the driver activates a tweak to workaround buggy firmware returning invalid HID report length. Some APC Back-UPS units are known to have this bug.

interruptonly

If this flag is set, the driver will not poll UPS. This also implies using of INPUT flagged objects. Some Powercom units need this option.

interruptsize=num

Limit the number of bytes to read from interrupt pipe. For some Powercom units this option should be equal to 8.

## INSTALLATION
This driver is not built by default. You can build it by using "configure --with-usb=yes". Note that it will also install other USB drivers.

You also need to install manually the legacy hotplug files (libhidups and libhid.usermap, generally in /etc/hotplug/usb/), or the udev file (nut-usbups.rules, generally in /etc/udev/rules.d/) to address the permission settings problem. For more information, refer to the README file in nut/scripts/hotplug or nut/scripts/udev.

On Linux with MGE equipment, you will need at least a 2.4.25 or 2.6.2 kernel as well as libusb-0.1.8 or later to disable hiddev support and avoid conflict.

## IMPLEMENTATION
The driver ignores the "port" value in ups.conf. Unlike previous versions of this driver, it is now possible to control multiple UPS units simultaneously with this driver, provided they can be distinguished by setting some combination of the "vendor", "product", "serial", "vendorid", and "productid" options. For instance:

```
[mge]

        driver = usbhid-ups

        port = auto

        vendorid = 0463
[tripplite]

        driver = usbhid-ups

        port = auto

        vendorid = 09ae
```

## KNOWN ISSUES AND BUGS

### Repetitive timeout and staleness
Some models tends to be unresponsive with the default polling frequency. The result is that your system log will have lots of messages like:

```
usb 2-1: control timeout on ep0in
usb 2-1: usbfs: USBDEVFS_CONTROL failed cmd usbhid-ups rqt 128 rq 6 len 256
ret -110
```

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

### Got EPERM: Operation not permitted upon driver startup
You have forgotten to install the hotplug files, as explained in the INSTALLATION section above. Don’t forget to restart hotplug so that it applies these changes.

### Unattended shutdowns
The hardware which was used for development of this driver is almost certainly different from what you have, and not all manufacturers follow the USB HID Power Device Class specifications to the letter. You don’t want to find out that yours has issues here when a power failure hits your server room and you’re not around to manually restart your servers.

If you rely on the UPS to shutdown your systems in case of mains failure and to restart them when the power returns, you must test this. You can do so by running upsmon -c fsd. With the mains present, this should bring your systems down and then cycle the power to restart them again. If you do the same without mains present, it should do the same, but in this case, the outputs shall remain off until mains power is applied again.

## AUTHORS
Originally sponsored by MGE UPS SYSTEMS. Now sponsored by Eaton http://opensource.eaton.com Arnaud Quette, Peter Selinger, Arjen de Korte

## SEE ALSO

### The core driver
nutupsdrv(8)

### Internet resources
The NUT (Network UPS Tools) home page: http://www.networkupstools.org/


victronups

title: victronups(8)

text:
# victronups(8)

## NAME
victronups - Driver for IMV/Victron UPS unit Match, Match Lite, NetUps

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

## SUPPORTED HARDWARE
The victronups driver should recognize all Victron models that use a serial protocol at 1200 bps. These include Match Lite, Match and the NetUps line.

The Match Lite line may only report a handful of variables. This is usually not a bug - they just don’t support anything else.

## CABLING
If your Victron cable is broken or missing, use this diagram to build a clone:

docs/cables/victron.txt

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

modelname=name

Set model name

usd=delay

Set delay before shutdown on UPS

## BUGS
The protocol for this UPS is not officially documented.

## AUTHOR
Radek Benedikt <benedikt@lphard.cz>, Daniel Prynych <Daniel.Prynych@hornet.cz>

## SEE ALSO

### The core driver:
nutupsdrv(8)

### Internet resources:
The NUT (Network UPS Tools) home page: http://www.networkupstools.org/