1.. title:: APCCTRL User Manual 2 3.. image:: ./apcctrl.png 4 5=================== 6APCCTRL User Manual 7=================== 8 9| **Adam Kropelin** 10| **Kern Sibbald** 11 12**apcctrl is a UPS control system that permits orderly shutdown of your 13computer in the event of a power failure.** 14 15| |date| |time| 16| This manual documents apcctrl version 3.14.x 17| Copyright |(C)| 2004-2015 Adam Kropelin 18| Copyright |(C)| 1999-2005 Kern Sibbald 19 20*Copying and distribution of this file, with or without modification, 21are permitted in any medium without royalty provided the name apcctrl, 22the copyright notice, and this notice are preserved.* 23 24*apcctrl source code is released under the GNU General Public License 25version 2. Please see the file COPYING in the main source directory.* 26 27For more information on the project, please visit the main web site 28at http://www.apcctrl.com 29 30--------------------------------------------------------------------------- 31 32.. contents:: Table of Contents 33 :local: 34 :depth: 3 35 36--------------------------------------------------------------------------- 37 38Important Legal Disclaimer 39========================== 40 41No person should rely on the contents of the APCCTRL Manual ("the manual") 42without first obtaining advice from APC Technical Support. 43 44The manual is provided on the terms and understanding that: 45 46 1. the authors, contributors and editors are not responsible for the 47 results of any actions taken on the basis of information in the manual, 48 nor for any error in or omission from the manual; and 49 2. the authors, contributors and editors are not engaged in rendering 50 technical or other advice or services. 51 52The the authors, contributors and editors, expressly disclaim all and any 53liability and responsibility to any person, whether a reader of the manual 54or not, in respect of anything, and of the consequences of anything, done or 55omitted to be done by any such person in reliance, whether wholly or partially, 56on the whole or any part of the contents of the manual. Without limiting the 57generality of the above, no author, contributor or editor shall have any 58responsibility for any act or omission of any other author, contributor or 59editor. 60 61 62How To Use This Manual 63====================== 64 65This is the manual for apcctrl, a 66daemon for communicating with UPSes (Uninterruptible Power 67Supplies) made by American Power Conversion Corporation (APC). If you have an 68APC-made UPS, whether sold under the APC nameplate or OEMed (for example, the HP 69PowerTrust 2997A), and you want you get it working with a computer running 70Linux, Unix, or Windows, you are reading the right document. 71 72This manual is divided into parts which increase in technical depth 73as they go. If you have just bought a state-of-the-art smart UPS 74with a USB or Ethernet interface, and you are running a current 75version of Red Hat or SUSE Linux, then apcctrl is 76very nearly plug-and-play and you will have to read only the `Basic 77User's Guide`_. 78 79If your operating system is older, or if you have an old-fashioned 80serial-line UPS, you'll have to read about serial installation (see 81`Installation: Serial-Line UPSes`_). If you need more 82details about administration for unusual situations (such as a 83master/slave or multi-UPS setup) you'll need to read the sections on 84those topics as well. Finally, 85there are a number of technical reference sections which 86gives full details on things like configuration file directives and 87event-logging formats. 88 89You should begin by reading the Quick Start (see `Quick Start for 90Beginners`_) instructions. 91 92Basic User's Guide 93================== 94 95Quick Start for Beginners 96------------------------- 97 98apcctrl is a complex piece of software, but 99most of its complexities are meant for dealing with older hardware 100and operating systems. On current hardware and software getting it 101running should not be very complicated. 102 103The following is a help guide to the steps needed to get apcctrl 104set up and running as painlessly as possible. 105 106#. Check to see if apcctrl supports your UPS and cable (see 107 `Supported UPSes and Cables`_). 108 109#. Check to see if apcctrl supports your operating system (see 110 `Supported Operating Systems`_). 111 112#. Plan your configuration type (see `Choosing a Configuration 113 Type`_). If you have just one UPS and 114 one computer, this is easy. If you have more than one machine being 115 served by the same UPS, or more than one UPS supplying power to 116 computers that are on the same local network, you have more choices 117 to make. 118 119#. Figure out if you have one of the easy setups. If you have a USB 120 UPS, and a supported operating system and you want to use one UPS 121 with one computer, that's an easy setup. APC supplies the cable 122 needed to talk with that UPS along with the UPS. All you need to do 123 is check that your USB subsystem is working (see `USB 124 Configuration`_); if so, you can go to the build 125 and install step. 126 127#. If you have a UPS designed to communicate via SNMP over 128 Ethernet, that is also a relatively easy installation. Details 129 are provided in `Support for SNMP UPSes`_. 130 131#. If you have a UPS that communicates via an RS232C serial 132 interface and it is a SmartUPS, then things are relatively simple, 133 otherwise, your life is about to get interesting. 134 135 #. If you have a vendor-supplied cable, find out what cable type 136 you have by looking on the flat ends of the cable for a number, 137 such as 940-0020A, stamped in the plastic. 138 139 #. If you don't have a vendor-supplied cable, or your type is not 140 supported, you may have to build one yourself (see 141 `Cables`_). Here is hoping you are good with a soldering 142 iron! 143 144#. Now you are ready to read the Building and Installing (see 145 `Building and Installing apcctrl`_) 146 section of the manual and follow those directions. If you are 147 installing from an RPM or some other form of binary package, this 148 step will probably consist of executing a single command. 149 150#. Tweak your /etc/apcctrl/apcctrl.conf file as necessary. Often it 151 will not be. 152 153#. Change the BIOS settings (see `Arranging for Reboot on 154 Power-Up`_) on your computer 155 so that boots up every time it gets power. (This is not the default 156 on most systems.) 157 158#. To verify that your UPS is communicating with your computer and 159 will do the right thing when the power goes out, read and follow 160 the instructions in the Testing (see `Testing 161 apcctrl`_) section. 162 163#. If you run into problems, check the apcctrl users' email list 164 archive for similar problems. This is an excellent resource with 165 answers to all sorts of questions. See 166 http://sourceforge.net/mailarchive/forum.php?forum_name=apcctrl-users. 167 168#. If you still need help, send a message to the apcctrl users' email 169 list (apcctrl-users@lists.sourceforge.net) describing your 170 problem, what version of 171 apcctrl you are using, what operating system you are using, and 172 anything else you think might be helpful. 173 174#. Read the manual section on `Monitoring and Tuning your UPS`_. 175 176Supported Operating Systems 177--------------------------- 178 179apcctrl supports many UNIX-like operating systems as well as several 180variants of Windows. Due to lack of API standardization, USB support is not 181available on every platform. See `Platform Support`_ below for details. 182 183In general it is recommended to obtain a prebuilt package for your platform. 184Given how apcctrl must integrate into the shutdown mechanism of the 185operating system and the rate at which such mechanisms are changed by 186vendors, the platform ports in the apcctrl tree may become out of date. In 187some cases, binary packages are provided by the apcctrl team (RedHat, 188Mandriva, SuSE, Windows, Mac OS X). For other platforms it is recommended to 189check your vendor's package repository and third party repositories for 190recent binary packages. Note that some vendors continue to distribute 191ancient versions of apcctrl with known defects. These packages should *not* be 192used. 193 194Platform Support 195~~~~~~~~~~~~~~~~ 196 197**LINUX** 198 199- RedHat [1]_ [2]_ 200- SuSE [2]_ 201- Mandriva/Mandrake [2]_ 202- Debian [3]_ 203- Slackware [3]_ 204- Engarde [3]_ 205- Yellowdog [3]_ 206- Gentoo [3]_ 207 208**WINDOWS** 209 210- Windows NT 4 [2]_ [4]_ 211- Windows 98/ME/2000 [2]_ [4]_ 212- Windows XP/Vista (including 64 bit) [1]_ [2]_ 213- Windows Server 2003/2008 (including 64 bit) [2]_ 214- Windows 7 [2]_ 215 216**OTHERS** 217 218- Mac OS X Darwin [1]_ [2]_ 219- Solaris 8/9 [4]_ 220- Solaris 10 221- NetBSD 222- FreeBSD 223- OpenBSD 224- HPUX [3]_ [4]_ 225- Unifix [3]_ [4]_ 226- QNX [4]_ 227 228.. [1] Platforms on which apcctrl is regularly developed and tested 229.. [2] Platforms for which apcctrl team distributes binary packages 230.. [3] Port included in apcctrl source tree but may be out of date, 231 unmaintained, or broken. 232.. [4] USB not supported 233 234Supported UPSes and Cables 235-------------------------- 236 237apcctrl supports nearly every APC brand UPS model in existence and enough 238different cable types to connect to all of them. 239 240The ``UPSTYPE <keyword>`` field is the value you will put in 241your /etc/apcctrl/apcctrl.conf file to tell apcctrl what type of UPS 242you have. We'll describe the possible values here, because they're 243a good way to explain your UPS's single most important interface 244property: the kind of protocol it uses to talk with its 245computer. 246 247apcsmart 248 The 'apcsmart' protocol uses an RS232 serial connection to pass 249 commands back and forth in a primitive language resembling 250 modem-control codes. APC calls this language "UPS-Link". Originally 251 introduced for Smart-UPS models (thus the name 'apcsmart'), this 252 class of UPS is in decline, rapidly being replaced in APC's product 253 line by USB and MODBUS UPSes. 254 255usb 256 A USB UPS speaks a universal well defined control 257 language over a USB wire. Most of APC's lineup now uses this method 258 as of late 2003, and it seems likely to completely take over in 259 their low- and middle range. The most recent APC UPSes support only a 260 limited set of data over the USB interface. MODBUS (see below) is required 261 in order to access the advanced data. 262 263net 264 This is the keyword to specify if you are using your 265 UPS in Slave mode (i.e. the machine is not directly connected to 266 the UPS, but to another machine which is), and it is connected to 267 the Master via an ethernet connection. You must have apcctrl's 268 Network Information Services NIS turned on for this mode to work. 269 270snmp 271 SNMP UPSes communicate via an Ethernet NIC and 272 firmware that speaks Simple Network Management Protocol. 273 274dumb 275 A dumb or voltage-signaling UPS and its computer 276 communicate through the control lines (not the data lines) on an RS232C 277 serial connection. Not much can actually be conveyed this way other than 278 an order to shut down. Voltage-signaling UPSes are obsolete; you 279 are unlikely to encounter one other than as legacy hardware. If you 280 have a choice, we recommend you avoid simple signalling UPSes. 281 282pcnet 283 PCNET is an alternative for SNMP available on APC's 284 AP9617 family of smart slot modules. The protocol is much simpler 285 and potentially more secure than SNMP. 286 287modbus 288 MODBUS is the newest APC protocol and operates over RS232 serial links or 289 USB. MODBUS is APC's replacement for the aging 'apcsmart' (aka UPS-Link) 290 protocol. MODBUS is the only way to access detailed control and status 291 information on newer (esp. SMT series) UPSes. 292 293 294Choosing a Configuration Type 295----------------------------- 296 297There are three major 298ways of running apcctrl on your system. The first is a standalone 299configuration where apcctrl controls a single UPS, which powers a 300single computer. This is the most common configuration. If you're 301working with just one machine and one UPS, skip the rest of this 302section. 303 304Your choices become more interesting if you are running a small 305cluster or a big server farm. Under those circumstances, it may not 306be possible or even desirable to pair a UPS with every single 307machine. apcctrl supports some alternate arrangements. 308 309The second type of configuration is the NIS (Network Information 310Server) server and client. In this configuration, where one UPS 311powers several computers, a copy of apcctrl running one one 312computer will act as a server while the other(s) will act as 313network clients which poll the server for information about the 314UPS. Note that "NIS" is *not* related to Sun's directory service 315also called "NIS" or "Yellow Pages". 316 317The third configuration is where a single 318computer controls multiple UPSes. In this case, there are several 319instances of apcctrl on the same computer, each controlling a 320different UPS. One instance of apcctrl will run in standalone mode, and 321the other instance will normally run in network mode. 322This type of configuration may be appropriate for large server 323farms that use one dedicated machine for monitoring and 324diagnostics 325 326Here is a diagram that summarizes the possibilities: 327 328Configuration types 329------------------- 330 331.. image:: ./main_configs.png 332 333If you decide to set up one of these more complex configurations, 334see the dedicated section on that particular configuration. 335 336 337USB Configuration 338================= 339 340apcctrl supports USB connections on all major operating systems: 341Linux, FreeBSD, OpenBSD, NetBSD, Windows, Solaris, and Mac OS X 342Darwin. If you plan to use a USB connection, please read the 343appropriate subsection in its entirety. You can skip this section 344if your UPS has a serial (RS232-C) or Ethernet interface or if you 345are not running one of the platforms listed above. 346 347Linux USB Configuration 348----------------------- 349 350Known Linux USB Issues 351~~~~~~~~~~~~~~~~~~~~~~ 352 353**Problem** 354 Linux 2.4 series kernels older than 2.4.22 (RH 9, RHEL 3) 355 do not bind the USB device to the proper driver. This is evidenced 356 by /proc/bus/usb/devices listing the UPS correctly but it will have 357 "driver=(none)" instead of "driver=(hid)". This affects RHEL3, 358 among others. 359 360**Workaround** 361 Upgrade linux kernel to 2.4.22 or higher. Alternately, 362 you apply the linux-2.4.20-killpower.patch and 363 linux-2.4.20-USB-reject.patch patches to your kernel and rebuild 364 it. These patches can be found in the examples/ directory in the 365 apcctrl source distribution. 366 367**Problem** 368 Mandrake 10.0 and 10.1 systems with high security mode 369 enabled (running kernel-secure kernel) use static device nodes but 370 still assign USB minor numbers dynamically. This is evidenced by 371 ``hiddev0: USB HID v1.10 Device [...]`` instead of ``hiddev96: ...`` in 372 dmesg log. 373 374**Workaround** 375 Boot standard kernel instead of kernel-secure or 376 disable CONFIG_USB_DYNAMIC_MINORS and rebuild kernel-secure. 377 378**Problem** 379 USB driver linux-usb.c fails to compile, reporting errors 380 about ``HID_MAX_USAGES undefined``. This is due to a defect in the 381 linux kernel hiddev.h header file on 2.6.5 and higher kernels. 382 383**Workaround** 384 Upgrade to apcctrl-3.10.14 or higher. These versions 385 contain a workaround for the defect. 386 387**Problem** 388 On some systems such as Slackware 10.0, no USB devices 389 will show up (see the next section). 390 391**Workaround** 392 Add the following to rc.local 393 394 :: 395 396 mount -t usbdevfs none /proc/bus/usb 397 398**Problem** 399 2.6 kernels use udev and some distributions to not 400 configure it to automatically create /dev/usb/hiddev?? as they 401 should, causing apcctrl to fail to locate the UPS. 402 403**Workaround** 404 Edit the file /etc/udev/rules.d/50-udev.rules, and add 405 the following: 406 407 :: 408 409 KERNEL="hiddev*", NAME="usb/hiddev%n" 410 411 More details are provided in the following section ... 412 413 414Verifying Device Detection and Driver 415~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 416 417To make sure that your USB subsystem can see the UPS, just do this 418from a shell prompt: 419 420:: 421 422 cat /proc/bus/usb/devices 423 424This information is updated by the kernel whenever a device is 425plugged in or unplugged, irrespective of whether apcctrl is running 426or not. It contains details on all the USB devices in your system 427including hubs (internal and external), input devices, and UPSes. 428 429You should get some output back that includes something like this, 430featuring a BackUPS RS 1000: 431 432:: 433 434 T: Bus=02 Lev=01 Prnt=01 Port=00 Cnt=01 Dev#= 3 Spd=1.5 MxCh= 0 435 D: Ver= 1.10 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1 436 P: Vendor=051d ProdID=0002 Rev= 1.06 437 S: Manufacturer=American Power Conversion 438 S: Product=Back-UPS RS 1000 FW:7.g3 .D USB FW:g3 439 S: SerialNumber=JB0308036505 440 C:* #Ifs= 1 Cfg#= 1 Atr=a0 MxPwr= 24mA 441 I: If#= 0 Alt= 0 #EPs= 1 Cls=03(HID ) Sub=00 Prot=00 Driver=hid 442 443The important things to check for are the ``S:`` lines describing 444your UPS and and the ``I:`` line showing what driver is handling it. 445If on the ``I:`` line, ``Driver`` is listed as ``Driver=none`` then 446you do not have the HID driver loaded or the driver did not attach 447to the UPS. One common cause is having a Linux kernel older than 4482.4.22 (such as a stock RedHat 9 or RHEL 3 kernel). If this is the 449case for your system, please upgrade to at least kernel version 4502.4.22 and try again. If you are already running a 2.4.22 or higher 451kernel, please read further for instructions for other possible 452courses of action. 453 454Here is another example, this time featuring a Back-UPS 350: 455 456:: 457 458 T: Bus=01 Lev=01 Prnt=01 Port=00 Cnt=01 Dev#= 2 Spd=1.5 MxCh= 0 459 D: Ver= 1.10 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1 460 P: Vendor=051d ProdID=0002 Rev= 1.00 461 S: Manufacturer=American Power Conversion 462 S: Product=Back-UPS 350 FW: 5.2.I USB FW: c1 463 S: SerialNumber=BB0115017954 464 C:* #Ifs= 1 Cfg#= 1 Atr=a0 MxPwr= 30mA 465 I: If#= 0 Alt= 0 #EPs= 1 Cls=03(HID ) Sub=00 Prot=00 Driver=hid 466 E: Ad=81(I) Atr=03(Int.) MxPS= 8 Ivl= 10ms 467 468In general, if you see your UPS model in the ``S:`` field, which 469means ``Manufacturer=``, ``Product=``, and ``SerialNumber=``, and you 470see ``Driver=hid`` in the ``I:`` field, you know the UPS has been 471recognized and is bound to the correct driver. 472 473If your UPS doesn't appear in the list at all, check the obvious 474things: The UPS must be powered on, and a cable must be properly 475seated in both the data port of the UPS and one of your machine's 476USB ports. Many UPSes have phone ports to provide surge protection 477for phones or modems -- make sure you haven't plugged your USB 478cable into one of those rather than the data port (which will 479usually be near the top edge of the case.) 480 481Also, ensure that the correct drivers are loaded. Under 482Linux-2.4.x, you can check this out easily by examining the 483/proc/bus/usb/drivers file. Here's how you can do that: 484 485:: 486 487 cat /proc/bus/usb/drivers 488 489...and you should get: 490 491:: 492 493 usbdevfs 494 hub 495 96-111: hiddev 496 hid 497 498On Linux-2.6.x, make sure the sysfs filesystem is mounted on /sys 499and do: 500 501:: 502 503 ls -l /sys/bus/usb/drivers/ 504 505...where you should get: 506 507:: 508 509 total 0 510 drwxr-xr-x 2 root root 0 May 1 18:55 hid 511 drwxr-xr-x 2 root root 0 May 1 18:55 hiddev 512 drwxr-xr-x 2 root root 0 May 1 18:55 hub 513 drwxr-xr-x 2 root root 0 May 1 18:55 usb 514 drwxr-xr-x 2 root root 0 May 1 18:55 usbfs 515 516...or perhaps something like: 517 518:: 519 520 total 0 521 drwxr-xr-x 2 root root 0 Jan 6 15:27 hiddev 522 drwxr-xr-x 2 root root 0 Jan 6 15:28 hub 523 drwxr-xr-x 2 root root 0 Jan 6 15:28 usb 524 drwxr-xr-x 2 root root 0 Jan 6 15:27 usbfs 525 drwxr-xr-x 2 root root 0 Jan 6 15:28 usbhid 526 527If your 2.6.x system does not have the /sys/bus/usb directory, 528either you do not have sysfs mounted on /sys or the USB module(s) 529have not been loaded. (Check /proc/mounts to make sure sysfs is 530mounted.) 531 532A USB UPS needs all of these drivers -- the USB device filesystem, 533the USB hub, the Human Interface Device subsystem driver, and the 534Human Interface Device driver. If you are compiling your own 535kernel, you want to enable 536 537:: 538 539 CONFIG_USB 540 CONFIG_USB_HID 541 CONFIG_USB_HIDDEV 542 CONFIG_USB_DEVICEFS 543 544...as well as at least one USB Host Controller Driver... 545 546:: 547 548 CONFIG_USB_UHCI_HCD (linux-2.6.x) 549 CONFIG_USB_OHCI_HCD (linux-2.6.x) 550 CONFIG_USB_UHCI (linux-2.4.x) 551 CONFIG_USB_OHCI (linux-2.4.x) 552 553Device Nodes 554~~~~~~~~~~~~ 555 556apcctrl accesses USB UPSes via the hiddev device nodes. Typically 557these are located in ``/dev/hiddevN``, ``/dev/usb/hiddevN`` or 558``/dev/usb/hiddev/hiddevN`` (where ``N`` is a digit 0 thru 9). Some 559distributions (some Debian releases, possibly others) do not 560provides these device nodes for you, so you will have to make them 561yourself. Check ``/dev``, ``/dev/usb``, and ``/dev/usb/hiddev`` and if you 562cannot find the ``hiddevN`` nodes, run (as root) the 563``examples/make-hiddev`` script from the apcctrl source distribution. 564 565Modern Linux distributions using the 2.6 kernel create device nodes 566dynamically on the fly as they are needed. It is basically a 567hotplug system, giving a lot more power to the user to determine 568what happens when a device is probed or opened. It is also a lot 569more complicated. 570 571Some early 2.6 distributions (Fedora Core 3, for one) do not 572include hiddev rules in their default udev rule set. The bottom 573line for apcctrl on such a system is that if the ``hiddevN`` is not 574created when you plug in your UPS, apcctrl will terminate with an 575error. The solution to the problem is to add a rule to the udev 576rules file. On Fedora FC3, this file is found in 577``/etc/udev/rules.d/50-udev.rules``. Start by adding the following 578line: 579 580:: 581 582 BUS="usb", SYSFS{idVendor}="051d", NAME="usb/hiddev%n" 583 584*Note that this rule uses obsolete udev syntax and is specific to 585FC3 and other distributions of similar vintage.* 586 587Then either reboot your system, or unplug and replug your UPS and 588then restart apcctrl. At that point a ``/dev/usb/hiddevN`` node 589should appear and apcctrl should work fine. 590 591If you have several UPSes or you just want to give your UPS a fixed 592name, you can use rules like the following: 593 594:: 595 596 KERNEL=="hiddev*", SYSFS{serial}=="JB0319033692", SYMLINK="ups0" 597 KERNEL=="hiddev*", SYSFS{serial}=="JB0320004845", SYMLINK="ups1" 598 599*Note that this rule uses udev syntax that is appropriate 600only for distros such as RHEL4 and FC4 and others of a similar vintage.* 601 602More recent distros such as FC15 should use something like this: 603 604:: 605 606 KERNEL=="hiddev*", ATTRS{manufacturer}=="American Power Conversion", ATTRS{serial}=="BB0100009999 ", OWNER="root", SYMLINK+="ups0" 607 608Replace the serial number in quotes with the one that corresponds 609to your UPS. Then whenever you plug in your UPS a symlink called 610ups0, ups1, etc. will be created pointing to the correct hiddev 611node. This technique is highly recommended if you have more than 612one UPS connected to the same server since rearranging your USB 613cables or even upgrading the kernel can affect the order in which 614devices are detected and thus change which hiddev node corresponds 615to which UPS. If you use the symlink-by-serial-number approach the 616link will always point to the correct device node. 617 618You can use... 619 620:: 621 622 udevinfo -a -p /sys/class/usb/hiddev0/ 623 624...to get more information on the fields that can be matched 625besides serial number. 626 627To find the available attributes to match (note that the serial is NOT always 628the UPS serial on the box or in the USB connect message in /var/log/messages), 629use: 630 631:: 632 633 udevadm info --attribute-walk --name=/dev/usb/hiddev0 634 635An additional device-node-related problem is the use of dynamic 636minors. Some distributions, such as Mandrake 10, ship with a kernel 637having ``CONFIG_USB_DYNAMIC_MINORS`` turned on. This is not ideal 638for running with apcctrl, and the easiest solution is to turn 639``CONFIG_USB_DYNAMIC_MINORS`` off and rebuild your kernel, or find a 640pre-built kernel with it off. For a kernel with 641``CONFIG_USB_DYNAMIC_MINORS`` turned on to work with apcctrl, you 642must enable ``devfs``. The following will tell you if devfs is 643enabled: 644 645:: 646 647 $ ps ax | grep devs 648 649...which should give something like the following: 650 651:: 652 653 533 ? S 0:00 devfsd /dev 654 655What complicates the situation much more on Mandrake kernels is 656their security level since ``CONFIG_DYNAMIC_USB_MINORS`` is turned 657on, but on higher security levels devfs is turned off. The net 658result, is that in those situations hiddev is completely unusable 659so apcctrl will not work. So, in these cases, the choices are: 660 661#. Reduce the security level setting of the system (not sure if 662 this is possible after the initial install). 663 664#. Custom build a high security kernel with devfs enabled and make 665 sure devfs is mounted and devfsd is running. 666 667#. Custom build a high security kernel with dynamic minors 668 disabled 669 670#. Use udev 671 672 673Miscellaneous 674~~~~~~~~~~~~~ 675 676If all these things check out and you still can't see the UPS, 677something is more seriously wrong than this manual can cover -- 678find expert help. If you are unable to list USB devices or drivers, 679you kernel may not be USB-capable and that needs to be fixed. 680 681BSD USB Configuration 682--------------------- 683 684Known BSD USB Issues 685~~~~~~~~~~~~~~~~~~~~ 686 687**Problem** 688 FreeBSD lockups: Some users have experienced lockups 689 (apcctrl stops responding) on FreeBSD systems. 690 691**Solution** 692 Recent versions of apcctrl have addressed this issue. 693 Please upgrade to apcctrl-3.10.18 or higher. 694 695**Problem** 696 FreeBSD kernel panics if USB cable is unplugged while 697 apcctrl is running. 698 699**Solution** 700 This is a kernel bug and is most easily worked around by 701 not hot- unplugging the UPS while apcctrl is running. This issue 702 may be fixed in recent FreeBSD kernels. 703 704 705Platforms and Versions 706~~~~~~~~~~~~~~~~~~~~~~ 707 708The \*BSD USB driver supports FreeBSD, OpenBSD and NetBSD. (Thanks 709go to the \*BSD developers who kept a nearly identical interface 710across all three platforms.) 711 712Kernel Configuration 713~~~~~~~~~~~~~~~~~~~~ 714 715Users of OpenBSD, NetBSD, and some versions of FreeBSD will need to 716rebuild the kernel in order to *enable the ugen driver* and 717*disable the uhid driver*. uhid is not sufficient for apcctrl at 718this time and we need to prevent it from grabbing the UPS device. 719You should *make the following changes* to your kernel config 720file: 721 722*FreeBSD (v5.4 and below, v6.0)* 723 | (you **will not** lose use of USB keyboard and mouse) 724 | **Disable:** uhid 725 | **Enable:** ugen 726 727*FreeBSD (v5.5, v6.1 and above)* 728 | (you **will not** lose use of USB keyboard and mouse) 729 | **Disable:** (nothing) 730 | **Enable:** ugen 731 732 This is the default configuration for a GENERIC kernel on many 733 platforms so you most likely will not need to recompile. 734 735*NetBSD (v3.x and below)* 736 | (you **will** lose use of USB keyboard and mouse) 737 | **Disable:** uhidev, ums, wsmouse, ukbd, wskbd, uhid 738 | **Enable:** ugen 739 740*NetBSD (v4.0 and above)* 741 You can use apcctrl on single USB port 742 without disabling the USB keyboard and mouse on other ports, though 743 all other devices will be disabled on the port you pick for your 744 UPS. 745 746 First, decide which hub and port you wish to use. You can find out 747 the hub and port numbers for any particular physical connector by 748 plugging a USB device into it and looking at the messages printed 749 by the kernel; you should messages something like this: 750 751 :: 752 753 uxx0 at uhub0 port 1 754 uxx0: <some device name> 755 756 To use your APC UPS on this port, configure the kernel to prefer 757 attachment of the ugen driver over other drivers on this hub and 758 port only, by adding a line like this to your kernel config file: 759 760 :: 761 762 ugen* at uhub0 port 1 flags 1 763 764 (The "flags 1" forces the ugen to attach instead of anything else 765 detected there.) 766 767 Configure and build that kernel as per the references below, and 768 your UPS will now attach as a ugen device when plugged into that 769 port. 770 771 Don't forget to '``cd /dev``' and '``./MAKEDEV ugen1``' (and 2 and so on) 772 if you have more than one generic usb device on your system. 773 774*OpenBSD* 775 | (you **will** lose use of USB keyboard and mouse): 776 | **Disable:** uhidev, ums, wsmouse, ukbd, wskbd, uhid 777 | **Enable:** ugen 778 779 780For detailed information on rebuilding your kernel, consult these 781references: 782 783*FreeBSD* 784 http://www.freebsd.org/doc/en\_US.ISO8859-1/books/handbook/kernelconfig.html 785 786*NetBSD* 787 http://www.netbsd.org/guide/en/chap-kernel.html 788 789*OpenBSD* 790 http://www.openbsd.org/faq/faq5.html#Building 791 792 793Verifying Device Detection and Driver 794~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 795 796After building a properly configured kernel, reboot into that 797kernel and plug in your UPS USB cable. You should see a dmesg log 798message like the following: 799 800:: 801 802 ugen0: American Power Conversion Back-UPS RS 1500 FW:8.g6 .D USB FW:g6, rev 1.10/1.06, addr 2 803 804Note that the ``ugen`` driver is called out. If you see ``uhid`` 805instead, it probably means you did not properly disable the uhid 806driver when you compiled your kernel or perhaps you're not running 807the new kernel. 808 809You can also check with '``usbdevs -d``' to get a list of USB devices 810recognized by the system as well as the drivers they are associated 811with. For example: 812 813:: 814 815 # usbdevs -d 816 addr 1: UHCI root hub, VIA 817 uhub0 818 addr 2: Back-UPS RS 1500 FW:8.g6 .D USB FW:g6, American Power Conversion 819 ugen0 820 821Device Nodes 822~~~~~~~~~~~~ 823 824apcctrl communicates with the UPS through the USB generic device, 825``ugen``. You may or may not need to manually make ``ugen`` device 826nodes in ``/dev``, depending on what OS you are using. 827 828FreeBSD 829 No manual intervention needed. FreeBSD automatically 830 creates the ugen nodes on demand. 831 832NetBSD 833 By default, NetBSD only creates nodes for the first ugen 834 device, ``ugen0``. Check ``usbdevs -d`` to see which device your 835 UPS was bound to and then create the appropriate node by running 836 '``cd /dev ; ./MAKEDEV ugenN``', where ``ugenN`` is the ugen device name 837 shown by ``usbdevs``. It is probably a good idea to create several sets 838 of ugen nodes in case you add more USB devices. 839 840OpenBSD 841 Similar to NetBSD, OpenBSD creates nodes for ``ugen0`` and 842 ``ugen1``. Check ``usbdevs -d`` to see which device your UPS was 843 bound to and then create the appropriate node by running '``cd /dev 844 ; ./MAKEDEV ugenN``', where ``ugenN`` is the ugen device name shown 845 by ``usbdevs``. It is probably a good idea to create several sets of 846 ugen nodes in case you add more USB devices. 847 848 849Windows USB Configuration 850------------------------- 851 852Platforms and Versions 853~~~~~~~~~~~~~~~~~~~~~~ 854 855apcctrl supports USB UPSes on Windows XP and newer, including 64 bit systems. 856 857USB Driver Installation 858~~~~~~~~~~~~~~~~~~~~~~~ 859 860USB connected UPSes on Windows require a special driver. In most 861cases, this driver is automatically installed when you install 862apcctrl. However in some cases you may need to install the driver manually. 863For detailed instructions, please see the ``install.txt`` file located 864in the driver folder of your apcctrl install. 865 866Verifying Device Detection and Driver 867~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 868 869After installing apcctrl (and the apcctrl USB driver, if 870necessary), plug in your UPS USB cable and open the Windows Device 871Manager. You should see a ``American Power Conversion USB UPS (apcctrl)`` 872listed under the ``Batteries`` section. If a device of that name does not 873appear, check that your UPS is powered on and that the USB cable is connected 874at both ends. Reinstall the driver as directed above if needed. 875 876Solaris USB Configuration 877------------------------- 878 879Platforms and Versions 880~~~~~~~~~~~~~~~~~~~~~~ 881 882apcctrl supports USB UPSes on Solaris 10 and higher. Both x86 and 883SPARC platforms are supported. 884 885Building apcctrl with USB 886~~~~~~~~~~~~~~~~~~~~~~~~~ 887 888Some specific packages are necessary when building apcctrl with USB 889support on Solaris. You must install the ``SUNWlibusb`` and 890``SUNWlibusbugen`` packages **BEFORE** attempting to build apcctrl. 891These packages can be found on the Solaris installation CDROMs and 892should be installed with the ``pkgadd`` utility. 893 894You also should build using the gcc compiler and ccs make, not 895Sun's compiler. The appropriate make utility can be found in 896``/usr/ccs/bin``. gcc can be installed from packages included on the 897Solaris installation CDROMs. 898 899Configure and build apcctrl normally, as described in `Building and 900Installing apcctrl`_. Be sure to 901include the ``--enable-usb`` flag to ``configure``. 902 903After building, install apcctrl as root using '``make install``', 904then *perform a reconfigure boot* ('``reboot -- -r``'). During 905installation, apcctrl will automatically configure your USB 906subsystem to attach APC USB devices to the ``ugen`` driver. This is 907a critical step and must be completed by a reconfigure boot. Note 908that the USB config changes will be reversed if you remove apcctrl 909using '``make uninstall``'. 910 911Verifying Device Detection and Driver 912~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 913 914After installing apcctrl as described above and performing a 915reconfigure boot, plug in your UPS USB cable. You should see a 916series of dmesg log messages similar to the following: 917 918:: 919 920 Dec 5 17:50:50 sunblade usba: [ID 912658 kern.info] USB 1.10 device (usb51d,2) operating at low speed (USB 1.x) on USB 1.10 root hub: input@4, ugen0 at bus address 3 921 Dec 5 17:50:50 sunblade usba: [ID 349649 kern.info] American Power Conversion Smart-UPS 1000 FW:600.1.D USB FW:1.2 AS0127232356 922 Dec 5 17:50:50 sunblade genunix: [ID 936769 kern.info] ugen0 is /pci@1f,0/usb@c,3/input@4 923 Dec 5 17:50:50 sunblade genunix: [ID 408114 kern.info] /pci@1f,0/usb@c,3/input@4 (ugen0) online 924 925Note that the ``ugen`` driver is called out. If you do not see any 926dmesg entries related to your UPS, ensure that it is turned on and 927that the USB cable is connected at both ends. Also verify that you 928installed apcctrl as root using the '``make install``' command and 929that you performed a reconfigure boot afterward. 930 931Device Nodes 932~~~~~~~~~~~~ 933 934apcctrl communicates with the UPS through the USB generic device, ``ugen``. 935The reconfigure boot performed after apcctrl installation 936will ensure the correct device nodes are created. Once your UPS has 937been recognized in dmesg as shown above, you can check /dev/usb to 938see if the device nodes have appeared: 939 940:: 941 942 [user@sunblade /]$ ls /dev/usb/51d.2/* 943 cntrl0 cntrl0stat devstat if0in1 if0in1stat 944 945(``51d.2`` is the vendor/product id for APC UPSes.) 946 947Mac OS X (Darwin) USB Configuration 948----------------------------------- 949 950Platforms and Versions 951~~~~~~~~~~~~~~~~~~~~~~ 952 953apcctrl supports USB UPSes on Mac OS X (Darwin) 10.4.x and higher. 954Both Intel and PowerPC platforms are supported. 955 956Building apcctrl with USB 957~~~~~~~~~~~~~~~~~~~~~~~~~ 958 959Some specific packages are necessary when building apcctrl with USB 960support on Darwin. You must install libusb-0.1.12 which 961can be obtained from MacPorts (http://www.macports.org) (formerly 962DarwinPorts) or Fink (http://fink.sourceforge.net) or downloaded and built 963by hand (http://www.libusb.org). *You must not use 964libusb-1.x or higher (apcctrl does not support the new 1.0 APIs) nor 965any version earlier than 0.1.12 (earlier versions have a bug that apcctrl 966triggers). Generally that means you must use exactly 0.1.12.* Note that 967apcctrl is sensitive to the install location of libusb, so beware if you 968change it from the default. 969 970apcctrl should be built using gcc, preferably from the XCode 971development tools. Currently the maintainer is using gcc-4.0.1 from 972XCode 2.4. Other versions of gcc from other sources may also work. 973 974Configure and build apcctrl normally, as described in `Building and 975Installing apcctrl`_. Be sure to 976include the ``--enable-usb`` flag to ``configure``. 977 978After building, install apcctrl as root using '``make install``' 979and then reboot. During installation, apcctrl will automatically 980install a simple dummy kext driver designed to prevent Apple's 981monitoring software from taking over the UPS. It is necessary to 982reboot in order to activate the kext. Note that this kext will be 983automatically removed if you uninstall apcctrl using 984'``make uninstall``', allowing Apple's monitoring tool to once 985again access the UPS. 986 987Verifying Device Detection and Driver 988~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 989 990After installing apcctrl as described above and rebooting, plug in 991your UPS USB cable. You should notice that Darwin does **NOT** 992display the battery monitor tool in the menu bar. You can also 993check Apple Menu -> About This Mac -> More Info... -> USB to ensure 994that your UPS appears in the list of USB devices. 995 996 997Building and Installing apcctrl 998=============================== 999 1000In general it is recommended to obtain a prebuilt binary package for your 1001platform. Given how apcctrl must integrate into the shutdown mechanism of the 1002operating system and the rate at which such mechanisms are changed by 1003vendors, the platform ports in the apcctrl tree may become out of date. In 1004some cases, binary packages are provided by the apcctrl team (RedHat, 1005Mandriva, SuSE, Windows, Mac OS X). For other platforms it is recommended to 1006check your vendor's package repository and third party repositories for 1007recent binary packages before resorting to building apcctrl from scratch. 1008Note that some vendors continue to distribute *ancient* versions of apcctrl 1009with known defects. These packages should **not** be used. 1010 1011 1012Installation from Binary Packages 1013--------------------------------- 1014 1015RPMS 1016~~~~ 1017 1018For systems based on RPM packages, such as Red Hat and SuSE, apcctrl is 1019available in binary RPM format. This is the simplest way to 1020install. If you have no previous version of apcctrl on your machine 1021and are creating a standalone configuration, simply install the RPM 1022with a normal '``rpm -ihv``' command. You're done, and can now skip 1023the rest of this chapter and go straight to tweaking your run-time 1024configuration file. (see `After Installation`_) 1025 1026If you have a previous installation, you can upgrade with a normal 1027'``rpm -Uhv``', but this may not upgrade the halt script. It may be 1028better to do the upgrade as a remove '``rpm -e``' followed by a 1029fresh install '``rpm -ihv``'. 1030 1031After installation of the binary RPM, please verify carefully that 1032/etc/rc.d/init.d/halt was properly updated and contains new script 1033lines flagged with ``***APCCTRL***``. 1034 1035Since there is no standard location for cgi-bin, the rpm will place 1036the binary CGI programs in the directory /etc/apcctrl/cgi. To 1037actually use them, you must copy or move them to your actual 1038cgi-bin directory, which on many systems is located in 1039/home/httpd/cgi-bin. 1040 1041 1042Microsoft Windows 1043~~~~~~~~~~~~~~~~~ 1044 1045The Windows version of apcctrl is distributed as a simple double-click 1046installer. Installation is very simple and straight-forward: Simply 1047double-click the installer executable and follow the instructions. See 1048`The Windows Version of apcctrl`_ for further details. 1049 1050 1051Installation from Source 1052------------------------ 1053 1054Installation from source might have to be be done different ways 1055depending on what system you are running. The basic procedure 1056involves getting a source distribution, running the configuration, 1057rebuilding, and installing. 1058 1059For building the system, we suggest that you run the configure and 1060make processes as your normal UNIX user ID. The '``make install``' 1061must be run as root. But if your normal ID has an environment setup 1062for using the C compiler, it's simpler to do that than to set up 1063root to have the correct environment. 1064 1065apcctrl requires ``gcc`` and ``g++`` compilers as well as GNU ``make``. 1066Other compilers or BSD ``make`` will **not** work. GNU make is sometimes 1067installed as ``gmake``. The configure script will check for this and will 1068inform you of what command to use to invoke GNU make. 1069 1070The basic installation from a tar source file is rather simple: 1071 1072#. Unpack the source code from its tar archive. 1073 1074#. Go into the directory containing the source code. 1075 1076#. Run '``./configure``' (with appropriate options as described 1077 below) 1078 1079#. '``make``' or '``gmake``'' as instructed by configure 1080 1081#. '``su``' (i.e. become root) 1082 1083#. Stop any running instance of apcctrl. The command to do this 1084 will look like '``system-dependent-path/apcctrl stop``' 1085 1086#. uninstall any old apcctrl This is important since the default 1087 install locations may have changed. 1088 1089#. '``make install``' or '``gmake install``' 1090 1091#. edit your /etc/apcctrl/apcctrl.conf file if necessary 1092 1093#. ensure that your halt script is properly updated 1094 1095#. Start the new apcctrl with: '``system-dependent-path/apcctrl 1096 start``' 1097 1098 1099If all goes well, the '``./configure``' will correctly determine which 1100operating system you are running and configure the source code 1101appropriately. ``configure`` currently recognizes the systems listed 1102below in the `Operating System Specifics`_ section of this chapter and 1103adapts the configuration appropriately. Check that the 1104configuration report printed at the end of the ``configure`` process 1105corresponds to your choice of directories, options, and that it has 1106correctly detected your operating system. If not, redo the 1107``configure`` with the appropriate options until your configuration is 1108correct. 1109 1110Please note that a number of the ``configure`` options preset 1111apcctrl.conf directive values in an attempt to automatically adapt 1112apcctrl as best possible to your system. You can change the values 1113in apcctrl.conf at a later time without redoing the configuration 1114process by simply editing the apcctrl.conf file. 1115 1116Other configuration options can be used to set up the installation 1117of HTML documentation and optional modules, notably the CGI 1118interface that enables the UPS state to be queried via the Web. You 1119will find a complete reference later in this chapter. 1120 1121In general, you will probably want to supply a more elaborate 1122``configure`` statement to ensure that the modules you want are built 1123and that everything is placed into the correct directories. 1124 1125On Red Hat, a fairly typical configuration command would look like 1126the following: 1127 1128:: 1129 1130 CFLAGS="-g -O2" LDFLAGS="-g" ./configure \ 1131 --enable-usb \ 1132 --with-upstype=usb \ 1133 --with-upscable=usb \ 1134 --prefix=/usr \ 1135 --sbindir=/sbin \ 1136 --with-cgi-bin=/var/www/cgi-bin \ 1137 --enable-cgi \ 1138 --with-log-dir=/etc/apcctrl 1139 1140By default, '``make install``' will install the executable files in 1141/sbin, the manuals in /usr/man, and the configuration and script 1142files in /etc/apcctrl. In addition, if your system is recognized, 1143certain files such as the startup script and the system halt script 1144will be placed in appropriate system directories (usually 1145subdirectories of /etc/rc.d). 1146 1147 1148Verifying a Source Installation 1149------------------------------- 1150 1151There are a number of things that you can do to check if the 1152installation (make install) went well. The fist is to check where 1153the system has installed apcctrl using '``which``' and '``whereis``'. On 1154my Red Hat system, you should get the following (lines preceded 1155with a $ indicate what you type): 1156 1157:: 1158 1159 $ which apcctrl 1160 /sbin/apcctrl 1161 $ whereis apcctrl 1162 apcctrl: /sbin/apcctrl /etc/apcctrl /etc/apcctrl.conf 1163 /etc/apcctrl.status /usr/man/man8/apcctrl.8.gz 1164 /usr/man/man8/apcctrl.8 1165 1166If you find an apcctrl in /usr/sbin, /usr/local/sbin, /usr/lib, or 1167another such directory, it is probably a piece of an old version of 1168apcctrl that you can delete. If you are in doubt, delete it, then 1169rerun the '``make install``' to ensure that you haven't deleted 1170anything needed by the new apcctrl. Please note that the files 1171specified above assume the default installation locations. 1172 1173As a final check that the '``make install``' went well, you should 1174check your halt script (in /etc/rc.d on SUSE systems, and in 1175/etc/rc.d/init.d on Red Hat systems) to see that the appropriate 1176lines have been inserted in the correct place. Modification of the 1177halt script is important so that at the end of the shutdown 1178procedure, apcctrl will be called again to command the UPS to turn 1179off the power. This should only be done in a power failure 1180situation as indicated by the presence of the /etc/powerfail file, 1181and is necessary if you want your machine to automatically be 1182restarted when the power returns. On a Red Hat system, the lines 1183containing the ``# ***apcctrl***`` should be inserted just 1184before the final halt command: 1185 1186:: 1187 1188 # Remount read only anything that's left mounted. 1189 #echo "Remounting remaining filesystems (if any) readonly" 1190 mount | awk '/ext2/ { print $3 }' | while read line; do 1191 mount -n -o ro,remount $line 1192 done 1193 1194 # See if this is a powerfail situation. # ***apcctrl*** 1195 if [ -f /etc/apcctrl/powerfail ]; then # ***apcctrl*** 1196 echo # ***apcctrl*** 1197 echo "APCCTRL will now power off the UPS" # ***apcctrl*** 1198 echo # ***apcctrl*** 1199 /etc/apcctrl/apccontrol killpower # ***apcctrl*** 1200 echo # ***apcctrl*** 1201 echo "Please ensure that the UPS has powered off before rebooting" # ***apcctrl*** 1202 echo "Otherwise, the UPS may cut the power during the reboot!!!" # ***apcctrl*** 1203 echo # ***apcctrl*** 1204 fi # ***apcctrl*** 1205 1206 # Now halt or reboot. 1207 echo "$message" 1208 if [ -f /fastboot ]; then 1209 echo "On the next boot fsck will be skipped." 1210 elif [ -f /forcefsck ]; then 1211 echo "On the next boot fsck will be forced." 1212 fi 1213 1214The purpose of modifying the system halt files is so that apcctrl 1215will be recalled after the system is in a stable state. At that 1216point, apcctrl will instruct the UPS to shut off the power. This is 1217necessary if you wish your system to automatically reboot when the 1218mains power is restored. If you prefer to manually reboot your 1219system, you can skip this final system dependent installation step 1220by specifying the ``disable-install-distdir`` option on the 1221'``./configure``' command (see below for more details). 1222 1223The above pertains to Red Hat systems only. There are significant 1224differences in the procedures on each system, as well as the 1225location of the halt script. Also, the information that is inserted 1226in your halt script varies from system to system. Other systems 1227such as Solaris require you the make the changes manually, which 1228has the advantage that you won't have any unpleasant surprises in 1229your halt script should things go wrong. Please consult the 1230specific system dependent README files for more details. 1231 1232Please note that if you install from RPMs for a slave machine, you 1233will need to remove the changes that the RPM install script made 1234(similar to what is noted above) to the halt script. This is 1235because on a slave machine there is no connection to the UPS, so 1236there is no need to attempt to power off the UPS. That will be done 1237by the master. 1238 1239 1240Configure Options 1241----------------- 1242 1243All the available ``configure`` options can be printed by entering: 1244 1245:: 1246 1247 ./configure --help 1248 1249When specifying options for '``./configure``', if in doubt, don't put 1250anything, since normally the configuration process will determine 1251the proper settings for your system. The advantage of these options 1252is that it permits you to customize your version of apcctrl. If you 1253save the '``./configure``' command that you use to create apcctrl, you 1254can quickly reset the same customization in the next version of 1255apcctrl by simply re-using the same command. 1256 1257The following command line options are available for ``configure`` 1258to customize your installation. 1259 1260--prefix=path This defines the directory for the 1261 non-executable files such as the manuals. 1262 The default is /usr. 1263--sbindir=path This defines the directory for 1264 the executable files such as apcctrl. 1265 The default is /sbin. You may 1266 be tempted to place the executable files in /usr/sbin or 1267 /usr/local/sbin. Please use caution here as these directories may 1268 be unmounted during a shutdown and thus may prevent the ``halt`` 1269 script from calling apcctrl to turn off the UPS power. Though your 1270 data will be protected, in this case, your system will probably not 1271 be automatically rebooted when the power returns 1272--enable-cgi This enables the building of the 1273 CGI programs that permit Web browser access to apcctrl data. This 1274 option is not necessary for the proper execution of apcctrl. 1275--with-cgi-bin=path The with-cgi-bin 1276 configuration option allows you to define the directory where the 1277 CGI programs will be installed. The default is /etc/apcctrl, which 1278 is probably not what you want. 1279--enable-apcsmart Turns on generation of the APC Smart driver (default). 1280--enable-dumb Turns on generation of the dumb signalling driver code (default). 1281--enable-usb Turns on generation of the USB driver code. By default this is disabled. 1282--enable-net Turns on generation of the NIS 1283 network driver for slaves. For each slave, this is the only driver 1284 needed. This driver works by reading the information from the the 1285 configured master using the NIS (Network Information Services) 1286 interface. 1287--enable-snmp Turns on generation of the 1288 SNMP driver. This driver accesses the UPS over the network using 1289 SNMP. This is compatible only with UPSes equipped with an SNMP or 1290 Web/SNMP management card. By default this is enabled. 1291--enable-net-snmp Turns on generation of the 1292 obsolete NET-SNMP driver. This driver was the precursor to the current 1293 snmp driver and is now obsolete. It is available as a fallback if the new 1294 driver cannot be used for some reason. By default this is disabled. 1295--enable-pcnet Turns on generation of the 1296 PCNET (PowerChute Network Shutdown) driver. This driver accesses 1297 the UPS over the network using APC's custom protocol. This driver 1298 can be used as an alternative to SNMP for UPSes equipped with a 1299 modern Web/SNMP management card. 1300--enable-modbus Turns on generation of the MODBUS/RS232 driver (default) 1301--enable-modbus-usb Turns on generation of the MODBUS/USB driver 1302--enable-test This turns on a test driver 1303 that is used only for debugging. By default it is disabled. 1304--enable-gapcmon This option enables building the GTK GUI front-end for 1305 apcctrl. Building this package requires numerous GNOME libraries. The 1306 default is disabled. 1307--enable-apcagent This option enables building the apcagent menubar application 1308 on Mac OS X platforms. The default is disabled. 1309--with-libwrap=path, --with-libwrap This option when 1310 enabled causes apcctrl to be built with the TCP WRAPPER library for 1311 enhanced security. In most cases, the path is optional since 1312 configure will determine where the libraries are on most systems. 1313--with-nologin=path This option allows you 1314 to specify where apcctrl will create the nologin file when logins 1315 are prohibited. The default is /etc 1316--with-pid-dir=path This option allows you 1317 to specify where apcctrl will create the process id (PID) file to 1318 prevent multiple copies from running. The default is system 1319 dependent but usually /var/run. 1320--with-log-dir=path This option allows you 1321 to specify where apcctrl will create the EVENTS and STATUS log 1322 files. The default is /etc/apcctrl. This option simply sets the 1323 default of the appropriate path in the apcctrl.conf file, which can 1324 be changed at any later time. 1325--with-lock-dir=path This option allows 1326 you to specify where apcctrl will create the serial port lock file. 1327 The default is system-dependent but usually /var/lock. This option 1328 simply sets the appropriate path in the apcctrl.conf file, which 1329 can be changed at any later time. 1330--with-pwrfail-dir=path This option 1331 allows you to specify where apcctrl will create the powerfail file 1332 when a power failure occurs. The default is system dependent but 1333 usually /etc. 1334--with-serial-dev=device-name This 1335 option allows you to specify where apcctrl will look for the serial 1336 device that talks to the UPS. The default is system dependent, but 1337 often /dev/ttyS0. This option simply sets the appropriate device 1338 name in the apcctrl.conf file, which can be changed at any later 1339 time. 1340--with-nis-port=port This option allows 1341 you to specify what port apcctrl will use for the Network 1342 Information Server (the CGI programs). The default is system 1343 dependent but usually 3551 because that port has been officially 1344 assigned to apcctrl by the IANA. This option simply sets the 1345 appropriate port in the apcctrl.conf file, which can be changed at 1346 any later time. 1347--with-nisip=ip-address This option allows 1348 you to specify the value that will be placed on then NISIP 1349 directive in the configuration file. The default is 0.0.0.0. No 1350 checking is done on the value entered, so you must ensure that it 1351 is a valid IP address. 1352--with-net-port=port This option allows 1353 you to specify what port apcctrl will use for Master and Slave 1354 communications. The default is system dependent but usually 6666. 1355 This option simply sets the appropriate port in the apcctrl.conf 1356 file, which can be changed at any later time. 1357--with-upstype=type This option allows you 1358 to specify the type of UPS that will be connected to your computer. 1359 The default is: smartups. This option simply sets the appropriate 1360 UPS type in the apcctrl.conf file, which can be changed at any 1361 later time. 1362--with-upscable=cable This option allows 1363 you to specify what cable you are using to connect to the UPS. The 1364 default is: smart. This option simply sets the appropriate UPS 1365 cable in the apcctrl.conf file, which can be changed at any later 1366 time. 1367--disable-install-distdir This 1368 option modifies the apcctrl Makefiles disable installation of the 1369 distribution (platform) directory. Generally, this used to do a 1370 full installation of apcctrl except the final modification of the 1371 operating system files (normally /etc/rc.d/halt, etc.). This is 1372 useful if your operating system is not directly supported by 1373 apcctrl or if you want to run two copies of apcctrl on the same 1374 system. This option can also be used by those of you who prefer to 1375 manually reboot your system after a power failure or who do not 1376 want to modify your system halt files. 1377 1378 1379Recommended Options for most Systems 1380------------------------------------ 1381 1382For most systems, we recommend the following options: 1383 1384:: 1385 1386 ./configure --prefix=/usr --sbindir=/sbin --enable-usb 1387 1388and you can optionally build and install the CGI programs as 1389follows: 1390 1391:: 1392 1393 ./configure --prefix=/usr --sbindir=/sbin --enable-usb \ 1394 --enable-cgi --with-cgi-bin=/home/httpd/cgi-bin 1395 1396Compilers and Options 1397--------------------- 1398 1399Some systems require unusual options 1400for compilation or linking that the '``./configure``' script does not 1401know about. You can specify initial values for variables by setting 1402them in the environment. Using a Bourne-compatible shell, you can 1403do that on the command line like this: 1404 1405:: 1406 1407 CFLAGS="-O2 -Wall" LDFLAGS= ./configure 1408 1409Or on systems that have the ``env`` program, you can do it like 1410this: 1411 1412:: 1413 1414 env CPPFLAGS=-I/usr/local/include LDFLAGS=-s ./configure 1415 1416Or for example on the Sun Solaris system, you can use: 1417 1418:: 1419 1420 setenv CFLAGS -O2 1421 setenv LDFLAGS -O 1422 ./configure 1423 1424You can get a listing of all available options by doing: 1425 1426:: 1427 1428 ./configure --help 1429 1430or simply see the previous section of this manual. 1431 1432 1433Operating System Specifics 1434-------------------------- 1435 1436With the exception of Linux SUSE and Linux Red Hat 1437systems used by the developers, we rely on users to help create 1438installation scripts and instructions as well as to test that 1439apcctrl runs correctly on their system. As you can imagine, most of 1440these people are system administrators rather than developers so 1441they are very busy and don't always have time to test the latest 1442releases. With that in mind, we believe that you will find that a 1443lot of very valuable work has been already done to make your 1444installation much easier (and probably totally automatic). 1445 1446Below, you will find a list of operating systems for which we have 1447received installation files: 1448 1449 1450- Debian (see `Debian`_) 1451- FreeBSD (see `FreeBSD`_) 1452- HPUX (see `HPUX`_) 1453- NetBSD (see `NetBSD`_) 1454- Mac OS X Darwin (see `Mac OS X Darwin`_) 1455- OpenBSD (see `OpenBSD`_) 1456- Red Hat (see `Red Hat Systems`_) 1457- Slackware (see `Slackware`_) 1458- SUSE (see `SUSE`_) 1459- Solaris (see `Sun Solaris`_) 1460- unknown (see `Unknown System`_) 1461- Win32 (see `Windows Systems`_) 1462 1463 1464 1465Debian 1466~~~~~~ 1467 1468This port is complete and is being used by several users. Since Debian 1469build and install procedures are somewhat particular, we have put the extra 1470Debian information into the following two subdirectories: 1471``platforms/debian/examples`` and ``platforms/debian/packageinfo`` 1472 1473You can also find the official Debian packages on the Debian site 1474at: 1475 1476- https://packages.debian.org/stable/apcctrl 1477- https://packages.debian.org/testing/apcctrl 1478- https://packages.debian.org/unstable/apcctrl 1479 1480 1481FreeBSD 1482~~~~~~~ 1483 1484This port is complete and is being used by several users. 1485 1486You will need to install and use GNU make (aka gmake) instead of the 1487BSD make supplied with the system. 1488 1489On the FreeBSD OS, there is no known way for a user program to get 1490control when all the disks are synced. This is needed for apcctrl 1491to be able to issue the killpower command to the UPS so that the 1492UPS shuts off the power. To accomplish the same thing on FreeBSD 1493systems, make sure you have a SmartUPS and that your UPS shutdown 1494grace period is set sufficiently long so that you system will power 1495down (usually 2 minutes), the use the ``--kill-on-powerfail`` option 1496on the apcctrl command line. 1497 1498 1499HPUX 1500~~~~ 1501 1502Status of this port is unknown. 1503 1504 1505NetBSD 1506~~~~~~ 1507 1508You will need to install and use GNU make (aka gmake) instead of the 1509BSD make supplied with the system. 1510 1511 1512Mac OS X Darwin 1513~~~~~~~~~~~~~~~ 1514 1515On OS X (Darwin), apcctrl can be built with ``configure`` defaults. 1516The USB driver can be enabled, as per the directions on `Mac OS X (Darwin) 1517USB Configuration`_ apcctrl *may* be usable 1518on OS X with a smart serial device, but certainly *does* work as a 1519NIS client or using a USB interface. 1520 1521The startup information will be installed in 1522``/Library/StartupItems/apcctrl`` which is part of darwin's 1523SystemStartup. 1524 1525 1526OpenBSD 1527~~~~~~~ 1528 1529You will need to install and use GNU make (aka gmake) instead of the 1530BSD make supplied with the system. 1531 1532Ensure that you read 1533the distributions/openbsd/README file before running apcctrl. There 1534are some critical differences in how the OpenBSD implementation 1535operates when the UPS batteries are exhausted. Failure to take this 1536into account may result in the system not being fully halted when 1537power is lost. 1538 1539 1540Red Hat Systems 1541~~~~~~~~~~~~~~~ 1542 1543Red Hat systems are 1544fully supported, and by following the standard installation 1545instructions given above, you should experience few or no 1546problems. 1547 1548 1549Slackware 1550~~~~~~~~~ 1551 1552Slackware 1553systems are fully supported, and by following the standard 1554installation instructions given above, you should experience few or 1555no problems. 1556 1557 1558SUSE 1559~~~~ 1560 1561SUSE systems are fully 1562supported, and by following the standard installation instructions 1563given above, you should experience few or no problems. 1564 1565 1566Sun Solaris 1567~~~~~~~~~~~ 1568 1569Please read this before attempting to compile or install the beta 1570software. It contains important information that will make your 1571efforts easier. 1572 1573Before running '``./configure``', please be sure that you do not have 1574/usr/ucb on your path. This may cause the ``configure`` to choose 1575the wrong shutdown program. If ``configure`` detects that /usr/usb 1576is on your path, it will print a warning message. Please follow the 1577advice to avoid shutdown problems. 1578 1579Your normal UNIX user ID must own the source tree directories, and 1580you must have the normal development tools in your path. This 1581includes make, the compiler, the M4 preprocessor, the linker, and 1582ar or ranlib. If the user you are logged in as can compile and link 1583a C program from a source file, then you have all the required 1584tools available. 1585 1586You will want to install the executables in a directory that 1587remains mounted during the shutdown. Solaris will unmount almost 1588everything except the root directories. Since the ability to power 1589the UPS off requires access to the executable programs, they need 1590to be in a directory that will never be unmounted. And since they 1591should also be in a directory that normal users cannot get into, 1592/sbin is the default. However, please be aware that if you want to 1593follow Sun's filesystem conventions you would use the following: 1594 1595:: 1596 1597 ./configure \ 1598 --prefix=/opt/apcctrl \ 1599 --sbindir=/etc/opt/apcctrl/sbin \ 1600 --sysconfdir=/etc/opt/apcctrl \ 1601 --with-cgi-bin=/opt/apcctrl/cgi-bin 1602 1603The way to setup the /sbin directory as the executables directory 1604is to pass configure the ``--sbindir=/sbin`` option. No other 1605arguments should be required, and your setup and platform should be 1606detected automatically by configure. 1607 1608Once you have run configure, you will need to do a '``gmake``'. Once 1609the make has completed with no errors, you must su to root to 1610complete the install. After the su, you may not have a path to the 1611make program anymore. In that case, you should do the '``gmake 1612install``' step as: 1613 1614:: 1615 1616 gmake install 1617 1618Once the install completes, you must edit the /sbin/rc0 script as 1619detailed below, then exit from the su'ed shell. 1620 1621In order to support unattended operation and shutdown during a 1622power failure, it's important that the UPS remove power after the 1623shutdown completes. This allows the unattended UPS to reboot the 1624system when power returns by re-powering the system. Of course, you 1625need autoboot enabled for your system to do this, but all Solaris 1626systems have this by default. If you have disabled this on your 1627system, please re-enable it. 1628 1629To get the UPS to remove power from the system at the correct time 1630during shutdown, i.e., after the disks have done their final sync, 1631we need to modify a system script. This script is /sbin/rc0. 1632 1633We do not have access to every version of Solaris, but we believe 1634this file will be almost identical on every version. Please let us 1635know if this is not true. 1636 1637At the very end of the /sbin/rc0 script, you should find lines just 1638like the following: 1639 1640:: 1641 1642 # unmount file systems. /usr, /var and /var/adm are not unmounted by umountall 1643 # because they are mounted by rcS (for single user mode) rather than 1644 # mountall. 1645 # If this is changed, mountall, umountall and rcS should also change. 1646 /sbin/umountall 1647 /sbin/umount /var/adm >/dev/null 2>\&1 1648 /sbin/umount /var >/dev/null 2>\&1 1649 /sbin/umount /usr >/dev/null 2>\&1 1650 1651 echo 'The system is down.' 1652 1653We need to insert the following lines just before the last 'echo': 1654 1655:: 1656 1657 #see if this is a powerfail situation 1658 if [ -f /etc/apcctrl/powerfail ]; then 1659 echo 1660 echo "APCCTRL will power off the UPS" 1661 echo 1662 /etc/apcctrl/apccontrol killpower 1663 echo 1664 echo "Please ensure that the UPS has powered off before rebooting" 1665 echo "Otherwise, the UPS may cut the power during the reboot!!!" 1666 echo 1667 fi 1668 1669We have included these lines in a file called rc0.solaris in the 1670distributions/sun subdirectory of the source tree. You can cut and 1671paste them into the /sbin/rc0 file at the correct place, or yank 1672and put them using vi or any other editor. Note that you must be 1673root to edit this file. 1674 1675You must be absolutely sure you have them in the right place. If 1676your /sbin/rc0 file does not look like the lines shown above, do 1677not modify the file. Instead, email a copy of the file to the 1678maintainers, and we will attempt to figure out what you should do. 1679If you mess up this file, the system will not shut down cleanly, 1680and you could lose data. Don't take the chance. 1681 1682You will then need to make the normal changes to the 1683/etc/apcctrl/apcctrl.conf file. This file contains the 1684configuration settings for the package. It is important that you 1685set the values to match your UPS model and cable type, and the 1686serial port that you have attached the UPS to. People have used 1687both /dev/ttya and /dev/ttyb with no problems. You should be sure 1688that logins are disabled on the port you are going to use, 1689otherwise you will not be able to communicate with the UPS. If you 1690are not sure that logins are disabled for the port, run the 1691'admintool' program as root, and disable the port. The 'admintool' 1692program is a GUI administration program, and required that you are 1693running CDE, OpenWindows, or another XWindows program such as KDE. 1694 1695Solaris probes the serial ports during boot, and during this 1696process, it toggles some handshaking lines used by dumb UPSes. As a 1697result, particularly for simple signalling "dumb" UPSes it seems to 1698kick it into a mode that makes the UPS think it's either in a 1699calibration run, or some self-test mode. Since at this point we are 1700really not communicating with the UPS, it's pretty hard to tell 1701what happened. But it's easy to prevent this, and you should. 1702Disconnect the UPS, and boot the system. When you get to a login 1703prompt, log in as root. Type the following command: 1704 1705:: 1706 1707 eeprom com1-noprobe=true 1708 1709or 1710 1711:: 1712 1713 eeprom com2-noprobe=true 1714 1715depending on which com port your UPS is attached to. Then sync and 1716shutdown the system normally, reattach the UPS, and reboot. This 1717should solve the problem. However, we have some reports that recent 1718versions of Solaris (7 & 8) appear to have removed this eeprom 1719option and there seems to be no way to suppress the serial port 1720probing during boot. 1721 1722At this point, you should have a complete installation. The daemon 1723will load automatically at the next boot. Watch for any error 1724messages during boot, and check the event logs in /etc/apcctrl. If 1725everything looks OK, you can try testing the package by removing 1726power from the UPS. NOTE! if you have a voltage-signalling UPS, 1727please run the first power tests with your computer plugged into 1728the wall rather than into the UPS. This is because dumb serial-port 1729UPSes have a tendency to power off if your configuration or cable 1730are not correct. 1731 1732As a user, your input is very helpful in solving problems with the 1733package, and providing suggestions and future directions for the 1734development of the package. We are striving to provide a useful 1735package that works across all platforms, and welcome your 1736feedback. 1737 1738 1739Unknown System 1740~~~~~~~~~~~~~~ 1741 1742During the '``./configure``', if apcctrl does not find one of the systems for 1743which it has specific installation programs, it will set the 1744Operating System to ``unknown`` and will use the incomplete 1745installation scripts that are in ``platforms/unknown``. You 1746will be on your own, or you can ask the developers list 1747(apcctrl-users@lists.sourceforge.net) for installation 1748instructions. This directory also contains a hint file for Linux 1749From Scratch, which could be helpful for other systems as well. 1750 1751 1752Windows Systems 1753~~~~~~~~~~~~~~~ 1754 1755Appropriate scripts 1756(actually Windows batch files) are included with the apcctrl Win32 1757installer package. 1758 1759 1760After Installation 1761================== 1762 1763Checking Your Configuration File 1764-------------------------------- 1765 1766Once you have installed apcctrl, 1767either from a binary package or by building from source, your next 1768step should be to inspect your ``/etc/apcctrl/apcctrl.conf`` file to 1769make sure it is valid. 1770 1771You can read the complete reference on configuration directives 1772(`Configuration Directive Reference`_), but if you are 1773setting up a normal standalone configuration you should only need 1774to check (and possibly fix) the first three items listed below. 1775 1776Your ``UPSTYPE`` should be the UPS's protocol type: dumb, apcsmart, 1777usb, net, pcnet, or snmp. Your ``UPSCABLE`` should be the type of cable 1778you are using. 1779 1780``DEVICE`` should be set to the path of the device node 1781(usually in /dev) to use to communicate with the UPS. This is used primarily 1782for serial port connections. If you have a USB device, it is better not to 1783specify a ``DEVICE`` directive by leaving it black or commenting it out. 1784apcctrl will automatically search for your device in the standard places. 1785If you specify a ``DEVICE``, it should be the name of the device that 1786apcctrl is to use to communicate with the UPS. 1787 1788If the first time you execute apcctrl, you get a message to the 1789effect that the apcctrl USB driver is missing, it means that you 1790most likely forgot to put ``--enable-usb`` on your '``./configure``' 1791command line. 1792 1793The `Configuration Examples`_ chapter of this manual provides 1794the essential characteristics of each main type of configuration 1795file. After those elements are correct, apcctrl should run, and 1796then it is only a matter of customization of your setup. 1797 1798 1799Arranging for Reboot on Power-Up 1800-------------------------------- 1801 1802The final consideration for a automatic reboot after a full power down 1803is to ensure that your computer will automatically reboot when the 1804power is restored. 1805 1806This is not the normal behavior of most computers as shipped from 1807the factory. Normally after the power is cut and restored, you must 1808explicitly press a button for the power to actually be turned on. 1809You can test your computer by powering it down; shutting off the 1810power (pull the plug); then plugging the cord back in. If your 1811computer immediately starts up, good. There is nothing more to do. 1812 1813If your computer does not start up, manually turn on the power (by 1814pressing the power on button) and enter your computer's SETUP 1815program (often by pressing DEL during the power up sequence; 1816sometimes by pressing F10). You must then find and change the 1817appropriate configuration parameter to permit instant power on. 1818 1819Normally, this is located under the ``BOOT`` menu item, and will be 1820called something such as ``Restore on AC/Power Loss`` or ``Full-On``. 1821The exact words will vary according to the ROM BIOS provider. 1822Generally you will have three options: ``Last State``, ``Power On``, 1823and ``Power Off``. Although ``Last State`` should normally work, we 1824recommend setting your computers to ``Power On``. This means that 1825whenever the power is applied they are on. The only way to shut 1826them off is to pull the plug or to have a special program that 1827powers them off (/sbin/poweroff on Linux systems). 1828 1829If after making all the changes suggested above, you cannot get 1830your computer to automatically reboot, you might examine your halt 1831script (/etc/rc.d/init.d/halt in the case of Red Hat Linux) and see 1832if the final line that performs the halt or reboot contains the 1833``-p`` option for powering down the computer. It should not with the 1834logic used by apcctrl, but if it does, the ``-p`` option could cause 1835your computer to power off while the UPS is still suppling power 1836(i.e. before the UPS kills the power). Depending on the setting of 1837your BIOS, it may prevent your computer from restarting when the 1838power returns. As already mentioned, this should not apply, but in 1839case of problems it is worth a try. 1840 1841Making sure apcctrl Is Running 1842------------------------------ 1843 1844The simplest way to invoke apcctrl is from the command line by entering: 1845 1846:: 1847 1848 /sbin/apcctrl 1849 1850To do so, you must be root. However, normally, you will want 1851apcctrl started automatically when your system boots. On some 1852systems with installation support (e.g. SUSE and Red Hat), the 1853installation procedure will create a script file that you will be 1854automatically invoked when your system reboots. On other systems, 1855you will have to invoke apcctrl from your rc.local script. 1856 1857On Red Hat systems, this script file that automatically invokes 1858apcctrl on system start and stops is ``/etc/rc.d/init.d/apcctrl`` 1859 1860To start apcctrl manually (as you will probably do immediately 1861following the installation), enter the following: 1862 1863:: 1864 1865 /etc/rc.d/init.d/apcctrl start 1866 1867To understand how this file is automatically invoked at system 1868startup and shutdown, see the man pages for ``chkconfig(8)``. 1869 1870On SUSE systems, the script file that automatically invokes apcctrl 1871on system start and stops is ``/etc/rc.d/apcctrl``. 1872 1873To start apcctrl manually (as you will probably do immediately 1874following the installation), enter the following: 1875 1876:: 1877 1878 /etc/rc.d/apcctrl start 1879 1880Normally, when properly installed, apcctrl will be started and 1881stopped automatically by your system. Unfortunately, the details 1882are different for each system. Below, we give the commands for 1883selected systems. Alternatively, there are simple stopapcctrl and 1884startapcctrl scripts in the examples directory, or you can modify 1885one of the scripts in the distributions directory to meet your 1886needs. 1887 1888To stop apcctrl you can do the following: 1889 1890On Red Hat systems: 1891 1892:: 1893 1894 /etc/rc.d/init.d/apcctrl stop 1895 1896On SUSE systems: 1897 1898:: 1899 1900 /etc/rc.d/apcctrl stop 1901 1902Please see the `Testing apcctrl`_ chapter for more details on insuring 1903that apcctrl is running properly. 1904 1905 1906Configuration Examples 1907====================== 1908 1909A Simple USB Configuration 1910-------------------------- 1911 1912If you have a USB UPS, the essential elements of your apcctrl.conf file 1913should look like the following: 1914 1915:: 1916 1917 ## apcctrl.conf v1.1 ## 1918 UPSCABLE usb 1919 UPSTYPE usb 1920 DEVICE 1921 LOCKFILE /var/lock 1922 UPSCLASS standalone 1923 UPSMODE disable 1924 1925Notice that we have not specified a device. In doing so, apcctrl 1926will try all the well known USB ports. We strongly recommend you 1927use this (empty device address) form unless you have a good reason 1928to do otherwise. 1929 1930Please use the explicit specifications of a device only if you know 1931exactly what you are doing. In general, it is much easier to let 1932apcctrl find the device itself. 1933 1934Please see `USB Configuration`_ for detailed help 1935on setting up your system to work with a USB UPS. 1936 1937 1938A Simple Configuration for a Serial SmartUPS 1939-------------------------------------------- 1940 1941If you have a Smart UPS 1942using the serial cable supplied by APC, or you build a CUSTOM SMART cable 1943outlined in the cables chapter, a very simple configuration file 1944would look like the following: 1945 1946:: 1947 1948 ## apcctrl.conf v1.1 ## 1949 UPSCABLE smart 1950 UPSTYPE apcsmart 1951 DEVICE /dev/ttyS0 1952 LOCKFILE /var/lock 1953 UPSCLASS standalone 1954 UPSMODE disable 1955 1956Normally you would have many more configuration directives to 1957completely customize your installation, but this example shows you 1958the minimum required. 1959 1960 1961A Simple Configuration for a Simple Signaling or Dumb 1962----------------------------------------------------- 1963 1964If you have a simple signaling 1965or dumb UPS such as a BackUPS, you will need to know exactly what 1966cable you have and specify it on the UPSCABLE directive. Please see 1967the list of UPSes versus cables in the beginning of this document 1968for more information. The cable number is normally stamped in the 1969plastic at one end of the cable. If you specify the wrong cable, it 1970is very likely that at the first power failure, your computer will 1971be immediately shutdown. This is an unfortunate consequence of the 1972dumb signaling mode. To avoid this, first replace 1973/etc/apcctrl/apccontrol with safe.apccontrol found in the 1974examples directory, then test until everything works correctly. 1975Once you have the correct cable, be sure to remember to reinstall 1976the correct apccontrol file and test that your computer is 1977correctly shutdown during a power failure. 1978 1979:: 1980 1981 ## apcctrl.conf v1.1 ## 1982 UPSCABLE (number of cable you have) 1983 UPSTYPE dumb 1984 DEVICE /dev/ttyS0 1985 LOCKFILE /var/lock 1986 UPSCLASS standalone 1987 UPSMODE disable 1988 1989If your cable does not have low battery detection, as is the case 1990with some older models, you will also need to define ``TIMEOUT nnn`` 1991where you set ``nn`` to be the number of seconds on a power failure 1992after which a shutdown is effected. 1993 1994Normally you would have many more configuration directives to 1995completely customize your installation, but this example shows you 1996the minimum required. 1997 1998 1999NIS Server/Client Configuration Using the Net Driver 2000---------------------------------------------------- 2001 2002NIS (Network Information Server) mode allows for communication 2003between instances of apcctrl running on different hosts. Only one 2004of those hosts, the server, needs to talk to the UPS directly. The 2005others, clients, obtain information about the state of the UPS by 2006querying the server. NIS is *not* related to Sun's NIS/YP 2007services. 2008 2009NIS clients and servers require that apcctrl be compiled with the 2010Net Driver ``--enable-net``. This is typically enabled by default. 2011 2012The NIS server is connected to the UPS and should be configured 2013exactly as a standalone configuration, but with ``NETSERVER on``. 2014In all other respects, the server should be configured in 2015standalone mode. You may also set the NIS server specific options 2016``NISIP`` to restrict which IP address of the server which apcctrl 2017listens on. The default, 0.0.0.0, means to list on all of the 2018server host's IP addresses; ``NISPORT`` (default 3551) to set which 2019TCP port the server listens on; and ``EVENTSFILE`` and 2020``EVENTSFILEMAX`` to provide information about the last few events 2021to clients. You may also need to modify your firewall rules on the 2022server's host to allow traffic to the ``NISPORT``. 2023 2024For the NIS client computer, you will have a configuration that 2025looks something like what follows. What is important is that you 2026get the information from an ``UPSCABLE ether`` with ``UPSTYPE 2027net`` over the network and you must specify the address of 2028a NIS server using ``DEVICE``. The client apcctrl will then poll 2029the NIS server specified in ``DEVICE`` every ``POLLTIME`` seconds 2030(formerly ``NETTIME``). 2031 2032:: 2033 2034 ## apcctrl.conf v1.1 ## 2035 UPSCABLE ether 2036 UPSTYPE net 2037 LOCKFILE /var/lock 2038 DEVICE server-network-address:3551 2039 UPSCLASS standalone 2040 UPSMODE disable 2041 POLLTIME 10 2042 2043The ``DEVICE`` is set to ``server-address:port``, where 2044``server-address`` is the fully qualified domain name or IP address 2045of the apcctrl NIS server, and ``port`` is the ``NISPORT`` that the 2046server is listening on. The default is 3551, but older versions of 2047apcctrl used port 7000. 2048 2049If you set ``POLLTIME`` too large, your client may not see the 2050change in state of the NIS server before the server has shutdown. 2051Normally, you have at least 30 seconds of grace time between the 2052time the NIS server decides to shutdown and the time it no longer 2053responds. Your slave must poll during this interval. 2054 2055Any client run using the Net driver will shutdown when its own 2056timers expire or when the NIS server shuts down, whichever occurs 2057first. This means that if you want the slave to shutdown before the 2058server, you need only set ``BATTERYLEVEL``, ``MINUTES`` or 2059``TIMEOUT`` on the client for a faster shutdown than the values 2060defined on the NIS server. This can often be useful if the slave is 2061less important than the master and you wish to reduce battery power 2062consumption so that the master can remain up longer during a power 2063outage. 2064 2065NIS clients work principally by reading the STATFLAG record that is 2066sent by the NIS server (present in the output of apcaccess). The 2067low 16 bits are the standard APC status flag, and the upper 16 bits 2068represent the internal state of apcctrl, so the slave can see when 2069the power fails and know when to shutdown. 2070 2071It would be possible to have a client also work as a server, but 2072that would increase the delay of information getting from the UPS 2073to the secondary client. 2074 2075 2076Differences between NIS Client/Server and the old (now removed) Master/Slave modes 2077~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2078 2079The difference between the NIS mode and the removed master/slave 2080mode is that the NIS server has no explicit knowledge of the 2081slaves. The NIS server makes its information available via the net 2082(NIS), and the NIS slaves read it. When the NIS server is going to 2083shutdown, it makes the information available to any NIS slave that 2084polls it, but the NIS server does not explicitly call each NIS 2085slave as is the case in the Master/Slave networking described 2086several sections above. 2087 2088Think of the difference as push (Master/Slave) vs. pull 2089(NIS-based). In the case of M/S, the master makes all the shutdown 2090decisions and notifies the slaves when they are to shut down or 2091when some other interesting event happens. The slaves just do 2092whatever the master says, whenever the master says to. On the other 2093hand, with the NIS-based network config you basically "publish" the 2094UPS status from one server and then your clients view that status 2095and make their own decisions. 2096 2097 2098PowerChute Network Shutdown Driver (PCNET) 2099------------------------------------------ 2100 2101As of 3.14, apcctrl supports the PowerChute Network Shutdown 2102protocol. This is an alternative to SNMP for use with APC's AP9617 2103family of network smartslot modules. Note that the older AP9606 2104modules do **not** support PCNET. 2105 2106To enable PCNET support, configure with the ``--enable-pcnet`` 2107flag. This is typically enabled by default. 2108 2109The required apcctrl.conf settings are straightforward: 2110 2111:: 2112 2113 ## apcctrl.conf v1.1 ## 2114 UPSCABLE ether 2115 UPSTYPE pcnet 2116 LOCKFILE /var/lock 2117 DEVICE ipaddr:user:passphrase 2118 UPSCLASS standalone 2119 UPSMODE disable 2120 2121The ``DEVICE`` setting specifies the IP address of the UPS as well 2122as the username and authentication passphrase to use. Note that the 2123username and passphrase are **not** the Web/SNMP login credentials. 2124They are separate settings. The default username on a new card is 2125"``apc``" and the default passphrase is "``admin user phrase``". To change 2126the passphrase, log in to the Web UI and go to the UPS tab, then to 2127PowerChute -> Configuration. (This assumes firmware v3.3.1. Other 2128versions may place the setting elsewhere.) *The password must be a 2129minimum of 15 characters long.* The web UI will silently ignore 2130shorter passwords and does not give an error message. There is no 2131apparent way to change the username. 2132 2133Note that you may leave ``DEVICE`` blank and apcctrl will accept 2134information from any PCNET UPS on the network, 2135**however it will be very insecure since an attacker could easily send packets 2136crafted to cause your server to shut down**. 2137Using the ``ipaddr``, ``user``, and ``passphrase`` will prevent this behavior. 2138 2139You may need to take steps to ensure networking stays active during 2140your OS's shutdown sequence in order for the PCNET driver to power 2141off the UPS (the so-called "killpower" operation). On a Linux 2142distro, you can use commands such as... 2143 2144:: 2145 2146 chkconfig --level 0 network on 2147 chkconfig --level 0 iptables on 2148 2149...to make sure networking stays up. 2150 2151 2152MODBUS Driver 2153------------- 2154 2155MODBUS is APC's replacement for the aging 'apcsmart' (aka UPS-Link) 2156protocol. It is recommended for modern (ex: SMT series) Smart-UPS models. 2157As of 3.14.11, apcctrl supports the MODBUS protocol over RS232 serial 2158interfaces. As of 3.14.13, apcctrl supports the MODBUS protocol over USB. 2159 2160Not all APC UPSes support MODBUS. New 2013 year Smart-UPS models are likely to 2161support it out-of-the-box and firmware updates are available for some older 2162models. APC/Schneider tech support is your best point of contact for determining 2163if a certain model will support MODBUS. That said, APC knowledge base article 2164FA164737 indicates MODBUS support is available for the majority of the SMC, 2165SMT, and SMX model lines. 2166 2167The required apcctrl.conf settings for MODBUS are straightforward. 2168 2169For MODBUS serial RS232: 2170 2171 :: 2172 2173 ## apcctrl.conf v1.1 ## 2174 UPSCABLE smart 2175 UPSTYPE modbus 2176 DEVICE /dev/ttyS0 2177 LOCKFILE /var/lock 2178 UPSCLASS standalone 2179 UPSMODE disable 2180 2181 The ``DEVICE`` setting identifies the serial port to which the UPS is connected. 2182 This can take the form of ``COM1``, etc. on Windows or ``/dev/XXX`` on UNIX 2183 systems. 2184 2185 You should use the APC-supplied serial cable (P/N 940-0625A) that ships with 2186 the UPS. Other 'smart' type cables may work, but only 940-0625A has been 2187 formally tested at this time. 2188 2189For MODBUS USB: 2190 2191 :: 2192 2193 ## apcctrl.conf v1.1 ## 2194 UPSCABLE usb 2195 UPSTYPE modbus 2196 DEVICE 2197 LOCKFILE /var/lock 2198 UPSCLASS standalone 2199 UPSMODE disable 2200 2201 The ``DEVICE`` setting can be left blank or, optionally, set to the serial 2202 number of the UPS. If ``DEVICE`` is blank, apcctrl will attach to the first 2203 APC UPS it finds, otherwise it will attach to the specific UPS identified by 2204 the serial number. 2205 2206Note that *most UPSes ship with MODBUS support disabled by default*. You must 2207use the UPS's front panel menu to enable MODBUS protocol support before apcctrl 2208will be able to communicate with the UPS. You may need to enable the "Advanced" 2209menu option before the MODBUS protocol option will be visible. 2210 2211 2212Testing apcctrl 2213=============== 2214 2215The following testing procedures apply for the 2216most part to SmartUPSes, whether USB or serial. If you have a 2217dumb voltage-signalling UPS, your testing procedures will be 2218somewhat different, and you should see the section on Testing 2219Serial UPSes (see `Testing Serial-Line UPSes`_). 2220 2221Process-Status Test 2222------------------- 2223 2224After you start apcctrl, execute the following command: 2225 2226:: 2227 2228 ps fax 2229 2230or the equivalent for your system. You should see something similar 2231to the following output. 2232 2233:: 2234 2235 632 ? S 0:00 /sbin/apcctrl -f /etc/apcctrl/apcctrl.conf 2236 841 ? S 0:00 \_ /sbin/apcctrl -f /etc/apcctrl/apcctrl.conf 2237 842 ? S 0:00 \_ /sbin/apcctrl -f /etc/apcctrl/apcctrl.conf 2238 2239This indicates that apcctrl is up and running and has started the 2240two standard threads in addition to the main thread. 2241 2242If you see only one instance of apcctrl running, don't worry about 2243it as this is normal on most non-Linux systems, and on Linux 2.6.x 2244kernels. 2245 2246If you do not find that apcctrl is in the above list, the most 2247likely problem is a configuration file glitch. If no messages were 2248printed, you should check your system log (normally 2249``/var/log/messages``) where you will find one or messages indicating 2250the nature of the problem. 2251 2252 2253Logging Test 2254------------ 2255 2256Once you have established that the proper processes are running, do 2257a tail of the system log file, normally ``/var/log/messages``: 2258 2259:: 2260 2261 tail /var/log/messages 2262 2263You should see output that looks similar to the following: 2264 2265:: 2266 2267 Dec 5 17:01:05 matou apcctrl[5917]: apcctrl 3.7.2 startup succeeded 2268 2269These messages should also appear in the temporary file 2270(``/etc/apcctrl/apcctrl.events``) if you are using the default 2271configuration file. If you have installed the RPM, they will 2272probably be in ``/var/log/apcctrl.events``. 2273 2274 2275apcaccess Test 2276-------------- 2277 2278This test consists of running ``apcaccess`` to see if apcctrl is properly 2279updating its internal variables. Please note that you must enable 2280the apcctrl Network Information Server in your configuration file 2281for ``apcaccess`` to work. This is done by setting: 2282 2283:: 2284 2285 NETSERVER on 2286 NISPORT 3551 2287 2288in your ``apcctrl.conf`` file. 2289 2290To run the apcaccess test, use the following command: 2291 2292:: 2293 2294 apcaccess status 2295 2296Depending on the type of UPS you have, you will get slightly 2297different output, but an example For a Smart-UPS is as follows: 2298 2299:: 2300 2301 APC : 001,048,1088 2302 DATE : Fri Dec 03 16:49:24 EST 1999 2303 HOSTNAME : daughter 2304 RELEASE : 3.7.2 2305 CABLE : APC Cable 940-0024C 2306 MODEL : APC Smart-UPS 600 2307 UPSMODE : Stand Alone 2308 UPSNAME : SU600 2309 LINEV : 122.1 Volts 2310 MAXLINEV : 123.3 Volts 2311 MINLINEV : 122.1 Volts 2312 LINEFREQ : 60.0 Hz 2313 OUTPUTV : 122.1 Volts 2314 LOADPCT : 32.7 Percent Load Capacity 2315 BATTV : 26.6 Volts 2316 BCHARGE : 095.0 Percent 2317 MBATTCHG : 15 Percent 2318 TIMELEFT : 19.0 Minutes 2319 MINTIMEL : 3 Minutes 2320 SENSE : Medium 2321 DWAKE : 000 Seconds 2322 DSHUTD : 020 Seconds 2323 LOTRANS : 106.0 Volts 2324 HITRANS : 129.0 Volts 2325 RETPCT : 010.0 Percent 2326 STATFLAG : 0x08 Status Flag 2327 STATUS : ONLINE 2328 ITEMP : 34.6 C Internal 2329 ALARMDEL : Low Battery 2330 LASTXFER : Unacceptable Utility Voltage Change 2331 SELFTEST : NO 2332 STESTI : 336 2333 DLOWBATT : 05 Minutes 2334 DIPSW : 0x00 Dip Switch 2335 REG1 : N/A 2336 REG2 : N/A 2337 REG3 : 0x00 Register 3 2338 MANDATE : 03/30/95 2339 SERIALNO : 13035861 2340 BATTDATE : 05/05/98 2341 NOMOUTV : 115.0 2342 NOMBATTV : 24.0 2343 HUMIDITY : N/A 2344 AMBTEMP : N/A 2345 EXTBATTS : N/A 2346 BADBATTS : N/A 2347 FIRMWARE : N/A 2348 APCMODEL : 6TD 2349 END APC : Fri Dec 03 16:49:25 EST 1999 2350 2351For a simple signaling or dumb UPS such as BackUPS, your output 2352will be very minimal as follows: 2353 2354:: 2355 2356 APC : 001,012,0319 2357 DATE : Mon Feb 18 09:11:50 CST 2002 2358 RELEASE : 3.8.5 2359 UPSNAME : UPS_IDEN 2360 CABLE : APC Cable 940-0128A 2361 MODEL : BackUPS 2362 UPSMODE : Stand Alone 2363 STARTTIME: Mon Feb 18 09:11:45 CST 2002 2364 LINEFAIL : OK 2365 BATTSTAT : OK 2366 STATFLAG : 0x008 Status Flag 2367 END APC : Mon Feb 18 09:15:01 CST 2002 2368 2369If you see the above output, it is a good sign that apcctrl is 2370working. Assuming that the output looks reasonable, check the 2371following variables: 2372 2373``LINEV`` 2374 This is the line voltage and it should be a value 2375 that is appropriate for your equipment. In the USA, it is typically 2376 about 120 Volts while in Europe, it is about 220 Volts. 2377 2378``BATTV`` 2379 Unless you have additional battery packs, this 2380 should be near 24 Volts plus or minus 5 Volts. 2381 2382``STATUS`` 2383 This is the status of the UPS and it should 2384 normally be ``ONLINE``. 2385 2386A very disturbing tendance is for some of the newer (Mar 2004) RS 2387and ES UPSes to have no Voltage information. This is an annoying bug, 2388but not serious. On the other hand, some of those UPSes now have no 2389battery charge information ``BCHARGE``. If ``BCHARGE`` is zero in your 2390listing and you are running a Smart or a USB UPS, then you will 2391have to set the ``BATTERYLEVEL`` directive in your apcctrl.conf file to 2392-1. 2393 2394If you see a message to the effect of: 2395 2396:: 2397 2398 APCACCESS FATAL ERROR in apcaccess.c at line 336 2399 tcp_open: cannot connect to server localhost on port 3551. 2400 2401It means that you have probably not enabled the Network Information 2402Server in your configuration file for ``apcaccess`` to work. This is 2403done by setting ``NETSERVER`` and ``NISPORT`` in your apcctrl.conf file 2404as shown above. 2405 2406 2407Communications Test 2408------------------- 2409 2410At this point, you should ensure 2411that apcctrl is handling the connection to the UPS correctly. This 2412test assumes you have a UPS that speaks apcsmart protocol, over 2413either USB or a serial port. If you have an old-style 2414voltage-signaling UPS, please skip to the next section (`Simulated 2415Power Fail Test`_). 2416 2417When apcctrl detects a problem, it generates an EVENT, which 2418consists of sending a message to the system log then invoking the 2419``apccontrol`` script (normally in /etc/acpupsd/apccontrol) to handle 2420the event. 2421 2422In order to create an event, remove the serial port plug from the 2423back of your computer or from the back of the UPS. Within 6 2424seconds, apcctrl should detect the lack of serial port 2425communications and broadcast a ``wall`` message indicating that the 2426serial port communications was lost: 2427 2428:: 2429 2430 Warning communications lost with UPS lost. 2431 2432At the same time, it sends the same message to the system log and 2433to the temporary EVENTS file (``/etc/apcctrl/apcctrl.events``). 2434 2435Plug the serial port plug back into your computer, and within about 243612 seconds, apcctrl should reestablish communications and broadcast 2437and log the following message: 2438 2439:: 2440 2441 Communications with UPS restored. 2442 2443If these messages are logged but not broadcast, either you have 2444your ``mesg`` permission set to ``no`` (see '``man wall``' or '``man mesg``'), 2445or there is a problem with apccontrol. If you are running a window 2446manager such as GNOME and don't have a console window open, you may 2447not receive the ``wall`` messages. However, you should find them in 2448your system log file (normally ``/var/log/messages``) and in the 2449temporary EVENTS file, ``/etc/apcctrl/apcctrl.events``. For example, to 2450observe these events in the temporary EVENTS file, you might do a 2451 2452:: 2453 2454 tail -f /etc/apcctrl/apcctrl.events 2455 2456Note, if you have installed from the RPM, the proper events file 2457may be ``/var/log/apcctrl.events``. You can find the actual filename by 2458checking your apcctrl.conf file before running the test. 2459 2460If you do not observe these messages, you should correct this 2461problem before proceeding with additional tests. 2462 2463 2464Simulated Power Fail Test 2465------------------------- 2466 2467At this point, you should 2468verify that in the event of a power fail apcctrl properly calls 2469apccontrol. This test is appropriate for all models of UPSes (smart 2470or dumb). 2471 2472To avoid the possibility that apcctrl might shut down your system, 2473locate where apccontrol resides on your system (normally, 2474/etc/apcctrl/apccontrol. Move this script to another location e.g. 2475apccontrol.save and replace it with the script found in 2476examples/safe.apccontrol. When that is done, ensure that your UPS 2477battery is fully charged and that you have at least 5 minutes of 2478remaining runtime on the batteries. This can be done by examining 2479the values of the ``BATTCHG`` and ``TIMELEFT`` variables in the 2480printout of '``apcaccess status``'. 2481 2482Athough this should not be necessary, as an extra precaution, you 2483can shutdown your machine, remove the plug from the UPS you are 2484testing, and plug your machine into another UPS or directly into 2485the wall. Doing so, will ensure that the UPS doesn't cut the power 2486to your machine at a bad time. Remember at the end of the testing 2487to plug your machine back into the UPS. 2488 2489You can also minimize the risk from an unexpected shutdown by using 2490a journaling filesystem such as Linux's EXT3. All modern disk 2491drives park themselves safely when they power down, rather than 2492ploughing up oxide on your disk's recording surface. Thus, 2493unexpected power less has to hit very narrow timing windows in 2494order to trash an EXT3 transaction. 2495 2496To begin the test, pull the power plug from the UPS. The first time 2497that you do this, psychologically it won't be easy, but after you 2498have pulled the plug a few times, you may even come to enjoy it. If 2499all goes well, apcctrl should detect the power failure and print 2500several warning messages. The first should appear after 5 to 6 2501seconds and read: 2502 2503:: 2504 2505 Warning power loss detected. 2506 2507Then generally 6 seconds later, apcctrl is sure that it isn't a 2508transient effect, so it sends: 2509 2510:: 2511 2512 Power failure. Running on UPS batteries. 2513 2514After a few more seconds (total around 15 seconds), plug the power 2515cord back in and ensure that apcctrl is aware that the power has 2516returned. It should print: 2517 2518:: 2519 2520 Power has returned... 2521 2522If you do not observe the above messages, please correct the 2523situation before proceeding. The most likely cause of problems 2524are: 2525 2526 2527- apcctrl doesn't recognize the power failure because the 2528 configuration directives are not correct. E.g. wrong cable. 2529 2530- The file ``/etc/apcctrl/apccontrol`` doesn't exist or is not marked 2531 as executable. 2532 2533 2534System Shutdown Test 2535-------------------- 2536 2537This is an intermediate 2538test that you can do, for all UPS models before doing the Full 2539Power Down Test. First modify the ``/etc/apcctrl/apccontrol`` file so 2540that in the ``killpower`` case, the line that re-executes apcctrl 2541with the ``--killpower`` option is commented out. The original 2542line probably looks something like: 2543 2544:: 2545 2546 ${APCCTRL} --killpower 2547 2548when it is commented out, it looks like: 2549 2550:: 2551 2552 #${APCCTRL} --killpower 2553 2554Now when you pull the power plug, and either the timer expires or 2555the batteries are exhausted (see the next section for more 2556details), the system should be fully shutdown. 2557 2558After performing this test, please be sure to restore 2559``/etc/apcctrl/apccontrol`` to its previous state. 2560 2561 2562Full Power Down Test 2563-------------------- 2564 2565To complete the testing, you should do a power fail shutdown of your 2566system. This test is applicable to all UPS models. Please do a 2567backup of your system or take other precautions before attempting 2568this to avoid the possibility of lost data due to a problem (I have 2569been through this at least 10 times and never once had problems, 2570but we all know that someday something will go wrong). 2571 2572Before proceeding, please ensure that your halt script or the 2573equivalent has been properly updated by the install process to 2574contain the logic to call ``apcctrl --killpower`` or ``apccontrol killpower`` 2575when it detects a power failure situation (the presence of a /etc/powerfail 2576file). See the `Building and Installing apcctrl`_ section of this manual, 2577or the README files for additional details about the halt modifications 2578necessary. 2579 2580When you are ready to do the test, either simply pull the plug and 2581wait for the batteries to become exhausted, or set the ``TIMEOUT`` 2582configuration directive to something like 60 so that the system 2583will shutdown before the batteries are exhausted. We recommend 2584doing the full shutdown without using ``TIMEOUT`` to correctly 2585simulate a real power failure, but the choice is yours (I did it 2586once here, but now use ``TIMEOUT 30``). 2587 2588If all goes well, your system should be shutdown before the 2589batteries are completely exhausted and the UPS should be powered 2590off by apcctrl. Please be aware that if you do the full power down, 2591you must ensure that your UPS is totally powered off. Otherwise, it 2592may have been given the command to power off, but due to a long 2593grace period it is still waiting. If you were to reboot your 2594computer during the grace period, the UPS could then suddenly turn 2595off the power (this happened to me). To avoid this problem, always 2596wait for your UPS to power itself off, or power if off manually 2597before restarting your computer. On my system, the UPS is 2598configured as at the factory to have a 180 second grace period 2599before shutting off the power. During this type of testing, 180 2600seconds *seems* like an eternity, so please take care to either 2601wait or manually power off your UPS. To determine what grace period 2602is programmed into your UPS EEPROM, run '``apcaccess eprom``' and look 2603at the "Shutdown grace delay". 2604 2605If you experienced so problems with 2606the above testing procedures, or if you are porting apcctrl to 2607another system, or you are simply curious, you may want to know 2608exactly what is going on during the shutdown process. If so, please 2609see the `Shutdown Sequence`_ section of this manual. 2610 2611 2612apctest 2613------- 2614 2615``apctest`` is a program that allows you to talk 2616directly to your UPS and run certain low-level tests, adjust various settings 2617such as the battery installation date and alarm behavior, and perform a 2618battery runtime calibration. Here we describe how to use it for a SmartUPS 2619utilizing the apcsmart driver and RS232 serial connection. 2620The menus and options for USB, MODBUS, and simple signaling UPSes are different 2621but mostly self-explanatory. 2622 2623*Shutdown apcctrl if it is running.* This is important. Only one program can 2624communicate with the UPS at a time and if apcctrl is running, apctest will fail 2625to contact the UPS. 2626 2627Run apctest by invoking it with no arguments. 2628 2629It will read your installed apcctrl.conf configuration (so it knows 2630where to find the UPS) and then it will present you with the 2631following output: 2632 2633:: 2634 2635 2003-07-07 11:19:21 apctest 3.10.6 (07 July 2003) redhat 2636 Checking configuration ... 2637 Attached to driver: apcsmart 2638 sharenet.type = DISABLE 2639 cable.type = CUSTOM_SMART 2640 2641 You are using a SMART cable type, so I'm entering SMART test mode 2642 mode.type = SMART 2643 Setting up serial port ... 2644 Creating serial port lock file ... 2645 Hello, this is the apcctrl Cable Test program. 2646 This part of apctest is for testing Smart UPSes. 2647 Please select the function you want to perform. 2648 2649 1) Query the UPS for all known values 2650 2) Perform a Battery Runtime Calibration 2651 3) Abort Battery Calibration 2652 4) Monitor Battery Calibration progress 2653 5) Program EEPROM 2654 6) Enter TTY mode communicating with UPS 2655 7) Quit 2656 2657 Select function number: 1 2658 2659Item 1 will probe the UPS for all values known to apcctrl and 2660present them in rather raw format. This output can be useful for 2661providing technical support if you are having problems with your 2662UPS. 2663 2664Item 2 will perform a Battery Runtime Calibration. This test will 2665only be performed if your battery is 100% charged. Running the test 2666will cause the batteries to be discharged to approximately 30% of 2667capacity. The exact number depends on the UPS model. In any case, 2668apctest will abort the test if it detects that the battery charge 2669is 20% or less. 2670 2671The advantage of doing this test is that the UPS will be able to 2672recalibrate the remaining runtime counter that it maintains in its 2673firmware. As your batteries age, they tend to hold less of a 2674charge, so the runtime calibration may not be accurate after 2675several years. 2676 2677We recommend that perform a Battery Calibration about once a year. 2678You should not perform this calibration too often since discharging 2679the batteries tends to shorten their lifespan. 2680 2681Item 3 can be used to abort a Battery Calibration in progress, if 2682you some how became disconnected. 2683 2684Item 4 can be used to restart the monitoring of a Battery 2685Calibration if you should some how become disconnected during the 2686test. 2687 2688Item 5 is used to program the EEPROM. Please see the `Configuration 2689Directives Used to Set the UPS EEPROM`_ chapter of this manual for the 2690details. 2691 2692Item 6 will initiate a direct communication between your terminal 2693and the UPS, at which point you can enter raw UPS commands. Please 2694be aware that you should be careful what commands you enter because 2695you can cause your UPS to suddenly shutdown, or you can modify the 2696EEPROM in a way to disable your UPS. The details of the raw Smart 2697mode UPS commands can be found in the `APC Smart Protocol`_ 2698chapter of this manual. 2699 2700Item 7 will terminate apctest. 2701 2702 2703Monitoring and Tuning your UPS 2704============================== 2705After you have verified 2706that your UPS is working correctly, you will probably want to query 2707the state of its health occasionally. The tools apcctrl gives you 2708to do this include one command-line utility (apcaccess) and a GUI 2709you can use through a Web browser. You can also use apctest to tune 2710some parameters of the UPS itself. 2711 2712 2713apcaccess 2714--------- 2715 2716``apcaccess`` is a program (normally found in 2717``/sbin/apcaccess``) that permits you to print out the complete status 2718of your UPS. 2719 2720apcaccess will use the Network Information Server to obtain the 2721necessary information. You 2722can specify a second optional argument to apcaccess in the form of 2723``host:port`` where the ``:port`` is optional. The default is 2724``localhost:3551``. Please note that in versions prior to 3.10.6, the 2725default NIS port was 7000, so if you are mixing versions, you will 2726need to take a lot of care to ensure that all components are using 2727the same port. 2728 2729To enable the apcctrl Network Information Server, which is normally 2730the default, you set: 2731 2732:: 2733 2734 NETSERVER on 2735 NISPORT 3551 2736 2737in your ``apcctrl.conf`` file. 2738 2739The full form of the apcaccess command is: 2740 2741:: 2742 2743 apcaccess status localhost:3551 2744 2745where only apcaccess status should normally be needed. localhost 2746may be replaced by any machine name, fully qualified domain name, 2747or IP address, which means that apcaccess can access any UPS on the 2748network running the Network Information Server. 2749 2750The ``status`` command line option of apcaccess will produce a full 2751printout of all the STATUS variables used by apcctrl. This can 2752be very helpful for checking the condition of your UPS and to know 2753whether or not apcctrl is properly connected to it. 2754 2755Please note that if you invoke apcaccess within the first 30 2756seconds of launching apcctrl, you will likely get an error message 2757such as: 2758 2759:: 2760 2761 APCACCESS FATAL ERROR in apcaccess.c at line 336 2762 tcp_open: cannot connect to server localhost on port 3551. 2763 2764This is because apcctrl is still in the process of initializing the 2765UPS. The solution is to wait at least 30 seconds after starting apcctrl 2766before launching apcaccess. 2767 2768For a SmartUPS 1000 apcaccess will emit the following output: 2769 2770:: 2771 2772 DATE : Fri Dec 03 12:34:26 CET 1999 2773 HOSTNAME : matou 2774 RELEASE : 3.7.0-beta-1 2775 CABLE : Custom Cable Smart 2776 MODEL : SMART-UPS 1000 2777 UPSMODE : Stand Alone 2778 UPSNAME : UPS_IDEN 2779 LINEV : 232.7 Volts 2780 MAXLINEV : 236.6 Volts 2781 MINLINEV : 231.4 Volts 2782 LINEFREQ : 50.0 Hz 2783 OUTPUTV : 232.7 Volts 2784 LOADPCT : 11.4 Percent Load Capacity 2785 BATTV : 27.7 Volts 2786 BCHARGE : 100.0 Percent 2787 MBATTCHG : 5 Percent 2788 TIMELEFT : 112.0 Minutes 2789 MINTIMEL : 3 Minutes 2790 SENSE : Low 2791 DWAKE : 060 Seconds 2792 DSHUTD : 180 Seconds 2793 LOTRANS : 204.0 Volts 2794 HITRANS : 253.0 Volts 2795 RETPCT : 050.0 Percent 2796 STATFLAG : 0x08 Status Flag 2797 STATUS : ONLINE 2798 ITEMP : 29.2 C Internal 2799 ALARMDEL : Low Battery 2800 LASTXFER : U command or Self Test 2801 SELFTEST : NO 2802 STESTI : 336 2803 DLOWBATT : 02 Minutes 2804 DIPSW : 0x00 Dip Switch 2805 REG1 : 0x00 Register 1 2806 REG2 : 0x00 Register 2 2807 REG3 : 0x00 Register 3 2808 MANDATE : 01/05/99 2809 SERIALNO : GS9902009459 2810 BATTDATE : 01/05/99 2811 NOMOUTV : 230.0 2812 NOMBATTV : 24.0 2813 HUMIDITY : N/A 2814 AMBTEMP : N/A 2815 EXTBATTS : 0 2816 BADBATTS : N/A 2817 FIRMWARE : 60.11.I 2818 APCMODEL : IWI 2819 END APC : Fri Dec 03 12:34:33 CET 1999 2820 2821For the various smaller, cheaper APC USB UPSes, such as the CS, ES, 2822..., you will get much of the information that is presented above, 2823but not all of it. For example, you will not get ``MAXLINEV``, 2824``MINLINEV``, ``LINEFREQ``, ... and in particular, the LOADPCT will be zero 2825when you are running on mains. ``LOADPCT`` will display when the UPS is 2826on batteries. You must remember that the non-SmartUPSes are much 2827simpler (and less expensive) and therefore produce less 2828information. 2829 2830 2831apcctrl Notification and Events 2832------------------------------- 2833 2834When a major event is 2835generated within apcctrl, control is passed to the script 2836apccontrol normally found in /etc/apcctrl/apccontrol. The event 2837name, and a number of other important parameters are passed to the 2838script. 2839 2840The major function of the apccontrol script is to perform a 2841shutdown of the system (as well as the killpower operation). In 2842addition, another major task for this script is to notify you by 2843email when certain events such as powerfail occur. 2844 2845Since apccontrol is a script, you can customize it to your own 2846needs using any text editor. To do so, you must have a minimal 2847knowledge of Unix shell programming. In addition, another feature 2848is that you can write your own scripts that will be automatically 2849called by apccontrol before any of its own code is executed. 2850Details of the events and how to program them are contained in the 2851Advanced topics section entitled `Customizing Event Handling`_. 2852 2853 2854apcctrl Network Monitoring (CGI) Programs 2855----------------------------------------- 2856 2857There are four CGI programs (multimon.cgi, upsstats.cgi, upsfstats.cgi, and 2858upsimage.cgi). To have them properly installed, you must run the 2859'``./configure``' command with ``--enable-cgi`` and you should 2860specify an installation directory with ``--with-cgi-bin=`` or 2861load them manually. The default directory for installation of the 2862CGI programs is ``/etc/apcctrl``, which is not really where you want 2863them if you are going to use them. Normally, they should go in the 2864cgi-bin of your Web server. 2865 2866Once built and loaded, they will give you the status of your UPS or 2867UPSes via a web browser. 2868 2869Normally only ``multimon.cgi`` is directly invoked by the user. 2870However, it is possible to directly invoke ``upsstats.cgi`` and 2871``upsfstats.cgi``. ``upsimage.cgi`` should never be directly invoked as it 2872is used by ``upsstats.cgi`` to produce the bar charts. 2873 2874Setting up and Testing the CGI Programs 2875~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2876 2877Before using multimon and the other CGI programs, first ensure that 2878apcctrl is configured to run the Network Information Server. This 2879is done by setting ``NETSERVER on`` in /etc/apcctrl/apcctrl.conf. 2880This switch is on by default. 2881 2882Next you must edit the hosts file /etc/apcctrl/hosts.conf and at 2883the end, add the name of the hosts you want to monitor and a label 2884string for them. For example: 2885 2886:: 2887 2888 MONITOR matou "Server" 2889 MONITOR polymatou "Backup server" 2890 MONITOR deuter "Disk server" 2891 2892matou, polymatou, and deuter are the network names of the three 2893machines currently running apcctrl. Please note that the network 2894names may either be IP addresses or fully qualified domain names. 2895The network name (or IP address) may optionally be followed by 2896``:port``, where the port is the NIS port address you wish to use. 2897This is useful if you are running multiple copies of apcctrl on the 2898same system or if you are running in a mixed vendor environment 2899where the NIS port assignments differ. An example could be the 2900following: 2901 2902:: 2903 2904 MONITOR matou "Server" 2905 MONITOR polymatou "Backup server" 2906 MONITOR deuter "Disk server" 2907 MONITOR polymatou:7001 "APC USB UPS" 2908 2909where the USB copy of apcctrl has been configured to use port 7001 by 2910modifying apcctrl.conf. Note, the default NIS port is 3551 on most 2911platforms. 2912 2913To test multimon.cgi, you can execute it as non-root directly from 2914the source cgi build directory. To do so, enter at a shell prompt: 2915 2916:: 2917 2918 ./multimon.cgi 2919 2920If everything is set up correctly, it will print a bunch of HTML 2921with the values of the machines that you have put in the hosts.conf 2922file. It should look something like the following (note, only a 2923small portion of the output is reproduced here): 2924 2925:: 2926 2927 Content-type: text/html 2928 2929 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" 2930 "http://www.w3.org/TR/REC-html40/loose.dtd"> 2931 <HTML> 2932 <HEAD><TITLE>Multimon: UPS Status Page</TITLE></HEAD> 2933 <BODY BGCOLOR="#FFFFFF"> 2934 <TABLE BGCOLOR="#50A0A0" ALIGN=CENTER> 2935 <TR><TD> 2936 <TABLE CELLPADDING=5> 2937 <TR> 2938 <TH COLSPAN=10 BGCOLOR="#60B0B0"> 2939 <FONT SIZE="+2">APCCTRL UPS Network Monitor</FONT> 2940 <BR>Sun Jan 16 12:07:27 CET 2000</TH> 2941 </TR> 2942 <TR BGCOLOR="#60B0B0"> 2943 <TH COLSPAN=1>System</TH> 2944 <TH COLSPAN=1>Model</TH> 2945 <TH COLSPAN=1>Status</TH> 2946 ... 2947 2948If you do not get similar output, check the permissions of the 2949/etc/apcctrl directory and of those of /etc/apcctrl/hosts.conf to 2950ensure that your web server can access it. At many sites, the Apache 2951server is not running as root, so you must be 2952careful to ensure that that /etc/apcctrl/hosts.conf and 2953/etc/apcctrl/multimon.conf are world readable. 2954 2955To invoke multimon in your Web browser, enter: 2956 2957``http://your-site/cgi-bin/multimon.cgi`` 2958 2959You should get something similar to the screen shot shown below. 2960 2961If you wish additional control over the colors, type faces, and 2962sizes of the multimon output, you may simply edit the apcctrl.css 2963file to specify the styles you prefer. 2964 2965Using the CGI Programs on Windows 2966~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2967 2968The CGI programs compiled for Windows are included in the Windows package 2969starting with apcctrl-3.14.7. 2970 2971The CGI programs included with the Windows package are intended 2972to be run on Windows. If your web server is running on Linux or another 2973operating system, you will need to obtain binary packages for that platform 2974(or build them from source) instead. The windows build of the CGI programs has 2975been tested with the Apache web server for Win32. They should also work with MS 2976Internet Information Server (IIS). 2977 2978To use the programs, copy the contents of the ``cgi/`` directory from your 2979apcctrl installation directory to the ``cgi-bin/`` directory of your web server. 2980Consult your web server's documentation for how to enable CGI programs to be 2981executed. Sometimes special security settings are required. 2982 2983Configure the hosts.conf file as described above. The programs expect to find 2984the ``hosts.conf`` file and the ``apcctrl.css`` file in the directory 2985``\apcctrl\etc\apcctrl`` on the same drive letter as the web server's 2986``cgi-bin`` directory. If you installed apcctrl into ``C:\apcctrl`` (the 2987default) and your web server's ``cgi-bin/`` directory is also located on the 2988``C:`` drive, no further changes are necessary. If you installed apcctrl into a 2989different directory or your web server ``cgi-bin`` is on another drive, you will 2990need to relocate ``hosts.conf`` and ``apcctrl.css`` from the apcctrl install 2991location to ``\apcctrl\etc\apcctrl`` on the appropriate drive. 2992 2993multimon.cgi 2994~~~~~~~~~~~~ 2995 2996This program 2997monitors multiple UPSes at the same time. A typical output of 2998multimon.cgi as displayed in your Web browser might look like the 2999following: 3000 3001.. image:: ./multimon.png 3002 :align: center 3003 3004The machines monitored as well as the values and their column 3005headings are all configurable (see /etc/apcctrl/hosts.conf and 3006/etc/apcctrl/multimon.conf) 3007 3008upsstats.cgi 3009~~~~~~~~~~~~ 3010 3011By clicking on the ``system`` name in the multimon.cgi display, you will 3012invoke upsstats.cgi for the specified system, which will produce a bar 3013graph display of three of the monitored values. For example, 3014 3015.. image:: ./status.png 3016 :align: center 3017 3018You can display different bar graphs by selecting different 3019variables from the drop down menus at the top of each of the three 3020bar graphs. 3021 3022As with multimon, if you have your local host configured in the 3023/etc/apcctrl/hosts.conf file, you can execute it from a Unix shell 3024from the source cgi directory as follows: 3025 3026:: 3027 3028 ./upsstats.cgi 3029 3030As with multimon, quite a few lines of html should then be displayed. 3031 3032upsfstatus.cgi 3033~~~~~~~~~~~~~~ 3034 3035If you 3036would like to see all of the STATUS variables available over the 3037network, click on the ``Data`` field of the desired system, and your 3038browser will display something like the following: 3039 3040:: 3041 3042 APC : 001,048,1109 3043 DATE : Thu Dec 02 17:27:21 CET 1999 3044 HOSTNAME : matou.sibbald.com 3045 RELEASE : 3.7.0-beta-1 3046 CABLE : Custom Cable Smart 3047 MODEL : SMART-UPS 1000 3048 UPSMODE : Stand Alone 3049 UPSNAME : UPS_IDEN 3050 LINEV : 223.6 Volts 3051 MAXLINEV : 224.9 Volts 3052 MINLINEV : 222.3 Volts 3053 LINEFREQ : 50.0 Hz 3054 OUTPUTV : 223.6 Volts 3055 LOADPCT : 6.2 Percent Load Capacity 3056 BATTV : 27.9 Volts 3057 BCHARGE : 100.0 Percent 3058 MBATTCHG : 5 Percent 3059 TIMELEFT : 167.0 Minutes 3060 MINTIMEL : 3 Minutes 3061 SENSE : High 3062 DWAKE : 060 Seconds 3063 DSHUTD : 020 Seconds 3064 LOTRANS : 196.0 Volts 3065 HITRANS : 253.0 Volts 3066 RETPCT : 050.0 Percent 3067 STATFLAG : 0x08 Status Flag 3068 STATUS : ONLINE 3069 ITEMP : 35.1 C Internal 3070 ALARMDEL : Low Battery 3071 LASTXFER : U command or Self Test 3072 SELFTEST : NO 3073 STESTI : 336 3074 DLOWBATT : 02 Minutes 3075 DIPSW : 0x00 Dip Switch 3076 REG1 : 0x00 Register 1 3077 REG2 : 0x00 Register 2 3078 REG3 : 0x00 Register 3 3079 MANDATE : 01/11/99 3080 SERIALNO : GS9903001147 3081 BATTDATE : 01/11/99 3082 NOMOUTV : 230.0 3083 NOMBATTV : 24.0 3084 HUMIDITY : N/A 3085 AMBTEMP : N/A 3086 EXTBATTS : 0 3087 BADBATTS : N/A 3088 FIRMWARE : 60.11.I 3089 APCMODEL : IWI 3090 END APC : Thu Dec 02 17:27:25 CET 1999 3091 3092You should get pretty much the same output mixed in with html if 3093you execute upsfstats.cgi directly from a Unix shell in the cgi 3094subdirectory as explained above for upsstats.cgi and multimon.cgi. 3095 3096 3097A Tip from Carl Erhorn for Sun Systems: 3098~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 3099 3100It is possible to run the CGI code to monitor your 3101UPS using the answerbook HTTP server that runs on Solaris. As long 3102as your server has the Answerbook2 web server installed and 3103running, you can insert the cgi scripts into the cgi directory of 3104the web server, and access the cgi using something like: 3105 3106``http://hostname:8888/cgi/multimon.cgi`` 3107 3108 3109CGI Credits 3110~~~~~~~~~~~ 3111 3112Many thanks go to Russell Kroll rkroll@exploits.org who wrote 3113the CGI programs to work with his UPS Monitoring system named 3114Network UPS Tools (NUT). Thanks also to Jonathan Benson 3115jbenson@technologist.com for initially 3116adapting the upsstatus.cgi program to work with apcctrl. 3117 3118We have enhanced the bar graph program and hope that our changes 3119can be useful to the original author in his project. 3120 3121 3122Security Issues: 3123---------------- 3124 3125- ``apcctrl`` runs as root. 3126 3127- If you have ``NETSERVER ON`` in your apcctrl.conf file (which is 3128 the default), be aware that anyone on the network can read the 3129 status of your UPS. This may or may not pose a problem. If you 3130 don't consider this information privileged, as is the case for 3131 many, there is little risk. In addition, if you have a perimeter 3132 firewall or NATting router with typical settings only users on your 3133 local network access to your UPS information. You may also restrict 3134 access using using firewall settings (see below) or TCP Wrappers 3135 (see below). 3136 3137 3138Firewall Settings 3139~~~~~~~~~~~~~~~~~ 3140 3141If you are running apcctrl as an NIS server, you will need to 3142ensure that the clients can reach it by opening up ``NISPORT`` 3143(default: TCP 3551) on any firewall running on the server. You may 3144wish to configure your firewall(s) to *only* allow connections from 3145your local network or specifically from the masters, slaves, and 3146servers as needed. 3147 3148 3149TCP Wrappers 3150~~~~~~~~~~~~ 3151 3152If your operating system does not support a host based firewall (a 3153firewall running on the local machine) then you may try to get some 3154of the functionality of such a firewall with TCP Wrappers. As of 3155apcctrl version 3.8.2, TCP Wrappers are implemented if you turn 3156them on when configuring ``./configure --with-libwrap``. With 3157this code enabled, you may control who may access your apcctrl via 3158TCP connections (the Network Information Server). This control is 3159done by modifying the file: /etc/hosts.allow. This code is 3160implemented but untested. If you use it, please send us some 3161feedback. 3162 3163 3164Configuring Your EEPROM 3165----------------------- 3166 3167If you have a SmartUPS, there 3168are depending on the UPS at least 12 different values stored in the 3169EEPROM that determine how the UPS reacts to various conditions such 3170as high line voltage, low line voltage, power down grace periods, 3171etc. 3172 3173In general, for the moment, we do not recommend that you change 3174your EEPROM values unless absolutely necessary. There have been 3175several reported cases of problems setting the Low Transfer 3176Voltage. Consequently, if at all possible, do not attempt to change 3177this value. 3178 3179 3180Using apctest to Configure Your EEPROM 3181~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 3182 3183*To make the EEPROM changes with apctest you must first stop the 3184apcctrl daemon.* After apcctrl is stopped you may invoke apctest (as root). 3185 3186We recommend that you change the EEPROM as little as is absolutely 3187necessary since it is a somewhat delicate process that has 3188occasionally produced problems (i.e. improper EEPROM values are 3189displayed after the update). 3190 3191apctest will present a menu of options which are generally self-explanatory. 3192Note that USB connections will show a difference set of options than 3193smart serial connections. 3194 3195 3196.. include:: maintaining_ups.rst 3197 3198 3199Frequently-Asked Questions 3200========================== 3201See the bugs section of this document for a list of 3202known bugs and solutions. 3203 3204:Question: 3205 Why all the craziness with custom serial cables? 3206:Answer: 3207 It was nothing more nor less than a form of customer 3208 control. For a long time APC wanted to keep other people from 3209 talking to its UPSes so it could lock out potential competition for 3210 its PowerChute software. Scrambling the leads on its serial cables 3211 was a cheap way to accomplish this -- in fact, they tended to be 3212 wired so that if you tried a straight-through cable, opening a 3213 serial link to the UPS would be interpreted as a shutdown command! 3214 3215 (Hardware companies often think like this -- they lock up 3216 interfaces by instinct, cornering a small market rather than 3217 growing a bigger one. It's fundamentally stupid and self-defeating, 3218 but it's the kind of stupid that tends to sound good at an 3219 executive meeting.) 3220 3221:Question: 3222 What UPS brands does apcctrl support? 3223:Answer: 3224 Currently apcctrl supports only APC UPSes. However, 3225 some companies such as Hewlett Packard put their own brand name on 3226 APC manufactured UPSes. Thus even if you do not have an APC branded 3227 UPS, it may work with apcctrl. You will need to know the 3228 corresponding APC model number. apcctrl supports all the popular 3229 APC models. See the installation and configurations sections of 3230 this document for more details. 3231 3232:Question: 3233 Does apcctrl support Windows? 3234:Answer: 3235 Yes. 3236 3237:Question: 3238 I don't have a cable, which one should I build? 3239:Answer: 3240 First you must know if you have an apcsmart UPS or a 3241 voltage-signalling UPS. If you have a apcsmart UPS, we 3242 recommend building a Custom Smart cable. (see `Smart-Custom Cable for 3243 SmartUPSes`_) If you have a voltage-signaling UPS, we recommend that 3244 you build a Custom Simple cable. (see `Simple-Custom Voltage-Signalling 3245 Cable for "dumb" UPSes`_) 3246 3247:Question: 3248 How much CPU resources does apcctrl use? 3249:Answer: 3250 Depending on your CPU speed, you may see more or less 3251 of the CPU consumed by apcctrl. On a 400MHz Unix system, the CPU 3252 usage should fall well below 0.1%. On slower systems, the 3253 percentage will increase proportionally to the decrease in the CPU 3254 speed. On a 400Mhz Win98 machine, the CPU usage will be on the 3255 order of 0.5-1.0%. This is higher than for Unix systems. However, 3256 compared to the 30% CPU usage by APC's PowerChute (the version on 3257 the CDROM shipped with my UPS), apcctrl's 0.5-1.0% is very modest. 3258 3259:Question: 3260 What language is apcctrl written in? 3261:Answer: 3262 It is written in C and C++. 3263 3264:Question: 3265 To test apcctrl, I unplugged the UPS to simulate a 3266 power outage. After the machine went into the shutdown process I 3267 plugged the UPS back into the commercial power source. This caused 3268 the shutdown process to hang after the daemon tried to shut-off the 3269 ups. Have you run into this problem, and if so do you have a 3270 remedy? 3271:Answer: 3272 Normally, once the shutdown process has begun, we 3273 cannot stop it -- how do you stop a 3274 shutdown that has killed off half of the daemons running on your 3275 system? Most likely you will be left with an unusable system. In 3276 addition, when apcctrl is re-executed in the halt script after the 3277 disks are synced, it tries to shut off the UPS power, but the UPS 3278 will generally refuse to do so if the AC power is on. Since we 3279 cannot be 100% sure whether or not the UPS will shut off the power, 3280 we don't attempt to reboot the system if we detect that the power 3281 is back as it might then get caught by a delayed power off (at 3282 least for Smart UPSes). 3283 3284:Question: 3285 After running apcctrl for a while, I get the following 3286 error: "Serial communications with UPS lost." What is the problem? 3287:Answer: 3288 We use standard Unix serial port read() and write() 3289 calls so once a connection is made, we generally have few problems. 3290 However, there have been reports that APC's SNMP Management Card 3291 can cause serial port problems. If you have such a card, we suggest 3292 that you remove it and see if the problem goes away. It is also 3293 possible that some other process such as a getty is reading the 3294 serial port. 3295 3296:Question: 3297 I get the following error: 3298 3299 :: 3300 3301 Starting apcctrl power management. 3302 Mar 20 21:19:40 box apcctrl[297]: apcctrl FATAL ERROR in apcserial.c at line 83. 3303 Cannot open UPS tty /dev/cua01: No such file or directory. 3304 3305 What is the problem? 3306:Answer: 3307 The two most likely causes of your problem are: 1. You 3308 have the wrong serial port device name in the apcctrl.conf file. 2. 3309 The device name is not defined on your system. Suggestions for 3310 proceeding:For the first item, check what your serial port device 3311 should be named. You might be able to find the name with an: 3312 3313 :: 3314 3315 ls /dev 3316 3317 Normally there will be hundreds or even thousands of names that 3318 print. If that doesn't produce anything useful, you can try step 2. 3319 Perhaps your device is not defined. To get more information on your 3320 devices try '``man MAKEDEV``' or '``find / -name MAKEDEV``'. It is often 3321 located in ``/dev/MAKEDEV``. Looking at the documentation may tell 3322 you what the correct name is, or at least allow you to create the 3323 device. 3324 3325:Question: 3326 How do I ensure that the slaves shutdown before the master? 3327:Answer: 3328 Slaves make their shutdown decision independently from the master. 3329 Therefore you can use the ``TIMEOUT``, ``MINUTES``, and ``BATTERYLEVEL`` 3330 settings in the slaves' apcctrl.conf to configure them to shut down 3331 before the master. 3332 3333:Question: 3334 How do I ensure that my database server is correctly shutdown? 3335:Answer: 3336 You simply add whatever commands are necessary in the 3337 appropriate case statements in /etc/apcctrl/apccontrol, which is a 3338 standard script file that is called to actually do the shutdown. 3339 Alternatively, you can add your own script file that will be called 3340 before doing the commands in apccontrol. Your script file must have 3341 the same name as the appropriate case statement in apccontrol; it 3342 must be executable; and it must be in the same directory as 3343 apccontrol. 3344 3345 3346Customizing Event Handling 3347========================== 3348 3349When apcctrl detects anomalies from your UPS device, it will make 3350some decisions that usually result in one or more calls to the 3351script located in ``/etc/apcctrl/apccontrol``. The ``apccontrol`` file 3352is a shell script that acts on the first argument that apcctrl 3353passes to it. These actions are set up by default to sane behavior 3354for all situations apcctrl is likely to detect from the UPS. 3355However, you can change the apccontrol behavior for every single 3356action. 3357 3358To customize, so create a file with the same name as the action, 3359which is passed as a command line argument. Put your script in the 3360``/etc/apcctrl`` directory. 3361 3362These events are sent to the system log, optionally sent to the 3363temporary events file (``/etc/apcctrl/apcctrl.events``), and they also 3364generate a call to ``/etc/apcctrl/apccontrol`` which in turn will call 3365any scripts you have placed in the ``/etc/apcctrl`` directory. 3366 3367Normally, ``/etc/apcctrl/apccontrol`` is called only by apcctrl. 3368Consequently, you should not invoke it directly. However, it is 3369important to understand how it functions, and in some cases, you 3370may want to change the messages that it prints using ``wall``. We 3371recommend that you do so by writing your own script to be invoked 3372by ``apccontrol`` rather than by modifying apccontrol directly. This 3373makes it easier for you to upgrade to the next version of apcctrl 3374 3375In other case, you may want to write your own shell scripts that 3376will be invoked by apccontrol. For example, when a power fail 3377occurs, you may want to send an email message to root. 3378 3379To write your own routine for the ``powerout`` action, you create 3380shell script named ``powerout`` and put it in the lib directory 3381(normally /etc/apcctrl). When the ``powerout`` action is invoked by 3382apcctrl, apccontrol will first give control to your script. If you 3383want apccontrol to continue with the default action, simply exit 3384your script with an exit status of zero. If you do not want 3385apccontrol to continue with the default action, your script should 3386exit with the special exit code of 99. However, in this case, 3387please be aware that you must ensure proper shutdown of your 3388machine if necessary. 3389 3390Some sample scripts (onbattery and mainsback) that email power 3391failure messages can be found in /etc/apcctrl after an install or 3392in the platforms/etc directory of the source code. 3393 3394apccontrol Command Line Options 3395------------------------------- 3396 3397When apcctrl detects an event, it calls the apccontrol script with 3398four arguments as: 3399 3400``apccontrol`` *event* *ups-name* *connected* *powered* 3401 3402where: 3403 3404*event* 3405 is the event that occurred and it may be any one 3406 of the values described in the next section. 3407 3408*ups-name* 3409 is the name of the UPS as specified in the 3410 configuration file (not the name in the EEPROM). 3411 3412*connected* 3413 is 1 if apcctrl is connected to the UPS 3414 via a serial port (or a USB port). In most configurations, this 3415 will be the case. In the case of a Slave machine where apcctrl is 3416 not directly connected to the UPS, this value will be 0. 3417 3418*powered* 3419 is 1 if the computer on which apcctrl is 3420 running is powered by the UPS and 0 if not. At the moment, this 3421 value is unimplemented and always 0. 3422 3423 3424The following *event* names are supported: 3425 3426**annoyme** 3427 When a shutdown is scheduled, and the time 3428 specified on the ANNOYME directive in the apcctrl.conf file 3429 expires, this event is generated. 3430 3431 *Default:* ``wall`` a message 3432 3433**changeme** 3434 When apcctrl detects that the mains are on, 3435 but the battery is not functioning correctly, this event is 3436 generated. It is repeated every x hours. 3437 3438 *Default:* ``wall`` a message 3439 3440**commfailure** 3441 This event is generated each time the 3442 communications line with the computer is severed. This event is not 3443 detected on dumb signaling UPSes. 3444 3445 *Default:* ``wall`` a message 3446 3447**commok** 3448 After a commfailure event is issued, when the 3449 communications to the computer is re-established, this event will 3450 be generated. 3451 3452 *Default:* ``wall`` a message 3453 3454**doreboot** 3455 This event is depreciated and should not be used. 3456 3457 *Default:* Shuts down the system using ``shutdown -h`` or similar 3458 3459**doshutdown** 3460 When the UPS is running on batteries and 3461 one of the limits expires (time, run, load), this event is 3462 generated to cause the machine to shutdown. 3463 3464 *Default:* Shuts down the system using ``shutdown -h`` or similar 3465 3466**emergency** 3467 Called for an emergency system shutdown. (What triggers such a shutdown 3468 is unclear...) After completing this event, apcctrl will immediately 3469 initiate a ``doshutdown`` event. 3470 3471 *Default:* ``wall`` a message 3472 3473**failing** 3474 This event is generated when the UPS is 3475 running on batteries and the battery power is exhausted. The event 3476 following this one will be a shutdown. 3477 3478 *Default:* ``wall`` a message 3479 3480**loadlimit** 3481 This event is generated when the battery 3482 charge is below the low limit specified in the apcctrl.conf file. 3483 After completing this event, apcctrl will immediately 3484 initiate a ``doshutdown`` event. 3485 3486 *Default:* ``wall`` a message 3487 3488**powerout** 3489 This event is generated immediately when 3490 apcctrl detects that the UPS has switched to batteries. It may be 3491 due to a short powerfailure, an automatic selftest of the UPS, or a 3492 longer powerfailure. 3493 3494 *Default:* ``wall`` a message 3495 3496**onbattery** 3497 This event is generated 5 or 6 seconds 3498 after an initial powerfailure is detected. It means that apcctrl 3499 definitely considers the UPS to be on batteries. The onset of this 3500 event can be delayed by the ``ONBATTERYDELAY`` apcctrl.conf 3501 configuration directive. 3502 3503 *Default:* ``wall`` a message 3504 3505**offbattery** 3506 This event is generated when the mains 3507 return only if the onbattery event has been generated. 3508 3509 *Default:* ``wall`` a message 3510 3511**mainsback** 3512 This event is generated when the mains 3513 power returns after a powerout condition. The shutdown event may or 3514 may not have been generated depending on the parameters you have 3515 defined and the length of the power outage. 3516 3517 *Default:* nothing 3518 3519**remotedown** 3520 This event is generated on a slave 3521 machine when it detects either that the master has shutdown, or 3522 that a onbattery situation exists and the communications line has 3523 been severed. 3524 3525 *Default:* ``wall`` a message 3526 3527**runlimit** 3528 This event is generated when the ``MINUTES`` 3529 value defined in the apcctrl.conf file expires while in a power 3530 fail condition. The ``MINUTES`` is the remaining runtime as internally 3531 calculated by the UPS and monitored by apcctrl. After completing this 3532 event, apcctrl will immediately initiate a ``doshutdown`` event. 3533 3534 *Default:* ``wall`` a message 3535 3536**timeout** 3537 This event is generated when the ``TIMEOUT`` value 3538 defined in the apcctrl.conf file expires while in a power fail 3539 condition. It indicates that the total time in a power failure has 3540 been exceeded and the machine should be shutdown. After completing this 3541 event, apcctrl will immediately initiate a ``doshutdown`` event. 3542 3543 *Default:* ``wall`` a message 3544 3545**startselftest** 3546 This event is generated when 3547 apcctrl detects a self test by the UPS. Normally due to the 6 3548 second onbattery delay default time, self test events are not 3549 detected. 3550 3551 *Default:* nothing 3552 3553**endselftest** 3554 This event is generated when the end 3555 of a self test is detected. 3556 3557 *Default:* nothing 3558 3559**battdetach** 3560 This event is generated when apcctrl 3561 detects that the UPS battery has been disconnected. 3562 3563 *Default:* nothing 3564 3565**battattach** 3566 This event is generated when apcctrl 3567 detects that the UPS battery has been reconnected after a 3568 battdetach event. 3569 3570 *Default:* nothing 3571 3572 3573Controlling Multiple UPSes on one Machine 3574========================================= 3575 3576*The following discussion does not apply to Windows servers. apcctrl on Windows 3577is limited to a single instance and cannot support monitoring multiple UPSes.* 3578 3579If you have multiple UPSes in use, you may wish to consolidate the monitoring 3580of all of these UPSes onto a single machine, which we shall call the "UPS 3581server". Generally one of the UPSes is powering the "UPS server" itself (and 3582possibly other machines as well). The remaining UPSes are powering additional 3583machines. 3584 3585apcctrl can work quite well in this environment by running one instance of 3586apcctrl on the UPS server for each UPS to be controlled. That is, you install 3587a single copy of apcctrl but launch it multiple times using different 3588configuration files and scripts. (Older versions of apcctrl required you to 3589actually compile the daemon multiple times with different ``configure`` options. 3590This is no longer required, as all necessary adjustments can be made in 3591``apcctrl.conf``.) 3592 3593Additionally, you will run one instance of apcctrl on each of the machines 3594you wish to be shut down. You will configure each of these apcctrl's to use 3595the 'net' driver to read UPS status from the proper instance of apcctrl on the 3596UPS server. See `NIS Server/Client Configuration Using the Net Driver`_ for 3597more information on the 'net' driver and setting up net clients. 3598 3599 3600Multiple UPS Example 3601-------------------- 3602 3603There are many ways one could set up multiple apcctrl instances. Here I will 3604present the way I have used with great success on Red Hat Linux. 3605 3606I have two apcctrl.conf files (this is for a 2 UPS setup, easily 3607expandable to N): 3608 3609:: 3610 3611 [adk0212@mail apcctrl]$ ls -l /etc/apcctrl/*.conf 3612 -rw-r--r-- 1 root root 11799 Aug 3 08:39 /etc/apcctrl/apcctrl.ups0.conf 3613 -rw-r--r-- 1 root root 11822 Aug 25 14:31 /etc/apcctrl/apcctrl.ups1.conf 3614 3615In my case, ups0 is the UPS powering the UPS server running the multiple 3616apcctrl instances, so only ups0 should initiate a shutdown of the local 3617machine. The differences between the confs are minor since both UPSes 3618are USB (although that is not a requirement; mixing cable types works 3619fine too): 3620 3621:: 3622 3623 [adk0212@mail apcctrl]$ diff -u apcctrl.ups0.conf apcctrl.ups1.conf 3624 --- apcctrl.ups0.conf 2007-08-03 08:39:26.000000000 -0400 3625 +++ apcctrl.ups1.conf 2007-08-25 14:31:17.000000000 -0400 3626 -UPSNAME ups0 3627 +UPSNAME ups1 3628 -DEVICE /dev/ups0 3629 +DEVICE /dev/ups1 3630 -SCRIPTDIR /etc/apcctrl 3631 +SCRIPTDIR /etc/apcctrl/null 3632 -PWRFAILDIR /etc/apcctrl 3633 +PWRFAILDIR /etc/apcctrl/null 3634 -NOLOGINDIR /etc 3635 +NOLOGINDIR /etc/apcctrl/null 3636 -ANNOY 300 3637 +ANNOY 0 3638 -NISPORT 3551 3639 +NISPORT 3552 3640 -EVENTSFILE /var/log/apcctrl.events 3641 +EVENTSFILE /var/log/apcctrl.2.events 3642 3643The important difference to note is that ups1 has its ``SCRIPTDIR``, 3644``PWRFAILDIR``, and ``NOLOGINDIR`` set to a special "null" directory that I have 3645created. This directory contains a copy of the event handling scripts 3646modified to avoid shutting down the local machine. (Details below). Also 3647the UPSes are given different ``EVENTSFILE`` and ``NISPORT`` settings. Plus I 3648disable the "annoy" feature on ups1. Since the state of that UPS does not 3649impact local users, there's no reason to annoy them. 3650 3651I have the following files in the special "null" directory: 3652 3653:: 3654 3655 [adk0212@mail apcctrl]$ ls -l /etc/apcctrl/null 3656 total 32 3657 -rwxr--r-- 1 root root 4176 Aug 3 08:24 apccontrol 3658 -rwxr-xr-x 1 root root 475 Aug 3 08:28 changeme 3659 -rwxr-xr-x 1 root root 502 Aug 3 08:28 commfailure 3660 -rwxr-xr-x 1 root root 503 Aug 3 08:28 commok 3661 -rwxr--r-- 1 root root 8 Aug 3 08:22 doshutdown 3662 -rwxr-xr-x 1 root root 470 Aug 3 08:27 offbattery 3663 -rwxr-xr-x 1 root root 435 Aug 3 08:27 onbattery 3664 3665The important change here is the addition of a 'doshutdown' script which 3666overrides apccontrol's shutdown action: 3667 3668:: 3669 3670 [adk0212@mail null]$ cat /etc/apcctrl/null/doshutdown 3671 exit 99 3672 3673The "exit 99" tells apccontrol to skip its normal processing for that 3674event. apccontrol itself is unchanged; it is a direct copy of the 3675original. The other scripts are also direct copies and have simply been 3676modified to generate status email from NISPORT 3552 instead of 3551. 3677 3678I also have a custom init.d start/stop script to manage multiple 3679instances. The start, stop, and status handlers are modified to iterate 3680over all /etc/apcctrl/apcctrl.*.conf files. This is derived from the 3681standard apcctrl redhat rc script: 3682 3683:: 3684 3685 #! /bin/sh 3686 # 3687 # apcctrl This shell script takes care of starting and stopping 3688 # the apcctrl UPS monitoring daemon. 3689 # 3690 # chkconfig: 2345 60 99 3691 # description: apcctrl monitors power and takes action if necessary 3692 # 3693 3694 if test -f /etc/whitebox-release ; then 3695 f=/etc/whitebox-release 3696 else 3697 f=/etc/redhat-release 3698 fi 3699 if test `cat $f | grep release |\ 3700 cut -f 3 -d ' '`x = "Enterprise"x ; then 3701 DISTVER="Enterprise "`cat $f | grep release |\ 3702 cut -f 6 -d ' '` 3703 else 3704 DISTVER=`cat /etc/redhat-release | grep release |\ 3705 cut -f 5 -d ' '` 3706 fi 3707 3708 # Source function library 3709 . /etc/rc.d/init.d/functions 3710 3711 case "$1" in 3712 start) 3713 rm -f /etc/apcctrl/powerfail 3714 rm -f /etc/nologin 3715 for conf in /etc/apcctrl/apcctrl.*.conf ; do 3716 inst=`basename $conf` 3717 echo -n "Starting UPS monitoring ($inst):" 3718 daemon /sbin/apcctrl -f $conf -P /var/run/apcctrl-$inst.pid 3719 RETVAL=$? 3720 echo 3721 [ $RETVAL -eq 0 ] && touch /var/lock/subsys/apcctrl-$inst 3722 done 3723 ;; 3724 stop) 3725 for conf in /etc/apcctrl/apcctrl.*.conf ; do 3726 inst=`basename $conf` 3727 echo -n "Shutting down UPS monitoring ($inst):" 3728 killproc -p /var/run/apcctrl-$inst.pid apcctrl 3729 echo 3730 rm -f /var/run/apcctrl-$inst.pid 3731 rm -f /var/lock/subsys/apcctrl-$inst 3732 done 3733 ;; 3734 restart|force-reload) 3735 $0 stop 3736 sleep 15 3737 $0 start 3738 ;; 3739 reload) 3740 echo "$0: reload not implemented" 3741 exit 3 3742 ;; 3743 status) 3744 for conf in /etc/apcctrl/apcctrl.*.conf ; do 3745 inst=`basename $conf` 3746 status -p /var/run/apcctrl-$inst.pid apcctrl-$inst 3747 RETVAL=$? 3748 if [ $RETVAL -eq 0 ] 3749 then 3750 NISPORT=`grep ^NISPORT < $conf | sed -e "s/NISPORT *\([0-9]\)/\1/"` 3751 /sbin/apcaccess status localhost:$NISPORT | egrep "(STATUS)|(UPSNAME)" 3752 fi 3753 done 3754 ;; 3755 *) 3756 echo "Usage: $0 {start|stop|restart|status}" 3757 exit 1 3758 ;; 3759 esac 3760 exit 0 3761 3762That's about all there is to it. There are still some rough edges to 3763clean up, but overall this is a *lot* easier with apcctrl 3.14.x than it 3764used to be. 3765 3766 3767Support for SNMP UPSes 3768====================== 3769 3770To run apcctrl with a SNMP UPS, you need the 3771following things: 3772 3773- An SNMP UPS, for example a Web/SNMP (AP9716) or PowerNet SNMP 3774 (AP9605) card installed into the SmartSlot. apcctrl also has support 3775 for some non-APC SNMP UPSes using RFC1628 or MGE MIBs, however the 3776 majority of the information in this section is for APC UPSes. 3777 3778 3779Planning and Setup for SNMP Wiring 3780---------------------------------- 3781 3782SNMP packet requests are relayed to 3783the UPS from monitoring APCCTRL servers over Ethernet via a switch, 3784hub, or router. Protecting these Ethernet devices with UPS supplied 3785power is necessary to ensure reliable SNMP communication during 3786power failures. Servers may fail to shutdown quietly during power 3787failures if SNMP communication is lost. 3788 3789 3790Planning and Setup for SNMP Configuration 3791----------------------------------------- 3792 3793To establish communication to the UPS SNMP card 3794installed in the UPS, the SNMP card will need the following: 3795 3796- Assign SNMP card IP Address 3797- Set SNMP card General Parameters 3798- Set SNMP card Shutdown Parameters 3799- Set SNMP card Event Trap Receivers (apcctrl-3.12.0 and later) 3800 3801 3802Assign SNMP Card IP Address 3803~~~~~~~~~~~~~~~~~~~~~~~~~~~ 3804 3805The following instructions come from the APC knowledge base: 3806 3807:: 3808 3809 The Network Management Card (AP9617, AP9618, AP9619) must be 3810 configured with network settings before it can communicate on the 3811 network. Once the cards have been configured with an IP address, 3812 Subnet Mask, and Default Gateway the cards can be access, managed, 3813 and controlled from other computers on the network. 3814 3815 There are two ways to configure the Network Management Card (NMC) 3816 with its initial settings: the (windows) Wizard and Address 3817 Resolution Protocol (ARP). 3818 3819 1. The wizard in included on the CD that comes with the card. The 3820 wizard must run on a Windows operating system. You can configure 3821 the card using the wizard over the network via FTP. If using the 3822 wizard please note, the un-configured NMC must be on the same 3823 subnet as the computer running the wizard. 3824 3825 2. Address resolution protocol (arp) can also be used to configure 3826 the NMC. The MAC Address of the NMC is needed for this method of 3827 configuration. The MAC address is located on the quality assurance 3828 slip that is shipped with the NMC, and is also located on the white 3829 sticker on the NMC itself. From a computer on the same subnet as 3830 the un-configured NMC, follow the instructions: 3831 3832 Open up a command prompt and type the following (replacing 3833 <IPaddress> and <MacAddress> with the actual values): 3834 3835 arp -s <IPaddress> <MacAddress> 3836 3837 Next, use Ping with a size of 113 bytes to assign the IP address 3838 defined by the ARP command. 3839 3840 3841 - Linux command format: ping <IPaddress> -s 113 3842 3843 - Windows command format: ping <IPaddress> -l 113 3844 3845 3846Set SNMP card General Parameters 3847~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 3848 3849After the SNMP Network Management Card is configured with an IP address, 3850the SNMP Card is ready for general configuration. This is accomplished by 3851telneting to the SNMP Card. 3852 3853:: 3854 3855 ~$ telnet <IPaddress> 3856 3857Login using "apc" for both the username and password and the 3858following menu will display: 3859 3860:: 3861 3862 ******************************************************************************* 3863 American Power Conversion Network Management Card AOS v2.6.4 3864 (c) Copyright 2004 All Rights Reserved Smart-UPS & Matrix-UPS APP v2.6.1 3865 ------------------------------------------------------------------------------- 3866 Name : Date : 07/03/2006 3867 Contact : Time : 04:43:33 3868 Location : User : Administrator 3869 Up Time : 0 Days 01 Hours 57 Minutes Stat : P+ N+ A+ 3870 3871 Smart-UPS 1000 named : On Line, No Alarms Present 3872 3873 ------- Control Console ------------------------------------------------------- 3874 3875 1- Device Manager 3876 2- Network 3877 3- System 3878 4- Logout 3879 3880 <ESC>- Main Menu, <ENTER>- Refresh, <CTRL-L>- Event Log 3881 > 3882 ******************************************************************************* 3883 3884Select **Option 2** for Network. Next select **Option 1** for TCP/IP 3885settings. 3886 3887At this point the following settings will be to be specified: 3888 3889- Verify System IP: <IPaddress> 3890- Specify Subnet Mask: i.e. "225.225.225.0" 3891- Specify Default Gateway 3892- Specify Host Name 3893- Specify Domain Name 3894 3895Specifying these parameters will complete the General Parameters 3896setup. Additionally the SNMP Network Management Card can now be 3897connected to from a web browser for monitoring and additional 3898configuration. 3899 3900Set SNMP card Shutdown Parameters 3901~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 3902 3903There are two shutdown parameters that must be set in the SNMP card 3904to ensure that connected servers shutdown quietly. These parameters 3905can be set via the telnet terminal or the web browser interface. 3906 3907- Shutdown Delay (sec) 3908- Return Battery Capacity (%) 3909 3910One of the draw-backs of SNMP communication to the UPS is that the 3911Stand-alone or Primary server must issue the power down command to 3912the UPS early in server halt procedure. This server must issue an 3913early command to the SNMP UPS to power down before its ethernet 3914service is halted. This creates a potential problem where the UPS 3915may kill power to any connected servers before these affected 3916servers' halt scripts complete a successful shutdown. 3917 3918The SNMP **Shutdown Delay** parameter is used to delay the UPS from 3919killing power to its load by a prescribed period of seconds. The 3920delay should be long enough to ensure that the Stand-alone or 3921Primary server has enough time to successfully halt. The prescribed 3922time should at least be 180 seconds. Any additional computers 3923connected to the SNMP UPS must not be configured to issue the 3924command to initiate UPS power down. These servers can be thought of 3925as secondary stand-alone server. The APCCTRL daemons of secondary 3926servers should be configured to initiate server halt a prescribed 3927period of time before the Primary server issues the UPS power down 3928command. 3929 3930The **Return on Battery Capacity** is useful during intermittent 3931sequential power failures. This parameter insures that the UPS will 3932not restore power to its loads until it has recharged it battery to 3933a prescribed percentage. This parameter should be set to a value 3934greater than value that the APCCTRL daemons configured 3935"BATTERYLEVEL" shutdown of any connected servers. This will ensure 3936that when the UPS restores power, any additional power failures 3937will successfully re-trigger a server shutdown. 3938 3939 3940Configure Event Trap Receivers 3941~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 3942 3943(Requires apcctrl-3.12.0 and later) 3944 3945By default, APCCTRL will poll the SNMP UPS card once per minute. In 3946this case, server notification of UPS alarms could potentially be 3947delayed one minute. Event trap catching mitigates this shortcoming. 3948Any UPS alarms are instantly sent to prescribe servers connected 3949SNMP UPS. These servers are referred to as Event Trap Receivers. 3950The SNMP UPS card can be configure to send event traps to a maximum 3951of four receivers that will "catch" these events. 3952 3953Event trap receivers IP address can be set using a telnet terminal 3954or web browser interface. 3955 3956Also, be aware that servers configured to be Event Trap Receivers 3957should have static IP set. Severs obtaining IPs from DHCP server 3958will not catch instantaneous Events if the IP address changes from 3959the address set in the SNMP UPS. 3960 3961 3962Connecting APCCTRL to a SNMP UPS 3963-------------------------------- 3964 3965The previous sections describe configuration of the actual SNMP 3966card. The remaining sections describe configuration of the APCCTRL 3967to communicate using SNMP Protocol. 3968 3969To enable the SNMP support it is enough to configure 3970the correct device in your apcctrl.conf configuration file. The 3971directive needed for this configuration is: 3972 3973:: 3974 3975 DEVICE <host>:<port>:<vendor>:<community> 3976 3977...where the directive is made by four parts. All but the first may be omitted 3978completely or left empty to accept the default. 3979 3980- *host*: IP address or DNS hostname of the UPS (required) 3981- *port*: Remote SNMP port (optional, default: 161) 3982- *vendor*: The type of SNMP MIB available on the UPS (optional, default: 3983 autodetect). Allowable choices for vendor are: 3984 3985 - APC : APC PowerNet MIB, used on most APC brand UPSes 3986 - RFC : RFC1628 MIB, used by some non-APC UPSes 3987 - MGE : MGE MIB, used by many MGE brand UPSes 3988 - blank : Autodetect 3989 3990 Append "_NOTRAP" to the vendor name to disable SNMP trap catching 3991 (ex: "APC_NOTRAP"). See `SNMP Trap Catching`_. 3992- *community*: The read-write community string, usually "private". You can 3993 specify a read-only community string, usually "public", if you do not 3994 require killpower support. If the community string is omitted, apcctrl will 3995 attempt to autotedect by trying "private" and "public". 3996 (optional, default: autodetect). 3997 3998A NIS Server/Client (Master/Slave) configuration 3999with multiple servers is still applicable. However, an alternative 4000configuration is possible with an SNMP 4001enabled UPS. In this arrangement, all connected servers will be 4002configured as a standalone server. Each will independently 4003communicate to the UPS. One (primary) server will be chosen to 4004manage the task of commanding the UPS to power down. All remaining 4005(secondary) servers will be configured to quietly power down before 4006the primary server issues the UPS power down command. 4007 4008Building with SNMP support 4009-------------------------- 4010 4011Follow the instructions in `Building and Installing apcctrl`_, being sure 4012to include the following options (in addition to any others you need) on the 4013'``./configure``' line: 4014 4015:: 4016 4017 ./configure --enable-snmp 4018 4019 4020SNMP Trap Catching 4021------------------ 4022 4023apcctrl-3.11.14 introduces support for SNMP trap catching. 4024Previous versions polled the UPS status 4025once per minute, leading to significant delays before UPS state 4026changes were recognized. With SNMP trap handling, apcctrl monitors 4027the SNMP trap port and will re-poll the UPS whenever a trap is 4028received. This happens, for example, when the UPS switches on or 4029off battery. 4030 4031In order for this feature to work, you must configure your UPS to 4032deliver traps to the server running apcctrl. This is generally done 4033by connecting to your SNMP card via a web browser or telnet 4034connection. You will need to enter your server's IP address as a 4035trap receiver and make sure trap delivery is enabled. 4036 4037Trap catching can lead to problems if you are already running 4038another SNMP trap daemon on your server. Only one daemon can listen 4039to the trap port, so whichever one is started first will succeed 4040and the others will fail. apcctrl will fall back to polling 4041behavior if it is unable to open the trap port. You can also 4042forcibly disable trap catching by appending ``_NOTRAP`` to your vendor 4043string in the apcctrl.conf ``DEVICE`` directive. 4044 4045Known Problems 4046-------------- 4047 4048Currently (as of 3.10.0) the code to power off the UPS needs 4049special configuration. The killpower command for SNMP UPSes can not 4050be issued during shutdown as typically at some time during shutdown 4051operations the network stack is stopped. To overcome this problem 4052it is needed to modify the /etc/rc.d/apcctrl system control script 4053to tell apcctrl to issue the power down command (killpower) to the 4054UPS immediately before apcctrl initiates the system shutdown. For 4055this reason it is paramount to set your UPS grace time to a value 4056greater than 120 seconds to allow for clean shutdown operations 4057before the UPS removes the power from its plugs. To enable correct 4058shutdown operation during powerdown do the following: 4059 4060 4061- Connect to your Web/SNMP card using your favorite web browser, 4062 go to the UPS configuration menu and change the "Shutdown Delay" 4063 parameter to 180 seconds or more, depending on how much time your 4064 system shutdown requires to umount all the filesystems. 4065 4066- **Option 1 (non-windows)** Edit the server halt script. Relocate 4067 the ups_kill_power() function higher in the shutdown sequence, 4068 primarily before the command to bring down the ethernet service. 4069 This is the preferred method for shutting down the UPS. The UPS 4070 will power down after the prescribed "Shut Down Delay" time (in 4071 seconds) has elapsed. 4072 4073- **Option 2** Change /etc/rc.d/apcctrl script adding the 4074 ``--kill-on-powerfail`` to the apcctrl invocation. This method is 4075 not preferred because the UPS is commanded to power down without 4076 delay. This creates the potential for UPS powering down before the 4077 server calling for UPS power down completes its shutdown. However, 4078 in the case of Microsoft Windows OS, this is the only method 4079 available for powering down the UPS. 4080 4081- Restart your apcctrl 4082 4083 4084With this setup your UPS operations should be safe. 4085 4086 4087apcctrl System Logging 4088====================== 4089 4090The apcctrl philosophy is that all logging should be done through the 4091``syslog`` facility (see: '``man syslog``') This is now implemented with 4092the exceptions that STATUS logging, for compatibility with 4093prior versions is still done to a file, and EVENTS logging can 4094be directed to a temporary file so that it can be reported by the 4095network information server. 4096 4097Logging Types 4098------------- 4099apcctrl splits its logging into four separate types called: 4100 4101#. DEBUG 4102#. DATA 4103#. STATUS 4104#. EVENTS 4105 4106Debug logging consists of debug messages. Normally these are turned 4107on only by developers, and currently there exist very few of these 4108debug messages. 4109 4110Data Logging 4111~~~~~~~~~~~~ 4112 4113This feature is somewhat outdated and not often used. 4114 4115Data logging consists of periodically logging important data 4116concerning the operation of the UPS. For the definitive definition 4117of the format, see log\_data() in apcreports.c. The format varies 4118according to the UPS model and the information available from the 4119UPS. 4120 4121For UPS models, NBKPRO, SMART, SHARESMART, and MATRIX, the output 4122is written in a format very similar to what PowerChute writes. That 4123is: 4124 4125MinLineVoltage, MaxLineVoltage, OutputVoltage, BatteryVoltage, 4126LineFrequency, LoadPercent, UPSTemperature, AmbientTemperature, Humidity, 4127LineVoltage, BatteryCharge, toggle 4128 4129Any value that is not supported by your UPS such as 4130AmbientTemperature and Humidity will be blank or possibly as 0.0. 4131In any case the commas before and after that field will still be 4132output. The toggle value alternates from 0 to 1 on each line. This 4133was added at user request so that no two adjacent samples are 4134identical. 4135 4136An actual example from the log file is: 4137 4138:: 4139 4140 Nov 2 12:43:05 matou apcctrl[23439]: 224.9,227.5,226.2,27.74,50.00,100.0,30.6,,,226.2,50.0,1 4141 4142 4143Status Logging 4144~~~~~~~~~~~~~~ 4145 4146Status logging consists of logging all available information known 4147about your UPS as a series of ASCII records. This information is 4148also made available by the apcctrl network information server. 4149 4150For more details on STATUS logging, see the `apcctrl Status Logging`_ 4151section for details. 4152 4153EVENTS Logging 4154~~~~~~~~~~~~~~ 4155 4156Events logging consists of logging events as they happen. For 4157example, successful startup, power fail, battery failure, system 4158shutdown, ... 4159 4160See the `Customizing Event Handling`_ section for more details. 4161 4162 4163Implementation Details 4164---------------------- 4165 4166In order to ensure that the data logged to syslog() can be directed 4167to different files, I have assigned syslog() levels to each of our 4168four types of data as follows: 4169 4170#. DEBUG logging has level LOG_DEBUG 4171#. DATA logging has level LOG_INFO 4172#. STATUS logging has level LOG_NOTICE 4173#. EVENTS logging has levels LOG_WARNING, LOG_ERR, LOG_CRIT, and LOG_ALERT 4174 4175It should be noted that more work needs to be done on the precise 4176definitions of each of the levels for EVENTS logging. Currently, it 4177is roughly broken down as follows: 4178 4179LOG_WARNING general information such as startup, etc. 4180 4181LOG_ERR an error condition detected, e.g. communications problem 4182with the UPS. 4183 4184LOG_CRIT a serious problem has occurred such as power failure, 4185running on UPS batteries, ... 4186 4187LOG_ALERT a condition that needs immediate attention such as 4188pending system shutdown, ... 4189 4190The default Facility for syslog() logging is DAEMON, although this 4191can be changed with the FACILITY directive in apcctrl.conf. In the 4192following example, we should the facility as local0. 4193 4194More work needs to be done to the code to ensure that it 4195corresponds to the above levels. 4196 4197As a practical example of how to setup your syslog() to use the new 4198logging feature, suppose you wish to direct all DATA logging to a 4199file named /var/log/apcctrl.data, all EVENTS to the standard 4200/var/log/messages file (to be mixed with other system messages), 4201and at the same time send all EVENTS to /var/log/apcctrl.events, 4202and finally, you want to send all STATUS logging to the named pipe 4203/var/log/apcctrl.status 4204 4205First as root, you create the named pipe: 4206 4207:: 4208 4209 mkfifo /var/log/apcctrl.status 4210 4211Change its permissions as necessary or use the -m option to set 4212them when creating the pipe. 4213 4214Then you modify your /etc/syslog.conf file to direct the 4215appropriate levels of messages where you want them. To accomplish 4216the above, my syslog.conf file looks like: 4217 4218:: 4219 4220 # exclude all apcctrl info by default 4221 *.info;local0.none /var/log/messages 4222 4223 # Everything for apcctrl goes here 4224 local0.info;local0.!notice /var/log/apcctrl.data 4225 local0.notice;local0.!warn |/var/log/apcctrl.status 4226 local0.warn /var/log/apcctrl.events 4227 local0.warn /var/log/messages 4228 4229 4230The Windows Version of apcctrl 4231============================== 4232 4233The Windows version of apcctrl has been tested on Win95, Win98, 4234WinMe, WinNT, WinXP, and Win2000 systems. This version of apcctrl 4235has been built to run natively on Windows (no Cygwin or other 4236emulation layer needed). Even though the Win32 version of apcctrl 4237is a port that relies on many Unix features, it is just the same a 4238true Windows program. When running, it is perfectly integrated with 4239Windows and displays its icon in the system icon tray, and provides 4240a system tray menu to obtain additional information on how apcctrl 4241is running (status and events dialog boxes). 4242 4243Once installed apcctrl normally runs as a system service. This 4244means that it is immediately started by the operating system when 4245the system is booted, and runs in the background even if there is 4246no user logged into the system. 4247 4248Installing apcctrl on Windows 4249----------------------------- 4250 4251Normally, you will install the Windows version of apcctrl from the 4252binaries. Starting with version 3.11.15, the Windows binaries are 4253distributed with a full GUI installer driven by NSIS, the 4254Nullsoft Scriptable Install System (http://nsis.sourceforge.net). 4255 4256Installation is very simple and straight-forward: Simply 4257double-click the installer executable and follow the instructions. 4258 4259Configuring apcctrl on Windows 4260------------------------------ 4261 4262If you are installing apcctrl for the first time, the installer 4263will give you an opportunity to edit the apcctrl.conf configuration 4264file to contain the values appropriate for your site. (Subsequent 4265installations will maintain your existing apcctrl.conf, so you need 4266not edit it again unless there are new features or syntax changes 4267that must be accounted for.) 4268 4269The default configuration calls for a USB connected UPS. This is 4270the most common connection for modern UPSes, especially those used 4271with Windows computers. All other apcctrl drivers are available 4272(apcsmart, dumb, net, snmp, pcnet) and can be used simply by 4273editing the configuration file ``UPSCABLE``, ``UPSTYPE``, and ``DEVICE`` 4274settings as described elsewhere in this manual. 4275 4276Note that on Windows, serial ports are specified using ``COM1``, ``COM2``, 4277etc. notation instead of the UNIX-style /dev/tty\* notation. 4278 4279Note also if you are using WinNT or Win2000, the operating system 4280may probe the serial port attempting to attach a serial mouse. This 4281will cause apcctrl to be unable to communicate with the serial 4282port. If this happens, or out of precaution, you can edit the 4283``c:\\boot.ini`` file. Find the line that looks something like the 4284following: 4285 4286:: 4287 4288 multi(0)disk(0)rdisk(0)partition(1)\WINNT="Windows NT Workstation Version 4.00" 4289 4290and add the following to the end of the line: ``/NoSerialMice:COM1`` 4291(or COM2 depending on what you want to use). The new line should 4292look similar to... 4293 4294:: 4295 4296 multi(0)disk(0)rdisk(0)partition(1)\WINNT="Windows NT Workstation Version 4.00" /NoSerialMice:COM1 4297 4298...where the only thing you have changed is to append to the end of 4299the line. This addition will prevent the operating system from 4300interfering with apcctrl 4301 4302Starting apcctrl on Windows 4303--------------------------- 4304 4305The installer will give you an opportunity start the apcctrl 4306service immediately. If you choose to start it manually, you may do 4307so by selecting the "Start apcctrl" link from the Start->Programs->apcctrl 4308folder. 4309 4310On Windows NT/2000/XP, you may alternatively go to the Control 4311Panel, open the Services folder, select apcctrl UPS Server, and 4312then click on the **Start** button as shown below: 4313 4314.. image:: ./wininstall6.png 4315 4316If the Services dialog reports a problem, it is normally because 4317your ``DEVICE`` statement does not contain the correct serial port 4318name. 4319 4320You probably should also click on the **Startup...** button to 4321ensure that the correct defaults are set. The dialogue box that 4322appears should have **Startup Type** set to **Automatic* and 4323**Logon** should be set to **System Account**. If these values are not set 4324correctly by default, please change them otherwise apcctrl will not 4325work. 4326 4327For WinXP and Win2K systems, the dialogs are a bit different from 4328those shown here for WinNT, but he concept is the same. You get to 4329the Services dialog by clicking on: Control Panel -> 4330Administrative Tools -> Component Services. The apcctrl service 4331should appear in the right hand window when you click on **Services 4332(Local)** in the left hand menu window. 4333 4334That should complete the installation process. When the system tray 4335icon turns from a question mark |image4| into a plug |image5|, 4336right click on it and a menu will appear. Select the **Events** 4337item, and the Events dialogue box should appear. There should be no 4338error messages. By right clicking again on the system tray plug and 4339selecting the **Status** item, you can verify that all the values 4340for your UPS are correct. 4341 4342When the UPS switches to the battery, the battery icon |image6| 4343will appear in the system tray. While the UPS is online, if the 4344battery is not at least 99% charged, the plug icon will become a 4345plug with a lightning bolt in the middle |image7| to indicate that 4346the battery is charging. 4347 4348Apctray 4349------- 4350 4351Starting with version 3.14.2, the tray icon is provided by a separate 4352program called 'apctray'. This cleanly separates the user interface 4353from the daemon (service) and is required for tray icon support on 4354Windows Vista. Note that if you close or disable the tray icon this 4355does **not** stop or disable the apcctrl service which will continue 4356to monitor the UPS and shutdown the computer when appropriate. To 4357stop or disable the service, use the service control panel. 4358 4359apctray has the capability of monitoring multiple apcctrl instances 4360using apcctrl's Network Information Server (NIS). It will create a 4361new icon for each instance being monitored. By default, apctray 4362monitors the local apcctrl (localhost on port 3551). To add 4363additional monitors, you can right-click an existing icon and choose 4364"Add Monitor". To remove a monitor, right-click its icon and choose 4365"Remove Monitor". To change thr settings for an existing monitor 4366(ip address, port, refresh rate), right-click its icon and choose 4367"Configure...". 4368 4369apctray can be installed standalone (without apcctrl) if you wish 4370to use it only to monitor remote apcctrl instances. This can be 4371convenient for keeping an eye on a room full of UPSes from your 4372desktop. Download and run the normal apcctrl installer and simply 4373uncheck all components except apctray. Then add as many monitors as 4374you wish as described above. 4375 4376Testing apcctrl on Windows 4377-------------------------- 4378 4379It would be hard to overemphasize the need to do a full testing of 4380your installation of apcctrl as there are a number of reasons why 4381it may not behave properly in a real power failure situation. 4382 4383Please read the `Testing apcctrl`_ section of this document for 4384general instructions on testing the Win32 version. However, on 4385Win32 systems, there is no Unix system log file, so if something 4386goes wrong, look in the file ``c:\apcctrl\etc\apcctrl\apcctrl.events`` 4387where apcctrl normally logs its events, and you will generally find 4388more detailed information on why the program is 4389not working. The most common cause of problems is either improper 4390configuration of the cable type, or an incorrect address for the 4391serial port. Additionally, check the application event log, if 4392you're running a platform that supports it such as Windows 2000 or 4393XP. 4394 4395Upgrading 4396--------- 4397 4398An upgrade may be accomplished by uninstalling the old version 4399(using the Add/Remove Programs Control Panel or clicking the 4400"Uninstall apcctrl" link from Start -> Programs -> apcctrl. Near the 4401end of the uninstall you will be prompted about removing 4402configuration and event files. You should answer "No" in order to 4403preserve your existing apcctrl.conf file. 4404 4405After the uninstall completes you may install the new version of 4406apcctrl as described above. If you preserved your existing 4407apcctrl.conf file, the new apcctrl.conf will be installed as 4408apcctrl.conf.new. 4409 4410Post-Installation 4411----------------- 4412 4413After installing 4414apcctrl and before running it, you should check the contents of the 4415config file ``c:\apcctrl\etc\apcctrl\apcctrl.conf``. You will 4416probably need to change your UPSCABLE directive, your UPSTYPE and 4417possibly your DEVICE directives. Please refer to the configuration 4418section of this manual for more details. 4419 4420Problem Areas 4421------------- 4422On some Windows systems, the 4423domain resolution does not seem to work if you have not configured 4424a DNS server in the Network section of the Control Panel. This 4425problem should be apparent only when running a slave configuration. 4426In this case, when you specify the name of the master in your 4427apcctrl.conf file, apcctrl will be unable to resolve the name to a 4428valid IP address. To circumvent this problem, simply enter the 4429address as an IP address rather than a hostname, or alternatively, 4430ensure that you have a valid DNS server configured on your system. 4431 4432On WinNT, WinXP, and Win2K systems, you can examine the System 4433Applications log to which apcctrl writes Windows error messages 4434during startup. 4435 4436Regardless of which Windows system you are running, apcctrl logs 4437most error messages to ``c:\apcctrl\etc\apcctrl\apcctrl.events``. 4438This type error messages such as configuration 4439file not found, etc are written to this file. Note that on some 4440systems (WinXP, possibly others) apcctrl is unable to write to this 4441file when running as a service. 4442 4443 4444Email Notification of Events 4445---------------------------- 4446 4447It is possible to receive email notification of apcctrl events 4448using some simple Visual Basic scripts contributed by Ed Dondlinger 4449<edondlinger@thepylegroup.com>. The scripts are automatically installed in 4450the ``etc/apcctrl`` directory of your apcctrl installation but are disabled 4451by default. To enable them, first open them in a text editor such as Notepad 4452and edit the ``USER VARIABLES`` section to set your email preferences including 4453address, server information, etc. Then rename the script files without the 4454``*.example`` suffix. Scripts are supplied for onbattery, offbattery, and 4455commfailure events. You can copy the scripts to other filenames and modify 4456the email body text to respond to other events as described in `Customizing 4457Event Handling`_. 4458 4459Killpower under Windows 4460----------------------- 4461 4462If your batteries become 4463exhausted during a power failure and you want your machine to 4464automatically reboot when the power comes back, it is useful to 4465implement the killpower feature of the UPS where apcctrl sends the 4466UPS the command to shut off the power. In doing so, the power will 4467be cut to your PC and if your BIOS is properly setup, the machine 4468will automatically reboot when the power comes back. This is 4469important for servers. 4470 4471This feature is implemented on Unix systems by first requesting a 4472system shutdown. As a part of the shutdown, apcctrl is terminated 4473by the system, but the shutdown process executes a script where 4474apcctrl is recalled after the disks are synced and the machine is 4475idle. apcctrl then requests the UPS to shut off the power 4476(killpower). 4477 4478Unfortunately on Windows, there is no such shutdown script that we 4479are aware of and no way for apcctrl to get control after the 4480machine is idled. If this feature is important to you, it is 4481possible to do it by telling apcctrl to immediately issue the 4482killpower command after issuing the shutdown request. The danger in 4483doing so is that if the machine is not sufficiently idled when the 4484killpower takes place, the disks will need to be rescanned (and 4485there is a possibility of lost data however small). Generally, 4486UPSes have a shutdown grace period which gives sufficient time for 4487the OS to shutdown before the power is cut. 4488 4489To implement this feature, you need to add the ``-p`` option to the 4490apcctrl command line that is executed by the system. Currently the 4491procedure is manual. You do so by editing the registry and changing 4492the line: 4493 4494:: 4495 4496 c:\apcctrl\apcctrl.exe /service 4497 4498found under the key: 4499 4500:: 4501 4502 HKEY_LOCAL_MACHINE Software\Microsoft\Windows\CurrentVersion\RunServices 4503 4504to 4505 4506:: 4507 4508 c:\apcctrl\apcctrl.exe /service -p 4509 4510If you have a Smart UPS, you can configure the kill power grace 4511period, and you might want to set it to 3 minutes. If you have a 4512dumb UPS, there is no grace period and you should not use this 4513procedure. If you have a Back-UPS CS or ES, these UPSes generally 4514have a fixed grace period of 2 minutes, which is probably 4515sufficient. 4516 4517Power Down During Shutdown 4518-------------------------- 4519 4520Our philosophy is to shutdown 4521a computer but not to power it down itself (as opposed to having 4522the UPS cut the power as described above). That is we prefer to 4523idle a computer but leave it running. This has the advantage that 4524in a power fail situation, if the killpower function described 4525above does not work, the computer will continue to draw down the 4526batteries and the UPS will hopefully shutoff before the power is 4527restore thus permitting an automatic reboot. 4528 4529Nevertheless some people prefer to do a full power down. To do so, 4530you might want to get a copy of PsShutdown, which does have a power 4531down option. You can find it and a lot more useful software at: 4532http://technet.microsoft.com/en-us/sysinternals/bb897541.aspx. To use their shutdown 4533program rather than the apcctrl supplied version, you simply edit: 4534 4535:: 4536 4537 c:\apcctrl\etc\apcctrl\apccontrol 4538 4539with any text editor and change our calls to shutdown to 4540psshutdown. 4541 4542 4543Command Line Options Specific to the Windows Version 4544---------------------------------------------------- 4545 4546These options are not normally 4547seen or used by the user, and are documented here only for 4548information purposes. At the current time, to change the default 4549options, you must either manually run apcctrl or you must manually 4550edit the system registry and modify the appropriate entries. 4551 4552In order to avoid option clashes between the options necessary for 4553apcctrl to run on Windows and the standard apcctrl options, all 4554Windows specific options are signaled with a forward slash 4555character (``/``), while as usual, the standard apcctrl options are 4556signaled with a minus (``-``), or a minus minus (``--``). All the 4557standard apcctrl options can be used on the Windows version. In 4558addition, the following Windows only options are implemented: 4559 4560/service Start apcctrl as a service 4561/run Run the apcctrl application 4562/install Install apcctrl as a service in the system registry 4563/remove Uninstall apcctrl from the system registry 4564/about Show the apcctrl about dialogue box 4565/kill Stop any running apcctrl 4566/help Show the apcctrl help dialogue box 4567 4568It is important to note that under normal circumstances the user 4569should never need to use these options as they are normally handled 4570by the system automatically once apcctrl is installed. However, you 4571may note these options in some of the .pif files that have been 4572created for your use. 4573 4574Installation: Serial-Line UPSes 4575=============================== 4576 4577 4578Overview of Serial-Interface UPSes 4579---------------------------------- 4580 4581If you have a UPS that communicates via 4582serial port, you need to do two things before you can even think 4583about configuring the software. First, you need to figure out 4584whether it's a dumb (voltage-signalling) UPS or speaks the apcsmart 4585protocol. Second, 4586if you have an interface cable from APC, you need to figure out 4587what kind it is. If you don't have such a cable, you need to build 4588one. A straight-through serial cable won't work. 4589 4590According to Bill Marr the Belkin F5U109, also sold as F5U409 also 4591works with apcctrl for kernel versions 2.4.25 or higher and kernels 45922.6.1 and higher. These newer kernels are needed to have the patch 4593that makes the mct\_u232 (Magic Control Technology) module and 4594other adapters work with RS-232 devices that do not assert the CTS 4595signal. 4596 4597Connecting a Serial-Line UPS to a USB Port 4598------------------------------------------ 4599 4600By using a special adaptor, you can 4601connect your serial-line UPS to a USB port. If you would like to 4602free up your serial port and connect your existing serial port UPS 4603to a USB port, it is possible if you have one of the later kernels. 4604You simply get a serial to USB adapter that is supported by the 4605kernel, plug it in and make one minor change to your apcctrl.conf 4606file and away you go. (Kern adds: Thanks to Joe Acosta for pointing 4607this out to me.) 4608 4609The device that Joe Acosta and Kern are using is IOgear GUC232A USB 46102 serial adapter. Bill Marr informs us that it also works with a 4611Back-UPS Pro 650 and the 940-0095B cable. 4612 4613At Kern's site, running Red Hat 7.1 with kernel 2.4.9-12, he simply 4614changed his /etc/apcctrl/apcctrl.conf configuration line to be: 4615 4616:: 4617 4618 DEVICE /dev/ttyUSB0 4619 4620Depending on whether or not you have hotplug working, you may 4621need to explicitly load the kernel modules ``usbserial`` and 4622``pl2303``. In Kern's case, this was not necessary. 4623 4624 4625Testing Serial-Line UPSes 4626------------------------- 4627 4628If you have a serial-line UPS, there are some tests you should run 4629before the general ones described in the `Testing apcctrl`_ section. 4630 4631To test your computer's connection with a serial-line UPS, you 4632first need to establish that the serial line is functioning, and 4633then that the UPS is responding to commands. This can be a bit 4634tricky, especially with a dumb voltage-signalling interface, 4635because it is completely quiescent when there are no commands being 4636passed, and the command repertoire doesn't include any self-tests. 4637 4638Because it is easy to configure a serial cable incorrectly in such 4639a way as to cause premature shutdowns of the UPS power, we 4640*strongly* recommend, especially for voltage- signaling (dumb) 4641UPSes, that you do most of the initial testing with your computer 4642plugged into the wall rather than your UPS. Thus if the UPS power 4643is suddenly shut off, your computer will continue to run. We also 4644recommend using safe-apccontrol as described below, until you are 4645sure that the signaling is correct. 4646 4647Also note that if you launch the execution of apcctrl while your 4648voltage-signaling UPS is on battery power, it is very likely that 4649your UPS will immediately shut off the power. This is due to the 4650initialization of the serial port line signals, which often looks 4651to the UPS like a shutdown command. 4652 4653Finally, double-check the state of your cabling and UPS indicator 4654lights frequently during testing. For voltage-signaling UPSes, 4655apcctrl is not currently able to detect whether or not the serial 4656cable is connected. In addition, some simple signaling UPSes with 4657certain cable combinations are not able to detect the low battery 4658condition. For more details please see `Voltage Signalling Features 4659Supported by apcctrl for Various Cables`_. 4660 4661Establishing Serial Port Connection 4662----------------------------------- 4663 4664Once you have compiled, installed, 4665and invoked apcctrl, you should wait to allow apcctrl to configure 4666itself and establish contact with the UPS. 4667 4668If you see a message similar to the following about 30 seconds after starting 4669apcctrl... 4670 4671:: 4672 4673 apcctrl FATAL ERROR in apcserial.c at line 156 4674 PANIC! Cannot communicate with UPS via serial port. 4675 4676it means that apcctrl tried for about 30 seconds to establish 4677contact with the UPS via the serial port, but was unable to do so. 4678Before continuing, you must correct this problem. Some of the 4679possible sources of the problem are: 4680 4681- You have not configured the correct serial port name on the 4682 ``DEVICE`` directive in your apcctrl configuration file. 4683 4684- The serial port that you have chosen has logins enabled. You 4685 must disable logins on that port, otherwise, the system prevents 4686 apcctrl from using it. Normally, the file /etc/inittab specifies 4687 the ports for which a getty process is started (on Sun machines, 4688 the serial port program equivalent to getty is called ttymon). You 4689 must disable this for the port that you wish to use. 4690 4691- Make sure you are doing your testing as root otherwise, you 4692 may have permissions problems accessing the serial port. 4693 4694- You may have cabling problems, either with an incorrect cable, 4695 or the incorrect cable specification directive in the configuration 4696 file. 4697 4698- You may have a problem with the /etc/apcctrl/acpupsd.conf file. 4699 For example, check that you have specified the correct type of UPS 4700 and the correct networking directives. For more details, see the 4701 `After Installation`_ section. 4702 4703- If you have a SmartUPS 5000 RM 15U or similar model, that comes 4704 with a "Web/SNMP management card" in one of the "Smart Slots", this 4705 card may interfere with the serial port operation. If you are 4706 having problems, please remove this card and try again. Supposedly 4707 V3.0 of the card firmware has been corrected to properly release 4708 the serial port. 4709 4710- Ensure that you have no other programs that are using the serial 4711 port. One user reported that he had problems because the serial 4712 port mouse (gpm) was using the same port as apcctrl. This causes 4713 intermittent seemingly random problems. 4714 4715- Try connecting your UPS to another machine. If it works, then 4716 you probably have a bad serial port card. As unlikely as this may 4717 sound, at least two of our users have had to replace bad serial 4718 port cards. 4719 4720- Try doing an '``lsof /dev/ttyS0``' where you replace the 4721 ``/dev/ttyS0`` with your serial port name. If you get no output, the 4722 port is free (or there is no physical port). If you get output, 4723 then another program is using the port, and you should see which 4724 one. 4725 4726- Try doing a '``dmesg | grep tty``'. This may show you if a program 4727 has grabbed the port. (Thanks to Joe Acosta for the suggestion.) 4728 4729- If all else fails, make sure your system is configured for 4730 serial port support. 4731 4732 4733The first thing to do is to look at your log file, usually 4734/var/log/messages because apcctrl writes more detailed information 4735to the log file whenever there is an error. 4736 4737If you have a UPS that uses apcsmart protocol, you can manually test the 4738serial communications with the UPS by starting a serial port communications 4739program (such as minicom, tip, or cu) with the settings 2400 8N1 (2400 baud, 47408 data bits, no parity, 1 stop bit). Be extremely careful what you send to 4741your UPS as certain characters may cause it to power down or may 4742even cause damage to the UPS. Try sending an upper case ``Y`` to the 4743UPS (without a return at the end). It should respond with ``SM``. If 4744this is not the case, review the possible problems listed above. If 4745you fat finger the Y and enter y instead, no cause for alarm, you 4746will simply get the APC copyright notice. 4747 4748Once you are sure that serial port communications is working, 4749proceed to the next test. 4750 4751 4752Once you have established serial communications 4753----------------------------------------------- 4754 4755Once you have established that apcctrl can talk 4756to the UPS over the serial part, go do the series of functional 4757tests described in the main Testing section (see `Testing apcctrl`_). 4758 4759 4760Troubleshooting Serial Line communications 4761------------------------------------------ 4762 4763*The most frequently encountered problem with voltage-signalling 4764UPSes (e.g. BackUPS 650) is that you have incorrectly specified 4765which cable is being used.* All cables furnished by APC have the 4766cable number stamped on the side of the computer connector end of 4767the cable. Using this number with apcctrl will normally work fine. 4768If you do not know what cable you have, you can use the apctest 4769program to determine the type of the cable. 4770 4771For simple signaling UPSes, you should **not** use ``simple`` in the 4772cable specification (i.e. ``UPSCABLE simple``) unless you have made 4773the cable yourself according to the wiring diagram given in the 4774cables chapter of this manual. 4775 4776Bizarre Intermittent Behavior: 4777~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 4778 4779In one case, a user reported that he received random incorrect 4780values from the UPS in the status output. It turned out that gpm, 4781the mouse control program for command windows, was using the serial 4782port without using the standard Unix locking mechanism. As a 4783consequence, both apcctrl and gpm were reading the serial port. 4784Please ensure that if you are running gpm that it is not configured 4785with a serial port mouse on the same serial port. 4786 4787 4788.. include:: cables.rst 4789 4790 4791Recalibrating the UPS Runtime 4792============================= 4793 4794Note: In a future release of apcctrl this procedure will be 4795replaced by a daemon operation that can be performed on all types 4796of UPS. 4797 4798This section does not apply to voltage-signalling or dumb UPSes 4799such as the older BackUPS models. 4800 4801Smart UPSes internally compute the remaining runtime, and apcctrl 4802uses the value supplied by the UPS. As the batteries age (after say 4803two or three years), the runtime computation may no longer be 4804accurate since the batteries no longer hold the same charge. As a 4805consequence, in the event of a power failure, the UPS and thus 4806apcctrl can report a runtime of 5 minutes remaining when in fact 4807only one minute remains. This can lead to a shutdown before you 4808might expect it, because regardless of the runtime remaining that 4809is reported, the UPS will always correctly detect low batteries and 4810report it, thus causing apcctrl to correctly shutdown your 4811computer. 4812 4813If you wish to have the UPS recalibrate the remaining runtime 4814calculations, you can do so manually as the current version of 4815apcctrl does not support this feature. To do so, 4816 4817- Shutdown apcctrl 4818 4819- contact your UPS directly using some terminal program such as 4820 minicom, tip, or cu with the settings 2400 8N1 (2400 baud, 8 bits, 4821 no parity, 1 stop bit). Be extremely careful what you send to your 4822 UPS as certain characters may cause it to power down or may even 4823 cause damage to the UPS. Try sending an upper case ``Y`` to the UPS 4824 (without a return at the end). It should respond with ``SM``. If this 4825 is not the case, read the chapter on testing. If you fat finger the 4826 ``Y`` and enter ``y`` instead, no cause for alarm, you will simply get the 4827 APC copyright notice. 4828 4829- when you are sure you are properly connected send an upper case 4830 D (no cr). This will put the UPS into calibration mode, and it will 4831 drain the battery down to 25% capacity (35% for a Matrix) at which 4832 point it will go back on the mains. In doing so, it will recompute 4833 the runtime calibration. 4834 4835- If you wish to abort the calibration, enter a second D command. 4836 4837- When you are done, restart apcctrl. 4838 4839 4840In principle, you should be able to do this with the computer 4841powered by the UPS, but if you wish to be completely safe, you 4842should plug your computer into the wall prior to performing the 4843runtime calibration. In that case, you will need to artificially 4844load the UPS with light bulbs or other means. You should supply a 4845load of about 30 to 35% but not more than 50%. You can determine 4846the load by looking at the output of the ``apcaccess status`` 4847command while apcctrl is running. 4848 4849You should not run the recalibration command more than once or 4850twice per year as discharging these kinds of batteries tends to 4851shorten their life span. 4852 4853 4854Configuration Directive Reference 4855================================= 4856 4857Configuration directives in /etc/apcctrl/apcctrl.conf control the 4858behavior of the apcctrl daemon. For most installations it is only 4859necessary to set a handful of general directives. The rest can be 4860left at their defaults unless you have an exotic configuration. 4861 4862Note that the apcctrl daemon must be restarted in order for changes to 4863the configuration file to become active. 4864 4865General Configuration Directives 4866-------------------------------- 4867 4868In general, each of these directives is required (except that the 4869``DEVICE`` directive is ignored for ``UPSCABLE ether`` and not required 4870for ``UPSCABLE usb``). 4871 4872**UPSTYPE** *driver* 4873 The name of a driver. Should be one of ``dumb``, ``apcsmart``, ``net``, 4874 ``usb``, ``pcnet``, ``snmp``, or ``test``. 4875 This describes your interface type. The UPSTYPE directive can be 4876 defined during installation by using the ``--with-upstype=`` option 4877 of the ``configure`` program. 4878 4879**UPSCABLE** *cable* 4880 Defines the type of cable connecting the UPS to your computer. 4881 4882 Possible generic choices for <cable> are: 4883 ``simple``, ``smart``, ``ether``, ``usb`` 4884 4885 Or a specific cable model number may be used: 4886 ``940-0119A``, ``940-0127A``, ``940-0128A``, ``940-0020B``, 4887 ``940-0020C``, ``940-0023A``, ``940-0024B``, ``940-0024C``, 4888 ``940-1524C``, ``940-0024G``, ``940-0095A``, ``940-0095B``, 4889 ``940-0095C``, ``M-04-02-2000`` 4890 4891 The ``--with-upscable=`` option of ``configure`` can be used to 4892 set a default for this directive during the your build. 4893 4894**DEVICE** *device* 4895 Specify which 4896 device is used for UPS communications. For serial ports, it is 4897 usually something like /dev/ttyS0. For USB ports, you may leave the 4898 name of the device blank (no specification) and apcctrl will 4899 automatically search the standard locations for the UPS. 4900 4901 Normally, the ``configure`` program will set an appropriate 4902 default value. You may also specify the ``--with-serial-dev=`` 4903 option of the ``configure`` program to set this directive at build 4904 time. 4905 4906 If you have specified ``UPSTYPE net``, then the device name to be 4907 specified consists of *hostname:port* where the *hostname* is the 4908 fully qualified name or IP address of the host (NIS server) and the 4909 *port* (optional) is the port to use to contact the server. 4910 4911 If you specified ``UPSTYPE snmp``, then the device name becomes 4912 *hostname:vendor:community*. Please see the `Support for SNMP UPSes`_ 4913 chapter in this manual for more details. 4914 4915**POLLTIME** *time in seconds* 4916 The interval, in seconds, at which apcctrl polls the UPS for status. 4917 This rate is automatically set to 1 second if the UPS goes on 4918 batteries and reset to your specified value when the mains power 4919 returns. This setting applies both to directly-attached UPSes 4920 (``UPSTYPE`` ``apcsmart``, ``usb``, ``dumb``) and networked UPSes 4921 (``UPSTYPE`` ``net``, ``snmp``). Lowering this setting will improve 4922 apcctrl's responsiveness to certain events at the cost of higher CPU 4923 utilization. The default of 60 is appropriate for most situations. 4924 This directive was formerly known as ``NETTIME``. 4925 4926**LOCKFILE** *path to lockfile* 4927 This option tells apcctrl where to create a lockfile for the USB or 4928 serial port in the specified directory. This is important to keep 4929 two programs from reading or writing the port at the same time. 4930 Please note that although the directive name is LOCKFILE, you are 4931 actually specifying the lock file path. apcctrl automatically 4932 appends the name of the device when creating the file. On most 4933 systems, this directive is automatically set by the ``./configure`` 4934 program. You may also explicitly set it during the build process by 4935 using the ``--with-lock-dir=`` option of the ``configure`` program. 4936 4937Configuration Directives Used by the Network Information Server 4938--------------------------------------------------------------- 4939None of these directives are required for proper operation of 4940apcctrl. 4941 4942**NETSERVER** *[on \| off]* 4943 This configuration directive turns the network information server on or 4944 off. If it is on, apcctrl will spawn a child process that serves 4945 STATUS and EVENTS information over the network. This information is 4946 currently used by the Web-based CGI programs. The default is on. *This 4947 option is required to be turned on for net clients and apcaccess to 4948 function.* 4949 4950**NISIP** *IP-address* 4951 This directive specifies the 4952 IP address of the network interface on which the NIS server will 4953 listen for incoming connections. Default value is 0.0.0.0 which 4954 means the NIS will listen for connections on all network 4955 interfaces. If your machine has more than one interface, you can 4956 specify the IP of a single interface to limit connections to only 4957 that interface. Furthermore, you can specify the loopback address 4958 (127.0.0.1) to accept connections only from the local machine. You 4959 may also use the ``--with-nisip=`` option of the ``configure`` 4960 program to set this directive during the build. 4961 4962**NISPORT** *port* 4963 This configuration directive 4964 specifies the port to be used by the apcctrl Network Information 4965 Server. The default is platform dependent, but typically 3551, 4966 which we have received from IANA as the official apcctrl networking 4967 port. This value should only be changed if it conflicts with an 4968 existing service in use on your network or if you are running multiple 4969 instances of apcctrl on the same machine. 4970 4971**EVENTSFILE** *filename* 4972 If you want the apcctrl network information server to provide the last 4973 10 events via the network, you must specify a file where apcctrl will save 4974 these events. The default is: /etc/apcctrl/apcctrl.events. 4975 Currently, apcctrl will save at most the last 50 events. 4976 Periodically (once an hour by default), apcctrl will check the size 4977 of this file. When more than 50 events are recorded, apcctrl will 4978 truncate the file to the most recent 10 events. Consequently this 4979 file will not grow indefinitely. Although we do not recommend it, 4980 you may change these values by editing apcevents.c and changing the 4981 appropriate defines. Be aware that if you set these values to very 4982 large numbers, apcctrl may make excessive memory demands on the 4983 system during the data access and file truncation operations. 4984 4985 This filename may also be specified at build time by using the 4986 ``--with-log-dir=`` option of the ``configure`` program. 4987 4988 4989Configuration Directives used during Power Failures 4990--------------------------------------------------- 4991 4992In general, none of these 4993directives are required. However, if you have a voltage-signalling 4994(dumb) UPS with a cable that does not support the Low Battery 4995signal, you must set the ``TIMEOUT`` directive to force a shutdown. 4996 4997**BATTERYLEVEL** *percent of battery* 4998 If ``BATTERYLEVEL`` is specified, during a power failure, apcctrl 4999 will halt the system when the remaining battery charge falls below 5000 the specified percentage. The default is 5 percent. This directive 5001 is ignored for dumb (voltage-signalling) UPSes. To totally disable 5002 this counter, set ``BATTERYLEVEL -1`` in your apcctrl.conf file. 5003 5004**MINUTES** *battery runtime in minutes* 5005 If ``MINUTES`` is specified, during a power failure, apcctrl 5006 will shutdown the system when the remaining runtime on batteries as 5007 internally calculated by the UPS falls below the time specified. 5008 The default is 3. This directive is ignored for dumb 5009 (voltage-signalling) UPSes. It should be noted that some UPSes 5010 report an incorrect value for remaining runtime when the battery is 5011 fully charged. This can be checked by examining the ``TIMELEFT`` 5012 value as printed in the output of an '``apcaccess status``' command. 5013 If the value is zero or otherwise unreasonable, your UPS is 5014 probably broken. In this case, we recommend that you disable this 5015 timer by setting ``MINUTES -1`` in your apcctrl.conf file. 5016 5017**TIMEOUT** *time in seconds* 5018 After a power 5019 failure, apcctrl will halt the system when ``TIMEOUT`` seconds have 5020 expired. A value of zero disables this timer. Normally for all 5021 Smart UPS models and dumb UPSes with cables that support low 5022 battery detection, this should be zero so that the shutdown time 5023 will be determined by the battery level and/or remaining runtime 5024 (see above) or in the case of a voltage-signalling UPS, when the 5025 battery is exhausted. This command is required for dumb UPSes that 5026 do not provide a battery exhausted signal (only testing can 5027 determine this point). For more information, see the 5028 `Testing apcctrl`_ section of this manual. This 5029 timer can also be useful if you want some slave machines to 5030 shutdown before other machines to conserve battery power. It is 5031 also useful for testing apcctrl because you can force a rapid 5032 shutdown by setting a small value (e.g. 60) and pulling the plug to 5033 the UPS. 5034 5035``TIMEOUT``, ``BATTERYLEVEL``, and ``MINUTES`` can be set together 5036without problems. apcctrl will react to the first case or test that 5037is valid. Normally SmartUPS users will set ``TIMEOUT`` to zero so 5038that the system is shutdown depending on the percentage battery 5039charge remaining (``BATTERYLEVEL``) or the remaining battery runtime 5040(``MINUTES``). 5041 5042**ANNOY** *time in seconds* 5043 Specify the time 5044 in seconds between messages requesting logged in users to get off 5045 the system during a power failure. This timer starts only when the 5046 UPS is running on batteries. The default is 300 seconds (5 5047 minutes). apcctrl sends the annoy messages by invoking the 5048 apccontrol script with the ``annoyme`` argument. The default is to 5049 send a wall message on Unix systems and a popup message in 5050 Windows. 5051 5052 The value of ``ANNOYDELAY`` must be greater than the value of 5053 ``ANNOY`` in order to receive annoy messages (this doesn't make sense, 5054 and means that the default values do not generate annoy messages: 5055 KES). 5056 5057 Note that if ``NOLOGON disable`` is set, the annoy messages 5058 will also be disabled. 5059 5060**ANNOYDELAY** *time in seconds* 5061 Specify delay time in seconds before apcctrl begins requesting logged in 5062 users to get off the system during a power failure. This timer 5063 starts only after the UPS is running on batteries. This timer is 5064 reset when the power returns. The default is 60 seconds. Thus, the 5065 first warning to log off the system occurs after 60 seconds on 5066 batteries, assuming that ``NOLOGON`` is not set to ``disable``. 5067 5068**NOLOGON** *disable* | *timeout* | *percent* | *minutes* | *always* 5069 Specifies when apcctrl should prevent user logins 5070 5071 The type specified allows you define the point when apcctrl will 5072 create the 'nologin' file and thus when user logins are prohibited. 5073 Once the 'nologin' file is created, normal users are prevented from 5074 logging in. Control of when this file is created is important for 5075 allowing systems with big UPSes to run as normally until the system 5076 administrator determines the need for preventing user logins. The 5077 feature also allows the system administrator to hold the "ANNOY" 5078 factor until the 'nologin' file is created. The default is always 5079 disable if no ``NOLOGON`` directive is specified. 5080 5081 The 'nologin' file will be created in the directory specified by 5082 the ``NOLOGINDIR`` directive described below. 5083 5084 As far as I can tell, the only useful types are disable and always 5085 since the difference in the time when the logout warning is given 5086 and shutdown occurs for the other types is very short (KES). 5087 5088 *disable* prevents apcctrl from creating the nologin 5089 file. Consequently, any user can login during a power failure 5090 condition. Also, the ANNOY feature is disabled so users will not be 5091 warned to logoff the system. 5092 5093 *timeout* specifies that apcctrl should prohibit logins 5094 after the UPS is on batteries for 90% of the time specified on the 5095 ``TIMEOUT`` configuration directive. Note! Normally you don't want 5096 to specify a TIMEOUT value, so this option is probably not too 5097 useful (KES). 5098 5099 *percent* specifies that apcctrl should prohibit logins 5100 when the remaining battery charge percentage reaches 110% or less 5101 than the value specified on the ``BATTERYLEVEL`` configuration 5102 directive. Thus if the ``BATTERYLEVEL`` is specified as 15, apcctrl 5103 will prohibit logins when the battery charge drops below 16% (15% X 5104 110% = 16%). 5105 5106 *minutes* specifies that apcctrl should prohibit logins 5107 when the remaining runtime in minutes reaches 110% or less than the 5108 value specified on the ``MINUTES`` configuration directive. Thus if 5109 ``MINUTES`` is set to 3, apcctrl will prohibit logins when the 5110 remaining runtime is less than 3 minutes (3 X 110% = 3). 5111 5112 *always* causes apcctrl to immediately prohibit logins 5113 when a power failure occurs. This will also enable the ANNOY 5114 feature. 5115 5116 5117**NOLOGINDIR** *path to nologin dir* 5118 This directive configures the directory into which apcctrl will 5119 write the nologin file, as described above for the ``NOLOGON`` 5120 directive. 5121 5122 Normally, the ``configure`` program will set an appropriate 5123 default value for your platform, often /etc. You may also specify 5124 the ``--with-nologdir=`` option of the ``configure`` program to 5125 change the default at compile time. 5126 5127**KILLDELAY** *time in seconds* 5128 If ``KILLDELAY`` is set, apcctrl will continue running after a shutdown 5129 has been requested, and after the specified time in seconds, 5130 apcctrl will attempt to shut off the UPS the power. This directive 5131 should normally be disabled by setting the value to zero, but on 5132 some systems such as Win32 systems apcctrl cannot regain control 5133 after a shutdown to force the UPS to shut off the power. In this 5134 case, with proper consideration for the timing, the ``KILLDELAY`` 5135 directive can be useful. Please be aware, if you cause apcctrl to 5136 kill the power to your computer too early, the system and the disks 5137 may not have been properly prepared. In addition, apcctrl must 5138 continue running after the shutdown is requested, and on Unix 5139 systems, this is not normally the case as the system will terminate 5140 all processes during the shutdown. 5141 5142**SCRIPTDIR** *path to apccontrol dir* 5143 This option configures the directory in which apccontrol and 5144 other event scripts are located. 5145 5146 Normally, the ``configure`` program will set an appropriate 5147 default value for your platform, often /etc/apcctrl. 5148 5149**PWRFAILDIR** *path to powerfail dir* 5150 When apcctrl shuts down your system, it creates a temporary 5151 "flag file" which is used by the operating system halt scripts to 5152 know if this shutdown is due to a power failure. This directive 5153 configures which directory the flag file will be written into. The 5154 chosen directory must be writable by the user apcctrl is running as 5155 (normally root) and must not be cleared or unmounted early in the 5156 shutdown sequence. 5157 5158 Normally, the ``configure`` program will set an appropriate 5159 default value for your platform, often /etc/apcctrl. You may also 5160 specify the ``--with-pwrfaildir=`` option of the ``configure`` 5161 program to change the default at compile time. 5162 5163 5164Configuration Directives used to Control System Logging 5165------------------------------------------------------- 5166 5167**STATTIME** *time in seconds* 5168 This directive supplies the time 5169 interval in seconds between writes to the STATUS file. If set to zero, the 5170 STATUS file will not be written. Please note that in a future 5171 version of apcctrl the STATUS file code will disappear since its 5172 functionality has been replaced by the Network Information Server 5173 and by ``apcaccess status``, as a consequence, it is normally 5174 disabled by setting it to zero. 5175 5176**STATFILE** *file* 5177 This directive specifies the file 5178 to be used when writing the STATUS information. The default is 5179 /etc/apcctrl/apcctrl.status. 5180 5181**DATATIME** *time in seconds* 5182 This directives supplies the time 5183 interval in seconds between writes of PowerChute-like data information to 5184 the log file. See the `DATA Logging`_ section of this manual for 5185 additional details. 5186 5187**FACILITY** *log-facility* 5188 The ``FACILITY`` 5189 directive can be used to change the system logging class or 5190 facility. The default is ``DAEMON``. This parameter can be useful if 5191 you wish to direct the apcctrl system logging information to other 5192 than your system default files. See the `apcctrl System Logging`_ 5193 section of this manual for additional details. 5194 5195 5196Configuration Directives for Sharing a UPS 5197------------------------------------------ 5198 5199The following directives apply to sharing an UPS using a ShareUPS 5200hardware module. Most users will not use this mode. 5201 5202**UPSCLASS** *standalone* | *shareslave* | *sharemaster* 5203 5204 The default is ``standalone`` and should be used for all machines 5205 powered by the UPS and having a serial port or other direct 5206 connection to the UPS. This is the normal case. 5207 5208 Use ``shareslave`` if and only if you are using a ShareUPS and 5209 connected to a BASIC Port with Simple Signal. This code is not 5210 fully tested. 5211 5212 Use ``sharemaster``, if and only if you are using a ShareUPS and 5213 connected to the ADVANCED Port Smart Signal control. This code is 5214 not fully tested. 5215 5216**UPSMODE** *disable* | *share* 5217 5218 For normal standalone operations, you will set ``UPSMODE disable`` 5219 to indicate that you are disabling the ShareUPS support. 5220 5221 Use ``share`` for two or seven additional simple signal ports on 5222 a SmartAccessories(tm) (internal/external box) for SmartUPSes. The 5223 share and sharenet code is not fully tested. 5224 5225 5226Configuration Directives Used to Set the UPS EEPROM 5227--------------------------------------------------- 5228 5229*These directives have no effect on the operation of apcctrl but are 5230reserved for use by apctest when bulk programming the values of the 5231UPS EEPROM configuration variables in a Smart-UPS model.* 5232 5233**UPSNAME** *<string>* 5234 5235 Name of UPS. Maximum of 8 characters. 5236 5237**BATTDATE** [ *mm/dd/yy* | *dd/mm/yy* ] 5238 5239 Last battery replacement date. Maximum of 8 characters. 5240 5241**SENSITIVITY** [ *H* | *M* | *L* ] 5242 5243 H : High (most sensitive setting) 5244 M : Medium 5245 L : Low (least sensitive setting) 5246 5247**WAKEUP** [ *000* | *060* | *180* | *300* ] 5248 5249 The time delay in seconds that the UPS waits after the return of utility 5250 power before "waking up" and restoring power to the connected equipment. 5251 5252**SLEEP** [ *020* | *180* | *300* | *600* ] 5253 5254 The time delay in seconds for which the UPS waits or "sleeps" after it 5255 receives a request to power off the connected system. 5256 5257**LOTRANSFER** *<voltage>* 5258 5259 Low line voltage causing transfer to battery power or activation of 5260 SmartBoost. Allowable values depend on the last letter of the firmware 5261 or APCMODEL. Typical values are:: 5262 5263 D 106 103 100 097 5264 M 177 172 168 182 5265 A 092 090 088 086 5266 I 208 204 200 196 5267 5268 where D = domestic (USA), M = Canada, A = Asia and I = International. 5269 5270**HITRANSFER** *<voltage>* 5271 5272 High line voltage causing transfer to battery power or activation of 5273 SmartTrim. Allowable values depend on the last letter of the firmware 5274 or APCMODEL. Typical values are:: 5275 5276 D 127 130 133 136 5277 M 229 234 239 224 5278 A 108 110 112 114 5279 I 253 257 261 265 5280 5281 where D = domestic (USA), M = Canada, A = Asia and I = International. 5282 5283**RETURNCHARGE** [ *00* | *15* | *50* | *90* ] 5284 5285 Percentage of battery charge needed for the UPS to restore power to the 5286 connected equipment. 5287 5288**BEEPSTATE** [ *0* | *T* | *L* | *N* ] 5289 5290 Alarm delay. 5291 5292 :: 5293 5294 0 : Zero delay after power fails. 5295 T : When power fails plus 30 seconds. 5296 L : When low battery occurs. 5297 N : Never. 5298 5299**LOWBATT** *<minutes>* 5300 5301 Low battery warning occurs when the specified number of minutes remains 5302 before the UPS estimates battery power will be exhausted. There are four 5303 user-changeable settings: 2, 5, 7, or 10 minutes 5304 5305**OUTPUTVOLTS** *<voltage>* 5306 5307 UPS nominal output voltage when running on battery. Allowable values 5308 depend on the last letter of the firmware or APCMODEL. Typical values are:: 5309 5310 D 115 5311 M 208 5312 A 100 5313 I 230 240 220 225 5314 5315 where D = domestic (USA), M = Canada, A = Asia and I = International. 5316 5317**SELFTEST** [ *336* | *168* | *ON* | *OFF* ] 5318 5319 Self test interval in hours (336 = 2 weeks, 168 = 1 week, 5320 ON = at power on, OFF = never). 5321 5322 5323apcctrl Status Logging 5324====================== 5325 5326There is a good deal of information available about the UPS and apcctrl's 5327status. This document describes the format of that information. 5328Normally you will get at it via ``apcaccess``, but there are other ways 5329as well. 5330 5331Status report format 5332-------------------- 5333 5334STATUS output is in ASCII format with a single data value or piece 5335of information on each line output. Because not all UPSes supply 5336the same information, the output varies based on the type of UPS 5337that you are using. In general, if the information is not available 5338for your UPS, the line will be missing entirely or the data portion of 5339the output record will contain an ``N/A`` indicating that the information 5340is not available. 5341 5342Status logging consists of periodically logging ALL available 5343information concerning the UPS. Since the volume of data is rather 5344large (over 1000 bytes per status), the STATUS data is not 5345automatically sent to the system log file. Instead, it is written 5346as a series of data records in a specific file (normally 5347/etc/apcctrl/apcctrl.status). 5348 5349After each write, the file is rewound so that the size of the file 5350remains constant. The STATUS file is kept for backward compatibility 5351and will be eliminated in a future version of apcctrl. The preferred 5352method for obtaining this information is from apcaccess or by using 5353the CGI interface (see `apcctrl Network Monitoring (CGI) Programs`_). 5354 5355To make reading the status data reliable via a named pipe, the 5356first record written contains a version number, the number of 5357records that follow the first record, and the total number of bytes 5358in those subsequent records. An actual example of such a status 5359file (/etc/apcctrl/apcctrl.status) is shown below. 5360 5361Consequently, the first record always consists of 24 bytes (23 5362characters followed by a newline). This record starts with APC and 5363as indicated in the example is followed by 37 records 5364consisting of 906 bytes. The last record begins with END APC and 5365contains the date and time matching the DATE record. 5366 5367When this data is written to a file, it is written as two records, 5368the first record, and all the other records together. In reading 5369the file, it can be either be read a record at a time, or in one 5370big read. 5371 5372When this data is written to syslog(), it is written a record at a 5373time. The first record is the first 24 bytes. By having the number 5374of records and the size in the first record, the complete status 5375can be reliably reassembled. 5376 5377 5378Status Report Example 5379--------------------- 5380 5381An example of output from a BackUPS RS 1500 follows: 5382 5383:: 5384 5385 APC : 001,037,0906 5386 DATE : Sun Apr 26 17:22:22 EDT 2009 5387 HOSTNAME : mail.kroptech.com 5388 VERSION : 3.14.2 (10 September 2007) redhat 5389 UPSNAME : ups0 5390 CABLE : USB Cable 5391 MODEL : Back-UPS RS 1500 5392 UPSMODE : Stand Alone 5393 STARTTIME: Sun Apr 26 10:22:46 EDT 2009 5394 STATUS : ONLINE 5395 LINEV : 123.0 Volts 5396 LOADPCT : 24.0 Percent Load Capacity 5397 BCHARGE : 100.0 Percent 5398 TIMELEFT : 144.5 Minutes 5399 MBATTCHG : 5 Percent 5400 MINTIMEL : 3 Minutes 5401 MAXTIME : 0 Seconds 5402 SENSE : Medium 5403 LOTRANS : 097.0 Volts 5404 HITRANS : 138.0 Volts 5405 ALARMDEL : Always 5406 BATTV : 26.8 Volts 5407 LASTXFER : Low line voltage 5408 NUMXFERS : 0 5409 TONBATT : 0 seconds 5410 CUMONBATT: 0 seconds 5411 XOFFBATT : N/A 5412 SELFTEST : NO 5413 STATFLAG : 0x07000008 Status Flag 5414 MANDATE : 2003-05-08 5415 SERIALNO : JB0319033692 5416 BATTDATE : 2001-09-25 5417 NOMINV : 120 5418 NOMBATTV : 24.0 5419 FIRMWARE : 8.g6 .D USB FW:g6 5420 APCMODEL : Back-UPS RS 1500 5421 END APC : Sun Apr 26 17:22:32 EDT 2009 5422 5423 5424Status Report Fields 5425-------------------- 5426 5427The meaning of the above variables are: 5428 5429**APC** 5430 Header record indicating the STATUS format 5431 revision level, the number of records that follow the APC 5432 statement, and the number of bytes that follow the record. 5433 5434**DATE** 5435 The date and time that the information was last obtained from the UPS. 5436 5437**HOSTNAME** 5438 The name of the machine that collected the UPS data. 5439 5440**UPSNAME** 5441 The name of the UPS as stored in the EEPROM or in the ``UPSNAME`` 5442 directive in the configuration file. 5443 5444**VERSION** 5445 The apcctrl release number, build date, and platform. 5446 5447**CABLE** 5448 The cable as specified in the configuration file (``UPSCABLE``). 5449 5450**MODEL** 5451 The UPS model as derived from information from the UPS. 5452 5453**UPSMODE** 5454 The mode in which apcctrl is operating as specified in the configuration 5455 file (``UPSMODE``) 5456 5457**STARTTIME** 5458 The time/date that apcctrl was started. 5459 5460**STATUS** 5461 The current status of the UPS (ONLINE, ONBATT, etc.) 5462 5463**LINEV** 5464 The current line voltage as returned by the UPS. 5465 5466**LOADPCT** 5467 The percentage of load capacity as estimated by the UPS. 5468 5469**BCHARGE** 5470 The percentage charge on the batteries. 5471 5472**TIMELEFT** 5473 The remaining runtime left on batteries as estimated by the UPS. 5474 5475**MBATTCHG** 5476 If the battery charge percentage (BCHARGE) 5477 drops below this value, apcctrl will shutdown your system. 5478 Value is set in the configuration file (``BATTERYLEVEL``) 5479 5480**MINTIMEL** 5481 apcctrl will shutdown your system if the 5482 remaining runtime equals or is below this point. 5483 Value is set in the configuration file (``MINUTES``) 5484 5485**MAXTIME** 5486 apcctrl will shutdown your system if the time 5487 on batteries exceeds this value. A value of zero disables the 5488 feature. Value is set in the configuration file (``TIMEOUT``) 5489 5490**MAXLINEV** 5491 The maximum line voltage since the UPS was started, as reported by the UPS 5492 5493**MINLINEV** 5494 The minimum line voltage since the UPS was started, as returned by the UPS 5495 5496**OUTPUTV** 5497 The voltage the UPS is supplying to your equipment 5498 5499**SENSE** 5500 The sensitivity level of the UPS to line voltage fluctuations. 5501 5502**DWAKE** 5503 The amount of time the UPS will wait before restoring power to your 5504 equipment after a power off condition when the power is restored. 5505 5506**DSHUTD** 5507 The grace delay that the UPS gives after 5508 receiving a power down command from apcctrl before it powers off 5509 your equipment. 5510 5511**DLOWBATT** 5512 The remaining runtime below which the UPS 5513 sends the low battery signal. At this point apcctrl will force an 5514 immediate emergency shutdown. 5515 5516**LOTRANS** 5517 The line voltage below which the UPS will switch to batteries. 5518 5519**HITRANS** 5520 The line voltage above which the UPS will switch to batteries. 5521 5522**RETPCT** 5523 The percentage charge that the batteries must 5524 have after a power off condition before the UPS will restore power 5525 to your equipment. 5526 5527**ITEMP** 5528 Internal UPS temperature as supplied by the UPS. 5529 5530**ALARMDEL** 5531 The delay period for the UPS alarm. 5532 5533**BATTV** 5534 Battery voltage as supplied by the UPS. 5535 5536**LINEFREQ** 5537 Line frequency in hertz as given by the UPS. 5538 5539**LASTXFER** 5540 The reason for the last transfer to batteries. 5541 5542**NUMXFERS** 5543 The number of transfers to batteries since apcctrl startup. 5544 5545**XONBATT** 5546 Time and date of last transfer to batteries, or N/A. 5547 5548**TONBATT** 5549 Time in seconds currently on batteries, or 0. 5550 5551**CUMONBATT** 5552 Total (cumulative) time on batteries in seconds since apcctrl startup. 5553 5554**XOFFBATT** 5555 Time and date of last transfer from batteries, or N/A. 5556 5557**SELFTEST** 5558 The results of the last self test, and may have the following values: 5559 5560 - OK: self test indicates good battery 5561 - BT: self test failed due to insufficient battery capacity 5562 - NG: self test failed due to overload 5563 - NO: No results (i.e. no self test performed in the last 5 minutes) 5564 5565**STESTI** 5566 The interval in hours between automatic self tests. 5567 5568**STATFLAG** 5569 Status flag. English version is given by STATUS. 5570 5571**DIPSW** 5572 The current dip switch settings on UPSes that have them. 5573 5574**REG1** 5575 The value from the UPS fault register 1. 5576 5577**REG2** 5578 The value from the UPS fault register 2. 5579 5580**REG3** 5581 The value from the UPS fault register 3. 5582 5583**MANDATE** 5584 The date the UPS was manufactured. 5585 5586**SERIALNO** 5587 The UPS serial number. 5588 5589**BATTDATE** 5590 The date that batteries were last replaced. 5591 5592**NOMOUTV** 5593 The output voltage that the UPS will attempt to supply when on battery 5594 power. 5595 5596**NOMINV** 5597 The input voltage that the UPS is configured to expect. 5598 5599**NOMBATTV** 5600 The nominal battery voltage. 5601 5602**NOMPOWER** 5603 The maximum power in Watts that the UPS is designed to supply. 5604 5605**HUMIDITY** 5606 The humidity as measured by the UPS. 5607 5608**AMBTEMP** 5609 The ambient temperature as measured by the UPS. 5610 5611**EXTBATTS** 5612 The number of external batteries as 5613 defined by the user. A correct number here helps the UPS compute 5614 the remaining runtime more accurately. 5615 5616**BADBATTS** 5617 The number of bad battery packs. 5618 5619**FIRMWARE** 5620 The firmware revision number as reported by the UPS. 5621 5622**APCMODEL** 5623 The old APC model identification code. 5624 5625**END APC** 5626 The time and date that the STATUS record was written. 5627 5628 5629Logging the STATUS Information 5630------------------------------ 5631 5632If specified in the configuration file, the STATUS data will also be 5633written to the system log file. Please note, that it would not 5634normally be wise to write this data to a normal system log file as 5635there is no mechanism in syslog() to rewind the file and hence the 5636log file would quickly become enormous. However, in two cases, it 5637can be very useful to use syslog() to write this information. 5638 5639The first case is to set up your syslog.conf file so that the data 5640is written to a named pipe. In this case, normally not more than 5641about 8192 bytes of data will be kept before it is discarded by the 5642system. 5643 5644The second case is to setup your syslog.conf file so that the 5645status data is sent to another machine, which presumably then 5646writes it to a named pipe. Consequently, with this mechanism, 5647provides a simple means of networking apcctrl STATUS information. 5648 5649Although we mention system logging of STATUS information, we 5650strongly recommend that you use apcaccess or the CGI interface to 5651get this information. 5652 5653 5654 5655The Shutdown Sequence and its Discontents 5656========================================= 5657 5658Shutdown Sequence 5659----------------- 5660 5661If you experienced so problems with the testing procedures, or if 5662you are porting apcctrl to another system, or you are simply 5663curious, you may want to know exactly what is going on during the 5664shutdown process. 5665 5666The shutdown sequence is as follows: 5667 5668- apcctrl detects that there is a power problem and it calls 5669 ``/etc/apcctrl/apccontrol powerout``. By default this event 5670 does nothing, but it can be overridden to notify users, etc. 5671 5672- After the configured ``ONBATTERYDELAY``, apcctrl 5673 calls ``/etc/apcctrl/apccontrol onbattery``, which normally sends a 5674 message to all users informing them that the UPS is on batteries. 5675 5676- When one of the conditions listed below occurs, apcctrl issues a 5677 shutdown command by calling ``/etc/apcctrl/apccontrol doshutdown``, 5678 which should perform a shutdown of your system using the system 5679 shutdown(8) command. You can modify the behavior as described in 5680 `Customizing Event Handling`_. 5681 5682 The conditions that trigger the shutdown can be any of the following: 5683 5684 - Running time on batteries have expired (``TIMEOUT``) 5685 - The battery runtime remaining is below the configured value (``BATTERYLEVEL``) 5686 - The estimated remaining runtime is below the configured value (``MINUTES``) 5687 - The UPS signals that the batteries are exhausted. 5688 5689 A shutdown could also be initiated if apcctrl detects that the 5690 batteries are no longer functioning correctly. This case, though 5691 very unusual, can happen at any time even if there is proper mains 5692 voltage, and ``/etc/apcctrl/apccontrol emergency`` is called. 5693 5694 Just before initiating any shutdown through the apccontrol script, 5695 apcctrl will create the file /etc/apcctrl/powerfail. This file will 5696 be used later in the shutdown sequence to recall apcctrl after 5697 syncing of the disks to initiate a power off of the UPS. 5698 5699 If the /etc/nologin file has not already been created, it will 5700 normally be created during the shutdown sequence to prevent 5701 additional users from logging in (see the ``NOLOGIN`` configuration 5702 directive). 5703 5704 Even though apcctrl has requested the system to perform a shutdown, 5705 it continues running. 5706 5707- When the system signals apcctrl to do exit, it does so. This is 5708 part of the normal system shutdown (at least on Unix and Linux 5709 systems) and the exact time that apcctrl receives the termination 5710 signal depends on how the shutdown links (usually in /etc/rc.d) are 5711 set. 5712 5713 Note that on Windows NT systems, apcctrl apparently continues to 5714 run as a Service even though the machine is "shutdown". 5715 5716- During the shutdown of the system after apcctrl has been forced 5717 to exit, one of the last things done by the system shutdown is to 5718 call the halt script, which is usually in /etc/rc.d/halt or 5719 /etc/rc.d/init.d/halt, or possibly in /sbin/init.d/rc.0 depending 5720 on your system. If apcctrl was properly installed, this standard 5721 halt script was modified to include a bit of new logic just before 5722 the final halt of the system. It first tests if the file 5723 /etc/apcctrl/powerfail exists, and if it does, it executes 5724 ``/etc/apcctrl/apccontrol killpower``. It is this last step that will 5725 cause apcctrl to be re-executed with the ``--killpower`` option 5726 on the command line. This option tells apcctrl to inform the UPS to 5727 kill the power. 5728 5729This final step is important if you want to ensure that your system 5730will automatically reboot when the power comes back on. The actual 5731code used on the Red Hat version is: 5732 5733 :: 5734 5735 # See if this is a powerfail situation. # ***apcctrl*** 5736 if [ -f /etc/apcctrl/powerfail ]; then # ***apcctrl*** 5737 echo # ***apcctrl*** 5738 echo "APCCTRL will now power off the UPS" # ***apcctrl*** 5739 echo # ***apcctrl*** 5740 /etc/apcctrl/apccontrol killpower # ***apcctrl*** 5741 echo # ***apcctrl*** 5742 echo "Please ensure that the UPS has powered off before rebooting" # ***apcctrl*** 5743 echo "Otherwise, the UPS may cut the power during the reboot!!!" # ***apcctrl*** 5744 echo # ***apcctrl*** 5745 fi # ***apcctrl*** 5746 5747The above code must be inserted as late as possible in the halt 5748script. On many systems, such as Red Hat, all the disk drives were 5749unmounted, then remounted read-only, thus permitting access to the 5750/etc files and the apcctrl executable. If your system does not 5751explicitly remount the disks, you must remount them in read-only 5752mode in the code that you add. Examples of code fragments that do 5753this can be found in the distributions/suse subdirectory of the 5754source. 5755 5756If you are not able to insert the above code in your halt script 5757because there is no halt script, or because your halt script calls 5758the init program as some Unix systems do, you can either just 5759forget about powering off the UPS, which means that your machine 5760will not automatically reboot after a power failure, or there is 5761yet another alternative, though not at all as satisfying as 5762inserting code in the halt script. 5763 5764Only if you cannot insert the appropriate code in the halt script, 5765when you start apcctrl, normally from the /etc/rc.d/init.d/apcctrl 5766script, use the ``--kill-on-powerfail`` option. This will cause 5767apcctrl to program the UPS to shutoff the power just before it 5768(apcctrl) does the system shutdown. Please note that this is not 5769the most ideal solution. Read on to understand why. 5770 5771A very important consideration is that you must set the EEPROM in 5772your UPS so that it waits a sufficient time for the system to halt 5773before it shuts off the UPS power. 5774 5775When using a USB connection, apcctrl automatically sets this value 5776to 60 seconds. When using a serial connection to a SmartUPS, you 5777must configure the value in the UPS EEPROM by hand using ``apctest``. 5778 5779 5780Shutdown Problems 5781----------------- 5782 5783Obviously if your halt script is not properly modified, apcctrl 5784will not be able to shut off the power to the UPS, and if the power 5785returns before the batteries are exhausted your system will not 5786automatically reboot. In any case, your machine should have been 5787cleanly shut down. 5788 5789Master/Slave Shutdown 5790--------------------- 5791 5792In master/slave configurations, however, the master cannot be 100 5793percent sure that the slaves have all shutdown before it performs 5794the power off. To avoid this situation, be sure to configure any 5795slaves (clients) to shut down before the master by setting different 5796``TIMEOUT``, ``BATTERYLEVEL``, or ``MINUTES`` parameters in the 5797config file. 5798 5799Also, on a slave machine, you do not want to use the modified halt 5800script since it will recall apcctrl, which will detect that it is a 5801slave (i.e. no connection to the UPS) and will complain that it 5802cannot do the killpower. This situation is not harmful just 5803annoying and possibly confusing. 5804 5805One possible problem during shutdown can be caused by remnants of 5806old versions. Please be sure to delete or rename all prior versions 5807(/usr/local/sbin/apcctrl or /sbin/powersc). 5808 5809 5810Startup 5811------- 5812 5813Normally, apcctrl is automatically started when 5814your system is rebooted. This normally occurs because the startup 5815script apcctrl is linked into the appropriate places in /etc/rc.d. 5816On most Linux systems, there is a program called chkconfig(8) that 5817will automatically link the startup script. This program is invoked 5818by the ``make install`` scripts, or it is explicitly done for those 5819systems that do not have chkconfig(8). If this is not the case, you 5820can either link it in appropriately yourself or explicitly call it 5821from your rc.local file. The appropriate manual way to startup 5822apcctrl is by executing: 5823 5824:: 5825 5826 <path>/apcctrl start 5827 5828where *path* is normally /etc/rc.d or /etc/rc.d/init.d depending on 5829your system. Using this script is 5830important so that any files remaining around after a power failure 5831are removed. Likewise, shutting down apcctrl should be done with 5832the same script: 5833 5834:: 5835 5836 <path>/apcctrl stop 5837 5838Windows Considerations 5839---------------------- 5840 5841Please see the `Killpower under Windows`_ chapter of this manual for 5842considerations pertaining to shutdown and killpower on Windows. 5843 5844 5845.. include:: smartprotocol.rst 5846 5847 5848NIS Network Server Protocol 5849=========================== 5850 5851The NIS network server in apcctrl is capable of sending status and events data 5852to clients that request it. The communication between the client and the server 5853is performed over a TCP connection to the NISPORT (normally port 3551). The 5854client opens a connection to the server and sends a message, to which the 5855server will reply with one or more messages. Each message consists of a 2-byte 5856length (in network byte order) followed by that many bytes of data. Both the 5857client->server and server->client messages follow this format. 5858 5859apcctrl supports two commands, sent as the body of a message: 5860 5861#. "status" - The status command requests that the server send a copy of all 5862 status values, in the form displayed by apcaccess. After the client sends the 5863 "status" command, the server will reply with a series of messges, each one 5864 containing one line of apcaccess status data. The end of the command series 5865 is indicated by an empty message (length of 0). 5866 5867#. "events" - The events command operates the same as "status" except the 5868 server replies with lines from the log of recent events. 5869 5870As an example, the following bytes would be sent by a client to solicit the status: 5871 5872:: 5873 5874 0x00 0x06 0x73 0x74 0x61 0x74 0x75 0x73 5875 5876The first two bytes are the data length (6) in network byte order. The 6 bytes 5877of data that follow are the ASCII characters for "status". The server will 5878respond to this command with a series of its own messages containing the status 5879data. 5880 5881 5882apcctrl RPM Packaging FAQ 5883========================= 5884 5885**How do I build apcctrl for platform xxx?** 5886 The apcctrl spec file contains defines 5887 to build for several platforms: RedHat 7.x (rh7), RedHat 8.0 (rh8), 5888 RedHat 9 (rh9), Fedora Core (fedora_core), RedHat Enterprise Linux 5889 and clones (rhel3 and rhel4), SuSE 9 & 10 (suse), and Mandrake 5890 (mdk). The package build is controlled by a define set at the 5891 beginning of the file. These defines basically just control the 5892 dependency information that gets coded into the finished rpm 5893 package. So while you could technically build a package without 5894 defining a platform, or with an incorrect platform, and have it 5895 install and run it would not contain correct dependency information 5896 for the rpm database. The platform define may be edited in the spec 5897 file directly (by default all defines are set to 0 or "not set"). 5898 For example, to build the RedHat 7.x package find the line in the 5899 spec file which reads 5900 5901 :: 5902 5903 %define rh7 0 5904 5905 5906 and edit it to read 5907 5908 :: 5909 5910 %define rh7 1 5911 5912 Alternately you may pass the define on the command line when 5913 calling rpmbuild: 5914 5915 :: 5916 5917 rpmbuild -ba --define "build_rh7 1" apcctrl.spec 5918 rpmbuild --rebuild --define build_rh7 1" apcctrl-x.x.x-x.src.rpm 5919 5920**How do I control whether usb support gets built?** 5921 Up through version 3.12, by default standard serial port support was built 5922 and the apcctrl-std package was produced. The usb package pre-configured 5923 the configuration files for usb devices and installed a couple 5924 additional tools in /etc/apcctrl but the usb driver was built 5925 regardless. To get the usb package and support in those versions 5926 either set the 5927 5928 :: 5929 5930 %define usb 0 5931 5932 5933 to 5934 5935 :: 5936 5937 %define usb 1 5938 5939 5940 in the spec file directly or pass it to rpmbuild on the command 5941 line: 5942 5943 :: 5944 5945 rpmbuild -ba --define "build_rh7 1" --define "build_usb 1" apcctrl.spec 5946 5947 With the release of 3.14 USB support is now considered standard and 5948 the apcctrl-std and apcctrl-usb packages are obsoleted in favor of 5949 a single apcctrl package configured for usb connected UPS's. The 5950 serial port driver is still built and can be configured accordingly 5951 after installation. If you are performing an upgrade it will of 5952 course not replace your current config file. 5953 5954 The build directive: 5955 5956 :: 5957 5958 --define "build_usb 1" 5959 5960 is no longer recognized. 5961 5962**What other defines are used?** 5963 There is a define for the initdir for the daemon control script. On 5964 RedHat or Mandrake systems this is set to /etc/rc.d/init.d/. On 5965 SuSE systems this is set to /etc/rc.d. You would only need to edit 5966 this if packaging for a platform that uses a different directory. 5967 5968 A second define controls whether the Gnome monitoring application, 5969 new in the 3.14 release, is built. This application requires the 5970 Gtk2 version to be >= 2.4. If you want to build the apcctrl-gapcmon 5971 package add: 5972 5973 :: 5974 5975 --define "build_gapcmon 1" 5976 5977 5978 A third define controls whether the SNMP driver is built. If you 5979 want to build the net-snmp driver add: 5980 5981 :: 5982 5983 --define "build_snmp 1" 5984 5985**Can I supply packages for other platforms you do not publish?** 5986 Yes, there are tools provided for contributors to supply rpm 5987 packages for platforms for which support is provided in the spec 5988 file but for which the development team chooses not to release 5989 binary packages, usually due to lack of interest or lack of an 5990 available platform. Please see platforms/contrib/README in the 5991 source package. 5992 5993**I'm getting errors about not having permission when I try to build the packages. Do I need to be root?** 5994 No, you do not need to be root 5995 and, in fact, it is better practice to build rpm packages as a 5996 non-root user. apcctrl's packages are designed to be built by a 5997 regular user but you must make a few changes on your system to do 5998 this. If you are building on your own system then the simplest 5999 method is to add write permissions for all to the build directory 6000 (/usr/src/redhat/). To accomplish this execute one of the following 6001 commands as root depending on your distribution, RedHat, SuSE or 6002 Mandriva, respectively: 6003 6004 :: 6005 6006 chmod -R 777 /usr/src/redhat 6007 chmod -R 777 /usr/src/packages 6008 chmod -R 777 /usr/src/RPM 6009 6010 If you are working on a shared system where you can not use the 6011 method above then you need to recreate the /usr/src/redhat (or 6012 other) directory tree with all of it's subdirectories inside your 6013 home directory. Then create a file named 6014 6015 :: 6016 6017 .rpmmacros 6018 6019 6020 in your home directory (or edit the file if it already exists) and 6021 add the following line: 6022 6023 :: 6024 6025 %_topdir /home/myuser/redhat 6026 6027 6028 6029Credits 6030======= 6031 6032.. image:: ./thanks.png 6033 6034The success of apcctrl is due to the many people that helped in 6035development, testing and in many other ways. 6036 6037Thank all the developers that worked hard to make APCCTRL one of the 6038best piece of software for UPS management. 6039 6040 6041Contributors 6042------------ 6043 6044**Current Code Maintainer and Project Manager** 6045 Adam Kropelin (adam@kroptech.com) 6046 6047**RPM Packager** 6048 D\. Scott Barninger 6049 6050**CGI and HTML fixer** 6051 William King (wrking@dadaboom.com) 6052 6053**Former Project Manager** 6054 Kern Sibbald (kern@sibbald.com) 6055 6056**Project Starter and Former Code Maintainer** 6057 Andre Hedrick (andre@linux-ide.org) 6058 6059**Former Code Maintainer and Project Manager** 6060 Riccardo Facchetti (riccardo@master.oasi.gpa.it) 6061 6062**Serial Communications** 6063 Andre Hedrick (andre@linux-ide.org) 6064 6065**2.0 User's Manual** 6066 Eric S. Raymond (esr@thyrsus.com) 6067 6068**Alpha Port** 6069 Kern Sibbald (kern@sibbald.com) 6070 J. Rochate (jrochate@ualg.pt) testing and machine loan 6071 6072**Caldera** 6073 John Pinner (john@clocksoft.com) 6074 6075**HP-UX Port** 6076 Carl Erhorn (Carl_Erhorn@hyperion.com) 6077 Robert K Nelson (rnelson@airflowsciences.com) 6078 6079**SOLARIS Port** 6080 Carl Erhorn (Carl_Erhorn@hyperion.com) 6081 6082**OpenBSD Port** 6083 Devin Reade (gdr@gno.org) 6084 6085**NetBSD Port** 6086 Neil Darlow (neil@darlow.co.uk) 6087 6088**Win32 Port** 6089 Kern Sibbald (kern@sibbald.com) 6090 Paul Z. Stagner 6091 6092**WEB Interfaces** 6093 Kern Sibbald (kern@sibbald.com) 6094 Joseph Acosta (joeja@mindspring.com) 6095 6096 6097apcctrl License 6098--------------- 6099 6100apcctrl is licensed under the terms of the GNU General Public License, version 2 6101(GPLv2). The full text of this license may be found in the COPYING file at the 6102top of the source tree and online at http://www.gnu.org/licenses/gpl-2.0.html. 6103 6104Source files are copyright of their specific author(s), as noted in the files. 6105 6106:: 6107 6108 This program is free software; you can redistribute it and/or 6109 modify it under the terms of version 2 of the GNU General 6110 Public License as published by the Free Software Foundation. 6111 6112 This program is distributed in the hope that it will be useful, 6113 but WITHOUT ANY WARRANTY; without even the implied warranty of 6114 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 6115 General Public License for more details. 6116 6117 You should have received a copy of the GNU General Public 6118 License along with this program; if not, write to the Free 6119 Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, 6120 MA 02111-1307, USA. 6121 6122 6123Other Open Source Licenses 6124-------------------------- 6125 6126apcctrl incorporates the libusbhid library which is subject to the following 6127copyright and license: 6128 6129:: 6130 6131 Copyright (c) 1999 Lennart Augustsson <augustss@netbsd.org> 6132 All rights reserved. 6133 6134 Redistribution and use in source and binary forms, with or without 6135 modification, are permitted provided that the following conditions 6136 are met: 6137 1. Redistributions of source code must retain the above copyright 6138 notice, this list of conditions and the following disclaimer. 6139 2. Redistributions in binary form must reproduce the above copyright 6140 notice, this list of conditions and the following disclaimer in the 6141 documentation and/or other materials provided with the distribution. 6142 6143 THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 6144 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 6145 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 6146 ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 6147 FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 6148 DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 6149 OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 6150 HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 6151 LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 6152 OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 6153 SUCH DAMAGE. 6154 6155 6156.. |image4| image:: ./commlost.png 6157.. |image5| image:: ./online.png 6158.. |image6| image:: ./onbatt.png 6159.. |image7| image:: ./charging.png 6160.. |date| date:: %B %e, %Y 6161.. |time| date:: %T 6162.. |(C)| unicode:: 0xA9 .. copyright sign 6163.. |TM| unicode:: U+2122 .. trademark sign 6164
