1apcupsd(8) System Manager's Manual apcupsd(8)
2
6 apcupsd - daemon for most APC's UPS for Linux
7
9 /sbin/apcupsd
10 /etc/apcupsd/apccontrol
11 /etc/apcupsd/apcupsd.conf
12 /sbin/apcaccess
13 /sbin/apcnetd
14
16 This document is considerably out of date. It can be used for a brief
17 overview of apcupsd, but you should consult the html manual for current
18 information. Normally this manual will be loaded on your system in the
19 doc directory, which varies from system to system. Otherwise, you may
20 find an online version at: http://www.apcupsd.com
21 This daemon can be used for controlling the most APC UPSes. During a
24 power failure, "apcupsd" will inform the users about the power failure
25 and that a shutdown may occur. If power is not restored, a system
26 shutdown will follow when the battery is exausted, a timeout (seconds)
27 expires, or runtime expires based on internal UPS calculations deter‐
28 mined by power consumption rates. If the power is restored before one
29 of the above shutdown conditions is met, apcupsd will inform users
30 about this fact.
31 The shutdown is made by script calls to "/etc/apcupsd/apccontrol",
33 which is called by "apcupsd". Consequently, no changes to /etc/inittab
34 are necessary. There is no communication between apcupsd and init(1)
35 process. Apcupsd modifies the halt script so that at the end of the
36 shutdown process, apcupsd will be re-executed in order to power off the
37 UPS. On certain platforms (e.g. FreeBSD) there is no halt script so
38 apccontrol must be modified to cause apcupsd to power off the UPS after
39 a delay time.
40 The apcupsd daemon now supports two networking modes that function
43 independently, but if desired they can both run at the same time.
44 Most users will probably enable the first network mode and simplest
46 (NIS or Network Information Service), which permits apcupsd to serve
47 status and event information to clients over the network.
48 The second networking mode is for multiple networked machines that are
50 powered by the same UPS. In this mode, one machine is configured as a
51 master with the UPS attached to the serial port. The other machines
52 (max. 20) powered by the same UPS are configured as slaves. The mas‐
53 ter has a network connection with the slaves and sends them information
54 about the UPS status. This mode is significantly more complicated to
55 setup than the NIS networking mode described above.
56 For details and configurations on these networking modes please see the
58 manual.
59 RedHat and SuSE versions of Linux have direct install support. All
62 other flavors of Linux may need some fussing with to get the install
63 correct.
64
66 -c --configure
67 Attempts to configure the UPS EPROM to the values specified in
68 the configuration file "/etc/apcupsd/apcupsd.conf". This option
69 is now deprecated (not supported) and should not be used.
70 Instead use the apctest program, which has an interactive EEPROM
71 configuration.
72 -d --debug <level>
74 Turns on debugging output.
75 -f --config-file <file>
77 Specifies the location of the configuration file. The default
78 is: /etc/apcupsd/apcupsd.conf
79 -k --killpower
81 Attempt to turn the UPS off. This option is normally only used
82 by the daemon itself to shut the UPS off after a system shutdown
83 has completed.
84 -V --version
86 Prints the apcupsd version number and the help.
87 -? --help
89 Prints a brief apcupsd help screen.
90
93 It may be necessary to change the configuration information in the file
94 "/etc/apcupsd/apcupsd.conf" to meet your needs and to correspond to
95 your configuration. This file is a plain ASCII file and you can use
96 your favorite editor to change it.
97 Configuration commands in /etc/apcupsd/apcupsd.conf are:
99 GENERAL CONFIGURATION COMMANDS
102 UPSCABLE -- <type of cable you are using>
103 [ simple | 940-0020B | 940-0023A (broken) ]
104 [ smart | 940-0024B | 940-0024C ]
105 [ 940-0095A | 940-0095C ]
106 [ ether ]
107 [ usb ]
108 UPSTYPE -- <Type of APCC UPS you have>
110 [ dumb | apcsmart | net | usb | snmp | test ]
111 DEVICE -- <name of serial port>
113 Please specify which device is used for UPS communication. The default
114 is /dev/ttyS[0|1|2|3]. If you have a USB UPS, you should leve the
115 DEVICE directive blank and apcupsd will figure out where your device is
116 located. If you have problems, please see the manual as it has more
117 details.
118 LOCKFILE -- <path to lockfile>
120 By supplying this argument, "apcupsd" tries to create a lockfile for
121 the serial or USB port in the specified directory.
122 CONFIGURATION COMMANDS USED BY THE NETWORK INFORMATION SERVER
125 NETSTATUS [on | off]
126 This configuration command turns the network information server on or
127 off. If it is on, apcupsd will spawn a child process that serves STATUS
128 and EVENTS information over the network. This information is currently
129 used by the Web based CGI programs. The default is on. In some cases,
130 for added security, you may want to invoke a separate information
131 server daemon from the inetd daemon. In this case, NETSTATUS should be
132 off.
133 STATUSPORT <port>
136 This configuration command specifies the port to be used by the apcupsd
137 server. The default is 3551.
138 EVENTFILE <filename>
141 If you want the apcupsd network information server to provide the last
142 10 events via the network, you must specify a file where apcupsd will
143 save these events. The default is: /var/log/apcupsd.events. Currently,
144 apcupsd will save at most the last 50 events. When more than 50 events
145 are recorded and a network request for the events arrives, the network
146 server will truncate the file to the most recent 10 events. Conse‐
147 quently this file will not grow indefinitely as long as the events are
148 checked from time to time.
149 CONFIGURATION COMMANDS USED TO CONTROL SYSTEM LOGGING
153 STATTIME
154 STATFILE
157 DATATIME
160 FACILITY
163 CONFIGUATION COMMANDS USED DURING POWER FAILURES
168 ANNOY -- <time in seconds>
170 Please specify the time in seconds between messages requesting logged
171 in users to get off the system. This timer starts only when the UPS is
172 running on batteries. The default is 300 seconds (5 minutes).
173 ANNOYDELAY -- <time in seconds>
175 Please specify delay time in seconds before apcupsd begins requesting
176 logged in users to get off the system. This timer starts only after the
177 UPS is running on batteries. This timer is reset when the power
178 returns. The default is 60 seconds. That is the first warning to log
179 off the system occurs after 60 seconds on batteries.
180 NOLOGON -- <specifies when apcupsd should create the nologon file>
184 [ disable | timeout | percent | minutes | always ] are valid types.
185 Based on Ten (10) percent of a setting. This allows one to define the
187 point when the /etc/nologin file is added. This is important for
188 allowing systems with BIG UPSes to run as normally until the system
189 administrator determines the need for dumping users. The feature also
190 allows the system administrator to hold the "ANNOY" factor until the
191 /etc/nologin file is added.
192 disable prevents apcupsd from creating the nologin file.
194 timeout specifies a specific wait time before creating the nologin
196 file.
197 percent specifies the percent battery charge remaining before creating
199 the nologin file.
200 minutes specifies the battery runtime remaining before creating the
202 nologin file.
203 always causes the nologin file to be immediately created on a power
205 failure.
206 BATTERYLEVEL -- <percent of battery>
208 If BATTERYLEVEL is specified, during a power failure, apcupsd will
209 shutdown the system when the remaining battery charge falls below the
210 specified percentage. The default is 5.
211 MINUTES -- <battery runtime in minutes>
213 If MINUTES is specified, during a power failure, apcupsd will shutdown
214 the system when the remaining remaining runtime on batteries as inter‐
215 nally calculated by the UPS falls below the time specified. The default
216 is 3.
217 TIMEOUT -- <time in seconds>
220 After a power failure, the system will be shutdown after TIMEOUT sec‐
221 onds have expired. Normally for SMARTUPSes, this should be zero so
222 that the shutdown time will be determined by the battery level or
223 remaining runtime (see above). This command is useful for dumb UPSes
224 that do not report battery level or the remaining runtime. It is also
225 useful for testing apcupsd in that you can force a rapid shutdown by
226 setting a small value (e.g. 60) and pulling the plug to the UPS.
227 The timeout for the master is always 30 seconds longer than slaves.
229 TIMEOUT, BATTERYLEVEL, and MINUTES can be set together without prob‐
231 lems. The daemon will react to the first case or test that is valid.
232 Normally SmartUPS users will set TIMEOUT to zero so that the system is
233 shutdown depending on the percentage battery charge remaining (BAT‐
234 TERYLEVEL) or the remaining battery runtime (MINUTES).
235 CONFIGURATION COMMANDS FOR SHARING A UPS
239 UPSCLASS -- <class of operation>
240 [ standalone | shareslave | sharemaster ] and
241 [ netslave | netmaster ] are valid types.
242 [ standalone | netslave | netmaster ] are tested classes.
243 [ shareslave | sharemaster ] classes are being tested.
244 The default is "standalone" and should be used for all machines powered
246 by the UPS and having a serial port connection to the UPS, but where
247 there are no other computers dependent power from the same UPS. This
248 is the "normal" case.
249 Use "netmaster", if and only if you have a serial port connection to
251 the UPS and there are other machines deriving power from the same UPS.
252 Use "netslave" if and only if you have no serial port connection to the
254 UPS, but you derive power from it.
255 Use "shareslave" if and only if you are using a ShareUPS and connected
257 to a BASIC Port with Simple Signal.
258 Use "sharemaster", if and only if you are using a ShareUPS and con‐
260 nected to the ADVANCED Port Smart Signal control.
261 UPSMODE -- [ disable | share | net | sharenet ] are valid types.
264 [ disable | net ] are the only known and tested classes.
266 [ share | sharenet ] classes are being tested.
267 BETA [ share ] For two or seven (2/7) additional simple signal ports on
269 a SmartAccessories(tm) (internal/external box) for SmartUPSes.
270 NETTIME -- <time in seconds>
272 The rate in seconds that broadcasts information to Slave machines.
273 This rate is reset if there is a power state change. This value is now
274 passed to the slaves to sync. the openning of a socket by the slave for
275 the master.
276 NETPORT -- <TCP|UDP port number>
278 This unix service port number must be set in the /etc/services file as
279 follows:
280 tab tab(spacejunk) tab tab
281 name (stuff)/xxp #
282 apcupsd NETPORT/tcp #
283 apcupsd NETPORT/udp #
284 MASTER -- <name of master> for Slave machine.
286 The name of the master which is authorized to send commands to this
287 slave.
288 SLAVE -- <name of slave(s)> for Master machine.
290 The name of the slave machine attached to the master. There can be
291 max. 20 slaves attached to one master.
292 USERMAGIC -- < user defined password> for the slave machine.
294 The second level of password security. It must be (17) characters long
295 without spaces. This is passed to the master machine during initializa‐
296 tion of sockets. This string should be different for each and every
297 slave on the network. This is not at all secure as passwords are passed
298 in the clear. Please protect your network by firewalling or tcpwrap‐
299 pers.
300
303 If you start getting the follow message:
304 Emergency -- Batteries Have Failed!
306 Change Them NOW!
307 Act upon it quickly. It means what it says.
309 Also, not all "SmartUPS" models are eqaully smart. A non-NET or old
311 class of "SmartUPS" has a subset of the full UPSlink(TM) language, and
312 can not be polled for its control codes.
313
315 Special note for ShareUPS users, TIMEOUT, BATTERYLEVEL, and MINUTES are
316 disabled or set to default values. Currently, there is not a known way
317 for early signals to be sent to BASIC Ports. MINUTES are set to 0.
318
320 /etc/apcupsd/apcupsd.conf - configuration file.
321 /var/log/apcupsd.status - STATUS file
322 /var/log/apcupsd.events - where up to the last 50 events are stored for
323 the network information server.
324
326 apcupsd generates events when certain conditions occur such as a power
327 failure, batteries exhausted, power return,
328 These events are sent to the system log, optionally sent to the tempo‐
330 rary events file (/var/log/apcupsd.events), and they also generate a
331 call to /etc/apcupsd/apccontrol which in turn will call any scripts you
332 have placed in the /etc/apcupsd directory.
333
336 If the DATATIME configuration command is set nonzero, apcupsd will log
337 a data record at the interval defined on the DATATIME command. This
338 data record is in a format similar to the PowerChute data file format.
339
342 The STATUS output is in ASCII format and generally there is a single
343 piece of information on each line output. The format varies based on
344 the type of UPS that you are using.
345 DATE : time and date of last update
347 CABLE : cable type used
348 UPSMODEL : ups type or signal method
349 UPSMODE : tells apcupsd what to check
350 SHARE : if ShareUPS is used, this determines what
351 SmartUPS and MatrixUPS Smart Signals
353 ULINE : Current (observed) Input Line Voltage
354 MLINE : Max (observed) Input Line Voltage
355 NLINE : Min (observed) Input Line Voltage
356 FLINE : Line Freq (cycles)
357 VOUTP : UPS Output Voltage
358 LOUTP : Percent Load of UPS Capacity
359 BOUTP : Current Charge Voltage of Batteries
360 BCHAR : Batteries Current Charge Percent of Capacity
361 BFAIL : UNSIGNED INT CODE (ups state)
362 UTEMP : Current UPS Temp. in Degrees Cel.
363 DIPSW : Current DIP switch settings for UPS.
364 Newer BackUPS Pro Smart Signals
366 ULINE : Current (observed) Input Line Voltage
367 MLINE : Max (observed) Input Line Voltage
368 NLINE : Min (observed) Input Line Voltage
369 FLINE : Line Freq (cycles)
370 VOUTP : UPS Output Voltage
371 LOUTP : Percent Load of UPS Capacity
372 BOUTP : Current Charge Voltage of Batteries
373 BCHAR : Batteries Current Charge Percent of Capacity
374 BFAIL : UNSIGNED INT CODE (ups state)
375 BackUPS Pro and SmartUPS v/s Smart Signals
377 LINEFAIL : OnlineStatus
378 BATTSTAT : BatteryStatus
379 MAINS : LineVoltageState
380 LASTEVNT : LastEventObserved
381 BackUPS and NetUPS Simple Signals
383 LINEFAIL : OnlineStatus
384 BATTSTAT : BatteryStatus
385 BackUPS Pro and SmartUPS v/s Smart Signals
387 OnlineStatus BatteryStatus LineVoltageState LastEventObserved
388 BackUPS and NetUPS Simple Signals
390 OnlineStatus BatteryStatus
391
394 The html manual installed on your system or http://www.apcupsd.com
395
398 Andre M. Hedrick
399 Retired Co-AUTHOR
401 Christopher J. Reimer
402 Current maintainers
404 Kern Sibbald Adam Kropelin
405 Contributors
407 An enormous list of past and former persons who have devoted their time
408 and energy to this project -- thanks.
409 APC UPS management under Linux -- November 1999 apcupsd(8)