301 lines
11 KiB
Text
301 lines
11 KiB
Text
UPS.CONF(5)
|
|
===========
|
|
|
|
NAME
|
|
----
|
|
|
|
ups.conf - UPS definitions for Network UPS Tools
|
|
|
|
DESCRIPTION
|
|
-----------
|
|
|
|
This file is read by the driver controller linkman:upsdrvctl[8], the UPS drivers
|
|
that use the common core (see linkman:nutupsdrv[8], and linkman:upsd[8]). The
|
|
file begins with global directives, and then each UPS has a section which
|
|
contains a number of directives that set parameters for that UPS.
|
|
|
|
A UPS section begins with the name of the UPS in brackets, and continues
|
|
until the next UPS name in brackets or until EOF. The name "default" is
|
|
used internally in upsd, so you can't use it in this file.
|
|
|
|
You must define the 'driver' and 'port' elements for each entry. Anything
|
|
after that in a section is optional. A simple example might look like this:
|
|
|
|
[myups]
|
|
driver = blazer_ser
|
|
port = /dev/ttyS0
|
|
desc = "Web server UPS"
|
|
|
|
A slightly more complicated version includes some extras for the
|
|
hardware-specific part of the driver:
|
|
|
|
[bigups]
|
|
driver = apcsmart
|
|
port = /dev/cua00
|
|
cable = 940-0095B
|
|
sdtype = 2
|
|
desc = "Database server UPS"
|
|
|
|
In this case, the linkman:apcsmart[8] driver will receive variables called
|
|
"cable" and "sdtype" which have special meanings. See the man pages of
|
|
your driver(s) to learn which variables are supported and what they do.
|
|
|
|
GLOBAL DIRECTIVES
|
|
-----------------
|
|
|
|
*chroot*::
|
|
|
|
Optional. The driver will chroot(2) to this directory during initialization.
|
|
This can be useful when securing systems.
|
|
|
|
*driverpath*::
|
|
|
|
Optional. Path name of the directory in which the UPS driver executables
|
|
reside. If you don't specify this, the programs look in a built-in default
|
|
directory, which is often /usr/local/ups/bin.
|
|
|
|
*maxstartdelay*::
|
|
|
|
Optional. Same as the UPS field of the same name, but this is the
|
|
default for UPSes that don't have the field.
|
|
|
|
*maxretry*::
|
|
Optional. Specify the number of attempts to start the driver(s), in case of
|
|
failure, before giving up. A delay of 'retrydelay' is inserted between each
|
|
attempt. Caution should be taken when using this option, since it can
|
|
impact the time taken by your system to start.
|
|
+
|
|
The default is 1 attempt.
|
|
|
|
*nowait*::
|
|
Optional. Specify to upsdrvctl to not wait at all for the driver(s) to
|
|
execute the request command.
|
|
+
|
|
The default (omission) is to wait.
|
|
|
|
*retrydelay*::
|
|
Optional. Specify the delay between each restart attempt of the driver(s),
|
|
as specified by 'maxretry'. Caution should be taken when using this option,
|
|
since it can impact the time taken by your system to start.
|
|
+
|
|
The default is 5 seconds.
|
|
|
|
*pollinterval*::
|
|
|
|
Optional. The status of the UPS will be refreshed after a maximum
|
|
delay which is controlled by this setting. This is normally 2 seconds. This
|
|
may be useful if the driver is creating too much of a load on your system or
|
|
network.
|
|
+
|
|
Note that some drivers (such as linkman:usbhid-ups[8], linkman:snmp-ups[8] and
|
|
linkman:nutdrv_qx[8]) also have an option called *pollfreq* which controls how
|
|
frequently some of the less critical parameters are polled. Details are
|
|
provided in the respective driver man pages.
|
|
|
|
*synchronous*::
|
|
|
|
Optional. The drivers work by default in asynchronous mode initially
|
|
but can fall back to synchronous mode if writes to server socket failed
|
|
(i.e *synchronous=auto*). This means that all data are pushed by the driver
|
|
on the communication socket to upsd (Unix socket on Unix, Named pipe
|
|
on Windows) without waiting for these data to be actually consumed.
|
|
With some HW, such as ePDUs, that can produce a lot of data,
|
|
asynchronous mode may cause some congestion, resulting in the socket to
|
|
be full, and the driver to appear as not connected. In such case, the
|
|
driver will provide the following debug message:
|
|
+
|
|
write XX bytes to socket Y failed
|
|
+
|
|
By enabling the 'synchronous' flag (value = 'yes'), the driver will wait
|
|
for data to be consumed by upsd, prior to publishing more. This can be
|
|
enabled either globally or per driver.
|
|
+
|
|
The default of 'auto' acts like 'no' (i.e. asynchronous mode) for backward
|
|
compatibility of the driver behavior, until communications fail with a
|
|
"Resource temporarily unavailable" condition, which happens when the
|
|
driver has many data points to send in a burst, and the server can not
|
|
handle that quickly enough so the buffer fills up.
|
|
|
|
*user*::
|
|
|
|
Optional. Overrides the compiled-in default unprivileged username for
|
|
all NUT device drivers. See the discussion of the `-u` option in
|
|
linkman:nutupsdrv[8] for details.
|
|
|
|
*group*::
|
|
|
|
Optional. Overrides the compiled-in (and/or global-section) default
|
|
unprivileged group name for all NUT device drivers, used for the
|
|
socket file access. See the discussion of the `-g` option in
|
|
linkman:nutupsdrv[8] for details.
|
|
This may be specifically useful for ensuring access to dynamic device
|
|
filesystem nodes, such as USB (or serial-over-USB) hot-plug support,
|
|
or with device filesystems re-generated by an OS for every reboot.
|
|
|
|
*debug_min* 'INTEGER'::
|
|
|
|
Optional. Specify a minimum debug level for all driver daemons, e.g. for
|
|
troubleshooting a deployment, without impacting foreground or background
|
|
running mode directly. Command-line option `-D` can only increase this
|
|
verbosity level.
|
|
|
|
UPS FIELDS
|
|
----------
|
|
|
|
*driver*::
|
|
|
|
Required. This specifies which program will be monitoring this UPS. You
|
|
need to specify the one that is compatible with your hardware. See
|
|
linkman:nutupsdrv[8] for more information on drivers in general and pointers to the
|
|
man pages of specific drivers.
|
|
|
|
*port*::
|
|
|
|
Required. This is the serial port where the UPS is connected. On a Linux
|
|
system, the first serial port usually is '/dev/ttyS0'. On FreeBSD and
|
|
similar systems, it probably will be '/dev/cuaa0'.
|
|
|
|
*user*::
|
|
|
|
Optional. Overrides the compiled-in (and/or global-section) default
|
|
unprivileged username for a particular NUT device driver. See the
|
|
discussion of the `-u` option in linkman:nutupsdrv[8] for details.
|
|
This may be specifically useful for ensuring access to dynamic device
|
|
filesystem nodes, such as USB (or serial-over-USB) hot-plug support,
|
|
or with device filesystems re-generated by an OS for every reboot.
|
|
|
|
*group*::
|
|
|
|
Optional. Overrides the compiled-in (and/or global-section) default
|
|
unprivileged group name for a particular NUT device driver, used for
|
|
the socket file access. See the discussion of the `-g` option in
|
|
linkman:nutupsdrv[8] for details.
|
|
This may be specifically useful for ensuring access to dynamic device
|
|
filesystem nodes, such as USB (or serial-over-USB) hot-plug support,
|
|
or with device filesystems re-generated by an OS for every reboot.
|
|
|
|
*sdorder*::
|
|
|
|
Optional. When you have multiple UPSes on your system, you usually need to
|
|
turn them off in a certain order. upsdrvctl shuts down all the 0s,
|
|
then the 1s, 2s, and so on. To exclude a UPS from the shutdown sequence,
|
|
set this to -1.
|
|
+
|
|
The default value for this parameter is 0.
|
|
|
|
*desc*::
|
|
|
|
Optional. This allows you to set a brief description that upsd will provide
|
|
to clients that ask for a list of connected equipment.
|
|
|
|
*nolock*::
|
|
|
|
Optional. When you specify this, the driver skips the port locking routines
|
|
every time it starts. This may allow other processes to seize the port if
|
|
you start more than one accidentally.
|
|
+
|
|
You should only use this if your system won't work without it.
|
|
+
|
|
This may be needed on Mac OS X systems.
|
|
|
|
*ignorelb*::
|
|
|
|
Optional. When you specify this, the driver ignores a low battery condition
|
|
flag that is reported by the UPS (some devices will switch off almost
|
|
immediately after setting this flag, or will report this as soon as the
|
|
mains fails). Instead it will use either of the following conditions to
|
|
determine when the battery is low:
|
|
|
|
battery.charge < battery.charge.low
|
|
battery.runtime < battery.runtime.low
|
|
+
|
|
The idea is to set the battery.charge.low and/or battery.runtime.low levels
|
|
in *ups.conf* to a value that gives enough time to cleanly shutdown your
|
|
system:
|
|
|
|
override.battery.charge.low = 30
|
|
override.battery.runtime.low = 180
|
|
+
|
|
In order for this to work, your UPS should be able to (reliably) report
|
|
charge and/or runtime remaining on battery. Use with caution!
|
|
|
|
*maxstartdelay*::
|
|
|
|
Optional. This can be set as a global variable above your first UPS
|
|
definition and it can also be set in a UPS section. This value controls how
|
|
long upsdrvctl will wait for the driver to finish starting. This keeps your
|
|
system from getting stuck due to a broken driver or UPS.
|
|
+
|
|
The default is 45 seconds.
|
|
|
|
*synchronous*::
|
|
|
|
Optional. Same as the global directive of the same name, but this is
|
|
for a specific device.
|
|
|
|
*usb_set_altinterface*[='altinterface']::
|
|
|
|
Optional. Force the USB code to call `usb_set_altinterface(0)`, as was done in
|
|
NUT 2.7.2 and earlier. This should not be necessary, since the default for
|
|
`bAlternateSetting` (as shown in lsusb) is zero on all USB devices seen to
|
|
date. However, this redundant call to `usb_set_altinterface()` prevents
|
|
certain UPSes from working on Mac OS X. If your UPS requires explicitly setting
|
|
the alternate interface, include this flag, and email the nut-upsdev list with
|
|
details about your UPS and operating system.
|
|
|
|
*default.<variable>*::
|
|
|
|
Optional. Set a default value for <variable> which is used in case the UPS
|
|
doesn't provide a value, but will be overwritten if a value is available
|
|
from the UPS:
|
|
|
|
default.input.voltage.nominal = 230
|
|
+
|
|
The above will report the nominal input voltage to be 230, unless the UPS
|
|
tells us differently.
|
|
|
|
*override.<variable>*::
|
|
|
|
Optional. Set a value for <value> that overrides any value that may be read
|
|
from the UPS. Used for overriding values from the UPS that are clearly wrong
|
|
(some devices report wrong values for battery voltage for instance):
|
|
|
|
override.battery.voltage.nominal = 12
|
|
+
|
|
Use with caution! This will only change the appearance of the variable to
|
|
the outside world, internally in the UPS the original value is used.
|
|
|
|
All other fields are passed through to the hardware-specific part of the
|
|
driver. See those manuals for the list of what is allowed.
|
|
|
|
*debug_min* 'INTEGER'::
|
|
|
|
Optional. Specify a minimum debug level for this driver daemon, e.g. for
|
|
troubleshooting a deployment, without impacting foreground or background
|
|
running mode directly. If the global `debug_min` is also set, this
|
|
driver-level setting overrides it. Command-line option `-D` can only
|
|
increase this verbosity level.
|
|
|
|
INTEGRATION
|
|
-----------
|
|
|
|
linkman:upsdrvctl[8] uses this file to start and stop the drivers.
|
|
|
|
The drivers themselves also obtain configuration data from this file.
|
|
Each driver looks up its section and uses that to configure itself.
|
|
|
|
linkman:upsd[8] learns about which UPSes are installed on this system by
|
|
reading this file. If this system is called "doghouse" and you have
|
|
defined a UPS in your *ups.conf* called "snoopy", then you can monitor it
|
|
from linkman:upsc[8] or similar as "snoopy@doghouse".
|
|
|
|
SEE ALSO
|
|
--------
|
|
|
|
linkman:upsd[8], linkman:nutupsdrv[8], linkman:upsdrvctl[8],
|
|
linkman:upsdrvsvcctl[8]
|
|
|
|
Internet resources
|
|
~~~~~~~~~~~~~~~~~~
|
|
|
|
The NUT (Network UPS Tools) home page: http://www.networkupstools.org/
|