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