241 lines
8.1 KiB
Plaintext
241 lines
8.1 KiB
Plaintext
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 linkman: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 linkman: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-like format) to stdout. This can be useful to
|
|
complement the nut-scanner to discover devices, along with in-depth data.
|
|
|
|
NOTE: You probably don't want to use any of these options directly. You
|
|
should use linkman:upsdrvctl[8] to control your drivers, and
|
|
linkman: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 linkman: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
|
|
linkman: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 the driver instance cannot be controlled by linkman:upsdrvctl[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-like format) to stdout after running the driver
|
|
update loop for '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.
|
|
|
|
*-q*::
|
|
Raise log level threshold. Use this multiple times to log more details.
|
|
+
|
|
The debugging comment above also applies here.
|
|
|
|
*-F*::
|
|
Enforce running the driver as a foreground process, regardless of debugging
|
|
or data-dumping settings.
|
|
|
|
*-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.
|
|
|
|
*-r* 'directory'::
|
|
The driver will chroot(2) to 'directory' during initialization.
|
|
This can be useful when securing systems.
|
|
+
|
|
In addition to the state path, many systems will require /dev/null to
|
|
exist within 'directory' for this to work. The serial ports are
|
|
opened before the chroot call, so you do not need to create them inside
|
|
the jail. In fact, it is somewhat safer if you do not.
|
|
|
|
*-u* 'username'::
|
|
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
|
|
linkman: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 the specific man pages
|
|
for more information.
|
|
+
|
|
This is like setting 'var'='val' in linkman:ups.conf[5], but
|
|
*-x* overrides any settings from that file.
|
|
|
|
DIAGNOSTICS
|
|
-----------
|
|
|
|
Information about the startup process is printed to stdout. Additional
|
|
messages after that point are available in the syslog. After linkman:upsd[8]
|
|
starts, the UPS clients such as linkman:upsc[8] can be used to query the status
|
|
of an UPS.
|
|
|
|
PROGRAM CONTROL
|
|
---------------
|
|
|
|
You should always use linkman:upsdrvctl[8] to control the drivers. While
|
|
drivers can be started by hand for testing purposes, it is not recommended for
|
|
production use.
|
|
|
|
FILES
|
|
-----
|
|
|
|
ups.conf::
|
|
Required configuration file. This contains all details on which drivers
|
|
to start and where the hardware is attached.
|
|
|
|
ENVIRONMENT VARIABLES
|
|
---------------------
|
|
|
|
*NUT_CONFPATH* is the path name of the directory that contains
|
|
`upsd.conf` and other configuration files. If this variable is not set,
|
|
*upsd* uses a built-in default, which is often `/usr/local/ups/etc`.
|
|
|
|
*NUT_STATEPATH* is the path name of the directory in which
|
|
*upsd* keeps state information. If this variable is not set,
|
|
*upsd* uses a built-in default, which is often `/var/state/ups`.
|
|
The *STATEPATH* directive in linkman: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*.
|
|
|
|
BUGS
|
|
----
|
|
|
|
Some of the drivers may have bugs. See their manuals for more
|
|
information.
|
|
|
|
SEE ALSO
|
|
--------
|
|
|
|
Server:
|
|
~~~~~~~
|
|
|
|
- linkman:upsd[8]
|
|
|
|
Clients:
|
|
~~~~~~~~
|
|
|
|
- linkman:upsc[8]
|
|
- linkman:upscmd[8]
|
|
- linkman:upsrw[8]
|
|
- linkman:upslog[8]
|
|
- linkman:upsmon[8]
|
|
|
|
CGI programs:
|
|
~~~~~~~~~~~~~
|
|
|
|
- linkman:upsset.cgi[8]
|
|
- linkman:upsstats.cgi[8]
|
|
- linkman:upsimage.cgi[8]
|
|
|
|
Driver control:
|
|
~~~~~~~~~~~~~~~
|
|
|
|
include::{builddir}/linkman-drivertool-names.txt[]
|
|
|
|
Drivers:
|
|
~~~~~~~~
|
|
|
|
include::{builddir}/linkman-driver-names.txt[]
|
|
|
|
Internet resources:
|
|
~~~~~~~~~~~~~~~~~~~
|
|
|
|
The NUT (Network UPS Tools) home page: http://www.networkupstools.org/
|