1APCUPSD.CONF(5)             BSD File Formats Manual            APCUPSD.CONF(5)
2

NAME

4     apcupsd.conf apcupsd(8) configuration file
5

DESCRIPTION

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
14     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
18     Note that the apcupsd daemon must be restarted in order for changes to
19     the configuration file to become active.
20
21     The configuration file directives are explained in the subsections below.
22
23   GENERAL CONFIGURATION DIRECTIVES
24     UPSNAME <string>
25
26              Specify a name for the UPS for log files, status reports etc.
27
28     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
33              The type of cable used to connect the UPS to the computer.
34
35     UPSTYPE [ dumb | apcsmart | net | usb | snmp | pcnet | modbus |test ]
36
37              The type of APC UPS that you have.
38
39     DEVICE <name>
40
41              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
46              ·   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
55              If you have problems, please see the apcupsd manual for more
56              detailed information and comprehensive troubleshooting advice.
57
58     POLLTIME <seconds>
59
60              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
68     LOCKFILE <path>
69
70              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
75     SCRIPTDIR <path>
76
77              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
82     PWRFAILDIR <path>
83
84              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
91     NOLOGINDIR <path>
92
93              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
98   NIS CONFIGURATION DIRECTIVES
99     NETSERVER [ on | off ]
100
101              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
106     NISIP <IP address>
107
108              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
117     NISPORT <port>
118
119              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
124     EVENTSFILE <filename>
125
126              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
135   LOGGING CONFIGURATION DIRECTIVES
136     STATTIME <seconds>
137
138              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
144     STATFILE <file>
145
146              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
151     LOGSTATS [ on | off ]
152
153              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
157     DATATIME <seconds>
158
159              Specifies the time interval between writes of the APC PowerChute
160              software-like data information to the log file.
161
162     FACILITY <log-facility>
163
164              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
170   POWER FAILURE CONFIGURATION DIRECTIVES
171     ONBATTERYDELAY <seconds>
172
173              The number of seconds from when a power failure is detected
174              until apcupsd reacts with an onbattery event.
175
176     BATTERYLEVEL <percentage>
177
178              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
182     MINUTES <minutes>
183
184              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
188     TIMEOUT <seconds>
189
190              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
200              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
204     ANNOY <seconds>
205
206              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
211     ANNOYDELAY <seconds>
212
213              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
220     NOLOGON [ disable | timeout | percent | minutes | always ]
221
222              Specifies when apcupsd should create the nologon file to prevent
223              users from logging on to the system.
224
225              "disable" prevents apcupsd from creating the nologin file.
226
227              "timeout" specifies a specific wait time before apcupsd creates
228              the nologin file.
229
230              "percent" specifies the percentage of battery charge remaining
231              before apcupsd creates the nologin file.
232
233              "minutes" specifies the battery runtime remaining before apcupsd
234              creates the nologin file.
235
236              "always" specifies that apcupsd should create the nologin file
237              immediately after a power failure occurs.
238
239              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
245     KILLDELAY <seconds>
246
247              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
255   SHARE-UPS CONFIGURATION DIRECTIVES
256     UPSCLASS [ standalone | shareslave | sharemaster ]
257
258              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
263              Use "shareslave" if you are using a Share-UPS interface expander
264              and connected to the BASIC port (simple signalling).
265
266              Use "sharemaster", if you are using a Share-UPS interface
267              expander and connected to the ADVANCED port (smart signalling).
268
269     UPSMODE [ disable | share ]
270
271              Set to "disable" for normal standalone operation to indicate
272              that you are disabling the Share-UPS interface expander support.
273
274              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
278   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
283     UPSNAME <string>
284
285              Name of UPS. Maximum of 8 characters.
286
287     BATTDATE [ mm/dd/yy | dd/mm/yy ]
288
289              Last battery replacement date. Maximum of 8 characters.
290
291     SENSITIVITY [ H | M | L ]
292
293              H : High (most sensitive setting)
294              M : Medium
295              L : Low (least sensitive setting)
296
297     WAKEUP [ 000 | 060 | 180 | 300 ]
298
299              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
303     SLEEP [ 020 | 180 | 300 | 600 ]
304
305              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
308     LOTRANSFER <voltage>
309
310              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
314                D  106  103  100  097
315                M  177  172  168  182
316                A  092  090  088  086
317                I  208  204  200  196
318
319              where D = domestic (USA), M = Canada, A = Asia and I = Interna‐
320              tional.
321
322     HITRANSFER <voltage>
323
324              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
328                D  127  130  133  136
329                M  229  234  239  224
330                A  108  110  112  114
331                I  253  257  261  265
332
333              where D = domestic (USA), M = Canada, A = Asia and I = Interna‐
334              tional.
335
336     RETURNCHARGE [ 00 | 15 | 50 | 90 ]
337
338              Percentage of battery charge needed for the UPS to restore power
339              to the connected equipment.
340
341     BEEPSTATE [ 0 | T | L | N ]
342
343              Alarm delay.
344
345              0 : Zero delay after power fails.
346              T : When power fails plus 30 seconds.
347              L : When low battery occurs.
348              N : Never.
349
350     LOWBATT <minutes>
351
352              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
357     OUTPUTVOLTS <voltage>
358
359              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
363                D  115
364                M  208
365                A  100
366                I  230  240  220  225
367
368              where D = domestic (USA), M = Canada, A = Asia and I = Interna‐
369              tional.
370
371     SELFTEST [ 336 | 168 | ON | OFF ]
372
373              Self test interval in hours (336 = 2 weeks, 168 = 1 week, ON =
374              at power on, OFF = never).
375

EXAMPLES

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
381   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
389     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
394   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
402     Normally there would be more configuration directives to completely cus‐
403     tomise your installation, but this example shows the minimum required.
404
405   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
413     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
419     Normally there would be more configuration directives to completely cus‐
420     tomise your installation, but this example shows the minimum required.
421

FILES

423     /etc/apcupsd/apcupsd.conf default configuration file
424

SEE ALSO

426     syslog.conf(5), apcupsd(8), apctest(8).
427
428     The HTML apcupsd manual installed on your system or available online at
429     http://www.apcupsd.org/
430

AUTHORS

432     Trevor Roydhouse (current)
433     Andre M. Hedrick
434     Christopher J. Reimer
435
436apcupsd.conf v3.14.6           January 10, 2009           apcupsd.conf v3.14.6
Impressum