1UPS.CONF(5) NUT Manual UPS.CONF(5)
2
6 ups.conf - UPS definitions for Network UPS Tools
7
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 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 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 [myups]
23 driver = blazer_ser
24 port = /dev/ttyS0
25 desc = "Web server UPS"
26 A slightly more complicated version includes some extras for the
28 hardware-specific part of the driver:
29 [bigups]
31 driver = apcsmart
32 port = /dev/cua00
33 cable = 940-0095B
34 sdtype = 2
35 desc = "Database server UPS"
36 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
42 chroot
43 Optional. The driver will chroot(2) to this directory during
44 initialization. This can be useful when securing systems.
45 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 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 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 The default is 1 attempt.
63 nowait
65 Optional. Specify to upsdrvctl to not wait at all for the driver(s)
66 to execute the request command.
67 The default (omission) is to wait.
69 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 The default is 5 seconds.
77 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 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 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 write XX bytes to socket Y failed
102 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 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 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 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 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
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 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 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 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 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 The default value for this parameter is 0.
171 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 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 You should only use this if your system won’t work without it.
182 This may be needed on Mac OS X systems.
184 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 battery.charge < battery.charge.low
193 battery.runtime < battery.runtime.low
194 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 override.battery.charge.low = 30
200 override.battery.runtime.low = 180
201 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 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 The default is 45 seconds.
214 synchronous
216 Optional. Same as the global directive of the same name, but this
217 is for a specific device.
218 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 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 default.input.voltage.nominal = 230
235 The above will report the nominal input voltage to be 230, unless
237 the UPS tells us differently.
238 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 override.battery.voltage.nominal = 12
246 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 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 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
262 upsdrvctl(8) uses this file to start and stop the drivers.
263 The drivers themselves also obtain configuration data from this file.
265 Each driver looks up its section and uses that to configure itself.
266 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
273 upsd(8), nutupsdrv(8), upsdrvctl(8), upsdrvsvcctl(8)
274 Internet resources
276 The NUT (Network UPS Tools) home page: http://www.networkupstools.org/
277Network UPS Tools 2.8.0 04/26/2022 UPS.CONF(5)