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

package: nut-server

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/

branch: sisyphus


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/


powercom

title: powercom(8)

text:
# powercom(8)

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

## SYNOPSIS
powercom -h

powercom -a UPS_NAME [OPTIONS]

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

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

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

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

linevoltage=value

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

manufacturer=name

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

modelname=name

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

serialnumber=value

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

type=name

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

shutdownArguments={{minutes,seconds},whether_minutes_should_be_used}

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

numOfBytesFromUPS=value

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

methodOfFlowControl=name

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

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

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

frequency={A,B}

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

loadPercentage={BatteryA,BatteryB,LineA,LineB}

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

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

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

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

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

nobt

If this flag is present, the battery check on startup is skipped. This is useful for systems that tend to overload the UPS when testing the battery on system startup — just when the power consumption tends to be high.

## DEFAULT VALUES FOR THE EXTRA ARGUMENTS

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

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

### Trust

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

### KP625AP

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

### Egys

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

### IMP

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

### KIN

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

### BNT

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

### BNT-other

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

### OPTI

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

## AUTHORS
•Peter Bieringer <pb@bieringer.de>

•Alexey Sidorov <alexsid@altlinux.org>

•Keven L. Ates <atescomp@gmail.com>

•Rouben Tchakhmakhtchian <rouben@rouben.net>

## SEE ALSO

### The core driver:
nutupsdrv(8)

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


powerpanel

title: powerpanel(8)

text:
# powerpanel(8)

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

## SYNOPSIS
powerpanel -h

powerpanel -a UPS_NAME [OPTIONS]

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

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

If your Cyber Power Systems UPS has a USB port, you may wish to use the usbhid-ups(8) driver. The snmp-ups(8) driver supports several network cards via SNMP.

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

protocol=[text,binary]

Override the default autodetection of the protocol.

manufacturer=value

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

model=value

Like manufacturer above.

serial=value

Like manufacturer above.

ondelay=value

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

offdelay=value

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

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

input.transfer.high

writable: high transfer voltage point in V

input.transfer.low

writable: low transfer voltage point in V

battery.charge.low

writable: remaining battery charge percentage for low battery warning

output.voltage.nominal

writable: nominal output voltage in V

ups.start.battery

writable: allow cold start from battery

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

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

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

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

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

•shutdown.stop

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

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

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

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

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

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

## SEE ALSO

### The core driver:
nutupsdrv(8)

### Other drivers:
usbhid-ups(8), snmp-ups(8)

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


title: powervar_cx_ser(8)

text:
# powervar_cx_ser(8)

## NAME
powervar_cx_ser - Driver for Powervar UPM Series UPS equipment with Serial connection

## SYNOPSIS
powervar_cx_ser -h

powervar_cx_ser -a UPS_NAME [OPTIONS]

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

## SUPPORTED HARDWARE
This driver supports the Powervar UPM UPS family (devices with serial port connection). For USB connected UPM Series devices, see also powervar_cx_usb(8).

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

startdelay=num

Change startup delay time from 1 second default.

offdelay=num

Change shutdown delay time from 0 second default.

disptesttime=num

Change display test time from the 10 second default.

## INSTANT COMMANDS
This driver supports the following Instant Commands (see upscmd(8)):

### All GTS and UPM UPS units
beeper.disable

Disable the UPS beeper.

beeper.enable

Enable the UPS beeper.

beeper.mute

Temporarily mute the UPS beeper.

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.

shutdown.stayoff

Turn off the load and remain off.

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.

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.

test.failure.start

Starts a simulation of an input power failure.

test.failure.stop

Stops a simulation of an input power failure.

### All UPM UPS units
test.panel.start

Start testing the UPS panel.

reset.input.minmax

Reset minimum and maximum input voltage status.

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

## AUTHORS
•Bill Elliot <bill@wreassoc.com>

## SEE ALSO
For USB connected GTS and UPM Series devices, see powervar_cx_usb(8).

### The core driver:
nutupsdrv(8)

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


title: powervar_cx_usb(8)

text:
# powervar_cx_usb(8)

## NAME
powervar_cx_usb - Driver for Powervar GTS and UPM Series UPS equipment with USB connection

## SYNOPSIS
powervar_cx_usb -h

powervar_cx_usb -a UPS_NAME [OPTIONS]

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

## SUPPORTED HARDWARE
This driver supports two Powervar UPS families with USB connections:

•UPM (either USB or Serial)

•GTS (USB only)

For serial connected UPM Series devices, see also powervar_cx_ser(8).

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

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

startdelay=num

Change startup delay time from 1 second default.

offdelay=num

Change shutdown delay time from 0 second default.

disptesttime=num

Change display test time from the 10 second default (UPM only).

## INSTANT COMMANDS
This driver supports the following Instant Commands (see upscmd(8)):

### All GTS and UPM UPS units
beeper.disable

Disable the UPS beeper.

beeper.enable

Enable the UPS beeper.

beeper.mute

Temporarily mute the UPS beeper.

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.

shutdown.stayoff

Turn off the load and remain off.

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.

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.

test.failure.start

Starts a simulation of an input power failure.

test.failure.stop

Stops a simulation of an input power failure.

### All UPM UPS units
test.panel.start

Start testing the UPS panel.

reset.input.minmax

Reset minimum and maximum input voltage status.

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

## AUTHORS
•Bill Elliot <bill@wreassoc.com>

## SEE ALSO
For serial connected UPM Series devices, see powervar_cx_ser(8).

### The core driver:
nutupsdrv(8)

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


rhino

title: rhino(8)

text:
# rhino(8)

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

## SYNOPSIS
rhino -h

rhino -a UPS_NAME [OPTIONS]

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

## SUPPORTED HARDWARE
This driver has been tested with:

•Rhino 6000 VA

•Rhino 7500 VA

•Rhino 10000 VA

•Rhino 20000 VA

All Rhino models are sinusoidal on-line.

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

battext=n

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

## COMMANDS
load.on

Turn on the load immediately.

load.off

Turn off the load immediately.

bypass.start

Put the UPS in bypass mode.

bypass.stop

Put the UPS out of bypass mode.

shutdown.stayoff

Shut down in 3 minutes and do not return.

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

## SEE ALSO

### The core driver:
nutupsdrv(8)

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


title: richcomm_usb(8)

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

text:
# richcomm_usb(8)

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

## SYNOPSIS
richcomm_usb -h

richcomm_usb -a UPS_NAME [OPTIONS]

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

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

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

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

## AUTHORS
•Peter van Valderen <p.v.valderen at probu.nl>

•Dirk Teurlings <dirk at upexia.nl>

## SEE ALSO

### The core driver:
nutupsdrv(8)

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

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


title: riello_ser(8)

text:
# riello_ser(8)

## NAME
riello_ser - Driver for Riello UPS Protocol UPS equipment via serial port connections

## SYNOPSIS
riello_ser -h

riello_ser -a UPS_NAME [OPTIONS]

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

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

Older Riello UPS products are not supported.

## EXTRA ARGUMENTS
You may need to tweak some settings, depending on the make and model of your UPS (see ups.conf(5)):

localcalculation

When enabled, driver will calculate values of battery.runtime and battery.charge "locally" in the driver. This is for some Riello models which provide incorrect values in hardware readings, or none at all. This "local calculation" is done according to nominal battery capacity, nominal battery voltage, actual battery charge, maximum and actual UPS load. You may want to also configure default.battery.voltage.low and default.battery.voltage.high in case the built-in default range (from 10.7V to 12.9V) does not match your hardware, or give a shot to default.battery.voltage.nominal (e.g. 24) if your device does not serve that either.

Note

Lead (PbAc) battery charge graph is not linear, so guesstimated charge value may not be perfectly accurate. However it should be good enough to determine battery actual status and roughly estimate the time it can still power the system.

Warning

This keyword may be deprecated in future releases of the driver, in favor of runtimecal and other settings which it requires (as seen in nutdrv_qx(8), blazer_ser(8) and blazer_usb(8) drivers).

## AUTHOR
Massimo Zampieri

## SEE ALSO

### Related drivers
riello_usb(8)

### The core driver
nutupsdrv(8)

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


title: riello_usb(8)

text:
# riello_usb(8)

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

## SYNOPSIS
riello_usb -h

riello_usb -a UPS_NAME [OPTIONS]

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

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

Older Riello UPS products are not supported.

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

You may need to tweak some settings, depending on the make and model of your UPS (see ups.conf(5)):

localcalculation

When enabled, driver will calculate values of battery.runtime and battery.charge "locally" in the driver. This is for some Riello models (iPlug and iDialog series) which provide incorrect values in hardware readings, or none at all. This "local calculation" is done according to nominal battery capacity, nominal battery voltage, actual battery charge, maximum and actual UPS load. You may want to also configure default.battery.voltage.low and default.battery.voltage.high in case the built-in default range (from 10.7V to 12.9V) does not match your hardware, or give a shot to default.battery.voltage.nominal (e.g. 24) if your device does not serve that either.

Note

Lead (PbAc) battery charge graph is not linear, so guesstimated charge value may not be perfectly accurate. However it should be good enough to determine battery actual status and roughly estimate the time it can still power the system.

Warning

This keyword may be deprecated in future releases of the driver, in favor of runtimecal and other settings which it requires (as seen in nutdrv_qx(8), blazer_ser(8) and blazer_usb(8) drivers).

## AUTHOR
Massimo Zampieri

## SEE ALSO

### Related drivers
riello_ser(8)

### The core driver
nutupsdrv(8)

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


safenet

title: safenet(8)

text:
# safenet(8)

## NAME
safenet - Driver for SafeNet compatible UPS equipment

## SYNOPSIS
safenet -h

safenet -a UPS_NAME [OPTIONS]

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

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

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

manufacturer=value

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

modelname=value

Like manufacturer above. The default is unknown.

serialnumber=value

Like manufacturer above. The default is unknown.

ondelay=value

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

offdelay=value

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

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

test.battery.start

Start UPS self test

test.battery.stop

Cancel UPS self test

test.failure.start

Start simulated power failure

test.failure.stop

Cancel simulated power failure

beeper.enable

Enable the UPS beeper

beeper.mute

Temporarily mute the UPS beeper

beeper.toggle

Toggle the UPS beeper

shutdown.return

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

shutdown.reboot

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

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

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

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

## SEE ALSO

### The core driver:
nutupsdrv(8)

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


title: sms_ser(8)

summary: Driver for SMS UPS Protocol 1Phase.

text:
# sms_ser(8)

## NAME
sms_ser - Driver for SMS UPS Protocol 1Phase.

## SYNOPSIS
sms_ser -h

sms_ser -a UPS_NAME [OPTIONS]

Note This man page only documents the hardware-specific features of the sms_ser driver. For information about the core driver, see nutupsdrv(8), and for the technical background check the docs/sms-brazil-protocol.txt file in NUT sources.

Note Given the proximity of this protocol to Megatec Qx family, this driver may later become part of nutdrv_qx collection.

## SUPPORTED HARDWARE
sms_ser supports only the "sms 1phase" SMS Product, as described in the monofasico.xml file delivered with the device.

Other SMS protocols (for their other products) are not supported by this driver.

## AUTHOR
Alex W. Baulé

## SEE ALSO

### The core driver
nutupsdrv(8)

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


sockdebug

title: sockdebug(8)

text:
# sockdebug(8)

## NAME
sockdebug - Simple developer/troubleshooting aid utility to communicate with a NUT driver using the socket protocol

## SYNOPSIS
sockdebug socketname

For example (WIN32 and POSIX builds):

```
:; sockdebug.exe dummy-ups-UPS1
```

For example (POSIX-compliant systems using an alternate state path):

```
:; sockdebug /var/state/ups/dummy-ups-UPS1
```

## DESCRIPTION
sockdebug is a tool built when NUT configure --with-dev is enabled. It may alternatively be built by calling make sockdebug in the root of the build workspace. Actual source files used depend on the platform.

It is used to connect to a NUT driver using the socket protocol on an Unix socket or Windows pipe, similarly to how the upsd(8) data server talks to the locally running drivers in order to represent them on the network further using the common NUT protocol of the Network UPS Tools project, or how driver programs can communicate to their already running instances to implement commands like live reload-or-error.

This tool allows a developer or troubleshooter to watch the broadcast updates emitted by the driver, as well as to issue unicast commands and receive replies (during an interactive investigation session, you may want to command NOBROADCAST first).

For more details see the docs/sock-protocol.txt file in NUT sources.

## OPTIONS
sockdebug accepts (and requires) the following option:

socketname

Either a full path (in POSIX builds) or the base name of device socket/pipe (on all platforms), comprised of a drivername-devicename tuple, e.g. some dummy-ups-UPS1 for a dummy-ups driver instance handling an UPS1 device configuration (which in turn may originate in the ups.conf file or be dynamically constructed for tests by calling the driver program with a -s TMP CLI option). On POSIX systems, if this argument only represents a base name and not a full path to the Unix socket file, the tool should first look for the file in the current directory, and then fall back to configured (built-in) state path or the value of NUT_STATEPATH environment variable, if set; e.g.:

```
:; NUT_STATEPATH=/tmp ./server/sockdebug dummy-ups-UPS1
```

## AUTHORS
This manual page was written by Jim Klimov <jimklimov+nut@gmail.com>.

The program is currently maintained as two separate sources, with one of them used for a build depending on the target platform:

•server/sockdebug.c (POSIX version) was originally written by Russell Kroll <rkroll@exploits.org>, and

•server/pipedebug.c (Windows version) was originally written by Frederic Bohe <fredericbohe@eaton.com>.

## SEE ALSO
upsd(8)

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


solis

title: solis(8)

text:
# solis(8)

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

## SYNOPSIS
solis -h

solis -a UPS_NAME [OPTIONS]

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

## SUPPORTED HARDWARE
This driver has been tested with:

•Solis 1000 VA

•Solis 1500 VA

•Solis 2000 VA

•Solis 3000 VA

•Back-UPS BZ1200-BR

•Back-UPS BZ2200BI-BR

All Solis models are sinusoidal on-line.

In 2009, Schneider Electric acquired Microsol Technologies, and by 2012, the entire Microsol line of equipment was being sold under the APC brand. Newer devices may be better supported by microsol-apc(8) driver instead.

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

battext=n

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

prgshut=n

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

## COMMANDS
shutdown.return

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

shutdown.stayoff

Shut down in .3 minutes and do not return.

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

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

## SEE ALSO

### The core driver:
nutupsdrv(8)

### Driver for newer devices under same brand:
microsol-apc(8)

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


tripplite

title: tripplite(8)

summary: Driver for Tripp\-Lite SmartPro UPS equipment

text:
# tripplite(8)

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

## SYNOPSIS
tripplite -h

tripplite -a UPS_NAME [OPTIONS]

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

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

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

offdelay=num

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

rebootdelay=num

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

startdelay=num

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

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

## AUTHORS
•Rickard E. (Rik) Faith

•Nicholas Kain

## SEE ALSO

### The core driver:
nutupsdrv(8)

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

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


title: tripplite_usb(8)

text:
# tripplite_usb(8)

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

## SYNOPSIS
tripplite_usb -h

tripplite_usb -a UPS_NAME [OPTIONS]

## SUPPORTED HARDWARE
This driver should work with older Tripp Lite UPSes which are detected as USB HID-class devices, but are not true HID Power-Device Class devices. So far, the devices supported by tripplite_usb have product ID 0001, and the newer units (such as those with "LCD" in the model name) with product ID 2001 require the usbhid-ups(8) driver instead.

Please report success or failure to the nut-upsuser mailing list. A key piece of information is the protocol number, returned in ups.firmware.aux. Also, be sure to turn on debugging (-DDD) for more informative log messages.

If your Tripp Lite UPS uses a serial port, you may wish to investigate the tripplite(8) or tripplitesu(8) drivers.

This driver has been tested with the following models:

•INTERNETOFFICE700

•OMNIVS1000

•OMNIVS1500XL (some warnings)

•SMART700USB

•SMART1500RM2U

•SMART2200RMXL2U

•SMART3000RM2U

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

•Protocol 0004

•Protocol 1001

•Protocol 2001

•Protocol 3003

•Protocol 3005

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

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

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

•-x upsid="12345"

Select a specific UPS by its unique UPS ID. The argument is a regular expression that must match the UPS ID string. This allows for precise identification of UPS devices when multiple devices of the same make and model are connected. See below regarding how to read and write the ups id (unit id) using upsrw(8).

Notes for tripplite_usb driver handling of common USB matching settings:

•product is a regular expression to match the product string for the UPS. This would be useful if you have two different Tripp Lite UPS models connected to the same monitoring system, and you want to be sure that you shut them down in the correct order. This regex is matched against the full USB product string as seen in lsusb(8). The ups.model in the upsc(8) output only lists the name after TRIPP LITE, so to match a SMART2200RMXL2U, you could use the regex like .*SMART2200.*.

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

•The serial option may be or not be helpful: it does not appear that these particular Tripp Lite UPSes supported by this driver use the iSerial descriptor field to return a serial number. However, in case your unit does, you may specify it here.

offdelay

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

battery_min, battery_max

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

## RUNTIME VARIABLES
ups.delay.shutdown

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

ups.id

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

outlet.1.switch

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

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

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

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

Some of the SMART*2U models have a configurable Unit ID number, and you can now use the upsid config argument to uniquely specify which UPS a given driver instance should control. This allows for precise identification of UPS devices when multiple devices are connected. To retrieve or set the upsid, you can use the upsrw(8) utility.

## AUTHORS
Written by Charles Lepple, based on the tripplite(8) driver by Rickard E. (Rik) Faith and Nicholas Kain.

Please do not email the authors directly — use the nut-upsdev mailing list.

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

## SEE ALSO

### The core driver:
nutupsdrv(8)

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

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

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


tripplitesu

title: tripplitesu(8)

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

text:
# tripplitesu(8)

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

## SYNOPSIS
tripplitesu -h

tripplitesu -a UPS_NAME [OPTIONS]

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

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

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

lowbatt=num

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

command_delay=milliseconds

Set a delay in milliseconds to be applied before each command sent to the UPS. The default value is 0 (disabled). If experiencing intermittent communication timeouts when multiple commands are sent in rapid succession, set this to 1000 (1 second) or adjust as needed.

This delay helps prevent "read timeout" errors when the hardware buffer is not ready to accept new commands immediately after completing the previous one.

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

## SEE ALSO

### The core driver:
nutupsdrv(8)

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

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


title: upscode2(8)

text:
# upscode2(8)

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

## SYNOPSIS
upscode2 -h

upscode2 -a UPS_NAME [OPTIONS]

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

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

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

manufacturer=value

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

input_timeout=value

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

output_pace=value

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

baudrate=value

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

full_update_timer=value

Number of seconds between collection of normative values.

use_crlf

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

use_pre_lf

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

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

•test.panel.start - Start UPS self test

•test.battery.start - Start battery self test

•beeper.enable - Enable UPS beeper

•beeper.disable - Disable UPS beeper

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

•shutdown.stayoff - Shut down in 1 seconds

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

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

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

## AUTHORS
•Håvard Lygre <hklygre@online.no>

•Niels Baggesen <niels@baggesen.net>

## SEE ALSO

### The core driver:
nutupsdrv(8)

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


upsd

title: upsd(8)

summary: Network UPS Tools data server

text:
# upsd(8)

## NAME
upsd - Network UPS Tools data server

## SYNOPSIS
upsd -h

upsd [OPTIONS]

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

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

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

This program is essential, and must be running at all times to actually make any use out of the drivers and clients (except for final UPS power-off commands just before your server goes down, which NUT driver programs can do alone when called as drivername -k in a shutdown hook or late ordered SysV init script).

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

## OPTIONS
-c command

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

reread configuration files

stop

stop process and exit

-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 upsd as a foreground process so it does not create a PID file. See also -FF option as an alternative.

-D

Raise the debugging level. upsd will run in the foreground by default, and will print information on stdout about the monitoring process. Use this option multiple times for more details.

-F

upsd will run in the foreground, regardless of debugging settings. Specify twice (-FF or -F -F) to save the PID file even in this mode.

-B

upsd will run in the background, regardless of debugging settings.

-h

Display the help text.

-r directory

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

-u user

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

-V

Display the version of the program.

## RELOADING
upsd can reload its configuration files without shutting down the process if you send it a SIGHUP or start it again with -c reload. This only works if the background process is able to read those files (permissions, chroot jail), and if the daemon did save a PID file when it started (for the reload command to find the older instance).

Note Service instances wrapped by systemd or SMF might not save them by default — use respective reload/refresh framework actions instead then), e.g. systemctl reload nut-server

NUT releases after 2.8.0 define aliases for these units, so if your Linux distribution uses NUT-provided unit definitions, systemctl reload upsd may also work.

If you think that upsd can’t reload, check your syslog for error messages. If it’s complaining about not being able to read the files, then you need to adjust your system to make it possible. Either change the permissions on the files, or run upsd as another user that will be able to read them, or restart it fully (may be needed e.g. if running in a chroot jail).

DO NOT make your upsd.conf(5) or upsd.users(5) files world-readable, as they hold important authentication information. In the wrong hands, it could be used by some evil person to spoof your primary-mode upsmon and command your systems to shut down, for example.

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

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

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

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

## FILES
The general upsd configuration file is upsd.conf(5).

The administrative functions like SET and INSTCMD for users, and various upsmon roles, are defined and controlled in upsd.users(5).

UPS definitions are found in ups.conf(5) (shared with actual drivers).

## 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 upsd.conf and other configuration files. If this variable is not set, upsd uses a built-in default, which is often /usr/local/ups/etc.

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

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.

## SEE ALSO

### 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:
•nutupsdrv(8)

•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/


upsdrvctl

title: upsdrvctl(8)

summary: Network UPS Tools driver controller

text:
# upsdrvctl(8)

## NAME
upsdrvctl - Network UPS Tools driver controller

## SYNOPSIS
upsdrvctl -h

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

upsdrvctl [OPTIONS] {list | -l} [ups]

upsdrvctl [OPTIONS] -c COMMAND [ups]

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

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

Warning For operating systems with service management frameworks, such as Solaris/illumos SMF or Linux systemd, the upsdrvsvcctl(8) may be a better choice.

In fact, service instances prepared by nut-driver-enumerator(8) based on contents of your ups.conf(5) file and automatically maintained by the respective framework can conflict with manual execution of drivers. In this case, upsdrvctl would emit a warning in NUT builds with that capability (can be silenced by exporting a NUT_QUIET_INIT_NDE_WARNING environment variable with any value).

You may be required to stop service units (if used) and run driver programs directly rather than via upsdrvctl for troubleshooting, e.g. to facilitate debug log collection or test any custom builds of drivers without conflict with a normally running packaged instance.

## OPTIONS
-h

Display the help text.

-r directory

If starting a driver, this value will direct it to chroot(2) into directory. This can be useful when securing systems. This may be set in the ups.conf(5) with the chroot directive in the global section.

-t

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

-u username

If starting a driver, this value will direct it to setuid(2) to the user id associated with username. If the driver is started as root without specifying this value, it will use the username that was compiled into the binary. This defaults to nobody (if not otherwise configured), which is far from ideal.

This may be set in ups.conf(5) with the user directive in the global section.

-D

Raise the debug level. Use this multiple times for additional details. Alternatively the value can be set via debug_min in global section of ups.conf(5). Note the global setting applies to both the tool and a started driver; but another line in a driver’s individual section can override that with a larger or smaller value (including a debug_min=0 to disable tracing the driver by default). Note that this does not preclude the upsdrvctl tool from exiting after its job is done (however an explicit -F option does).

Also note that this option alone modifies the debug verbosity of the tool, but not of the drivers it launches. See the additional -d option for that.

-d

Pass the selected debug level from upsdrvctl to launched drivers. Note that by default for NUT daemons, enabled debugging means running in foreground mode; you can specify -B additionally to avoid that.

-F

Driver will run in the foreground (not fork away from the upsdrvctl process), regardless of debugging settings. It would also keep the tool program itself foregrounded with driver daemons running as its children (in case of a single driver startup, it would not even fork). It would also not wait for drivers to complete initialization, so upsdrvctl will warn about such situations.

Specify twice (-FF or -F -F) to save the driver PID file even in this mode (not saved by default when staying in foreground).

-B

Drivers will run in the background, regardless of debugging settings, as set by -D and passed-through by -d options.

-l

Alias for list command.

## COMMANDS
upsdrvctl supports three active commands — start, stop and shutdown. It also supports passing requests to running drivers using -c COMMAND syntax, similar to that in some other daemons. A couple of helper commands are also available — list and status.

They all can take an optional argument which is a UPS name from ups.conf(5). Without that argument, they operate on every UPS that is currently configured.

Note upsdrvctl can not manage devices not listed in ups.conf (such as test drivers started with -s TMP option).

start

Start the UPS driver(s). In case of failure to start within maxstartdelay time-frame, further attempts may be executed by using the maxretry and retrydelay values. Conversely, the nowait global option can be used, especially to speed up parallel start of many drivers. See ups.conf(5) about these options. Built-in defaults are: maxstartdelay=75 (sec), maxretry=1 (meaning one attempt at starting), retrydelay=5 (sec).

stop

Stop the UPS driver(s). This does not send commands to the UPS.

shutdown

Command the UPS driver(s) to run their shutdown sequence. This assumes that the driver is no longer running, and starts a fresh instance via drivername -k. It is intended to be used as the last step in system shutdown, after the filesystems are no longer mounted rw. Drivers are stopped according to their sdorder value — see ups.conf(5).

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

Note Refer to ups.conf(5) for using the nowait parameter. It can be overridden by NUT_IGNORE_NOWAIT environment variable (e.g. used to work around certain issues with systemd otherwise).

list

Without a further argument, report all currently known device configuration names to stdout, one per line. With an argument, also try to report that name, but exit with an error code if that name is not known.

Note The tool would exit with an error if ups.conf file is not found, readable, or does not define any device sections (whose names are reported here and managed in other commands).

Note The tool name and NUT version banner line is also printed to stdout before any other processing. This can be suppressed by NUT_QUIET_INIT_BANNER environment variable (exported by caller and empty or "true"):

```
:; NUT_QUIET_INIT_BANNER=true upsdrvctl list
dummy
UPS1
UPS2
```

status

Similar to list, but reports more information — also the driver name, the PID if it is running, and result of a signal probe to check it is responding. The NUT_QUIET_INIT_BANNER suppression can be helpful for scripted parsing. If there is anything to print (at least one device is known), the first line of status report would be the heading with column names:

```
:; NUT_QUIET_INIT_BANNER=true upsdrvctl status
UPSNAME              UPSDRV  RUNNING PF_PID  S_RESPONSIVE    S_PID   S_STATUS
dummy             dummy-ups  N/A     -3      NOT_RESPONSIVE  N/A
eco650           usbhid-ups  RUNNING 3559207 RESPONSIVE      3559207 "OL"
UPS2              dummy-ups  RUNNING 31455   RESPONSIVE      31455   "OL BOOST"
```

Values are TAB-separated, but UPSNAME and UPSDRV may be padded by spaces on the right and on the left respectively. Any complex string values would be encased in double-quotes.

Fields reported (PF_* = according to PID file, if any; S_* = via socket protocol):

UPSNAME

driver section configuration name

UPSDRV

driver program name per ups.conf

RUNNING

RUNNING if PF_PID or S_PID is valid, STOPPED if at least one PID value was parsed but none was found running with a correct program name; N/A if no PID file/socket reply or failed to parse. First the PID file is consulted, but it may be absent either due to command-line parameters of daemons, or due to platform (WIN32). If no PID value was found and confirmed this way, we fall back to checking the PID reported via protocol (if available and different).

PF_PID

PID of driver according to PID file (if any), or some negative values upon errors (as defined in common.c) including an absent PID file, invalid contents, or unsupported platform for this mechanism (e.g. WIN32)

S_RESPONSIVE

RESPONSIVE if PING/PONG during socket protocol session setup succeeded; NOT_RESPONSIVE otherwise

S_PID

PID of driver according to GETPID active query, or N/A if the query failed

S_STATUS

Quoted value of ups.status variable

This mode does not discover drivers that are not in ups.conf (e.g. started manually for experiments with many -x CLI options).

-c command

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

tell the driver(s) to dump currently known state information to their stdout (if attached anywhere)

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)

If the upsdrvctl was launched to remain in memory and manage NUT driver processes, it can receive supported signals and pass them to those drivers.

## 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, upsdrvctl (and the drivers) use a built-in default, which is often /usr/local/ups/etc.

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.

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

## SEE ALSO
upsdrvsvcctl(8), nut-driver-enumerator(8), nutupsdrv(8), upsd(8), ups.conf(5)

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