APC UPS control system User Manual

Apcupsd is a UPS control system that permits orderly

shutdown of your computer in the event of a power failure.

Kern Sibbald

April 3, 2005

This manual documents apcupsd version 3.10.17

Copying and distribution of this ﬁle, with or without modiﬁcation, are permitted 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 ﬁle COPYING in the main source directory.

For more information on the project, please visit the main web site at http://www.apcupsd.com

Contents

Apcupsd User’s Manual . . . . . . . . . . . . . . . . . . . . . . . . 6

Release Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

New Features . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

How To Use This Manual . . . . . . . . . . . . . . . . . . . . . . . 9

Basic User’s Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Planning Your Installation . . . . . . . . . . . . . . . . . . . . . . . 9

Quick Start for Beginners . . . . . . . . . . . . . . . . . . . . 9

Supported Operating Systems, UPSes and Cables . . . . . . . 11

Apcupsd Known USB Issues . . . . . . . . . . . . . . . . . . . 15

Checking Out Your USB Subsystem . . . . . . . . . . . . . . 17

Building and Installing apcupsd . . . . . . . . . . . . . . . . . . . . 26

Installation from Binary Packages . . . . . . . . . . . . . . . . 26

Installation from Source . . . . . . . . . . . . . . . . . . . . . 27

Verifying a Source Installation . . . . . . . . . . . . . . . . . 28

Conﬁgure Options . . . . . . . . . . . . . . . . . . . . . . . . 30

Recommended Options for most Systems . . . . . . . . . . . 33

Compilers and Options . . . . . . . . . . . . . . . . . . . . . . 34

Operating System Speciﬁcs . . . . . . . . . . . . . . . . . . . 35

After Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

Checking Your Conﬁguration File . . . . . . . . . . . . . . . . 44

Arranging for Reboot on Power-Up . . . . . . . . . . . . . . . 45

Making sure apcupsd Is Running . . . . . . . . . . . . . . . . 46

Conﬁguration Examples . . . . . . . . . . . . . . . . . . . . . . . . 47

Simple USB Conﬁguration . . . . . . . . . . . . . . . . . . . . 47

Simple Conﬁguration for a SmartUPS . . . . . . . . . . . . . 48

Simple Conﬁguration for a Simple Signaling or Dumb . . . . 49

Simple Master Conﬁguration . . . . . . . . . . . . . . . . . . 49

Simple Slave Conﬁguration . . . . . . . . . . . . . . . . . . . 50

Variation on the Master/Slave Conﬁguration . . . . . . . . . 51

Sample NIS Slave Conﬁguration Using the Net Driver . . . . 51

Testing Apcupsd . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

Process-Status Test . . . . . . . . . . . . . . . . . . . . . . . . 53

Logging Test . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

apcaccess Test . . . . . . . . . . . . . . . . . . . . . . . . . . 55

Communications Test . . . . . . . . . . . . . . . . . . . . . . 58

Simulated Power Fail Test . . . . . . . . . . . . . . . . . . . . 59

System Shutdown Test . . . . . . . . . . . . . . . . . . . . . . 61

Full Power Down Test . . . . . . . . . . . . . . . . . . . . . . 62

Shutdown Sequence . . . . . . . . . . . . . . . . . . . . . . . . 63

apctest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

Troubleshooting Your Installation . . . . . . . . . . . . . . . . . . . 65

Known Problems with USB UPSes . . . . . . . . . . . . . . . 65

Monitoring and Tuning your UPS . . . . . . . . . . . . . . . . . . . 66

apcaccess . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

Apcupsd Notiﬁcation and Events . . . . . . . . . . . . . . . . 70

hid-ups and USB Speciﬁc Information . . . . . . . . . . . . . 71

apcupsd Network Monitoring (CGI) Programs . . . . . . . . . 71

Setting up and Testing the CGI Programs . . . . . . . . . . . 71

Conﬁguring Your EEPROM . . . . . . . . . . . . . . . . . . . 79

Maintaining Your UPS . . . . . . . . . . . . . . . . . . . . . . . . . 82

What Various People Have to Say about Batteries . . . . . . 83

Where Carl Suggests You Get Batteries . . . . . . . . . . . . 89

Frequently-Asked Questions . . . . . . . . . . . . . . . . . . . . . . 90

Apcupsd Bugs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

Advanced topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

Customizing Event Handling . . . . . . . . . . . . . . . . . . . . . 96

apccontrol Command Line Options . . . . . . . . . . . . . . . 97

Master/Slave Conﬁgurations . . . . . . . . . . . . . . . . . . . . . 100

Conﬁguration Directives . . . . . . . . . . . . . . . . . . . . . 101

Master/Slave Problems . . . . . . . . . . . . . . . . . . . . . . 101

Network Problems with Master/Slave or Server/Slave Conﬁgurations 103

Controlling Multiple UPSes on one Machine . . . . . . . . . . . . . 106

Conﬁguration . . . . . . . . . . . . . . . . . . . . . . . . . . . 106

Support for SNMP UPSes . . . . . . . . . . . . . . . . . . . . . . . 108

Connecting an SNMP UPS . . . . . . . . . . . . . . . . . . . 108

Building and Installing apcupsd . . . . . . . . . . . . . . . . . 109

SNMP Speciﬁc Information . . . . . . . . . . . . . . . . . . . 109

Known Problems . . . . . . . . . . . . . . . . . . . . . . . . . 109

Alternate Ways To Run The Network Information Server . . . . . 110

Running the server as a child of apcupsd . . . . . . . . . . . . 110

Running apcnisd from INETD . . . . . . . . . . . . . . . . . 111

Running apcnisd Standalome . . . . . . . . . . . . . . . . . . 112

apcupsd System Logging . . . . . . . . . . . . . . . . . . . . . . . . 113

Logging Types . . . . . . . . . . . . . . . . . . . . . . . . . . 113

Implementation Details . . . . . . . . . . . . . . . . . . . . . 114

Developers Notes . . . . . . . . . . . . . . . . . . . . . . . . . 115

Installation: Windows . . . . . . . . . . . . . . . . . . . . . . . . . 116

Windows Version of apcupsd . . . . . . . . . . . . . . . . . . . . . 116

Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

Installation Directory . . . . . . . . . . . . . . . . . . . . . . 122

Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

Upgrading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

Post Installation . . . . . . . . . . . . . . . . . . . . . . . . . 124

Problem Areas . . . . . . . . . . . . . . . . . . . . . . . . . . 124

Utility Functions . . . . . . . . . . . . . . . . . . . . . . . . . 125

Disclaimer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126

Email Notiﬁcation of Events . . . . . . . . . . . . . . . . . . . 127

Killpower under Windows . . . . . . . . . . . . . . . . . . . . 127

Power Down During Shutdown . . . . . . . . . . . . . . . . . 128

Command Line Options Speciﬁc to the Windows Version . . 129

Building the Win32 Version from the Source . . . . . . . . . . 129

Installation: Serial-Line UPSes . . . . . . . . . . . . . . . . . . . . 130

Overview of Serial-Interface UPSes . . . . . . . . . . . . . . . . . . 130

Connecting a Serial-Line UPS to a USB Port . . . . . . . . . . . . 130

Connecting a APC USB UPS to either a PC USB or Serial Port . 131

Cables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

Smart-Custom Cable for SmartUPSes . . . . . . . . . . . . . 131

Smart Signalling Cable for BackUPS CS Models . . . . . . . 132

Voltage-Signalling Cable for ”dumb” UPSes . . . . . . . . . . 134

Other APC Cables that apcupsd Supports . . . . . . . . . . . 136

Voltage Signalling Features Supported by Apcupsd for Various Cables 137

Voltage Signalling . . . . . . . . . . . . . . . . . . . . . . . . 137

Back-UPS Oﬃce 500 signals . . . . . . . . . . . . . . . . . . . 138

Analyses of APC Cables . . . . . . . . . . . . . . . . . . . . . 138

Win32 Implementation Restrictions for Simple UPSes . . . . 146

Internal Apcupsd Actions for Simple Cables . . . . . . . . . . 146

RS232 Wiring and Signal Conventions . . . . . . . . . . . . . 148

Pin Assignment for the Serial Port (RS-232C), 25-pin and 9-pin, Female End 148

Ioctl to RS232 Correspondence . . . . . . . . . . . . . . . . . 149

Testing Serial-Line UPSes . . . . . . . . . . . . . . . . . . . . . . . 149

Establishing Serial Port Connection . . . . . . . . . . . . . . 150

Using apctest on Serial-Line UPSses . . . . . . . . . . . . . . 153

Troubleshooting Serial Line communications . . . . . . . . . . . . . 155

Determining Which Voltage-Signaling Cable You Have . . . . 155

Once you have established serial communications . . . . . . . 155

Recalibrating the UPS Runtime . . . . . . . . . . . . . . . . . . . . 156

Status Logging On Serial-Line UPSes . . . . . . . . . . . . . . 157

DATA Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158

Technical Reference . . . . . . . . . . . . . . . . . . . . . . . . . . 159

Conﬁguration Directive Reference . . . . . . . . . . . . . . . . . . . 159

General Conﬁguration Directives . . . . . . . . . . . . . . . . 159

Conﬁguration Directives Used by the Network Information Server160

Conﬁguration Directives used during Power Failures . . . . . 161

Conﬁguration Directives used to Control System Logging . . 164

Conﬁguration Directives for Sharing a UPS . . . . . . . . . . 165

Conﬁguration Directives Used to Set the UPS EPROM . . . 168

apcupsd Status Logging . . . . . . . . . . . . . . . . . . . . . . . . 170

Status report format . . . . . . . . . . . . . . . . . . . . . . . 170

Status Report Example . . . . . . . . . . . . . . . . . . . . . 171

Status Report Fields . . . . . . . . . . . . . . . . . . . . . . . 173

Logging the STATUS Information . . . . . . . . . . . . . . . 176

Shutown Sequence and its Discontents . . . . . . . . . . . . . . . . 176

Shutdown Sequence . . . . . . . . . . . . . . . . . . . . . . . . 176

Shutdown Problems . . . . . . . . . . . . . . . . . . . . . . . 180

Master/Slave Shutdown . . . . . . . . . . . . . . . . . . . . . 180

Startup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181

Windows Considerations . . . . . . . . . . . . . . . . . . . . . 181

APC smart protocol . . . . . . . . . . . . . . . . . . . . . . . . . . 181

Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182

RS-232 diﬀerences . . . . . . . . . . . . . . . . . . . . . . . . 182

Diagram for cable hackers . . . . . . . . . . . . . . . . . . . . 182

Smart Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . 183

Dip switch info . . . . . . . . . . . . . . . . . . . . . . . . . . 188

Status bits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188

Alert messages . . . . . . . . . . . . . . . . . . . . . . . . . . 189

Interpretation of the Old Firmware Revision . . . . . . . . . . 191

Interpretation of the New Firmware Revision . . . . . . . . . 192

EEPROM Values . . . . . . . . . . . . . . . . . . . . . . . . . 192

Programming the UPS EEPROM . . . . . . . . . . . . . . . . 194

Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 195

Apcupsd — RPM Packaging FAQ . . . . . . . . . . . . . . . . . . 195

Answers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195

Credits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197

Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . . 197

Disclaimer: NO WARRANTY . . . . . . . . . . . . . . . . . . 199

Kernel Conﬁg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200

List of Figures

Multimon Main Page . . . . . . . . . . . . . . . . . . . . . . . . . . 74

Multimon Statistics Display . . . . . . . . . . . . . . . . . . . . . . 74

Windows Install - Explorer Window . . . . . . . . . . . . . . . . . 116

Windows Install - Winzip Unpack . . . . . . . . . . . . . . . . . . 117

Windows Install - Winzip Extract Window . . . . . . . . . . . . . 117

Windows Install - Setup Complete . . . . . . . . . . . . . . . . . . 119

Windows NT - Start Service . . . . . . . . . . . . . . . . . . . . . . 120

Windows NT - Stopping the Service . . . . . . . . . . . . . . . . . 123

Windows NT - Disabling the Service . . . . . . . . . . . . . . . . . 123

Thanks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197

List of Tables

Supported UPS Models . . . . . . . . . . . . . . . . . . . . . . . . 13

Supported Features . . . . . . . . . . . . . . . . . . . . . . . . . . . 137

RS232 Wiring and Signal Conventions . . . . . . . . . . . . . . . . 148

Single Character Commands . . . . . . . . . . . . . . . . . . . . . 183

DIP Switch Info . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188

UPS Status Bits . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188

Alert Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189

Programming the UPS EEPROM . . . . . . . . . . . . . . . . . . . 194

Apcupsd User’s Manual

Release Notes

This release contains a good number of cleanups and bug ﬁxes to prior 3.10.x versions, and is intended to be the oﬃcial release. See the ChangeLog below for more details.

New Features

- Implement USB on all *BSD systems. Note, the kernel drivers on most of these systems are still fragile. There are known problems, for example, on FreeBSD.

- Fix killpower on USB UPSes to properly turn off UPS.

- More killpower fixes for BackUPS Pros.

- Fix killpower sequence for serial UPSes.

Change Log for current version

----> Release 3.10.17 xxMar05

- Update default apcupsd.conf to recommend a blank DEVICE setting for USB driver.

- Add /dev/hiddev? to Linux USB driver device node search path.

- Add Mac OS X startup script

- Add new *BSD USB driver to support USB UPSes on FreeBSD, OpenBSD, and NetBSD. THIS DRIVER IS BETA SOFTWARE AND HAS A KNOWN LOCKUP ISSUE ON FREEBSD. Please keep this in mind when deciding whether or not to deploy it. PLEASE READ THE "CHECKING OUT YOUR USB SUBSYSTEM (BSD)" SECTION OF THE MANUAL as it contains crucial details on how to configure your system for the new driver.

- Add BackUPS Pro shutdown code to USB driver

- Prefer BackUPS style shutdown over SmartUPS in USB driver to resolve shutdown issues on BackUPS CS models

- Restructure USB driver to share common code

- Fix slave mode segfault bug introduced by --killpower fixes in 3.10.16.

- Commit kernstodo

- Added an anonymous patch to powerflute.c and to the slack-apcupsd.in file.

- Add Whitebox to detected systems.

- Minor tweak to RedHat spec.in

- Apply Carl Lindbergs patch for apcaction.c to fix the network management card shutdown.

- Fix typo in targets.mak that prevents uninstall from working.

- Change name of thread_terminate to apc_thread_terminate to avoid conflict on AIX.

- Put configure found SHUTDOWN in apccontrol.in

- Figured out how to scale the pdf images, so re-did them.

- Some minor updates to the manual, particularly the title

page.

Change Log for older versions

----> Release 3.10.16 04Nov04

- Adam has fixed the killpower problem for USB so that the USB now properly turns off the power. Nice job.

- Converted manual from docbook to texinfo format. There is some cleanup to be done, but we get an index.

- Thanks to Adam for converting the .png images to .pdf

- Apply patch to fix aastr... supplied by Manfred Schwarb.

- Changed Solaris to use mailx by default at the suggestion of Neil Brookins.

- Added Adam’s snoopdecode.c to examples that allows viewing USB events.

- A number of typos fixed in apccontrol files.

- Adam fixed a race condition in killpower with --kill-on-powerfail.

- --kill-on-powerfail disallowed for dumb UPSes since the kill power will always occur before the system has been halted.

- Lots of doc updates.

- Add proper platform code so that configure will create the 4 platform specific apccontrol files (some were missing).

- Apply fix from user to correct one of the shutdown sequences for the Smart UPS. During the conversion to drivers this was apparently mangled.

- Added code to close all file descriptors before becoming daemon unless debug turned on.

- Add APCBATTCapBeforeRestore found by Adam to hid-ups.c

- Update copyright in apc_struct.h

- Take Adam’s new apc_defines.h with minor modification.

- Correct a bug reported by a user (he also had the fix) to the snmp driver where Sensitivity was incorrectly reported.

- Add astrncpy() to snmp driver.

- Fix apcstatus.c to report Unknown for the sensitivity rather than High if the sense word cannot be read or is incorrect.

----> Release 3.10.15 07Aug04

- Document Mandrake USB kernel problems.

- Fix HID_MAX_USAGES in the examples directory

- Apply David Walser’s patch for missing colors in multimon. Reads the apcupsd.css file from the sysconf directory.

- Add EEPROM fix from Giuseppe Ghibo passed on by David Walser

----> Release 3.10.14 28Jul04

- Add workaround from Adam for linux/hiddev.h missing define.

- Updates to manual.

- Integrate patch for Mandrake apcupsd.in forwarded by David Walser.

- Found another store into the ups buffer so ifdefed it. Cannot store into the ups buffer on non-pthreads systems.

- Fiddle with apcconfig.c to correct astrncpy() problem noted by Adam.

- ifdef code in apcaccess that tries to write in the shared memory buffer.

- Applied Adam’s patch for fixing the pthreads dependencies in asys.c

- Tweak the patch a bit hopefully so that OpenBSD will work.

- Made a sweep through quite a few files updating the copyright, eliminating the disclaimer (now in DISCLAIMER), and adding as many astrncpy() and astrncat()s as I could find. There still remain some drivers and the cgi code to do.

- Implemented true/false and bool. Started implementing it in many of the files I touched.

- Updated the net driver and did a fairly good testing of it.

- Made apcupsd remain in the foreground when doing a kill power.

- Eliminated some of the error messages during kill power by not doing useless things.

- Added back code to print what is happening during kill power in the USB code.

- Corrected a few of the USB error messages that could have been missleading or confusing.

- Eliminated some inappropriate usages of size_t.

- Integrated a number of updates into the manual, particularly from Adam.

- If the IP address is 0.0.0.0 force it to localhost in apcaccess.

- Integrat Thomas Habets’ changes to keep connect() from blocking in apcnet.c so that apcupsd can service more slaves.

- Ensure that stdin/out/err are allocated in daemon_start() of apcuspd.c

- Update snmp.c with bug fix from Bacula.

- Bill has made numerous changes to improve the code such as adding consts where appropriate.

----> Release 3.10.13 20Apr04

- Added code to support net snmp configured with --enable-net-snmp based on patch sent by Sander Siemonsma.

- Build smtp on Unix systems.

- Update to most current smtp and make it easier to configure for apcupsd or Bacula

- Start implementing native Win32 version.

- Rename cmd - ups_event and cmd_msg - event_msg

- Add user supplied code to make apcaccess read the conf file and self configure to proper port. Thanks to Martin Flack for this patch.

- Start simplifying the Copyright and making the dates current.

- Rework the net driver. It was really in poor shape.

- Replace sprintf with asnprint. Replace strcpy with astrncpy

- Apply a fix supplied by Jim Pick where syslog releases the usb port and then re-attaches it to /dev/log.

- I finally took a careful look at the old master/slave networking code as well as ran it here, and it was sadly broken. Hopefully this commit fixes the problems.

- Fix a few string functions using the new routines.

- Added asys.c imported from Bacula, which contains a number of simple system routines such as astrncpy(), ...

How To Use This Manual

This is the manual for apcupsd, a daemon for communicating with UPSes (Uninterruptible Power Supplies) made by American Power Corporation (APC). If you have an APC-made UPS, whether sold under the APC nameplate or OEMed (The HP PowerTrust 2997A UPS has been tested as a “smartups” with cable Hewlett Packard part number 5061-2575 equivalent to a custom-smart cable), and you want you get it working with a computer running Linux, Unix, or Windows NT, you are reading the right document.

This manual is divided into parts which increase in technical depth as they go. If you have just bought a state-of-the-art smart UPS with a USB or Ethernet interface, and you are running a current version of Red Hat or SUSE Linux (8.0 or later), then apcupsd is very nearly plug-and-play and you will have to read only the Basic User’s Guide (see Basic User’s Guide).

If your operating system is older, or if you have an old-fashioned serial-line UPS, you’ll have to read about serial installation (see Installation on Serial-Line UPSes). If you need more details about administration for unusual situations (such as a master/slave or multi-UPS setup) you’ll need to read the section on advanced topics (see Advanced topics). Finally, there is a Technical Reference (see Technical Reference) section which gives full details on things like conﬁguration ﬁle directives and event-logging formats.

You should begin by reading the Quick Start (see Quick Start for Beginners) instructions.

Basic User’s Guide

Planning Your Installation

Quick Start for Beginners

apcupsd is a complex piece of software, but most of its complexities are meant for dealing with older hardware and operating systems. On current hardware and software getting it running should not be very complicated.

The following is a help guide to the steps needed to get apcupsd set up and running as painlessly as possible.

1. First, check to see if apcupsd supports your UPS and operating system (see Supported Operating Systems; UPSes and Cables).

2. Second, plan your conﬁguration type (see Choosing a Conﬁguration Type). If you have just one UPS and one computer, this is easy. If you have more than one machine being served by the same UPS, or more than one UPS supplying power to computers that are on the same local network, you have more choices to make.

3. Third, ﬁgure out if you have one of the easy setups. If you have a USB UPS, and a USB-capable recent Linux such as Red Hat or SuSE at version 8.0, and you want to use one UPS with one computer, that’s an easy setup. APC supplies the cable needed to talk with that UPS along with the UPS. All you need to do is check that your USB subsystem is working (see Checking Out Your USB Subsystem); if so, you can go to the build and install step.

4. If you have a UPS designed to communicate via SNMP over Ethernet, that is also a relatively easy installation. It’s in Advanced Topics (see Advanced topics) mainly because it’s an unusual situation.

5. If you have a UPS that communicates via an RS232C serial interface and it is a SmartUPS, then things are relatively simple, otherwise, your life is about to get interesting.

(a) If you have a vendor-supplied cable, ﬁnd out what cable type you

have by looking on the ﬂat ends of the cable for a number, such as 940-0020A, stamped in the plastic. Check the cables column of the table of types (see type type.

(b) If you don’t have a vendor-supplied cable, or your type is not

supported, you may have to build one yourself (see Cables). Here is hoping you are good with a soldering iron!

6. Now you are ready to read the Building and Installing (see Building and Installing apcupsd) section of the manual and follow those directions. If you are installing from an RPM or some other form of binary package, this step will probably consist of executing a single command.

7. Tweak your /etc/apcupsd/apcupd.conf ﬁle as necessary. Often it will not be.

8. Change the BIOS settings (see Arranging for Reboot on Power-Up) on your computer so that boots up every time it gets power. (This is not the default on most systems.)

table) to see if it’s a supported

9. To verify that your UPS is communicating with your computer and will do the right thing when the power goes out, read and follow the instructions in the Testing (see Testing Apcupsd) section.

10. If you run into problems, read the Troubleshooting (see Troubleshooting Your Installation) section of this manual.

11. If you still need help, send a message to the developer’s email list apcupsd-users at lists.sourceforge.net describing your problem, what version of apcupsd you are using, what operating system you are using, and anything else you think might be helpful.

12. Read the manual sections on monitoring and maintaining your UPS.

Supported Operating Systems, UPSes and Cables

Please note that due to the lack of Unix USB API standards, the USB code in apcupsd works only on Linux and *BSD systems. In addition, at the current release (3.10.17) the USB support for *BSD systems can at best be considered BETA due to fragile kernel drivers. Drivers for other OSes can be written, but it requires someone with a knowledge of the OS and the USB to do so. (This lack of a Unix USB API interface is one of the big failings of Unix. It occurs in other areas such as the GUI. Many people tout the diversity as an advantage, but it is in fact a weakness.)

The apcupsd maintainers develop it under Fedora (Red Hat); that port is, accordingly, the most up to date and best tested. There are enough Debian Linux users that that port is also generally pretty fresh. Slackware Linux is also fully supported.

apcupsd has also been ported to FreeBSD, NetBSD, OpenBSD, HP/UX, Solaris, Alpha Unix and the Cygwin Unix emulation under Windows. It is quite likely to work on those systems, though the port may occasionally get stale and require minor tweaking.

In Operating System Speciﬁcs you’ll ﬁnd operating-system-speciﬁc tips for building and conﬁguring apcupsd.

You can generally count on your UPS being supported if it has either an Ethernet-connected SNMP interface or a USB interface with an APCsupplied cable.

The “UPSTYPE Keyword” ﬁeld is the value you will put in your /etc/apcupsd/apcupd.conf ﬁle to tell apcupsd what type of UPS you have.

We’ll describe the possible values here, because they’re a good way to explain your UPS’s single most important interface property – the kind of protocol it uses to talk with its computer.

apcsmart An APCSmart UPS and its computer also communicate

through an RS232C serial connection, but they actually use it as a character channel (2400bps, 8 data bits, 1 stop bit, no parity) and pass commands back and forth in a primitive language (see APC smart protocol) resembling modem-control codes. The diﬀerent APC UPSes all use closely related ﬁrmware, so the language doesn’t vary much (later versions add more commands). This class of UPS is in decline, rapidly being replaced in APC’s product line by USB UPSes.

usb A USB UPS speaks a universal well deﬁned control language over a

USB wire. Most of APC’s lineup now uses this method as of late 2003, and it seems likely to completely take over in their low- and middle range. Other manufacturers (Belkin, Tripp-Lite, etc.) are moving the same way, though with a diﬀerent control protocol for each manufacturer. As long as USB hardware can be mass-produced more cheaply than an Ethernet card, most UPSes are likely to go this design route. Please note that even if you have a USB UPS, if you use a serial cable with it (as can be supplied by APC), you will need to conﬁgure your UPS as apcsmart rather than usb.

net This is the keyword to specify if you are using your UPS in Slave mode

(i.e. the machine is not directly connected to the UPS, but to another machine which is), and it is connected to the Master via an ethernet connection. You must have apcupsd’s Network Information Services NIS turned on for this mode to work. It is a much simpler form of running a Slave than the old Master/Slave code.

snmp SNMP UPSes communicate via an Ethernet NIC and ﬁrmware that

speaks Simple Network Management Protocol.

dumb A dumb or voltage-signaling UPS and its computer communicate

through the signal lines on an RS232C serial connection. Not much can actually be conveyed this way other than an order to shut down. Voltage-signaling UPSes are obsolete; you are unlikely to encounter one other than as legacy hardware. If you have a choice, we recommend you avoid simple signalling UPSes.

The table shown below lists the APC model supported, and the possible kewords that you would use in the conﬁguration with the listed cables. Some

of the models, particularly USB enabled models, can be run in multiple modes, so they may appear more than once in the table. APC is putting out new models at a furious rate, and so it is very likely that your model is not listed in the table. If it is USB enabled, it will probably work in USB mode. Please note that some of these new models are extremely inexpensive, so they are stripped down versions of more expensive units, and as such they do not oﬀer as many features, so some of the example output you see elsewhere in this manual may not be available with your unit.

APC Model UPSTYPE

Keyword

BackUPS CS/ES (serial mode)

BackUPS Pro, Smarter BackUPS Pro SmartUPS, SmartUPS VS (It has not been conﬁrmed that the cable shipped with the VS is a 940-0095.), PowerStack 450, Matrix UPS, ShareUPS Advanced Port

apcsmart smart (note:

apcsmart 940-0095A Supported

apcsmart smart (note:

UPSCABLE keywords for Cables Supported

using Smart Custom RJ45) the new BackUPS RS 500 models are reported NOT to work with this cable.

using SmartCustom), 940-0024C

Status

Supported

BackUPS CS USB, Pro USB, ES USB, RS/XS 1000, RS/XS 1500, and probably other USB models SmartUPS USB, BackUPS Oﬃce USB, and any other USB UPS All SNMPcapable models BackUPS dumb simple (note:

BackUPS Ofﬁce, BackUPS ES BackUPS CS and possibly ES models (serial mode) ShareUPS Basic Port

usb usb (note:

using APC cables 9400127A/B/C)

usb usb (note: us-

ing APC cable, no number)

snmp ether Supported

using SimpleCustom (This cable is not an APC product. You have to build it yourself using the instructions in Cables.), 940-0020B, 940-0020C, 940-0119A, 940-0023A

dumb 940-0119A Supported

dumb 940-0128A Supported

dumb 940-0020B,

940-0020C, 940-0023A

Supported in version >=3.9.8

Supported, version >=3.9.8

Supported

There are three major ways of running apcupsd on your system. The ﬁrst is a standalone conﬁguration where apcupsd controls a single UPS, which

powers a single computer. This is the most common conﬁguration. If you’re working with just one machine and one UPS, skip the rest of this section.

Your choices become more interesting if you are running a small cluster or a big server farm. Under those circumstances, it may not be possible or even desirable to pair a UPS with every single machine. apcupsd supports some alternate arrangements.

The second type of conﬁguration is a master/slave conﬁguration, where one UPS powers several computers, each of which runs a copy of apcupsd. The computer that controls the UPS is called the master, and the other computers are called slaves. The master copy of apcupsd communicates with and controls the slaves via an Ethernet connection. This type of conﬁguration may be appropriate for a small cluster of machines. Some example conﬁguration ﬁles for the master and the slave machines can be found in the examples directory of the source distribution. The more recent examples are in master.apcupsd.conf and slave.apcupsd.conf.

The third conﬁguration (new with version 3.8.3), is where a single computer controls multiple UPSes. In this case, there are several copies of apcupsd on the same computer, each controlling a diﬀerent UPS. One copy of apcupsd will run in standalone mode, and the other copy or copies will normally run in master/slave mode. This type of conﬁguration may be appropriate for large server farms that use one dedicated machine for monitoring and diagnostics

Here is a diagram that summarizes the possibilities:

Conﬁguration types.

\addcontentsline{lof}{figure}{Configuration Types}\includegraphics{./main_configs.eps}

If you decide to set up one of these more complex conﬁgurations, see the Advanced Topics (see Advanced topics) section for details.

Apcupsd Known USB Issues

- Problem: USB is only supported on Linux and *BSD systems (though the *BSD is still BETA). Although the conﬁguration script allows the usb

driver to be enabled on other platforms, it will only compile and run on Linux and *BSD systems.

- Workaround: Try using UPS in serial mode instead of USB.

- Problem: Linux 2.4 series kernels older than 2.4.22 do not bind the USB device to the proper driver. This is evidenced by /proc/bus/usb/devices listing the UPS correctly but it will have “driver=(none)” instead of “driver=(hid)”. This aﬀects RHEL3, among others.

- Workaround: Upgrade linux kernel to 2.4.22 or higher.

- Problem: Mandrake 10.0 and 10.1 systems with high security mode enabled (running kernel-secure kernel) use static device nodes but still assign USB minor numbers dynamically. This is evidenced by hiddev0: USB HID v1.10 Device [...] instead of hiddev96: ... in dmesg log.

- Workaround: Boot standard kernel instead of kernel-secure or disable CONFIG

USB DYNAMIC MINORS and rebuild kernel-secure.

- Problem: USB driver linux-usb.c fails to compile, reporting errors about

MAX USAGES undeﬁned. This is due to a defect in the linux

HID

kernel hiddev.h header ﬁle on 2.6.5 and higher kernels.

- Workaround: Workaround: Upgrade to apcupsd-3.10.14 or higher. These versions contain a workaround for the defect.

- Problem: On some systems such as Slackware 10.0, no USB devices will showup (see the next section).

- Workaround: add the following to rc.local

mount -t usbdevfs none /proc/bus/usb

- Problem: 2.6 kernels use udev and does not autmatically create /dev/usb/hiddev?? as it should, causing apcupsd to

- Workaround: Edit the ﬁle /etc/udev/rules.d/50-udev.rules, and add the following:

KERNEL="hiddev*", NAME="usb/hiddev%n"

More details are provided in the following section ...

Checking Out Your USB Subsystem

You can skip this section if your UPS has an Ethernet or RS232-C interface or you are not running on a Linux kernel. If it has a USB interface, you need to make sure that your USB subsystem can see the UPS. On a Linux system this is easy, just do this from a shell prompt (please see below for

2.6 kernel considerations):

Most of this section applies to Linux. However, toward the end, there is critical information about the BSD USB driver, including a list of known issues and kernel conﬁguration requirements.

cat /proc/bus/usb/devices

This information is updated by the kernel whenever a device is plugged in or unplugged, irrespective of whether apcupsd is running or not. To interpret the codes in this ﬁle, please see http://www.linuxhq.com/kernel/v2.4/doc/usb/proc usb info.txt.html

You should get some output back that includes something like this from ESR’s site, featuring an RS 1000:

T: Bus=02 Lev=01 Prnt=01 Port=00 Cnt=01 Dev#= 3 Spd=1.5 MxCh= 0 D: Ver= 1.10 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1 P: Vendor=051d ProdID=0002 Rev= 1.06 S: Manufacturer=American Power Conversion S: Product=Back-UPS RS 1000 FW:7.g3 .D USB FW:g3 S: SerialNumber=JB0308036505 C:* #Ifs= 1 Cfg#= 1 Atr=a0 MxPwr= 24mA I: If#= 0 Alt= 0 #EPs= 1 Cls=03(HID ) Sub=00 Prot=00 Driver=hid

Note, if on the last line, Driver is listed as Driver=none then you do not have the HID driver loaded or the driver did not attach to the UPS. One common cause is having a Linux kernel older than 2.4.22 (such as a stock RedHat 9 kernel). If this is the case for your system, please upgrade to at least kernel version 2.4.22 and try again. Otherwise, please read further for instructions for other possible courses of action.

For more details on how to interpret these codes, please see the end of this section.

Here are two more ample entries from Kern Sibbald. The ﬁrst features a Back-UPS 350 direct connected USB device:

T: Bus=01 Lev=01 Prnt=01 Port=00 Cnt=01 Dev#= 2 Spd=1.5 MxCh= 0 D: Ver= 1.10 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1 P: Vendor=051d ProdID=0002 Rev= 1.00 S: Manufacturer=American Power Conversion S: Product=Back-UPS 350 FW: 5.2.I USB FW: c1 S: SerialNumber=BB0115017954 C:* #Ifs= 1 Cfg#= 1 Atr=a0 MxPwr= 30mA I: If#= 0 Alt= 0 #EPs= 1 Cls=03(HID ) Sub=00 Prot=00 Driver=hid E: Ad=81(I) Atr=03(Int.) MxPS= 8 Ivl= 10ms

The second features an IOgear USB-to-serial adapter that runs my serial SmartUPS 1000:

T: Bus=01 Lev=01 Prnt=01 Port=01 Cnt=02 Dev#= 4 Spd=12 MxCh= 0 D: Ver= 1.10 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1 P: Vendor=0557 ProdID=2008 Rev= 0.01 C:* #Ifs= 1 Cfg#= 1 Atr=a0 MxPwr=100mA I: If#= 0 Alt= 0 #EPs= 3 Cls=ff(vend.) Sub=00 Prot=00 Driver=serial E: Ad=81(I) Atr=03(Int.) MxPS= 10 Ivl= 1ms E: Ad=02(O) Atr=02(Bulk) MxPS= 64 Ivl= 0ms E: Ad=83(I) Atr=02(Bulk) MxPS= 64 Ivl= 0ms

Note that the IOgear device is using the serial driver (the I: line) while the Back-UPS 350 is using the hid driver.

In general, if you see your UPS model in the S ﬁeld, which means Manu- facturer=, Product=, and SerialNumber=, and you see hid in the I ﬁeld (or serial if you are using an IOGear connection), you’re done. You can skip the rest of this section and go straight to building and installing.

If it doesn’t show, check the obvious things; the UPS must be powered on, and a cable must be properly seated in both the data port of the UPS and one of your machine’s USB ports. Many UPSes have phone ports to provide surge protection for phones or modems – make sure you haven’t plugged your USB cable into one of those rather than the data port (which will usually be near the top edge of the case.)

Note, on recent Debian systems, they do not include the hiddev device nodes in /dev, so you may need to manually create them using the examples/make-hiddev script.

Also, ensure that the correct drivers are loaded. Under Linux-2.4.x, you can check this out easily by examining the right ﬁle in the /proc system. Here’s how you can do that:

esr@grelber$ cat /proc/bus/usb/drivers

and you should get:

usbdevfs hub

96-111: hiddev

hid

On Linux-2.6.x, make sure the sysfs ﬁlesystem is mounted on /sys and do:

adk0212@mail$ ls -l /sys/bus/usb/drivers/

where you should get

total 0 drwxr-xr-x 2 root root 0 May 1 18:55 hid drwxr-xr-x 2 root root 0 May 1 18:55 hiddev drwxr-xr-x 2 root root 0 May 1 18:55 hub drwxr-xr-x 2 root root 0 May 1 18:55 usb drwxr-xr-x 2 root root 0 May 1 18:55 usbfs

or perhaps something like

total 0 drwxr-xr-x 2 root root 0 Jan 6 15:27 hiddev drwxr-xr-x 2 root root 0 Jan 6 15:28 hub drwxr-xr-x 2 root root 0 Jan 6 15:28 usb drwxr-xr-x 2 root root 0 Jan 6 15:27 usbfs drwxr-xr-x 2 root root 0 Jan 6 15:28 usbhid

If your 2.6.x system does not have the /sys/bus/usb directory, either you do not have sysfs mounted on /sys or the USB module(s) have not been loaded. (Check /proc/mounts to make sure sysfs is mounted.)

A USB UPS needs all of these drivers – the USB device ﬁlesystem, the USB hub, the Human Interface Device subsystem driver, and the Human Interface Device driver. If you are compiling your own kernel, you want to enable

CONFIG USB, CONFIG USB HID, CONFIG USB HIDDEV, and CON-

USB DEVICEFS as well as at least one USB Host Controller Driver

FIG (CONFIG USB UHCI HCD [2.6.x], CONFIG USB UHCI [2.4.x], etc.).

If CONFIG USB is set as M, CONFIG USB HID must be M (if enabled at all). If CONFIG USB is set as Y, CONFIG USB HID can be M or Y. hiddev, in turn, will be built however HID is.

To complicate things more many Linux ﬂavors running 2.6 kernels such as Fedora FC3 use the udev ﬁlesystem, which creates the devices in /dev (as well as some others such as network devices) on the ﬂy as they are needed. It is basically a hotplug system, giving a lot more power to the user to determine what happens when a device is probed or opened. It is also a lot more complicated.

The bottom line for apcupsd on such a system is that the ﬁle /dev/usb/hiddev# is not deﬁned, and hence apcupsd terminates in error. The solution to the problem is to add a rule to the udev rules ﬁle. On Fedora FC3, this ﬁle is found in /etc/udev/rules.d/50-udev.rules. Start by adding the following line:

BUS="usb", SYSFS[idVendor]="051d", NAME="usb/hiddev%n"

where you replace the [ and ] with braces in the line above.

Then either reboot your system, or unplug and replug your UPS and then restart apcupsd. At that point apcupsd should work ﬁne. You can use:

udevinfo -a -p /sys/class/usb/hiddev0/

to get more information on the ﬁelds that can be matched.

Adam has provided the following as a more generic rule:

KERNEL="hiddev*", NAME="usb/hiddev%n"

If you have several UPSes or you just want to give your UPS a ﬁxed name, you can use:

BUS="usb", SYSFS[serial]="AS0123456789", NAME="usb/ups0"

where you replace the [ and ] with braces and the serial number with the one that correspnds to your UPS.

Some kernels ship, such as Mandrake 10, ship with CON-

USB DYNAMIC MINORS turned on. This is not ideal for

FIG running with apcupsd, and the easiest solution is to turn CONFIG USB DYNAMIC MINORS oﬀ and rebuild your kernel, or ﬁnd a pre-built kernel with it oﬀ. For a kernel with CONFIG USB DYNAMIC MINORS turned on to work with apcupsd, you must enable devfs. The following will tell you if devfs is enabled:

$ ps ax | grep devs

which should give something like the following:

533 ? S 0:00 devfsd /dev

What complicates the situation much more on Mandrake kernels is their security level since CONFIG DYNAMIC USB MINORS is turned on, but on higher security levels devfs is turned oﬀ. The net result, is that in those situations hiddev is hosed (to use Adam’s terms) so apcupsd will not work. So, in these cases, the choices are:

(a) Reduce the security level setting of the system

(not sure if this is possible after the initial install).

(b) Custom build a high security kernel with devfs enabled

and make sure devfs is mounted and devfsd is running.

minors disabled

(d) Use udev

For a typical USB section of a kernel .conﬁg ﬁle, please see the end of this section.

For the IOGear serial USB connection, you need:

usbcore usbserial pl2303

Finally, check that appropriate USB devices exist. On a Red Hat system you can do this:

esr@grelber$ ls /dev/usb/h* /dev/usb/hiddev0 /dev/usb/hiddev12 /dev/usb/hiddev2 /dev/usb/hiddev6 /dev/usb/hiddev1 /dev/usb/hiddev13 /dev/usb/hiddev3 /dev/usb/hiddev7 /dev/usb/hiddev10 /dev/usb/hiddev14 /dev/usb/hiddev4 /dev/usb/hiddev8 /dev/usb/hiddev11 /dev/usb/hiddev15 /dev/usb/hiddev5 /dev/usb/hiddev9

This will tell you that the Human Interface Device nodes, one of which apcupsd will use to talk with the UPS, exist. On other Linuxes the layout will be slightly diﬀerent; the hiddev devices will usually live in a /dev/usb/hid/ subdirectory. If these devices don’t exist, you may need to run <apcupsd-source>/examples/make-hiddev to create them.

Now build and run the hid-ups test program. You do not have to conﬁgure and build the rest of apcupsd to do this. To build hid-ups enter:

cd <apcupsd-source>/examples make hid-ups

There should be no errors. Now assuming that everything has gone well to this point and that you have connected your USB UPS, enter:

./hid-ups

It should print a sample report of the information that it has obtained from your UPS. CAUTION! if you have a 2.4.x Linux kernel do not run two copies of this program at the same time, or your kernel will freeze. The report that is printed should look very similar to the report in <apcupsdsource>/examples/hid-ups.rpt. If the program reports that the device was not found ensure that all the appropriate modules are loaded (as described earlier), then unplug your UPS and plug it back in. This should permit the kernel to recognize the UPS.

If ./hid-ups tells you “No permission, try this as root”, you know what to try. If it says “Couldn’t ﬁnd USB UPS device, check your /dev.”, then it is very unlikely that apcupsd will work. You probably need to run the script “make-hiddev” before continuing.

If all there things check out and you still can’t see the UPS, something is more seriously wrong than this manual can cover – ﬁnd expert help. If you are unable to list USB devices or drivers, you kernel may not be USB-capable and that needs to be ﬁxed. Please check if your kernel has the three patches listed in the <apcupsd-source>/examples directory. Each of the ﬁles ends with the name .patch, and at the current writing they are:

linux-2.4.20-killpower.patch linux-2.4.20-USB-reject.patch linux-2.6.0-USB-queue-overflow.patch

For example, RedHat 9 and/or pre-2.4.22 kernels are known to need the linux-2.4.20-USB-reject.patch for APC SmartUPS XL series devices.

There are also a few email ﬁles that you can consult in the examples directory for additional information and details.

Finally, check your Kernel Conﬁg. You will ﬁnd more information about it at:

Kernel Conﬁg.

KNOWN ISSUES WITH BSD USB

The BSD USB driver for apcupsd is BETA software and has some known issues.

- FreeBSD lockups: Some users have experienced lockups (apcupsd stops responding) on FreeBSD systems. In at least one case this problem was worked around by disabling pthreads (—disable-pthreads ﬂag to conﬁgure). The problem seems to be caused by a FreeBSD kernel bug.

- FreeBSD kernel panics if USB cable is unplugged while apcupsd is running. This is another kernel bug and is most easily worked around by not hotunplugging the UPS while apcupsd is running.

PLATFORMS & VERSIONS

The new (beta) FreeBSD USB driver supports FreeBSD, OpenBSD and NetBSD. (Thanks go to the *BSD developers who kept a nearly identical interface across all three platforms.)

The driver has been tested with the following platform versions:

FreeBSD-5.3 (Primary development platform)

FreeBSD-4.11 NetBSD-2.0 NetBSD-1.6.2 OpenBSD-3.6

FreeBSD-5.3 has had the most testing since it is the primary platform on which the driver is developed. The other platforms and versions have had somewhat less testing. The only architecture tested so far (on any platform) is i386, althought there is no reason to think it will not work on other archs. If you run the driver on a new platform version or architecture, please report your experience to the apcupsd-users mailing list.

KERNEL CONFIGURATION

You will need to rebuild your kernel in order to disable the uhid driver. uhid is not suﬃcient for apcupsd at this time and we need to prevent it from grabbing the UPS device. You should disable the following devices in your kernel conﬁg ﬁle (comment them out):

FreeBSD (you WILL NOT lose use of USB keyboard and mouse): uhid

NetBSD (you WILL lose use of USB keyboard and mouse): uhidev, ums, wsmouse, ukbd, wskbd, uhid

OpenBSD (you WILL lose use of USB keyboard and mouse): uhidev, ums, wsmouse, ukbd, wskbd, uhid

For detailed information on rebuilding your kernel, consult these references:

FreeBSD: http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/kernelconfig.html

NetBSD: http://www.netbsd.org/guide/en/chap-kernel.html

OpenBSD: http://www.openbsd.org/faq/faq5.html#Building

CHECKING UPS IS RECOGNIZED BY THE KERNEL

After building a properly conﬁgured kernel, reboot into that kernel and plug in your UPS USB cable. You should see a dmesg log message like the following:

ugen0: American Power Conversion Back-UPS RS 1500 FW:8.g6 .D USB FW:g6, rev 1.10/1.06, addr 2

+ 203 hidden pages