apcupsd User's Manual apcupsd User's Manual Revision History Revision 2.0 20 Sept 2003 esr First XML−DocBook version. Table of Contents Release Notes New Features in in 3.10.6 New Features in 3.10.5 New Features in 3.10.4 How To Use This Manual I. Basic User's Guide 1. Planning Your Installation Quick Start for Beginners Supported Operating Systems, UPSes and Cables Choosing a Configuration Type Checking Out Your USB Subsystem 2. Building and Installing apcupsd Installation from Binary Packages Red Hat Linux Microsoft Windows Installation from Source Verifying a Source Installation Configure Options Recommended Options for most Systems Compilers and Options Operating System Specifics Alpha Debian FreeBSD HPUX NetBSD OpenBSD Red Hat Systems Slackware SuSE Sun Solaris Unknown System Windows Systems with CYGWIN Installed 3. After Installation Checking Your Configuration File Arranging for Reboot on Power−Up Making Sure apcupsd Is Running 4. Testing apcupsd Process−Status Test Logging Test apcaccess Test apcupsd User's Manual 1 apcupsd User's Manual Communications Test Simulated Power Fail Test System Shutdown Test Full Power Down Test Shutdown Sequence apctest 5. Troubleshooting Your Installation Known Problems with USB UPSes Reconnection does not clean up the lockfile Power Off (killpower) of UPS Does Not Work apcupsd Cannot Reconnect After a Reboot 6. Monitoring and Tuning your UPS apcaccess apcaccess status apcaccess eprom hid−ups and USB Specific Information apcupsd Network Monitoring (CGI) Programs Setting up and Testing the CGI Programs multimon.cgi upsstats.cgi ./upsstats.cgi upsfstatus.cgi Working Example Client Test Program A Tip from Carl Erhorn for Sun Systems Credits Security Issues Configuring Your EEPROM apcupsd No Longer Configures EEPROM Using apctest to Configure Your EEPROM 7. Maintaining Your UPS What Various People Have to Say about Batteries Where Carl Suggests You Get Batteries 8. Frequently−Asked Questions 9. Apcupsd Bugs II. Advanced topics 10. Customizing Event Handling apccontrol Command Line Options 11. Master/Slave Configurations Configuration Directives Master/Slave Problems Master/Slave Shutdown Master/Slave Networking using NIS and the NET Driver Network Problems with Master/Slave Configurations Error Messages from a Master Configuration Error Messages from a Slave Configuration Master/Slave Connection Not Working 12. Controlling Multiple UPSes on one Machine Configuration The First Copy of apcupsd The Second Copy of apcupsd apcupsd User's Manual 2 apcupsd User's Manual Important Steps after Installation of the Second Copy 13. Support for SNMP UPSes Connecting an SNMP UPS Building and Installing apcupsd SNMP Specific Information Known Problems 14. Alternate Ways To Run The Network Information Server Running the server as a child of apcupsd Running apcnisd from INETD Running apcnisd Standalome 15. apcupsd System Logging Logging Types Implementation Details Developer's Notes III. Legacy Installation: Windows 16. The Windows Version of apcupsd Installation Installation Directory Testing Upgrading Post Installation Problem Areas Utility Functions Disclaimer Email Notification of Events Killpower under Windows Power Down During Shutdown Command Line Options Specific to the Windows Version Building the Win32 Version from the Source IV. Legacy Installation: Serial−Line UPSes 17. Overview of Serial−Interface UPSes 18. Connecting a Serial−Line UPS to a USB Port 19. Cables Smart−Custom Cable for SmartUPSes Smart Signalling Cable for BackUPS CS Models Voltage−Signalling Cable for "dumb" UPSes Other APC Cables that apcupsd Supports Voltage Signalling Features Supported by Apcupsd for Various Cables Voltage Signalling The Back−UPS Office 500 signals Analyses of APC Cables 940−0020B Cable Wiring 940−0020C Cable Wiring 940−0023A Cable Wiring 940−0095A Cable Wiring 940−0095B Cable Wiring 940−0119A Cable Wiring BackOffice ES BackUPS ES and CS in Serial mode with Cable 940−0128A Win32 Implementation Restrictions for Simple UPSes Internal Apcupsd Actions for Simple Cables apcupsd User's Manual 3 apcupsd User's Manual RS232 Wiring and Signal Conventions Pin Assignment for the Serial Port (RS−232C), 25−pin and 9−pin, Female End Ioctl to RS232 Correspondence 20. Testing Serial−Line UPSes Establishing Serial Port Connection Using apctest on Serial−Line UPSses Expected apctest Signals for a UPS Expected apctest Signals for a BackUPS Pro 21. Troubleshooting Serial Line communications Determining Which Voltage−Signaling Cable You Have Once you have established serial communications Bizarre Intermittent Behavior 22. Recalibrating the UPS Runtime Status Logging On Serial−Line UPSes 23. DATA Logging V. Technical Reference 24. Configuration Directive Reference General Configuration Directives Configuration Directives Used by the Network Information Server Configuration Directives used during Power Failures Configuration Directives used to Control System Logging Configuration Directives for Sharing a UPS Configuration Directives Used to Set the UPS EPROM 25. Configuration Examples A Simple Configuration for a SmartUPS A Simple USB Configuration A Simple Master Configuration A Simple Slave Configuration Variation on the Master/Slave Configuration A Sample Slave Configuration Using the Net Driver 26. apcupsd Status Logging Status report format Status Report Example Status Report Fields Logging the STATUS Information 27. The Shutown Sequence and its Discontents Shutdown Sequence Shutdown Problems Master/Slave Shutdown Startup Windows Considerations 28. APC's smart protocol Description RS−232 differences Diagram for cable hackers The Smart Protocol Dip switch info Status bits Alert messages Register 1 Register 2 apcupsd User's Manual 4 apcupsd User's Manual Register 3 Interpretation of the Old Firmware Revision Interpretation of the New Firmware Revision EEPROM Values Programming the UPS EEPROM Acknowledgements A. Credits Contributors Disclaimer: NO WARRANTY List of Figures 1.1. Configuration types. Release Notes Table of Contents New Features in in 3.10.6 New Features in 3.10.5 New Features in 3.10.4 This release contains a good number of cleanups and bug fixes to prior 3.10.x versions, and is intended to be the official release. See the ChangeLog below for more details. New Features in in 3.10.6 This release contains a good number of cleanups and bug fixes to prior 3.10.x versions, and is intended to be the official release. See the ChangeLog below for more details. Change Log − Lots of updates to the document. − Fixed a slave crash in master/slave mode. It was a missing setup_device, and was diagnosed and reported by Christian Schacht −− many thanks. − Made non−existent header files non−fatal and added #ifdef around sys/socket.h so it will compile on IRIX. − Add Scott's latest apcupsd.conf with the hid−ups program code (actually I had done this some time ago ...). − Start a ReleaseNotes file − Fixed a typo error (mine) that prevented Scott from building rpms. Strange, it worked for me???? − More DESTDIR cleanup for building non−root rpms. − Add DESTDIR everywhere so we can build rpms non−root − Additional documentation − Add Scott's new apcupsd.spec − On Hilary Jones suggestion, I fixed the ./configure message that is printed when no libgd is found to direct the user to the main source. − Add Sergey Vlasov's kernel patch to the examples directory, and it replaces the previous patch. This patch now solves the killpower problem on Linux USB. <apcupsd−source>/examples/linux−2.4.20−alt−apc_usb_ups.patch Release Notes 5 apcupsd User's Manual notes are in: linux−usb−patch−email.txt − Add TTY mode to apctest to communicated directly with UPS. − Apply patch to linux−usb.c in killpower supplied by Sergey Vlasov (thanks!). − Eliminate pow() function in linux−usb.c so that −lm is not needed. − Add automatic detection of socklen_t − I received a kernel patch from Sergey Vlasov that fixes the killpower problem on CS UPSes. apcupsd can now shutdown these devices! I've removed some debug code that was in the killpower routine and is not needed or used. I have put the kernel patch in: <apcupsd−source>/examples/linux−2.4.20−alt−hidups.patch − When the Win32 version starts as a service, delete the NOLOGIN and PWRFAIL files to prevent later confusion. Thanks to Allen Crawford for pointing this out. − Modify all Win32 program so that only windowed programs (apcupsd, popup) have the −mwindows flags. The others do not. − Tweak apctest.c a bit −− add EEPROM programming (still a bit kludgy), but at least it can be done. − Lots of clean ups for Cygwin stuff. Events now work, and exit. − Clean up a few undefined symbols in building with everything on. − Eliminate pid and serial port lock file on Win32 systems. − Modify init script to use daemon so that STDIN/OUT, ... are detached from the terminal and pointed to the log file. This prevents remotely logged in users who start apcupsd from being unable to log out. − Made some mindor modifications to configure.in and aclocal.m4 to make consistent use of double quotes in test statements in response to problems with make install reported by Andrew Surratt. − Thanks to Richard Schwaninger for finding and submitting a patch to the tcp−wrappers code that prevented it from working because of an invalid name. Fixed. − Thanks to Andrew Reid for pointing out that the child reaping code should be clearing the pid slot if a −1 is returned. The pid table was filling up on his system due to killed children. Fixed − A bug report against the Mandrake version of apcupsd indicates that apcupsd is not releasing /dev/console. I've moved the close() of STDIN so that it is always executed to prevent this possibility. − Implement very crude first cut of EEPROM programming in apctest. Set battery date, set UPS name, and print EEPROM values should work. New Features in 3.10.5 This release is primarily version 3.10.4 but including a fix that closes a root exploit of slave machines. In addition, it makes the −−enable−master−slave ./configure option work and has a few updates to the Mandrake release.