Apcupsd is a UPS control system that permits orderly shutdown of your computer in the event of a power failure. Kern Sibbald February 10, 2007 This manual documents apcupsd version 3.14.x Copyright (C) 1999-2005 Kern Sibbald Copying and distribution of this file, with or without modification, are per- mitted in any medium without royalty provided the name Apcupsd, the copyright notice, and this notice are preserved. Apcupsd source code is released under the GNU General Public License version 2. Please see the file COPYING in the main source directory. For more information on the project, please visit the main web site at http://www.apcupsd.com 1 Contents How To Use This Manual . 11 Basic User's Guide . 11 Planning Your Installation . 11 Quick Start for Beginners . 11 Supported Operating Systems . 13 Supported UPSes and Cables . 14 Choosing a Configuration Type . 16 Building and Installing apcupsd . 29 Installation from Binary Packages . 29 Installation from Source . 30 Verifying a Source Installation . 32 Configure Options . 34 Recommended Options for most Systems . 37 Compilers and Options . 37 Operating System Specifics . 38 After Installation . 46 Checking Your Configuration File . 46 Arranging for Reboot on Power-Up . 47 Making sure apcupsd Is Running . 48 2 Configuration Examples . 49 Simple USB Configuration . 49 Simple Configuration for a SmartUPS . 49 Simple Configuration for a Simple Signaling or Dumb . 50 NIS Server/Client Configuration Using the Net Driver . 51 PowerChute Network Shutdown Driver (PCNET) . 53 Testing Apcupsd . 54 Process-Status Test . 54 Logging Test . 55 apcaccess Test . 55 Communications Test . 58 Simulated Power Fail Test . 59 System Shutdown Test . 61 Full Power Down Test . 61 Shutdown Sequence . 62 apctest . 63 Troubleshooting Your Installation . 65 Known Problems with USB UPSes . 65 Monitoring and Tuning your UPS . 66 apcaccess . 66 Apcupsd Notification and Events . 69 hid-ups and USB Specific Information . 70 apcupsd Network Monitoring (CGI) Programs . 70 Setting up and Testing the CGI Programs . 71 Configuring Your EEPROM . 77 3 Maintaining Your UPS . 81 What Various People Have to Say about Batteries . 81 Where Carl Suggests You Get Batteries . 87 Frequently-Asked Questions . 89 Apcupsd Bugs . 93 Advanced topics . 94 Customizing Event Handling . 94 apccontrol Command Line Options . 95 Controlling Multiple UPSes on one Machine . 98 Configuration . 98 Support for SNMP UPSes . 100 Planning and Setup for SNMP Wiring . 100 Planning and Setup for SNMP Configuration . 101 Connecting APCUPSD to a SNMP UPS . 104 Building with SNMP support . 105 SNMP Trap Catching . 106 Known Problems . 106 Running The Network Information Server . 107 apcupsd System Logging . 108 Logging Types . 108 Implementation Details . 109 Developers Notes . 110 Windows Version of apcupsd . 110 Installation . 111 Configuration . 111 4 Starting Apcupsd . 112 Testing . 113 Upgrading . 113 Post Installation . 114 Problem Areas . 114 Disclaimer . 115 Email Notification of Events . 116 Killpower under Windows . 116 Power Down During Shutdown . 117 Command Line Options Specific to the Windows Version . 118 Building the Win32 Version from the Source . 118 Installation: Serial-Line UPSes . 119 Overview of Serial-Interface UPSes . 119 Connecting a Serial-Line UPS to a USB Port . 119 Connecting a APC USB UPS to either a PC USB or Serial Port . 120 Cables . 120 Smart-Custom Cable for SmartUPSes . 120 Voltage-Signalling Cable for "dumb" UPSes . 121 Custom-RJ45 Smart Signalling Cable for BackUPS CS Models 123 Other APC Cables that apcupsd Supports . 124 Voltage Signalling Features Supported by Apcupsd for Various Cables125 Voltage Signalling . 125 Back-UPS Office 500 signals . 126 Analyses of APC Cables . 126 Win32 Implementation Restrictions for Simple UPSes . 135 5 Internal Apcupsd Actions for Simple Cables . 135 RS232 Wiring and Signal Conventions . 136 Pin Assignment for the Serial Port (RS-232C), 25-pin and 9-pin, Female End137 Ioctl to RS232 Correspondence . 137 Testing Serial-Line UPSes . 138 Establishing Serial Port Connection . 139 Using apctest on Serial-Line UPSses . 141 Troubleshooting Serial Line communications . 144 Determining Which Voltage-Signaling Cable You Have . 144 Once you have established serial communications . 144 Recalibrating the UPS Runtime . 144 Status Logging On Serial-Line UPSes . 146 DATA Logging . 146 Technical Reference . 147 Configuration Directive Reference . 147 General Configuration Directives . 147 Configuration Directives Used by the Network Information Server148 Configuration Directives used during Power Failures . 149 Configuration Directives used to Control System Logging . 153 Configuration Directives for Sharing a UPS . 153 Configuration Directives Used to Set the UPS EPROM . 154 apcupsd Status Logging . 156 Status report format . 157 Status Report Example . 158 Status Report Fields . 159 6 Logging the STATUS Information . 162 Shutown Sequence and its Discontents . 162 Shutdown Sequence . 162 Shutdown Problems . 166 Master/Slave Shutdown . 166 Startup . 166 Windows Considerations . 167 APC smart protocol . 167 Description . 168 RS-232 differences . 168 Diagram for cable hackers . 168 Smart Protocol . 169 Dip switch info . 173 Status bits . 174 Alert messages . 174 Register 1 . 175 Register 2 . 176 Register 3 . 176 Interpretation of the Old Firmware Revision . 177 Interpretation of the New Firmware Revision . 177 EEPROM Values . 178 Programming the UPS EEPROM . 179 Acknowledgements . 180 Apcupsd | RPM Packaging FAQ . 181 Answers . 181 7 Credits . 183 Contributors . 184 Disclaimer: NO WARRANTY . 186 8 List of Figures Configuration Types . ..