UPSDRVCTL(8) | NUT Manual | 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
-r directory
This may be set in the ups.conf(5) with the chroot directive in the global section.
-t
This may be helpful when defining the sdorder directive in your ups.conf(5) section for the device.
-u 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
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
Note that by default for NUT daemons, enabled debugging means running in foreground mode; you can specify -B additionally to avoid that.
-F
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
-l
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
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
shutdown
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
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
:; 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
UPSDRV
RUNNING
PF_PID
S_RESPONSIVE
S_PID
S_STATUS
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
dump
reload
reload-or-error
reload-or-exit
exit
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.3/
05/29/2025 | Network UPS Tools 2.8.3 |