1APCUPSD.CONF(5) BSD File Formats Manual APCUPSD.CONF(5)
2
4 apcupsd.conf — apcupsd(8) configuration file
5
7 apcupsd.conf is the configuration file for the apcupsd(8) program. The
8 file is a plain ASCII text file which comprises a number of configuration
9 directives which control how the apcupsd program behaves when controlling
10 most American Power Conversion Corp (APC) UPSes. The configuration file
11 is also used for the apctest(8) program when bulk programming the EEPROM
12 in a Smart-UPS model.
13 It will almost certainly be necessary to customise the information in the
15 configuration file to suit your particular configuration and operating
16 requirements.
17 Note that the apcupsd daemon must be restarted in order for changes to
19 the configuration file to become active.
20 The configuration file directives are explained in the subsections below.
22 GENERAL CONFIGURATION DIRECTIVES
24 UPSNAME <string>
25 Specify a name for the UPS for log files, status reports etc.
27 UPSCABLE [ simple | smart | ether | usb | 940-0119A | 940-0127A |
29 940-0128A | 940-0020B | 940-0020C | 940-0023A | 940-0024B |
30 940-0024C | 940-1524C | 940-0024G | 940-0095A | 940-0095B |
31 940-0095C | 940-0625A | MAM-04-02-2000 ]
32 The type of cable used to connect the UPS to the computer.
34 UPSTYPE [ dumb | apcsmart | net | usb | snmp | pcnet | modbus |test ]
36 The type of APC UPS that you have.
38 DEVICE <name>
40 The name of the device used for communication between the UPS
42 and the computer. For a USB UPS, you should leave the DEVICE
43 directive blank and apcupsd will figure out where the device is
44 located.
45 · apcsmart : /dev/tty** (serial connection)
47 · usb : leave blank! (USB connection)
48 · net : hostname:port (NIS connection)
49 · snmp : hostname:port:vendor:community (SNMP connection)
50 · dumb : /dev/tty** (serial connection)
51 · pcnet : ipaddr:username:passphrase (AP9617 SmartSlot card)
52 · modbus : /dev/tty** (serial connection)
53 · modbus : leave blank (USB connection)
54 If you have problems, please see the apcupsd manual for more
56 detailed information and comprehensive troubleshooting advice.
57 POLLTIME <seconds>
59 The rate in seconds that the daemon polls the UPS for status.
61 This rate is automatically set to 1 second when the UPS goes on
62 battery and reset to the specified value when the utility power
63 returns. This setting applies both to directly-attached UPSes
64 and networked UPSes. A low setting will improve the daemon's
65 responsiveness to certain events at the cost of higher CPU util‐
66 isation. The default of 60 is appropriate for most situations.
67 LOCKFILE <path>
69 apcupsd creates a lockfile for the serial or USB port in the
71 specified directory. It must be changed when running more than
72 one copy of apcupsd on the same computer to control multiple
73 UPSes.
74 SCRIPTDIR <path>
76 Directory in which apccontrol and event scripts are located.
78 Defaults to /usr/local/etc/apcupsd. It must be changed when
79 running more than one copy of apcupsd on the same computer to
80 control multiple UPSes.
81 PWRFAILDIR <path>
83 Directory in which apcupsd writes the powerfail flag file cre‐
85 ated when apcupsd initiates a system shutdown. The directory is
86 checked in halt scripts to determine if turning off the UPS out‐
87 put power is required. Defaults to /var/run. It must be
88 changed when running more than one copy of apcupsd on the same
89 computer to control multiple UPSes.
90 NOLOGINDIR <path>
92 Directory in which apcupsd writes the nologin file which tells
94 the OS to disallow new logins. Defaults to /var/run. It must be
95 changed when running more than one copy of apcupsd on the same
96 computer to control multiple UPSes.
97 NIS CONFIGURATION DIRECTIVES
99 NETSERVER [ on | off ]
100 Turns the network information server (NIS) on or off. When on,
102 apcupsd serves status and event information over the network.
103 This information is also used by the web-based CGI monitoring
104 programs. The default is set to on.
105 NISIP <IP address>
107 Specifies the IP address of the network interface on which
109 apcupsd will listen for incoming connections. The default value
110 is 0.0.0.0 which means the NIS will listen for connections on
111 all network interfaces. If the computer has more than one inter‐
112 face, you can specify the IP of a single interface to limit con‐
113 nections to that interface. Specifying the loopback address
114 (127.0.0.1) will cause the NIS daemon to accept connections only
115 from the local computer.
116 NISPORT <port>
118 Specifies the port to be used by the NIS daemon. The default is
120 3551 which has been received from IANA as the official apcupsd
121 networking port. It must be changed when running more than one
122 copy of apcupsd on the same computer to control multiple UPSes.
123 EVENTSFILE <filename>
125 If you want NIS to provide the last 10 events via the network,
127 you must specify a file where apcupsd will save these events.
128 The default is: /var/log/apcupsd.events. apcupsd will save at
129 most the last 50 events to this file. When more than 50 events
130 are saved and a network request for the events arrives, apcupsd
131 will truncate the file to the most recent 10 events. It must be
132 changed when running more than one copy of apcupsd on the same
133 computer to control multiple UPSes.
134 LOGGING CONFIGURATION DIRECTIVES
136 STATTIME <seconds>
137 Specifies the time interval between writes to the status file.
139 If set to zero, the status file will not be written. The status
140 file will disappear in a future apcupsd version as its func‐
141 tionality has been replaced by the Network Information Server
142 and the apcaccess(8) program.
143 STATFILE <file>
145 Specifies the file to be used when writing the status informa‐
147 tion. The default is /etc/apcupsd/apcupsd.status. It must be
148 changed when running more than one copy of apcupsd on the same
149 computer to control multiple UPSes.
150 LOGSTATS [ on | off ]
152 Activate log file. This generates a lot of output, so if you
154 turn this on, be sure that the file defined in syslog.conf(5)
155 for LOG_NOTICE is a named pipe.
156 DATATIME <seconds>
158 Specifies the time interval between writes of the APC PowerChute
160 software-like data information to the log file.
161 FACILITY <log-facility>
163 Change the system logging (syslog) facility. The default is dae‐
165 mon. This parameter can be useful if you wish to direct the
166 apcupsd system logging information to other than your system
167 default files. See syslog.conf(5) for details of other possible
168 facilities and general system logging configuration.
169 POWER FAILURE CONFIGURATION DIRECTIVES
171 ONBATTERYDELAY <seconds>
172 The number of seconds from when a power failure is detected
174 until apcupsd reacts with an onbattery event.
175 BATTERYLEVEL <percentage>
177 apcupsd will shutdown the system during a power failure when the
179 remaining battery charge falls below the specified percentage.
180 The default is 5.
181 MINUTES <minutes>
183 apcupsd will shutdown the system during a power failure when the
185 remaining runtime on batteries as internally calculated by the
186 UPS falls below the specified minutes. The default is 3.
187 TIMEOUT <seconds>
189 After a power failure occurs, apcupsd will shutdown the system
191 after the specified number of seconds have expired. For a
192 Smart-UPS, this should normally be set to zero so that the shut‐
193 down time will be determined by the battery level or remaining
194 runtime (see above). This command is, however, useful for a
195 Back-UPS or other simple signalling UPS which does not report
196 battery level or the remaining runtime. It is also useful for
197 testing apcupsd because you can force a rapid shutdown by set‐
198 ting a small value (eg 60) and turning off the power to the UPS.
199 TIMEOUT, BATTERYLEVEL, and MINUTES can all be set without prob‐
201 lems. apcupsd will initiate a shutdown when the first of these
202 conditions becomes valid.
203 ANNOY <seconds>
205 Specifies the time in seconds between broadcast messages
207 requesting logged in users to log off from the system. This
208 timer starts only when the UPS is running on battery. The
209 default is 300 seconds (5 minutes).
210 ANNOYDELAY <seconds>
212 Specifies the delay time in seconds before broadcast messages
214 requesting logged in users to log off from the system. This
215 timer starts only after the UPS is running on battery power.
216 This timer is reset when the power returns. The default is 60
217 seconds (ie the first request to log off occurs after 60 seconds
218 on battery power).
219 NOLOGON [ disable | timeout | percent | minutes | always ]
221 Specifies when apcupsd should create the nologon file to prevent
223 users from logging on to the system.
224 "disable" prevents apcupsd from creating the nologin file.
226 "timeout" specifies a specific wait time before apcupsd creates
228 the nologin file.
229 "percent" specifies the percentage of battery charge remaining
231 before apcupsd creates the nologin file.
232 "minutes" specifies the battery runtime remaining before apcupsd
234 creates the nologin file.
235 "always" specifies that apcupsd should create the nologin file
237 immediately after a power failure occurs.
238 This directive is important for allowing systems with BIG UPSes
240 to run normally until the system administrator determines the
241 need for dumping users. It also allows the system administrator
242 to hold the "ANNOY" factor until the /etc/nologin file is cre‐
243 ated.
244 KILLDELAY <seconds>
246 Specifies the number of seconds for which apcupsd will continue
248 running after a shutdown has been requested. After the specified
249 time, apcupsd will attempt to put the UPS into hibernate mode
250 and kill the power to the computer. This is for use on operating
251 systems where apcupsd cannot regain control after a shutdown (eg
252 FreeBSD) to issue an apcupsd --killpower command. Setting the
253 delay to 0 disables it.
254 SHARE-UPS CONFIGURATION DIRECTIVES
256 UPSCLASS [ standalone | shareslave | sharemaster ]
257 The default is "standalone" and should be used for all computers
259 powered by the UPS, with a direct connection to the UPS and
260 where there are no other computers dependent on power from the
261 UPS. This is the "normal" case.
262 Use "shareslave" if you are using a Share-UPS interface expander
264 and connected to the BASIC port (simple signalling).
265 Use "sharemaster", if you are using a Share-UPS interface
267 expander and connected to the ADVANCED port (smart signalling).
268 UPSMODE [ disable | share ]
270 Set to "disable" for normal standalone operation to indicate
272 that you are disabling the Share-UPS interface expander support.
273 Set to "share" for two to seven additional simple signalling
275 ports on a Share-UPS interface expander. This code may not be
276 fully tested in every new release.
277 APCTEST EEPROM CONFIGURATION DIRECTIVES
279 These directives have no effect on the operation of apcupsd(8) but are
280 reserved for use by apctest(8) when bulk programming the values of the
281 UPS EEPROM configuration variables in a Smart-UPS model.
282 UPSNAME <string>
284 Name of UPS. Maximum of 8 characters.
286 BATTDATE [ mm/dd/yy | dd/mm/yy ]
288 Last battery replacement date. Maximum of 8 characters.
290 SENSITIVITY [ H | M | L ]
292 H : High (most sensitive setting)
294 M : Medium
295 L : Low (least sensitive setting)
296 WAKEUP [ 000 | 060 | 180 | 300 ]
298 The time delay in seconds that the UPS waits after the return of
300 utility power before "waking up" and restoring power to the con‐
301 nected equipment.
302 SLEEP [ 020 | 180 | 300 | 600 ]
304 The time delay in seconds for which the UPS waits or "sleeps"
306 after it receives a request to power off the connected system.
307 LOTRANSFER <voltage>
309 Low line voltage causing transfer to battery power or activation
311 of SmartBoost. Allowable values depend on the last letter of
312 the firmware or APCMODEL. Typical values are:
313 D 106 103 100 097
315 M 177 172 168 182
316 A 092 090 088 086
317 I 208 204 200 196
318 where D = domestic (USA), M = Canada, A = Asia and I = Interna‐
320 tional.
321 HITRANSFER <voltage>
323 High line voltage causing transfer to battery power or activa‐
325 tion of SmartTrim. Allowable values depend on the last letter
326 of the firmware or APCMODEL. Typical values are:
327 D 127 130 133 136
329 M 229 234 239 224
330 A 108 110 112 114
331 I 253 257 261 265
332 where D = domestic (USA), M = Canada, A = Asia and I = Interna‐
334 tional.
335 RETURNCHARGE [ 00 | 15 | 50 | 90 ]
337 Percentage of battery charge needed for the UPS to restore power
339 to the connected equipment.
340 BEEPSTATE [ 0 | T | L | N ]
342 Alarm delay.
344 0 : Zero delay after power fails.
346 T : When power fails plus 30 seconds.
347 L : When low battery occurs.
348 N : Never.
349 LOWBATT <minutes>
351 Low battery warning occurs when the specified number of minutes
353 remains before the UPS estimates battery power will be
354 exhausted. There are four user-changeable settings: 2, 5, 7, or
355 10 minutes
356 OUTPUTVOLTS <voltage>
358 UPS nominal output voltage when running on battery. Allowable
360 values depend on the last letter of the firmware or APCMODEL.
361 Typical values are:
362 D 115
364 M 208
365 A 100
366 I 230 240 220 225
367 where D = domestic (USA), M = Canada, A = Asia and I = Interna‐
369 tional.
370 SELFTEST [ 336 | 168 | ON | OFF ]
372 Self test interval in hours (336 = 2 weeks, 168 = 1 week, ON =
374 at power on, OFF = never).
375
377 Note that in the following examples, the device names assume that you are
378 using Linux. Device names for serial devices in *BSD and other operating
379 systems will be different.
380 Minimal USB Configuration for a USB UPS
382 UPSCABLE usb
383 UPSTYPE usb
384 DEVICE
385 LOCKFILE /var/lock
386 UPSCLASS standalone
387 UPSMODE disable
388 Notice no device name is specified. apcupsd(8) will try all the well
390 known USB ports. Only specify a specific USB device name if you know what
391 you are doing. For detailed information on setting up a USB UPS, refer to
392 the "USB Configuration" section of the apcupsd manual.
393 Minimal Serial Configuration for a Smart UPS
395 UPSCABLE smart
396 UPSTYPE apcsmart
397 DEVICE /dev/ttyS0
398 LOCKFILE /var/lock
399 UPSCLASS standalone
400 UPSMODE disable
401 Normally there would be more configuration directives to completely cus‐
403 tomise your installation, but this example shows the minimum required.
404 Minimal Serial Configuration for a Dumb UPS
406 UPSCABLE <number of the cable used>
407 UPSTYPE dumb
408 DEVICE /dev/ttyS0
409 LOCKFILE /var/lock
410 UPSCLASS standalone
411 UPSMODE disable
412 If your cable does not have low battery detection (eg such cables include
414 the APC 940-0020B and 940-0023A), you will also need to define the TIME‐
415 OUT <seconds> configuration directive to set the number of seconds on
416 battery during a power failure after which apcupsd will do a system shut‐
417 down.
418 Normally there would be more configuration directives to completely cus‐
420 tomise your installation, but this example shows the minimum required.
421
423 /etc/apcupsd/apcupsd.conf default configuration file
424
426 syslog.conf(5), apcupsd(8), apctest(8).
427 The HTML apcupsd manual installed on your system or available online at
429 http://www.apcupsd.org/
430
432 Trevor Roydhouse (current)
433 Andre M. Hedrick
434 Christopher J. Reimer
435apcupsd.conf v3.14.6 January 10, 2009 apcupsd.conf v3.14.6