UPSDRVCTL(8)
============

NAME
----

upsdrvctl - UPS driver controller

SYNOPSIS
--------

*upsdrvctl* -h

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

*upsdrvctl* ['OPTIONS'] -c COMMAND ['ups']

DESCRIPTION
-----------

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

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

Note: For operating systems with service management frameworks, such as
Solaris SMF or Linux systemd, the *upsdrvsvcctl* may be a better choice.

OPTIONS
-------

*-h*::
Display the help text.

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

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

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

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

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

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

*-D*::
Raise the debug level.  Use this multiple times for additional details.
Note that this does not preclude the `upsdrvctl` tool from exiting after
its job is done (however an explicit *-F* option does).

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

COMMANDS
--------

upsdrvctl supports three commands - start, stop and shutdown.
It also supports passing requests to running drivers using
`-c COMMAND` syntax, similar to that in some other daemons.

They all can take an optional argument which is a UPS name from
linkman: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, further attempts may be executed
by using the 'maxretry' and 'retrydelay' options - see linkman:ups.conf[5].

*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 "driver -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
linkman: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 linkman: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).

*-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)
/////////
        *reload-or-restart*;; reread configuration files, causing the
                   old driver process to close the device connection
                   and re-exec itself if it encounters modified settings
                   which can not be applied "on the fly" (may fail for
                   critical changes like run-time user/group accounts)
/////////

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

linkman:upsdrvsvcctl[8], linkman:nutupsdrv[8], linkman:upsd[8], linkman:ups.conf[5]

Internet resources:
~~~~~~~~~~~~~~~~~~~

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