1UPS.CONF(5)                       NUT Manual                       UPS.CONF(5)
2
3
4

NAME

6       ups.conf - UPS definitions for Network UPS Tools
7

DESCRIPTION

9       This file is read by the driver controller upsdrvctl(8), the UPS
10       drivers that use the common core (see nutupsdrv(8), and upsd(8)). The
11       file begins with global directives, and then each UPS has a section
12       which contains a number of directives that set parameters for that UPS.
13
14       A UPS section begins with the name of the UPS in brackets, and
15       continues until the next UPS name in brackets or until EOF. The name
16       "default" is used internally in upsd, so you can’t use it in this file.
17
18       You must define the driver and port elements for each entry. Anything
19       after that in a section is optional. A simple example might look like
20       this:
21
22           [myups]
23                   driver = blazer_ser
24                   port = /dev/ttyS0
25                   desc = "Web server UPS"
26
27       A slightly more complicated version includes some extras for the
28       hardware-specific part of the driver:
29
30           [bigups]
31                   driver = apcsmart
32                   port = /dev/cua00
33                   cable = 940-0095B
34                   sdtype = 2
35                   desc = "Database server UPS"
36
37       In this case, the apcsmart(8) driver will receive variables called
38       "cable" and "sdtype" which have special meanings. See the man pages of
39       your driver(s) to learn which variables are supported and what they do.
40

GLOBAL DIRECTIVES

42       chroot
43           Optional. The driver will chroot(2) to this directory during
44           initialization. This can be useful when securing systems.
45
46       driverpath
47           Optional. Path name of the directory in which the UPS driver
48           executables reside. If you don’t specify this, the programs look in
49           a built-in default directory, which is often /usr/local/ups/bin.
50
51       maxstartdelay
52           Optional. Same as the UPS field of the same name, but this is the
53           default for UPSes that don’t have the field.
54
55       maxretry
56           Optional. Specify the number of attempts to start the driver(s), in
57           case of failure, before giving up. A delay of retrydelay is
58           inserted between each attempt. Caution should be taken when using
59           this option, since it can impact the time taken by your system to
60           start.
61
62           The default is 1 attempt.
63
64       nowait
65           Optional. Specify to upsdrvctl to not wait at all for the driver(s)
66           to execute the request command.
67
68           The default (omission) is to wait.
69
70       retrydelay
71           Optional. Specify the delay between each restart attempt of the
72           driver(s), as specified by maxretry. Caution should be taken when
73           using this option, since it can impact the time taken by your
74           system to start.
75
76           The default is 5 seconds.
77
78       pollinterval
79           Optional. The status of the UPS will be refreshed after a maximum
80           delay which is controlled by this setting. This is normally 2
81           seconds. This may be useful if the driver is creating too much of a
82           load on your system or network.
83
84           Note that some drivers (such as usbhid-ups(8), snmp-ups(8) and
85           nutdrv_qx(8)) also have an option called pollfreq which controls
86           how frequently some of the less critical parameters are polled.
87           Details are provided in the respective driver man pages.
88
89       synchronous
90           Optional. The drivers work by default in asynchronous mode
91           initially but can fall back to synchronous mode if writes to server
92           socket failed (i.e synchronous=auto). This means that all data are
93           pushed by the driver on the communication socket to upsd (Unix
94           socket on Unix, Named pipe on Windows) without waiting for these
95           data to be actually consumed. With some HW, such as ePDUs, that can
96           produce a lot of data, asynchronous mode may cause some congestion,
97           resulting in the socket to be full, and the driver to appear as not
98           connected. In such case, the driver will provide the following
99           debug message:
100
101               write XX bytes to socket Y failed
102
103           By enabling the synchronous flag (value = yes), the driver will
104           wait for data to be consumed by upsd, prior to publishing more.
105           This can be enabled either globally or per driver.
106
107           The default of auto acts like no (i.e. asynchronous mode) for
108           backward compatibility of the driver behavior, until communications
109           fail with a "Resource temporarily unavailable" condition, which
110           happens when the driver has many data points to send in a burst,
111           and the server can not handle that quickly enough so the buffer
112           fills up.
113
114       user
115           Optional. Overrides the compiled-in default unprivileged username
116           for all NUT device drivers. See the discussion of the -u option in
117           nutupsdrv(8) for details.
118
119       group
120           Optional. Overrides the compiled-in (and/or global-section) default
121           unprivileged group name for all NUT device drivers, used for the
122           socket file access. See the discussion of the -g option in
123           nutupsdrv(8) for details. This may be specifically useful for
124           ensuring access to dynamic device filesystem nodes, such as USB (or
125           serial-over-USB) hot-plug support, or with device filesystems
126           re-generated by an OS for every reboot.
127
128       debug_min INTEGER
129           Optional. Specify a minimum debug level for all driver daemons,
130           e.g. for troubleshooting a deployment, without impacting foreground
131           or background running mode directly. Command-line option -D can
132           only increase this verbosity level.
133

UPS FIELDS

135       driver
136           Required. This specifies which program will be monitoring this UPS.
137           You need to specify the one that is compatible with your hardware.
138           See nutupsdrv(8) for more information on drivers in general and
139           pointers to the man pages of specific drivers.
140
141       port
142           Required. This is the serial port where the UPS is connected. On a
143           Linux system, the first serial port usually is /dev/ttyS0. On
144           FreeBSD and similar systems, it probably will be /dev/cuaa0.
145
146       user
147           Optional. Overrides the compiled-in (and/or global-section) default
148           unprivileged username for a particular NUT device driver. See the
149           discussion of the -u option in nutupsdrv(8) for details. This may
150           be specifically useful for ensuring access to dynamic device
151           filesystem nodes, such as USB (or serial-over-USB) hot-plug
152           support, or with device filesystems re-generated by an OS for every
153           reboot.
154
155       group
156           Optional. Overrides the compiled-in (and/or global-section) default
157           unprivileged group name for a particular NUT device driver, used
158           for the socket file access. See the discussion of the -g option in
159           nutupsdrv(8) for details. This may be specifically useful for
160           ensuring access to dynamic device filesystem nodes, such as USB (or
161           serial-over-USB) hot-plug support, or with device filesystems
162           re-generated by an OS for every reboot.
163
164       sdorder
165           Optional. When you have multiple UPSes on your system, you usually
166           need to turn them off in a certain order. upsdrvctl shuts down all
167           the 0s, then the 1s, 2s, and so on. To exclude a UPS from the
168           shutdown sequence, set this to -1.
169
170           The default value for this parameter is 0.
171
172       desc
173           Optional. This allows you to set a brief description that upsd will
174           provide to clients that ask for a list of connected equipment.
175
176       nolock
177           Optional. When you specify this, the driver skips the port locking
178           routines every time it starts. This may allow other processes to
179           seize the port if you start more than one accidentally.
180
181           You should only use this if your system won’t work without it.
182
183           This may be needed on Mac OS X systems.
184
185       ignorelb
186           Optional. When you specify this, the driver ignores a low battery
187           condition flag that is reported by the UPS (some devices will
188           switch off almost immediately after setting this flag, or will
189           report this as soon as the mains fails). Instead it will use either
190           of the following conditions to determine when the battery is low:
191
192               battery.charge < battery.charge.low
193               battery.runtime < battery.runtime.low
194
195           The idea is to set the battery.charge.low and/or
196           battery.runtime.low levels in ups.conf to a value that gives enough
197           time to cleanly shutdown your system:
198
199               override.battery.charge.low = 30
200               override.battery.runtime.low = 180
201
202           In order for this to work, your UPS should be able to (reliably)
203           report charge and/or runtime remaining on battery. Use with
204           caution!
205
206       maxstartdelay
207           Optional. This can be set as a global variable above your first UPS
208           definition and it can also be set in a UPS section. This value
209           controls how long upsdrvctl will wait for the driver to finish
210           starting. This keeps your system from getting stuck due to a broken
211           driver or UPS.
212
213           The default is 45 seconds.
214
215       synchronous
216           Optional. Same as the global directive of the same name, but this
217           is for a specific device.
218
219       usb_set_altinterface[=altinterface]
220           Optional. Force the USB code to call usb_set_altinterface(0), as
221           was done in NUT 2.7.2 and earlier. This should not be necessary,
222           since the default for bAlternateSetting (as shown in lsusb) is zero
223           on all USB devices seen to date. However, this redundant call to
224           usb_set_altinterface() prevents certain UPSes from working on Mac
225           OS X. If your UPS requires explicitly setting the alternate
226           interface, include this flag, and email the nut-upsdev list with
227           details about your UPS and operating system.
228
229       default.<variable>
230           Optional. Set a default value for <variable> which is used in case
231           the UPS doesn’t provide a value, but will be overwritten if a value
232           is available from the UPS:
233
234               default.input.voltage.nominal = 230
235
236           The above will report the nominal input voltage to be 230, unless
237           the UPS tells us differently.
238
239       override.<variable>
240           Optional. Set a value for <value> that overrides any value that may
241           be read from the UPS. Used for overriding values from the UPS that
242           are clearly wrong (some devices report wrong values for battery
243           voltage for instance):
244
245               override.battery.voltage.nominal = 12
246
247           Use with caution! This will only change the appearance of the
248           variable to the outside world, internally in the UPS the original
249           value is used.
250
251       All other fields are passed through to the hardware-specific part of
252       the driver. See those manuals for the list of what is allowed.
253
254       debug_min INTEGER
255           Optional. Specify a minimum debug level for this driver daemon,
256           e.g. for troubleshooting a deployment, without impacting foreground
257           or background running mode directly. If the global debug_min is
258           also set, this driver-level setting overrides it. Command-line
259           option -D can only increase this verbosity level.
260

INTEGRATION

262       upsdrvctl(8) uses this file to start and stop the drivers.
263
264       The drivers themselves also obtain configuration data from this file.
265       Each driver looks up its section and uses that to configure itself.
266
267       upsd(8) learns about which UPSes are installed on this system by
268       reading this file. If this system is called "doghouse" and you have
269       defined a UPS in your ups.conf called "snoopy", then you can monitor it
270       from upsc(8) or similar as "snoopy@doghouse".
271

SEE ALSO

273       upsd(8), nutupsdrv(8), upsdrvctl(8), upsdrvsvcctl(8)
274
275   Internet resources
276       The NUT (Network UPS Tools) home page: http://www.networkupstools.org/
277
278
279
280Network UPS Tools 2.8.0           04/26/2022                       UPS.CONF(5)
Impressum