nut-recorder

title: nut-recorder(8)

text:
# nut-recorder(8)

## NAME
nut-recorder - Utility to record device status and values changes

## SYNOPSIS
nut-recorder device-name [output-file] [interval]

## DESCRIPTION
nut-recorder is an utility to record sequences from running devices (such as power failures, or any other value changes) from upsd(8) data server, and dump it in a .seq format.

The .seq file can then be used by the dummy-ups(8) driver to replay the sequence.

## OPTIONS
device-name

Record the changes of this device. The format for this option is devname[@hostname[:port]]. The default hostname is "localhost".

output-file

Optional. Data will be saved to this file. The default is dummy-device.seq.

interval

Optional. The status of the device will be checked every interval. The default is 5 seconds.

## EXAMPLES
To record data from ups1@host1 every 10 seconds:

```
:; nut-recorder ups1@host1' ups1-output.seq 10
. . .
battery.charge: 100.0
battery.voltage: 13.9
battery.voltage.nominal: 13.6
ups.status: OL
. . .
battery.charge: 90.0
ups.status: OB
. . .
```

You can then define a dummy device in ups.conf(5):

```
[ups-test]

        driver = dummy-ups

        port = ups1-output.seq
```

## AUTHOR
Arnaud Quette

## SEE ALSO

### The dummy-ups driver:
dummy-ups(8)

### The logging daemon:
upslog(8)

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


nut-scanner

package: nut-server

title: nut-scanner(8)

text:
# nut-scanner(8)

## NAME
nut-scanner - Tool to 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.

nut-scanner can also display the detected devices in various formats, including ups.conf, and ensures that the generated devices name are unique across buses.

## INSTALLATION
nut-scanner is only built if libltdl (part of libtool development suite) is available.

Available scanning options (USB, SNMP, IPMI, UPower, ...) will vary according to the available compile-time and run-time dependencies. For example, if Net-SNMP is installed, thus providing libsnmp libraries (*.so or *.dll) and header files during compilation, and at least the library files on the monitoring system, then SNMP discovery will be available. Similarly, UPower discovery requires GDBus/libgio libraries.

## OPTIONS
-h

Display the help text.

## DISPLAY OPTIONS
-Q | --disp_nut_conf_with_sanity_check

Display result in the ups.conf format with sanity-check warnings (if any) as comments (default).

-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. This option can be specified several times, for more hardware link-specific details; these can be counter-productive in case of USB enumeration changes over time:

Option count

Practical meaning

-U

do not report any `bus`/`device`/`busport` details

```

```

-UU

report `bus` and `busport`, if available

```

```

-UUU

report `bus`/`device`/`busport` details

```

```

-UUUU

report `bus`/`device`/`busport` details, and `bcdDevice` (limited use and benefit)

```

```

Note

For reliability, it is preferable to match just by vendor and product identification, and a serial number if available and unique.

-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. Can broadcast a network message on the current network interface(s) to retrieve XML/HTTP capable devices. No IP required in this mode. If IP address ranges are specified, they would be scanned instead of a broadcast.

-O | --oldnut_scan

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

-n | --nut_simulation_scan

Scan NUT simulated devices (.dev files in the built-in "sysconfig" location).

Warning

The NUT_CONFPATH environment variable override is not currently supported.

-A | --avahi_scan

Scan NUT servers using Avahi request on the current network interface(s). No IP address options are required or used.

-I | --ipmi_scan

Scan NUT compatible power supplies available via IPMI on the current host, or over the network if IP address ranges are specified.

-J | --upower_scan

Scan UPower devices. Requires GDBus/libgio libraries to be available.

-E | --eaton_serial serial ports

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

•auto to scan all serial ports.

•a single character 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 syntax, where X and Y are characters referring to the port number.

•a single port name.

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

## NETWORK OPTIONS

Note The networked buses (such as SNMP, NetXML, IPMI and "Old NUT") allow to specify several IP (IPv4 or IPv6) address ranges, down to individual single IP addresses.

Normally a new range is specified by a set of one -s and one -e options following each other (in any order on the command line).

Lone or consecutive -s or -e options present on the command line would translate to single-IP queries.

Also, a -m option squashed between two -s and -e options would be a new range, turning those two into single-IP queries. This feature does not by itself recombine "neighboring" addresses into one range, nor even check for duplicate or overlapping specifications.

A single-address range may be a host name which would be resolved into one IP address by the system resolver. A CIDR using a host name and netmask length would be resolved into an IP address and subjected to the mask application, to query hosts "near" the named one.

Also note that some buses require IP address(es) to scan, and others have a different behavior when exactly no addresses are specified (it is not currently possible to mix the two behaviors in one invocation of the nut-scanner tool).

Finally note that currently even if multi-threaded support is available, each range specification is a separate fan-out of queries constrained by the timeout. Requests to scan many single IP addresses will take a while to complete, much longer than if they were a single range. This will be hopefully fixed in later releases.

Note Colon-separated IPv6 addresses must be passed in square brackets.

-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) or optional (XML/HTTP).

-e | --end_ip end IP

Set the last IP (IPv4 or IPv6) when a range of IP is required (SNMP, old_nut) or optional (XML/HTTP). 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 addresses by using CIDR notation. A special form -m auto allows nut-scanner to detect local IP address(es) and scan corresponding subnet(s) on supported platforms, and -m auto4 or -m auto6 limits the selected addresses to IPv4 and IPv6 respectively. Only the first "auto*" request would be honoured, others ignored with a warning.

An /ADDRLEN suffix can be added to the option, to filter out discovered subnets with too many bits available for the host address part (avoiding millions of scans in the extreme cases). For example, if the IPv4 network range of your LAN is 10.2.3.0/24, its address part is (32-24)=8. Note that while this is applied to IPv6 networks also, their typical /64 subnets are not likely to have a NUT/SNMP/NetXML/... server that close nearby (in addressing terms), for a tight filter to find them. Default is 8.

## 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. This parameter is mandatory if you use non-trivial authentication.

-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, SHA, SHA256, SHA384 or SHA512 (depending on Net-SNMP library capabilities; check help of the nut-scanner binary program for the run-time supported list). 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, AES, AES192 or AES256 (depending on Net-SNMP library capabilities; check help of the nut-scanner binary program for the run-time supported list). 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.

-L | --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 buses that can be scanned, depending on how the nut-scanner binary program has been compiled. (e.g. OLDNUT, USB, SNMP, XML, AVAHI, IPMI).

-q | --quiet

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

-D | --nut_debug_level

Raise the debugging level. Use this multiple times to see more details.

Note The level of debugging needed depends both on nut-scanner and the problem you’re trying to diagnose. Therefore, first explain the problem you have with nut-scanner 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.

## EXAMPLES
To scan USB devices only:

```
:; nut-scanner -U
[nutdev-usb1]

        driver = "snmp-ups"

        port = "192.168.0.42"
```

To scan SNMP v1 device with public (default) 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
[nutdev-snmp1]

        driver = "snmp-ups"

        port = "192.168.0.42"
```

The same using CIDR notation:

```
:; nut-scanner -S -m 192.168.0.0/24
[nutdev-snmp1]

        driver = "snmp-ups"

        port = "192.168.0.42"
```

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
[nutdev-nut1]

        driver = "dummy-ups"

        port = "dummy-test@192.168.1.28"
```

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 using CIDR notation:

```
:; 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
```

To scan for UPower devices:

```
:; nut-scanner -J
[nutdev-upower1]

        driver = "upower"

        port = "/org/freedesktop/UPower/devices/ups_hiddev0"

        vendor = "APC"

        product = "Back-UPS ES 700G"

        serial = "5B1234567890"

        bus = "upower"
```

## SEE ALSO
ups.conf(5)

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


nut-upower

title: nut-upower(8)

summary: Driver for UPower devices via D\-Bus

text:
# nut-upower(8)

## NAME
nut-upower - Driver for UPower devices via D-Bus

## SYNOPSIS
nut-upower -h

nut-upower -a UPS_NAME [OPTIONS]

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

## DESCRIPTION
This driver allows the monitoring of power devices (UPS, batteries) that are managed by the UPower daemon via the D-Bus system bus.

It maps UPower properties (state, percentage, voltage, etc.) to standard NUT variables, allowing NUT clients to monitor devices that are natively supported by the OS desktop environment but not directly by other NUT drivers.

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

port

The UPower Object Path of the device to monitor.

If set to auto (the default), the driver will scan for the first UPower device whose object path contains the string "ups_".

If set to a specific path (e.g., /org/freedesktop/UPower/devices/ups_hiddev0), the driver will attempt to monitor that specific device.

lowbatt

The battery percentage threshold below which the LB (Low Battery) status flag is set. The default value is 20.0.

## INSTALLATION
To use this driver, add a section to your ups.conf:

```
[myups]

    driver = nut-upower

    port = auto

    lowbatt = 20

    desc = "Laptop Battery or generic UPS via UPower"
```

## REQUIREMENTS
This driver requires the upower daemon to be running and accessible via the D-Bus system bus. It also requires GLib 2.0 and GIO libraries.

## AUTHOR
Tim Niemueller <tim@niemueller.de>

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

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


nutconf

title: nutconf(8)

summary: NUT configuration tool

text:
# nutconf(8)

## NAME
nutconf - NUT configuration tool

## SYNOPSIS
nutconf --help

nutconf [OPTIONS]

## DESCRIPTION
nutconf tool is used to create and manipulate NUT configuration files. It also supports device scanning (to suggest configuration of devices).

## INSTALLATION
The scanning feature depends on the very same compile time and run time dependencies as the nut-scanner.

## OPTIONS
-h | -help | --help

Display the help text.

-D

Raise the debugging level. Use this option multiple times for more details. Overrides the optional NUT_DEBUG_LEVEL environment variable.

-v | --verbose

Increase output verbosity (may be used multiple times).

--is-configured

Checks whether NUT was configured, before.

--system

System configuration directory shall be used.

--local directory

Sets alternative configuration directory.

--get-mode

Prints current NUT configuration mode

--set-mode mode

Sets NUT configuration mode. Known modes are:

•standalone

•netserver

•netclient

•controlled

•manual

•none

## CONFIGURATION ENTRY SET/ADD OPTIONS
These options mostly have 2 forms: --set-... or --add-....

The difference is that the set options discard previous settings while the add options keep them.

Note that such options may be specified multiple times for one run (to enable setting multiple entries at once).

--set-monitor | --add-monitor <arguments>

Sets/adds a NUT monitor.

•Arguments:

```
'<ups_ID>' '<host>[:<port>]' '<power_value>' '<user>' '<passwd>' '(\"master\"|\"slave\")'
```

--set-listen | --add-listen <address> [<port>]

Sets/adds upsd(8) daemon listen address.

--set-device | --add-device <arguments>

Sets/adds a device (typically a UPS).

•Arguments:

```
'<ups_ID>' '<driver>' '<port>' '[<attribute>=<value>]*'
```

The attribute/value pairs follow device configuration syntax. Devices may have very different configuration attributes depending on the driver. Exhaustive description of them is beyond this man page and may be found in NUT documentation.

--set-notifyflags | --add-notifyflags <type> <flag>+

Sets/adds notification flags for the notification type.

•Notification types are:

•ONLINE (mains is present)

•ONBATT (mains is gone)

•LOWBATT (remaining battery capacity is low)

•FSD (shutdown was forced)

•COMMOK (communication with device established)

•COMMBAD (lost communication with device)

•SHUTDOWN (system is going down, now)

•REPLBATT (UPS battery needs replacing)

•NOCOMM (device is unavailable)

•NOPARENT (upsmon parent process died, shutdown is impossible)

•CAL (calibration in progress)

•NOTCAL (calibration finished)

•OFF (UPS is administratively OFF or asleep, should wake up on command)

•NOTOFF (UPS is no longer administratively OFF or asleep)

•BYPASS (on bypass = powered, not protecting)

•NOTBYPASS (no longer on bypass)

•ALARM (UPS is in an alarm state (has active alarms))

•NOTALARM (UPS is no longer in an alarm state (no active alarms))

•OVER (overloaded)

•NOTOVER (no longer overloaded)

•TRIM (trimming incoming voltage)

•NOTTRIM (no longer trimming incoming voltage)

•BOOST (boosting incoming voltage)

•NOTBOOST (no longer boosting incoming voltage)

•OTHER (UPS has at least one unclassified status token)

•NOTOTHER (UPS has no unclassified status tokens anymore)

•SUSPEND_STARTING (OS is entering sleep/suspend/hibernate mode)

•SUSPEND_FINISHED (OS just finished sleep/suspend/hibernate mode)

•Notification flags:

•SYSLOG (use syslogd to log the notification)

•WALL (push a message to users' terminals)

•EXEC (execute a command)

•IGNORE (don’t act)

--set-notifymsg <type> <message>

Sets message for the specified notification type.

--set-shutdowncmd <command>

Sets command used to shut the system down.

--set-user | --add-user <arguments>

Sets/adds NUT user.

•Arguments:

•<username> (specifies user name). For upsmon user, it has a special form of upsmon=(primary|master|secondary|slave) which specifies the monitoring mode.

•password=<passwd> sets password for the user

•actions=<actions> sets actions (SET, FSD are supported)

•instcmds=<command> sets instant commands allowed for the user (may be used multiple times)

## SCANNING OPTIONS
Availability of each scanning option depends on availability of various 3rd-party libraries both at compile time and run time.

Run the tool with the --help option to check which of the --scan-... options are actually supported.

All timeouts are in microseconds.

--scan-snmp <start IP> <stop IP> [<attribute>=<value>]*

Scans for SNMP devices on IP addresses from the specified range.

•Known attributes are:

•timeout device scan timeout

•community SNMP community (default: public)

•sec-level security level (SNMPv3); one of noAuthNoPriv authNoPriv, authPriv

•sec-name security name (SNMPv3); mandatory companion of sec-level

•auth-password authentication password (SNMPv3); mandatory for authNoPriv and authPriv

•priv-password privacy password (SNMPv3); mandatory for authPriv

•auth-protocol authentication protocol (SNMPv3): MD5 or SHA, MD5 is the default

•priv-protocol priv. protocol (SNMPv3): DES or AES, DES is the default

•peer-name peer name

--scan-usb

Scans the USB bus for known devices

--scan-xml-http [<timeout>]

Scans for XML/HTTP devices on the network.

--scan-nut <start IP> <stop IP> <port> [<timeout>]

Scans for NUT (pseudo-)devices on the network.

--scan-avahi [<timeout>]

Scans for Avahi devices.

--scan-ipmi <start IP> <stop IP> [<attribute>=<value>]*

Scans for IPMI devices on IP addresses from the specified range.

•Known attributes are:

•username username (mandatory for IPMI/LAN)

•password user password (mandatory for IPMI/LAN)

•auth-type authentication type (see below)

•cipher-suite-id cipher suite ID (see below)

•K-g-BMC-key optional second key (???)

•priv-level priv. level

•workaround-flags

•version (1.5 or 2.0)

•Authentication types: Specifies 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.

•none (authentication is disabled)

•MD2

•MD5 (default)

•plain-password (no ciphering used for password sending)

•OEM

•RMCPplus

•Cipher suite IDs: Specifies 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:

Code

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

--scan-serial <port>*

Scans for serial devices (of supported types) on the specified serial port(s).

## EXAMPLES
To set alternative directory for configuration files:

```
:; nutconf --local ~/test/nut/etc
```

To add another user (keeping the existing ones):

```
:; nutconf --add-user bart password=qwerty
```

To scan USB devices and serial devices (on the first two ports):

```
:; nutconf --scan-usb --scan-serial /dev/ttyS1 /dev/ttyS2
```

## SEE ALSO
ups.conf(5) nut-scanner(8)

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


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

## SYNOPSIS
nutdrv_atcl_usb -h

nutdrv_atcl_usb -a UPS_NAME [OPTIONS]

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), and some others.

## 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 (or specify "NULL" if the device does not provide a vendor string but you want this driver to match). Note that a more likely case for mismatch is that your device is handled by another driver for 0001:0000 devices, such as nutdrv_qx(8).

Note

This driver does not intend to support USB-matching settings common to other drivers, such as vendorid, product, productid, serial, device or bus; also the vendor setting supported here is not a regular expression.

## 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 upsmon in primary mode runs on the box powered by the UPS, but may be an issue if the UPS is monitored by a remote (secondary) 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 secondary 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.

## AUTHOR
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: https://www.networkupstools.org/historic/v2.8.5/


title: nutdrv_hashx(8)

text:
# nutdrv_hashx(8)

## NAME
nutdrv_hashx - Driver for #* protocol serial based UPS equipment

## SYNOPSIS
nutdrv_hashx -h

nutdrv_hashx -a UPS_NAME [OPTIONS]

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

## SUPPORTED HARDWARE
The protocol originates from Cyber Energy that apparently developed the protocol for their UPS and it was used then by various other vendors (that in some cases they just re-brand the Cyber Energy products).

The nutdrv_hashx driver is expected to work with various UPSes from Ablerex, Atlantis Land, Epyc, Infosec, ION, PowerWalker, Right Power Technology, Salicru, UPS Solutions and various others.

Long story short: if your UPS came with a software called PowerMaster+ (or the older PowerMaster and PowerGuide), chances are high that it works with this driver.

Only devices with a serial interface are supported.

## KNOWN ISSUES AND BUGS
The driver has only been tested with a single line-interactive device (Atlantis Land A03-S1200) so far, thus the protocol reverse engineering has been currently limited to what such device supports.

Thus the lack of these features:

•Specific support for PDU or ATS devices.

•Detection of the UPS type (line-interactive / online).

•Detection of max/min voltage ratings.

•Detection of load banks.

•Detection of Extended battery modules.

•Detection of Over voltage state.

•Detection of Under voltage state.

•Detection of Frequency failure state.

•Detection of Wiring Fault state.

•Detection of lack of Neutral line connection.

•Detection of UPS generators.

•Detection of other Battery / UPS error states.

•Reading of actual Voltage, Frequency, Current, Power factor, Temperature values.

•Reading the status of the battery packs.

•Bypass modes usage and detection.

•USB Support (PM+ mentions being it supported, unsure if with the same protocol).

The driver shutdown function is not implemented (while it’s supported), so other arrangements must be made to turn off the UPS.

## AUTHORS
Marco Trevisan <mail@3v1n0.net>

### The core driver:
nutupsdrv(8)

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

•PowerMaster+: https://www.powermonitor.software/


title: nutdrv_qx(8)

text:
# nutdrv_qx(8)

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

## SYNOPSIS
nutdrv_qx -h

nutdrv_qx -a UPS_NAME [OPTIONS]

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 protocol originates from Mega System Technologies, Inc. in Taiwan and was used by numerous vendors, as well as evolved over time, growing both in features and nuance incompatibilities. NUT documentation usually refers to this large family of similar dialects as the Megatec Q* or Megatec Qx protocol family.

The nutdrv_qx driver is known to work with various UPSes from Armac, Blazer, Energy Sistem, Fenton Technologies, General Electric, Gtec, Hunnox, Masterguard, Mustek, Powercool, Voltronic Power, SKE (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.

Note Due to historical reasons, two important tunables of this driver are somewhat inconveniently named protocol (for the Qx dialect) and subdriver (for USB to serial link conversion). Other multi-dialect drivers refer to their dialect modules as subdrivers, and actually the modular source code of nutdrv_qx also does.

Note Due to the amount of supported Qx dialects, and the time it takes to query for relevant combinations of commands and wait for a reply or absence thereof, in order to detect hardware/firmware support of some particular way for the driver to communicate with the device, automatic nutdrv_qx driver initialization may take about a minute. It is recommended to store the detected and reported protocol and/or subdriver values into your ups.conf(5) file to speed up later driver start-ups and avoid possible service timeouts.

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 or reported back.

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, gtec, hunnox, innovart31, innovart33, innovatae, masterguard, mecer, megatec, megatec/old, mustek, q1, q2, q6, voltronic, voltronic-axpert, voltronic-qs, voltronic-qs-hex and zinto. Run the driver program with the --help option to see the exact list of protocol values it would currently recognize.

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 = num

Set polling interval for full updates, in seconds, to reduce the message traffic. Between two polling requests, the driver will do quick polls dealing just with ups.status at an interval specified by the pollinterval driver option (details in ups.conf(5)). 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 GUESSTIMATION).

default.battery.voltage.low = value

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

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

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

override.battery.packs = value

Some devices "natively" report just a part of the total battery voltage (see also battery_voltage_reports_one_pack below). 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 number automatically, but if this fails somehow, you may want to override this value.

Note that this is primarily useful for "guesstimation" of battery.charge and/or battery.runtime (with runtimecal setting), if those readings are not provided by the device directly.

battery_voltage_reports_one_pack

Some devices "natively" report just report a part of the total battery voltage (see also override.battery.packs above, if that value is not reported by the device or properly guessed by the driver otherwise). If this flag is set, most of the subdrivers (except those which know about more complicated device-specific nuances, currently: ablerex, masterguard and voltronic-qs-hex) adjust their ultimately reported battery.voltage value as a multiple of battery.packs and "native" battery.voltage).

Note this is primarily useful for consistent diagnostics and graphing of the numbers, and should not impact the "guesstimation" of battery.charge and/or battery.runtime — so rather a cosmetic adjustment, than critical.

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, INNOVART31, INNOVART33, INNOVATAE, MECER, MEGATEC, MEGATEC/OLD, MUSTEK, Q1, Q2, Q6, 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, MEGATEC, 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].

### MASTERGUARD PROTOCOL
slave_addr = value

Make the claim function verify it’s talking to the specified slave address (ups.id). Safeguard against talking to the wrong one of several identical UPSes on the same USB bus. Note that when changing ups.id (through upsrw(8)) the driver will continue to talk to the UPS with the new slave address, but won’t claim it again on restart until the slave_addr parameter is adjusted.

### INNOVART31, INNOVART33, INNOVATAE, Q1, Q2, Q6 PROTOCOLS
ondelay

The acceptable range is 0..599940 seconds.

offdelay

The acceptable range is 12..600 seconds.

### Q2, Q6 PROTOCOLS
nooutstats

Some UPSes don’t support WA command which returns output load stats. Using this flag will make the driver ignore these requests.

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

The acceptable range is 60..599940 seconds.

offdelay

The acceptable range is 12..540 seconds.

### VOLTRONIC-AXPERT PROTOCOL

Note This protocol is currently largely experimental, many features may be only exposed in specially configured builds of the NUT driver program.

reset_to_default

Reset capability options and their limits to safe default values

bypass_alarm

Alarm (BEEP!) at Bypass Mode [enabled/disabled]

battery_alarm

Alarm (BEEP!) at Battery Mode [enabled/disabled]

### 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 are 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 information, 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

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

Note

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

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

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

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

Examples:

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

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

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

bus = regex

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

Note

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

device = regex

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

Note

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

busport = regex

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

Note

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

allow_duplicates

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

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

Warning

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

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

usb_set_altinterface = bAlternateSetting

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

usb_config_index, usb_hid_rep_index, usb_hid_desc_index, usb_hid_ep_in, usb_hid_ep_out

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

LIBUSB_DEBUG = INTEGER

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

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

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

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

subdriver = string

Select a serial-over-USB subdriver to use. You have a choice between ablerex, armac, cypress, fabula, fuji, gtec, hunnox, ippon, krauler, phoenix, phoenixtec, sgs and snr. Run the driver program with the --help option to see the exact list of subdriver values it would currently recognize.

Note

When using this option, it is mandatory to also specify the vendorid and productid matching parameters.

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

noscanlangid

If this flag is set, don’t autoscan valid range for langid.

IMPLEMENTATION NOTES

armac subdriver

The Armac communication subdriver reproduces a communication protocol used by an old release of "PowerManagerII" software, which doesn’t seem to be Armac specific: its banner is "2004 Richcomm Technologies, Inc. Dec 27 2005 ver 1.1." Maybe other Richcomm UPSes would work with this — maybe better than with the older standalone richcomm_usb driver.

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.

gtec subdriver

Currently, the Gtec specific support is only known to work with USB devices (tested with a Gtec ZP120N), and was not seen with Serial port. This mode is not automatically detected, and should be enabled manually in your ups.conf, e.g.:

```
[gtec-ups]

    driver = "nutdrv_qx"

    port = "auto"

    subdriver = "gtec"

    protocol = "gtec"
```

Other subdrivers and protocol implementations (including blazer_usb(8)) sort of work, but both have two problems:

•They use the simple "Q1" query, which doesn’t report the result of the latest battery test.

•For some reason the UPS reports normal battery voltage even when the battery is completely disconnected. So you won’t know the battery is dead until a power failure.

•This driver sends the more advanced "Q4" request instead. Here the answer includes status letters with more information than the Q1 binary flags, including battery status.

•USB reply is read in 8-byte chunks, which causes the UPS to disconnect from USB. The UPS reconnects in a second, but it still breaks the initialization of nutdrv_qx, where the query is sent twice in a short time (unlike blazer_usb).

•The solution is simple: read the whole reply at once.

hunnox subdriver

This protocol subdriver is closely related to fabula one, with a few tweaks for devices not directly supported by that driver.

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.

snr 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, INNOVART31, INNOVART33, INNOVATAE, MECER, MEGATEC, MEGATEC/OLD, MUSTEK, Q1, Q2, Q6, ZINTO PROTOCOLS
test.battery.start value

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

### MASTERGUARD PROTOCOL
clear.fault.record

Clear fault/error record

beeper.enable

Enable the UPS beeper.

beeper.disable

Disable the UPS beeper.

test.battery.start.low

Perform a battery test until the battery charge is low. The difference between the "battery test until battery low" and "deep battery test" is that the latter is actually a battery calibration test and needs some preconditions to be met, i.e. the load must be between 30% and 100% and the starting battery capacity is greater than 99%.

The "Battery test until battery low" can be started anytime.

Feature was tested on Masterguard A1000 and A2000 units.

test.battery.start value

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

bypass.start

Put the UPS in bypass mode

bypass.stop

Take the UPS in normal mode

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

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.

### MASTERGUARD UNITS
The driver is supposed to support both "new" A series (A700/1000/2000/3000 and their -19 cousins) and E series (E60/100/200) but was tested only on A due to lack of E hardware.

### VOLTRONIC-AXPERT UNITS
This protocol supports Voltronic Power Axpert inverters, based on P30 protocol (used e.g. in photovoltaic equipment, often paired with an UPS charged by the solar panels).

The code is currently largely experimental, with data point and command names not aligned with concepts that are part of NUT standard vocabulary (this many of them are prefixed with experimental. namespace). In fact, many features may be only exposed in specially configured builds of the NUT driver program.

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

•Edgar Fuß <ef@math.uni-bonn.de>

## 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: https://www.networkupstools.org/historic/v2.8.5/

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


title: nutdrv_siemens-sitop(8)

text:
# nutdrv_siemens-sitop(8)

## NAME
nutdrv_siemens-sitop - Driver for the Siemens SITOP UPS500 series UPS

## SYNOPSIS
nutdrv_siemens-sitop -h

nutdrv_siemens-sitop -a UPS_NAME [OPTIONS]

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

## SUPPORTED HARDWARE
nutdrv_siemens-sitop supports Siemens UPS models from the SITOP UPS500 series. Some models have a serial port, others have a USB port. The models with USB port actually contain a serial-over-USB chip, so as far as this driver is concerned, all models are serial models. This driver should work with all models in the SITOP UPS500 series, as long as your kernel has support for the serial port device (see section USB driver below).

Note This driver has only been tested with the SITOP UPS500S-2.5 with USB port (Siemens product number 6EP1933-2EC41).

## DEVICE SETTINGS
The UPS is configured via DIP-switches. For correct functioning in combination with NUT, set the DIP-switches to the following:

switch 1-4

Choose whatever suits your situation. Any combination will work with NUT.

switch 5 (⇒ / t)

Set to OFF (t). This ensures that the UPS will not cut power unless NUT tells it to do so (or unless the batteries are exhausted).

switch 6-10 (delay)

Set to OFF (minimum delay). Setting a higher delay will actually also work, but any command from NUT will be delayed as well before being executed by the UPS. With the minimum setting, it will already take 5 seconds before a command from NUT is executed.

switch 11 (INTERR.)

Set to ON (interrupt the output after the timer expires). This ensures that the UPS briefly interrupts the output power in response to the shutdown.return command. See the section Instant Commands below.

switch 12 (ON/OFF)

set to ON (enable the UPS functionality). Without this, the UPS will never supply power from its batteries.

## USB DRIVER
The USB-versions of the UPS contain an FTDI USB-to-serial converter chip. It is programmed with a non-standard product ID (for example 0403:e0e3), but can still be used with the normal ftdi_sio driver.

Note The following hints may be specific to GNU/Linux.

Use lsusb to figure out which product ID is used in your model, and replace all occurrences of e0e3 in the following examples with the actual Product ID.

```
modprobe ftdi_sio
echo 0403 e0e3 > /sys/bus/usb-serial/drivers/ftdi_sio/new_id
```

If your system uses udev, this can be automated via an udev rule:

```
ACTION=="add", ATTRS{idVendor}=="0403", ATTRS{idProduct}=="e0e3", \

  RUN+="/sbin/modprobe ftdi_sio", \

  RUN+="/bin/sh -c 'echo 0403 e0e3 > /sys/bus/usb-serial/drivers/ftdi_sio/new_id'"
```

You can use the following udev rule to obtain a predictable device name, for example /dev/ttyUPS:

```
SUBSYSTEM=="tty" ATTRS{idVendor}=="0403", ATTRS{idProduct}=="e0e3" SYMLINK+="ttyUPS"
```

## POLLING
The UPS does not have a special get status command. Instead, it continuously sends out status update messages (tens of messages per second). Every pollinterval, these messages are read from the serial port buffer.

In order to react quickly on status changes from the UPS, and to prevent the serial buffer from overflowing, pollinterval should be set to a relatively low value. The recommended value is 1 (second).

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

max_polls_without_data=num

The serial port is polled periodically for new data (see Polling). If there is no valid new data after num polls, it is assumed that communication with the UPS is lost. The default value is 2. Lower values may cause spurious Data stale messages, especially at startup.

## INSTANT COMMANDS
shutdown.return

The behavior of this command depends on the line state:

•on line: after 5 seconds (or longer, if DIP switches 6-10 are not OFF), the UPS will shut off its output. After another 5 seconds, the output is activated again.

•on battery: after 5 seconds (or longer, if DIP switches 6-10 are not OFF), the UPS will shut off its output. The output will stay off, until the line voltage has returned.

shutdown.stayoff

The behavior of this command depends on the line state:

•on line: after 5 seconds (or longer, if DIP switches 6-10 are not OFF), the UPS will shut off its output. The output stays off, until the line voltage has been removed for at least 1 second, and has been re-applied.

•on battery: this command behaves the same as shutdown.return.

## INSTALLATION
Make sure that your operating system has created a serial device for the UPS. See the section USB driver for more information.

Next, make sure that NUT has access rights to this device file. For example, by creating an udev rule that grants permission to the NUT user, or by adding the NUT user to a user group that can access serial devices (e.g. the dialout group on Debian-based systems).

## DIAGNOSTICS
You can verify the correct functioning of the hardware, by monitoring the serial port with a terminal program, for example picocom:

```
:; picocom -b 9600 -d 8 -p n /dev/ttyUPS
```

NUT must not be running when you do this. You should now see a continuous stream of 5-character texts coming in, for example:

```
BUFRD
BA>85
DC_OK
```

To exit picocom, use Ctrl-A Ctrl-X.

## KNOWN ISSUES AND BUGS
Untested models

As mentioned under Supported hardware, this driver has not been tested with all models in the SITOP UPS500 series.

Data stale messages

The firmware in these UPSes is quite buggy. After sending data to the UPS, it sometimes stops sending status updates. This driver tries to prevent this (e.g. by sending commands twice, and by sending additional LF characters after each command). Once the UPS is in this state, communication can only be restored by rebooting the UPS, or by unplugging and reconnecting the USB cable.

During normal operation, no commands are sent to the UPS at all (only at shutdown), so this issue is expected to have little impact on usability.

It is not certain if the serial models are affected by this issue as well.

## AUTHOR
Matthijs H. ten Berge

## SEE ALSO

### The core driver:
nutupsdrv(8)

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


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 three 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, as per the pollinterval parameter in ups.conf(5). The results of this command are presented to upsd. The driver will also handle setting variables and instant commands if available.

In the second mode, using -k, the driver can 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.

In the third mode, using -d, the driver will exit after some update loops, dumping the data tree (in upsc(8)-like format) to stdout. This can be useful to complement the nut-scanner(8) to discover devices, along with in-depth data.

Note You probably don’t want to use any of these options directly. You should use upsdrvctl(8) (or upsdrvsvcctl(8) on systems with a service management framework like systemd or SMF) 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.

-s id

Configure this driver only with command line arguments instead of reading ups.conf(5). To be used instead of -a option when need to run a driver not present in driver configuration file. Instead, driver configuration have to be set with -x options directly in the command line. As such driver instance cannot be controlled by upsdrvctl(8) or upsdrvsvcctl(8), this option should be used for specific needs only.

-D

Raise the debugging level. Use this multiple times to see more details. Running a driver in debug mode will (by default) 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.

-d update_count

Dump the data tree (in upsc(8)-like format) to stdout after running the driver update loop for the specified update_count times and exit. By default this prevents the driver process from backgrounding after startup. Note that the driver banner will be printed too, so when using this option in scripts, don’t forget to trim the first line, or use the NUT_QUIET_INIT_BANNER environment variable.

-q

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

-c command

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

reread configuration files, ignoring modified settings which can not be applied "on the fly"

reload-or-error

reread configuration files, ignoring but counting changed values which require a driver restart (can not be changed on the fly), and return a success/fail code based on that count, so the caller can decide the fate of the currently running driver instance

reload-or-exit

reread configuration files, exiting the old driver process if it encounters modified settings which can not be applied "on the fly" (so caller like systemd can launch another copy of the driver)

exit

tell the currently running driver instance to just exit (so an external caller like the new driver instance, or the systemd or SMF frameworks would start another copy)

With recent NUT v2.8.x releases, such commands can be sent using the Unix socket for driver-server interaction. As a fallback, like older releases, signals can be sent to the PID of an older driver instance (where possible).

-P pid

Send the command signal above using specified PID number, rather than consulting the PID file. This can help define service units which start each NUT driver as a foreground process so it does not create a PID file. See also -FF option as an alternative.

-F

Enforce running the driver as a foreground process, regardless of debugging or data-dumping settings. Specify twice (-FF or -F -F) to save the PID file even in this mode.

-B

Enforce running the driver as a background process, regardless of debugging or data-dumping settings.

-i interval

Set the poll interval for the device. The default value is 2 (in seconds).

-V

Print only version information, then exit.

-L

Print a parsable 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. Note that the constrained operating system context for shutdown typically rules out use of upsdrvsvcctl shutdown.

-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 (but reconnection to devices may be no longer possible and could require a full restart of the driver).

-u username

Override the unprivileged username that the driver may use after startup. If started as root, after opening configuration files (and optionally calling chroot(2), as described in the previous option), the driver will look up username in the passwd database, then change to the user and group identities associated with username. (If started with a nonzero UID or effective UID, the driver will silently ignore this option.) When compiling NUT from source, the default username is typically nobody, and this may cause permission errors when the driver opens the UPS device node. You can use this option to temporarily override the defaults. For testing purposes, you can set this option to root to bypass permission errors, especially with USB-based drivers. However, you will want to remove this option later in order to avoid permission conflicts between the driver and the unprivileged copy of upsd(8).

-g groupname

Override the unprivileged group name that the driver may use after startup to set permissions for the filesystem socket so upsd may still access it if the run-time user of the driver normally would deny that access.

-x var=val

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

Note that for fallback values of NUT variables poorly supported by a specific device and/or its NUT driver, you can specify default.var.name=val to set a default value (may be replaced at run-time by a reading from the device, if one does arrive), or override.var.name=val to hard-code a value and ignore its readings from the device even if they are served. For example, this is often used with override.battery.voltage.nominal when the device reports a single cell in 2V range, and you are interested in a standard battery package in 12V range, for PbAc.

## DIAGNOSTICS
Information about the startup process is printed to stdout and/or stderr. Additional messages after that point are only available in the syslog, unless the driver remains in foreground (e.g. due to raised debugging verbosity).

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) (or upsdrvsvcctl(8) on systems with a service management framework like systemd or SMF) 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.

## ENVIRONMENT VARIABLES
NUT_DEBUG_LEVEL sets default debug verbosity if no -D arguments were provided on command line, but does not request that the daemon runs in foreground mode.

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

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

NUT_ALTPIDPATH is the path name of the directory in which upsd and drivers store .pid files. If this variable is not set, upsd and drivers use either NUT_STATEPATH if set, or ALTPIDPATH if set, or otherwise the built-in default STATEPATH.

NUT_QUIET_INIT_UPSNOTIFY=true can be used to prevent daemons which can notify service management frameworks (such as systemd) about passing their lifecycle milestones from emitting such notifications (including those about lack of system support for such modern features, once per run).

NUT_QUIET_INIT_BANNER=true can be used to suppress NUT tool name and version banner. NOT recommended for services due to adverse troubleshooting impact, but may be helpful in shell profiles or scripts which process NUT tool outputs.

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

## SEE ALSO

### Configuration:
•ups.conf(5)

•nut.conf(5)

### 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:
•nut-driver-enumerator(8)

•upsdrvctl(8)

•upsdrvsvcctl(8)

### Drivers:
•al175(8)

•apcsmart-old(8)

•apcsmart(8)

•apcupsd-ups(8)

•bcmxcp(8)

•bcmxcp_usb(8)

•belkin(8)

•belkinunv(8)

•bestfcom(8)

•bestfortress(8)

•bestuferrups(8)

•bestups(8)

•bicker_ser(8)

•blazer_ser(8)

•blazer_usb(8)

•clone-outlet(8)

•clone(8)

•dummy-ups(8)

•etapro(8)

•everups(8)

•failover(8)

•gamatronic(8)

•genericups(8)

•isbmex(8)

•ivtscd(8)

•liebert-esp2(8)

•liebert-gxe(8)

•liebert(8)

•masterguard(8)

•meanwell_ntu(8)

•metasys(8)

•mge-shut(8)

•mge-utalk(8)

•microdowell(8)

•microsol-apc(8)

•nhs_ser(8)

•nut-ipmipsu(8)

•nut-upower(8)

•nutdrv_atcl_usb(8)

•nutdrv_hashx(8)

•nutdrv_qx(8)

•nutdrv_siemens-sitop(8)

•oneac(8)

•optiups(8)

•powercom(8)

•powerpanel(8)

•powervar_cx_ser(8)

•powervar_cx_usb(8)

•rhino(8)

•richcomm_usb(8)

•riello_ser(8)

•riello_usb(8)

•safenet(8)

•sms_ser(8)

•snmp-ups(8)

•solis(8)

•tripplite(8)

•tripplite_usb(8)

•tripplitesu(8)

•upscode2(8)

•usbhid-ups(8)

•ve-direct(8)

•victronups(8)

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


oneac

title: oneac(8)

summary: Driver for Oneac UPS equipment

text:
# oneac(8)

## NAME
oneac - Driver for Oneac UPS equipment

## SYNOPSIS
oneac -h

oneac -a UPS_NAME [OPTIONS]

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

## AUTHORS
•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: https://www.networkupstools.org/historic/v2.8.5/


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

## SYNOPSIS
optiups -h

optiups -a UPS_NAME [OPTIONS]

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.

## AUTHORS
•Russell Kroll

•Scott Heavner

•Matthias Goebl

## SEE ALSO

### The core driver:
nutupsdrv(8)

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