APC UPS control system User Manual

Download

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

Note that the “ugen” driver is called out. If you see “uhid” instead, it probably means you did not properly disable the uhid driver when you compiled your kernel or perhaps you’re not running the new kernel.

You can also check with ’usbdevs -d’ to get a list of USB devices recognized by the system as well as the drivers they are associated with. For example:

# usbdevs -d addr 1: UHCI root hub, VIA

uhub0

addr 2: Back-UPS RS 1500 FW:8.g6 .D USB FW:g6, American Power Conversion

ugen0

MAKING DEVICE NODES

Apcupsd communicates with the UPS through the USB generic device, ugen. You may or may not need to manually make ugen device nodes in /dev, depending on what OS you are using.

FreeBSD: No manual intervention needed. FreeBSD automatically creates the ugen nodes on demand.

NetBSD: By default, NetBSD only creates nodes for the ﬁrst ugen device, ugen0. Check ’usbdevs -d’ to see which device your UPS was bound to and then create the appropriate nodes by running ’cd /dev ; ./MAKEDEV ugenN’, where ugenN is the ugen device name shown by usbdevs. It is probably a good idea to create several sets of ugen nodes in case you add more USB devices.

OpenBSD: Similar to NetBSD, OpenBSD creates nodes for ugen0 and ugen1. Check ’usbdevs -d’ to see which device your UPS was bound to and then create the appropriate nodes by running ’cd /dev ; ./MAKEDEV ugenN’, where ugenN is the ugen device name shown by usbdevs. It is probably a good idea to create several sets of ugen nodes in case you add more USB devices.

APCUPSD CONFIGURATION

Apcupsd must be built with USB support, which is accomplished via the —enable-usb switch to conﬁgure.

Your apcupsd.conf ﬁle needs the following hardware-related settings:

UPSCABLE usb UPSTYPE usb DEVICE

The DEVICE setting is blank on purpose; apcupsd will automatically locate your UPS.

The delay-, timeout-, and NIS-related settings should be conﬁgured as per your usual preference.

Building and Installing apcupsd

Installation from Binary Packages

Red Hat Linux:

For Red Hat systems, apcupsd is available in binary RPM format. This is the simplest way to install. If you have no previous version of apcupsd on your machine and are creating a standalone conﬁguration, simply install the RPM with a normal rpm -ihv command. You’re done, and can now skip the rest of this chapter and go straight to tweaking your run-time conﬁguration ﬁle. (see After Installation)

If you have a previous installation, you can upgrade with a normal rpm

-Uhv, but this may not upgrade the halt script. It may be better to do the upgrade as a remove (rpm -e) foll;owed by a fresh install (rpm -ihv).

After installation of the binary RPM, please verify carefully that /etc/rc.d/init.d/halt was properly updated and contains new script lines ﬂagged with ***APCUPSD***.

Since there is no standard location for cgi-bin, the rpm will place the binary CGI programs in the directory /etc/apcupsd/cgi. To actually use them, you must copy or move them to your actual cgi-bin directory, which on many systems is located in /home/httpd/cgi-bin.

Microsoft Windows:

If you have a binary release of the Win32 apcupsd, please see the instructions in the Advanced Topics (see Advanced topics) section of this manual.

Installation from Source

Installation from source might have to be be done diﬀerent ways depending on what system you are running. The basic procedure involves getting a source distribution, running the conﬁguration, rebuilding, and installing.

The basic installation from a tar source ﬁle is rather simple:

1. Unpack the source code from its tar archive.

2. Go into the directory containing the source code.

3. Run ./configure (with appropriate options as described below)

4. make

5. su (i.e. become root)

6. Stop any running instance of apcupsd. The command to do this will look like <system-dependent-path>/apcupsd stop

7. uninstall any old apcupsd This is important since the default install locations may have changed.

8. make install

9. edit your /etc/apcupsd/apcupsd.conf ﬁle if necessary

10. ensure that your halt script is properly updated

11. Start the new apcupsd with: <system-dependent-path>/apcupsd

start

If all goes well, the ./configure will correctly determine which operating system you are running and conﬁgure the source code appropriately. configure currently recognizes the systems listed below in the Operating System Speciﬁcs section of this chapter and adapts the conﬁguration appropriately. Check that the conﬁguration report printed at the end of the configure process corresponds to your choice of directories, options, and that it has correctly detected your operating system. If not, redo the configure with the appropriate options until your conﬁguration is correct.

Please note that a number of the configure options preset apcupsd.conf directive values in an attempt to automatically adapt apcupsd as best possible to your system. You can change the values in apcupsd.conf at a later time

without redoing the conﬁguration process by simply editing the apcupsd.conf ﬁle.

Other conﬁguration options can be used to set up the installation of HTML documentation and optional modules, notably the CGI interface that enables the UPS state to be queried via the Web and the optional powerﬂute cursesbased control panel. Still others enable features such as thread support. You will ﬁnd a complete reference later in this chapter.

In general, you will probably want to supply a more elaborate configure statement to ensure that the modules you want are built and that everything is placed into the correct directories.

On Red Hat, a fairly typical conﬁguration command would look like the following:

CFLAGS="-g -O2" LDFLAGS="-g" ./configure \

--enable-usb \

--with-upstype=usb \

--with-upscable=usb \

--prefix=/usr \

--sbindir=/sbin \

--with-cgi-bin=/var/www/cgi-bin \

--enable-cgi \

--with-css-dir=/var/www/docs/css \

--with-log-dir=/etc/apcupsd \

--enable-pthreads \

--enable-powerflute

By default, make install will install the executable ﬁles in /sbin, the manuals in /usr/man, and the conﬁguration and script ﬁles in /etc/apcupsd. In addition, if your system is recognized, certain ﬁles such as the startup script and the system halt script will be placed in appropriate system directories (usually subdirectories of /etc/rc.d).

Verifying a Source Installation

There are a number of things that you can do to check if the installation (make install) went well. The ﬁst is to check where the system has installed apcupsd using which and whereis. On my Red Hat system, you should get the following (lines preceded with a $ indicate what you type):

$ which apcupsd

/sbin/apcupsd $ whereis apcupsd apcupsd: /sbin/apcupsd /etc/apcupsd /etc/apcupsd.conf /etc/apcupsd.status /usr/man/man8/apcupsd.8.gz /usr/man/man8/apcupsd.8

If you ﬁnd an apcupsd in /usr/sbin, /usr/local/sbin, /usr/lib, or another such directory, it is probably a piece of an old version of apcupsd that you can delete. If you are in doubt, delete it, then rerun the make install to ensure that you haven’t deleted anything needed by the new apcupsd. Please note that the ﬁles speciﬁed above assume the default installation locations.

As a ﬁnal check that the make install went well, you should check your halt script (in /etc/rc.d on SUSE systems, and in /etc/rc.d/init.d on Red Hat systems) to see that the appropriate lines have been inserted in the correct place. Modiﬁcation of the halt script is important so that at the end of the shutdown procedure, apcupsd will be called again to command the UPS to turn oﬀ the power. This should only be done in a power failure situation as indicated by the presence of the /etc/powerfail ﬁle, and is necessary if you want your machine to automatically be restarted when the power returns. On a Red Hat system, the lines containing the # ***apcupsd*** should be inserted just before the ﬁnal halt command:

# Remount read only anything that’s left mounted. #echo "Remounting remaining filesystems (if any) readonly" mount | awk ’/ext2/ { print $3 }’ | while read line; do

mount -n -o ro,remount $line

done

# See if this is a powerfail situation. # ***apcupsd*** if [ -f /etc/apcupsd/powerfail ]; then # ***apcupsd***

echo # ***apcupsd*** echo "APCUPSD will now power off the UPS" # ***apcupsd*** echo # ***apcupsd*** /etc/apcupsd/apccontrol killpower # ***apcupsd*** echo # ***apcupsd*** echo "Please ensure that the UPS has powered off before rebooting" # ***apcupsd*** echo "Otherwise, the UPS may cut the power during the reboot!!!" # ***apcupsd*** echo # ***apcupsd***

fi # ***apcupsd***

# Now halt or reboot. echo "$message" if [ -f /fastboot ]; then

echo "On the next boot fsck will be skipped."

elif [ -f /forcefsck ]; then

echo "On the next boot fsck will be forced."

The purpose of modifying the system halt ﬁles is so that apcupsd will be recalled after the system is in a stable state. At that point, apcupsd will instruct the UPS to shut oﬀ the power. This is necessary if you wish your system to automatically reboot when the mains power is restored. If you prefer to manually reboot your system, you can skip this ﬁnal system dependent installation step by specifying the disable-install-distdir option on the ./configure command (see below for more details).

The above pertains to Red Hat systems only. There are signiﬁcant diﬀerences in the procedures on each system, as well as the location of the halt script. Also, the information that is inserted in your halt script varies from system to system. Other systems such as Solaris require you the make the changes manually, which has the advantage that you won’t have any unpleasant surprises in your halt script should things go wrong. Please consult the speciﬁc system dependent README ﬁles for more details.

Please note that if you install from RPMs for a slave machine, you will need to remove the changes that the RPM install script made (similar to what is noted above) to the halt script. This is because on a slave machine there is no connection to the UPS, so there is no need to attempt to power oﬀ the UPS. That will be done by the master.

Conﬁgure Options

All the available configure options can be printed by entering:

./configure --help

When specifying options for ./configure, if in doubt, don’t put anything, since normally the conﬁguration process will determine the proper settings for your system. The advantage of these options is that it permits you to customize your version of apcupsd. If you save the ./configure command that you use to create apcupsd, you can quickly reset the same customization in the next version of apcupsd by simply re-using the same ./configure command.

The following command line options are available for configure to customize your installation.

—preﬁx=<path> This deﬁnes the directory for the non-executable ﬁles

such as the manuals. The default is /usr.

—sbindir=<path> This deﬁnes the directory for the executable ﬁles

such as apcupsd. The default is /sbin. You may be tempted to place the executable ﬁles in /usr/sbin or /usr/local/sbin. Please use caution here as these directories may be unmounted during a shutdown and thus may prevent the halt script from calling apcupsd to turn oﬀ the UPS power. Though your data will be protected, in this case, your system will probably not be automatically rebooted when the power returns.

—enable-powerﬂute This option enables the building of the powerﬂute

executable, which is a ncurses based program to monitor the UPS. This program is not necessary for the proper execution of apcupsd.

—enable-cgi This enables the building of the CGI programs that permit

Web browser access to apcupsd data. This option is not necessary for the proper execution of apcupsd.

—with-cgi-bin=<path> The with-cgi-bin conﬁguration option allows

you to deﬁne the directory where the CGI programs will be installed. The default is /etc/apcupsd, which is probably not what you want.

—with-css-dir=<path> This option allows you to specify where you

want apcupsd to put the Cascading Style Sheet that goes with the multimoncss.cgi CGI program.

—enable-master-slave Turns on the master/slave networking code (de-

fault). This is sometimes referred to as the old master/slave code, and is more complicated than using NIS and the net driver to control Slaves (see below).

—enable-apcsmart Turns on generation of the APC Smart driver (de-

fault).

—enable-dumb Turns on generation of the dumb signalling driver code

(default).

—enable-usb Turns on generation of the Linux (only) USB driver code.

By default this is disabled.

—enable-net Turns on generation of the NIS network driver for slaves.

This is an alternative to old master/slave code. For the master, this code should be disabled. For each slave, this is the only driver needed. This driver works by reading the information from the the conﬁgured master using the NIS (Network Information Services) interface.

—enable-snmp Turns on generation of the SNMP driver. This driver

will control the computer by reading the UPS information over the network assuming you are running SNMP. By default this is disabled.

—enable-test This turns on a test driver that is used only for debugging.

By default it is disabled.

—enable-nis Turns on the Network Information Server (NIS) code within

apcupsd. This is enabled by default. If you do not want to access the status of the UPS from the network and you are not controlling any slaves via NIS (enable-net), this can be disabled.

—enable-pthreads This option enables pthreads support causing

apcupsd to be built as a threaded program rather than forking to create separate processes. apcupsd built in this fashion is more eﬃcient that the standard version being one third the data size and less overhead locking and coping shared memory. This option is highly recommended for Windows builds.

—with-libwrap=<path> This option when enabled causes apcupsd to

be built with the TCP WRAPPER library for enhanced security. In most cases, the <path> is optional since conﬁgure will determine where the libraries are on most systems.

—with-nologin=<path> This option allows you to specify where

apcupsd will create the nologin ﬁle when logins are prohibited. The default is /etc

—with-pid-dir=<path> This option allows you to specify where

apcupsd will create the process id (PID) ﬁle to prevent multiple copies from running. The default is system dependent but usually /var/run.

—with-log-dir=<path> This option allows you to specify where

apcupsd will create the EVENTS and STATUS log ﬁles. The default is /etc/apcupsd. This option simply sets the default of the appropriate path in the apcupsd.conf ﬁle, which can be changed at any later time.

—with-lock-dir=<path> This option allows you to specify where

apcupsd will create the serial port lock ﬁle. The default is systemdependent but usually /var/lock. This option simply sets the appropriate path in the apcupsd.conf ﬁle, which can be changed at any later time.

—with-pwrfail-dir=<path> This option allows you to specify where

apcupsd will create the powerfail ﬁle when a power failure occurs. The default is system dependent but usually /etc.

—with-serial-dev=<device-name> This option allows you to specify

where apcupsd will look for the serial device that talks to the UPS. The default is system dependent, but often /dev/ttyS0. This option simply sets the appropriate device name in the apcupsd.conf ﬁle, which can be changed at any later time.

—with-nis-port=<port> This option allows you to specify what port

apcupsd will use for the Network Information Server (the CGI programs). The default is system dependent but usually 3551 because that port has been oﬃcially assigned to apcupsd by the IANA. This option simply sets the appropriate port in the apcupsd.conf ﬁle, which can be changed at any later time.

—with-nisip=<IP-Address> This option allows you to specify the

value that will be placed on then NISIP directive in the conﬁguration ﬁle. The default is 0.0.0.0. No checking is done on the value entered, so you must ensure that it is a valid IP address.

—with-net-port=<port> This option allows you to specify what port

apcupsd will use for Master and Slave communications. The default is system dependent but usually 6666. This option simply sets the appropriate port in the apcupsd.conf ﬁle, which can be changed at any later time.

—with-upstype=<type> This option allows you to specify the type

of UPS that will be connected to your computer. The default is: smartups. This option simply sets the appropriate UPS type in the apcupsd.conf ﬁle, which can be changed at any later time.

—with-upscable=<path> This option allows you to specify what cable

you are using to connect to the UPS. The default is: smart. This option simply sets the appropriate UPS cable in the apcupsd.conf ﬁle, which can be changed at any later time.

—disable-install-distdir This option modiﬁes the apcupsd Makeﬁles dis-

able installation of the distribution (platform) directory. Generally, this used to do a full installation of apcupsd except the ﬁnal modiﬁcation of the operating system ﬁles (normally /etc/rc.d/halt, etc.). This is useful if your operating system is not directly supported by apcupsd or if you want to run two copies of apcupsd on the same system. This option can also be used by those of you who prefer to manually reboot your system after a power failure or who do not want to modify your system halt ﬁles.

Recommended Options for most Systems

For most systems, we recommend the following options:

./configure --prefix=/usr --sbindir=/sbin --enable-usb \

--enable-pthreads

and you can optionally build and install the CGI programs as follows:

./configure --prefix=/usr --sbindir=/sbin --enable-usb \

--enable-cgi --with-cgi-bin=/home/httpd/cgi-bin \

--enable-pthreads

Compilers and Options

Some systems require unusual options for compilation or linking that the ./configure script does not know about. You can specify initial values for variables by setting them in the environment. Using a Bourne-compatible shell, you can do that on the command line like this:

CFLAGS="-O2 -Wall" LDFLAGS= ./configure

Or on systems that have the env program, you can do it like this:

env CPPFLAGS=-I/usr/local/include LDFLAGS=-s ./configure

Or for example on the Sun Solaris system, you can use:

setenv CFLAGS -O2 setenv LDFLAGS -O ./configure

You can get a listing of all available options by doing:

./configure --help

or simply see the previous section of this manual.

Operating System Speciﬁcs

With the exception of Linux SUSE and Linux Red Hat systems used by the developers, we rely on users to help create installation scripts and instructions as well as to test that apcupsd runs correctly on their system. As you can imagine, most of these people are system administrators rather than developers so they are very busy and don’t always have time to test the latest releases. With that in mind, we believe that you will ﬁnd that a lot of very valuable work has been already done to make your installation much easier (and probably totally automatic).

Below, you will ﬁnd a list of operating systems for which we have received installation ﬁles:

• Alpha (see Alpha)

• Debian (see Debian)

• FreeBSD (see FreeBSD)

• HPUX (see HPUX)

• NetBSD (see NetBSD)

• OpenBSD (see OpenBSD)

• Red Hat (see Red Hat Systems)

• Slackware (see Slackware)

• SUSE (see SUSE)

• Solaris (see Sun Solaris)

• unknown (see Unknown System)

• Win32 (see Windows Systems with CYGWIN Installed)

Alpha:

The Alpha V4.0 version of apcupsd builds without compiler errors with gcc version 2.95.2. It is unlikely that the native Alpha compiler will work because of varargs diﬀerences. Unless you are a system guru, we recommend that you connect your UPS to the second serial port /dev/tty01 to avoid conﬂicts with the console device.

DEVICE /dev/tty01

In addition, you should ensure serial port lock ﬁle in apcupsd.conf is deﬁned as:

LOCKFILE /var/spool/locks

Unlike the Linux systems, the system halt routine is located in /sbin/rc0, so after the make install, please check that this ﬁle has been correctly updated.

The start/stop script can be found in:

/sbin/init.d/apcupsd

Debian:

This port is complete and is operation by several users. Since Debian build and install procedures are somewhat particular, we have put the extra Debian information into the following two subdirectories: <src>/distributions/debian/examples/ and <src>/distributions/debian/packageinfo

You can also ﬁnd the oﬃcial Debian packages on the Debian site at:

• http://packages.debian.org/stable/admin/apcupsd.html

• http://packages.debian.org/testing/admin/apcupsd.html

• http://packages.debian.org/unstable/admin/apcupsd.html

FreeBSD:

This port is complete and is being used by several users. As of version 3.8.3, we do not recommend that you compile apcupsd with pthreads enabled. This is because the current FreeBSD implementation of pthreads runs as a

single process, and thus is less eﬃcient (consumes more CPU time) than the forking version of apcupsd. We hope to rectify this in a future version by using the FreeBSD LinuxThreads implementation of pthreads.

On the FreeBSD OS, there is no known way for a user program to get control when all the disks are synced. This is needed for apcupsd to be able to issue the killpower command to the UPS so that the UPS shuts oﬀ the power. To accomplish the same thing on FreeBSD systems, make sure you have a SmartUPS and that your UPS shutdown grace period is set suﬃciently long so that you system will power down (usually 2 minutes), the use the kill-on-powerfail option on the apcupsd command line.

Please note the concerns listed below under OpenBSD concerning the use of pthreads.

HPUX:

We have no reports from testing this yet on version 3.8.4, but worked ﬁne on 3.8.1

NetBSD:

Submitted during development of 3.8.2, this should be a complete distribution. Please read the comments on the pthreads implementation in the FreeBSD section above as they may apply equally to OpenBSD.

Please note the concerns listed below under OpenBSD concerning the use of pthreads.

OpenBSD:

Ensure that you read the distributions/openbsd/README ﬁle before running apcupsd. There are some critical diﬀerences in how the OpenBSD implementation operates when the UPS batteries are exhausted. Failure to take this into account may result in the system not being fully halted when power is lost. Please read the comments on the pthreads implementation in the FreeBSD section above as they may apply equally to OpenBSD.

PLEASE NOTE. Due to some deﬁciencies or errors in the OpenBSD pthreads libraries, if you build apcupsd on OpenBSD with pthread and a child program is launched (i.e. mail notiﬁcation of events), this may cause

OpenBSD to freeze up. The best solution is probably to build without pthread. However, in doing so, you must realize that the bulk of this manual assumes that pthreads is enabled, and thus many of the comments about apcaccess will not be applicable. A second solution that seems to work is to delete all calls to the email notiﬁcation routines from apccontrol. In doing so, some users have succeeded in running apcupsd with pthreads.

If you want to know the technical problems with pthreads on OpenBSD, it is as best we can tell because the pthreads are not real kernel pthreads as on Linux and Solaris, but rather a user program that makes all I/O nonblocking. So when apcupds does I/O, the userland pthreads libarary will switch to another thread if it wants to run. This works ﬁne except that when a child process is called and it exits, all the blocking/non-blocking statuses of the open ﬁle descriptors in the parent program are reset as blocking — this causes chaos and an almost immediate freezing of the program (apcupsd).

Red Hat Systems:

Red Hat systems are fully supported, and by following the standard installation instructions given above, you should experience few or no problems.

Slackware:

Slackware systems are fully supported, and by following the standard installation instructions given above, you should experience few or no problems.

SUSE:

SUSE systems are fully supported, and by following the standard installation instructions given above, you should experience few or no problems.

Sun Solaris:

Please read this before attempting to compile or install the beta software. It contains important information that will make your eﬀorts easier.

If you ﬁnd bugs, or run into problems that seem to be related to the version of Solaris that you run, please feel free to contact the maintainers by email, or through the development mailing list. We’ll attempt to help with problems getting the beta running, although we can’t promise a quick response.

As always, remember testing UPSes can be hazardous to you system, and, apcupsd may contain bugs that can damage your system and data ﬁles! You must accept all responsibility for running this software. An unexpected power-oﬀ of a running system can be a disaster. As always, make backups of any critical information before you install this software.

Remember, we told you. we’ll listen sympathetically if you lose data, but there will be nothing we can do to help you.

Please read the general installation instructions given above before continuing on with these Solaris-speciﬁc instructions. Then come back and read this section before attempting to build the package.

For building the system, we suggest that you run the conﬁgure and make processes as your normal UNIX user ID. The make install must be run as root. But if your normal ID has an environment setup for using the C compiler, it’s simpler to do that than to set up root to have the correct environment.

Normally, we support the GCC compiler, but we have also attempted to support the Solaris workshop compilers and EGCS compilers. Please be aware that if you do not use GCC, you may experience a few problems.

Whichever compiler you do have, please insure that you can execute the compiler from the command line before running conﬁgure. If you do not have an environment setup to run the compiler ﬁrst, conﬁgure will fail.

Before running ./configure, please be sure that you do not have /usr/ucb on your path. This may cause the ./configure to choose the wrong shutdown program. If ./configure detects that /usr/usb is on your path, it will print a warning message. Please follow the advice to avoid shutdown problems.

Your normal UNIX user ID must own the source tree directories, and you must have the normal development tools in your path. This includes make, the compiler, the M4 preprocessor, the linker, and ar or ranlib. If the user you are logged in as can compile and link a C program from a source ﬁle, then you have all the required tools available.

You will want to install the executables in a directory that remains mounted during the shutdown. Solaris will unmount almost everything except the root directories. Since the ability to power the UPS oﬀ requires access to the executable programs, they need to be in a directory that will never be unmounted. And since they should also be in a directory that normal users cannot get into, /sbin is the default. However, please be aware that if you want to follow Sun’s ﬁlesystem conventions you would use the following:

./configure \

--prefix=/opt/apcupsd \

--sbindir=/etc/opt/apcupsd/sbin \

--sysconfdir=/etc/opt/apcupsd \

--with-cgi-bin=/opt/apcupsd/cgi-bin

The way to setup the /sbin directory as the executables directory is to pass conﬁgure the sbindir=/sbin option. No other arguments should be required, and your setup and platform should be detected automatically by conﬁgure.

Once you have run conﬁgure, you will need to do a make. Once the make has completed with no errors, you must su to root to complete the install. After the su, you may not have a path to the make program anymore. In that case, you should do the make install step as:

/usr/ccs/bin/make install

Once the install completes, you must edit the /sbin/rc0 script as detailed below, then exit from the su’ed shell.

In order to support unattended operation and shutdown during a power failure, it’s important that the UPS remove power after the shutdown completes. This allows the unattended UPS to reboot the system when power returns by re-powering the system. Of course, you need autoboot enabled for your system to do this, but all Solaris systems have this by default. If you have disabled this on your system, please re-enable it.

To get the UPS to remove power from the system at the correct time during shutdown, i.e., after the disks have done their ﬁnal sync, we need to modify a system script. This script is /sbin/rc0.

We do not have access to every version of Solaris, but we believe this ﬁle will be almost identical on every version. Please let us know if this is not true.

At the very end of the /sbin/rc0 script, you should ﬁnd lines just like the following:

# unmount file systems. /usr, /var and /var/adm are not unmounted by umountall # because they are mounted by rcS (for single user mode) rather than # mountall.

# If this is changed, mountall, umountall and rcS should also change. /sbin/umountall /sbin/umount /var/adm >/dev/null 2>\&1 /sbin/umount /var >/dev/null 2>\&1 /sbin/umount /usr >/dev/null 2>\&1

echo ’The system is down.’

We need to insert the following lines just before the last ’echo’:

#see if this is a powerfail situation if [ -f /etc/apcupsd/powerfail ]; then

echo echo "APCUPSD will power off the UPS" echo /etc/apcupsd/apccontrol killpower echo echo "Please ensure that the UPS has powered off before rebooting" echo "Otherwise, the UPS may cut the power during the reboot!!!" echo

We have included these lines in a ﬁle called rc0.solaris in the distributions/sun subdirectory of the source tree. You can cut and paste them into the /sbin/rc0 ﬁle at the correct place, or yank and put them using vi or any other editor. Note that you must be root to edit this ﬁle.

You must be absolutely sure you have them in the right place. If your /sbin/rc0 ﬁle does not look like the lines shown above, do not modify the ﬁle. Instead, email a copy of the ﬁle to the maintainers, and we will attempt to ﬁgure out what you should do. If you mess up this ﬁle, the system will not shut down cleanly, and you could lose data. Don’t take the chance.

This feature has only been tested with APC SmartUPS models. If you do not have a SmartUPS, you will be one of the ﬁrst testers to try this feature. Please send email to let us know if it works with your UPS model, what model you have, and if possible, the event logs located in /etc/apcupsd. We’d be very interested in your results, and would be glad to work with you to get this feature working correctly with all the APC models. A detailed description of the screen output during the shutdown would be very helpful if you see problems.

You will then need to make the normal changes to the /etc/apcupsd/apcupsd.conf ﬁle. This ﬁle contains the conﬁguration settings for the package. It is important that you set the values to match

your UPS model and cable type, and the serial port that you have attached the UPS to. People have used both /dev/ttya and /dev/ttyb with no problems. You should be sure that logins are disabled on the port you are going to use, otherwise you will not be able to communicate with the UPS. If you are not sure that logins are disabled for the port, run the ’admintool’ program as root, and disable the port. The ’admintool’ program is a GUI administration program, and required that you are running CDE, OpenWindows, or another XWindows program such as KDE.

Solaris probes the serial ports during boot, and during this process, it toggles some handshaking lines used by dumb UPSes. As a result, particularly for simple signalling “dumb” UPSes it seems to kick it into a mode that makes the UPS think it’s either in a calibration run, or some self-test mode. Since at this point we are really not communicating with the UPS, it’s pretty hard to tell what happened. But it’s easy to prevent this, and you should. Disconnect the UPS, and boot the system. When you get to a login prompt, log in as root. Type the following command:

eeprom com1-noprobe=true

eeprom com2-noprobe=true

depending on which com port your UPS is attached to. Then sync and shutdown the system normally, reattach the UPS, and reboot. This should solve the problem. However, we have some reports that recent versions of Solaris (7 & 8) appear to have removed this eeprom option and there seems to be no way to suppress the serial port probing during boot.

At this point, you should have a complete installation. The daemon will load automatically at the next boot. Watch for any error messages during boot, and check the event logs in /etc/apcupsd. If everything looks OK, you can try testing the package by removing power from the UPS. NOTE! if you have a voltage-signalling UPS, please run the ﬁrst power tests with your computer plugged into the wall rather than into the UPS. This is because dumb serial-port UPSes have a tendency to power oﬀ if your conﬁguration or cable are not correct.

As a user, your input is very helpful in solving problems with the package, and providing suggestions and future directions for the development of the

package. We are striving to provide a useful package that works across all platforms, and welcome your feedback.

Best regards, and thanks for your interest and help, The Apcupsd Development Team.

Unknown System:

During the ./configure, if apcupsd does not ﬁnd one of the systems for which it has speciﬁc installation programs, it will set the Operating System to unknown and will use the incomplete installation scripts that are in <src>/distributions/unknown/. You will be on your own, or you can ask the developers list (apcupsd-users at lists.sourceforge.net) for installation instructions. This directory also contains a hint ﬁle for Linux From Scratch, which could be helpful for other systems as well.

Windows Systems with CYGWIN Installed:

If you wish to build from the source, and if you have CYGWIN version

1.5.5 and GCC 2.95.3-5 installed, it is possible to build the Win32 version of apcupsd. Please don’t try any other versions of CYGWIN as there were known problems.

To date, the Win32 version has only been build on a Win98 SR2 and a WinXP system with the above CYGWIN environment and all the available CYGWIN tools loaded. In addition, the builds were done running under the bash shell. As time permits, we will experiment with other environments, and if any of you do build it from source, please let us know. The current CYGWIN environment was loaded using the CYGWIN setup.exe program, downloading ALL the latest binaries and installing them.

We recommend that you run the ./configure command with the following options:

./configure \

--prefix=/apcupsd \

--sbindir=/apcupsd/bin \

--sysconfdir=/apcupsd/etc/apcupsd \

--with-pid-dir=/apcupsd/etc/apcupsd \

--mandir=/apcupsd \

--with-cgi-bin=/apcupsd/etc/apcupsd/cgi \

--enable-pthreads

After which, you can do a:

make

And to install apcupsd, do:

make install

Finally, you should follow the Win32 (see Installation on Windows) installation instruction, skipping the part that describes unZipping the binary release.

After Installation

Checking Your Conﬁguration File

Once you have installed apcupsd, either from a binary package or by building from source, your next step should be to inspect your /etc/apcupsd/apcupsd.conf ﬁle to make sure it is valid.

You can read the complete reference on conﬁguration directives (see Conﬁguration Directive Reference), but if you are setting up a normal standalone conﬁguration you should only need to check (and possibly ﬁx) the ﬁrst three items listed below.

Your UPSTYPE should be the UPS’s protocol type: dumb, apcsmart, usb, net, snmp, or ether. Your UPSCABLE should be the type of cable you are using. You should have gotten both from the table of types (see type table); usually they will both be the string “usb”.

If you have a USB device, it is better not to specify a DEVICE directive by commenting it out. Apcupsd will automatically search for your device in the standard places. If you specify a DEVICE, it should be the name of the device (or device range) that apcupsd is to use to communicate with the UPS. If you’re using a USB UPS under Linux, you may leave the device name ﬁeld blank and apcupsd will search all the standard locations for the UPS. You may also explicitly specify the device location as either /dev/usb/hid/hiddev[0-15] (on non-Red-Hat systems) or /dev/usb/hiddev[0-15] (on Red Hat systems), but this is not recommended.

Note that you should enter “/dev/usb/hiddev[0-15]” literally as shown. The “[0-15]” expression tells apcupsd to search all hiddev devices until it ﬁnds a UPS. You can restrict the search to a subset of devices by using something like “[0-4]”, but keep in mind this will limit apcupsd’s ability to locate the UPS if the kernel relocates it to a diﬀerent device node, which happens occasionally during short power failures. Again, it is highly recommended to leave the DEVICE directive blank and let apcupsd ﬁnd your device automatically.

If the ﬁrst time you execute apcupsd, you get a message to the eﬀect that the Apcupsd USB driver is missing, it means that you most likely forgot to put —enable-usb on your ./conﬁgure command line. If you loaded apcupsd from an rpm ﬁle, you may have selected the wrong one — please ensure that the word usb appears in the rpm package name.

The next chapter (see Conﬁguration Examples) of this manual provides you with the essential characteristics of each main type of conﬁguration ﬁle. After those elements are correct, apcupsd should run, and then it is only a matter of customization of your setup.

Arranging for Reboot on Power-Up

The ﬁnal consideration for a automatic reboot after a full power down is to ensure that your computer will automatically reboot when the power is restored.

This is not the normal behavior of most computers as shipped from the factory. Normally after the power is cut and restored, you must explicitly press a button for the power to actually be turned on. You can test your computer by powering it down; shutting oﬀ the power (pull the plug); then plugging the cord back in. If your computer immediately starts up, good. There is nothing more to do.

If your computer does not start up, manually turn on the power (by pressing the power on button) and enter your computer’s SETUP program (often by pressing DEL during the power up sequence; sometimes by pressing F10). You must then ﬁnd and change the appropriate conﬁguration parameter to permit instant power on.

Normally, this is located under the BOOT menu item, and will be called something such as Restore on AC/Power Loss or Full-On. The exact words will vary according to the ROM BIOS provider. Generally you will have three options: Last State, Power On, and Power Oﬀ. Although Last State should normally work, we recommend setting your computers

to Power On. This means that whenever the power is applied they are on. The only way to shut them oﬀ is to pull the plug or to have a special program that powers them oﬀ (/sbin/poweroﬀ on Linux systems).

If after making all the changes suggested above, you cannot get your computer to automatically reboot, you might examine your halt script (/etc/rc.d/init.d/halt in the case of Red Hat Linux) and see if the ﬁnal line that performs the halt or reboot contains the -p option for powering down the computer. It should not with the logic used by apcupsd, but if it does, the -p option could cause your computer to power oﬀ while the UPS is still suppling power (i.e. before the UPS kills the power). Depending on the setting of your BIOS, it may prevent your computer from restarting when the power returns. As already mentioned, this should not apply, but in case of problems it is worth a try.

Making sure apcupsd Is Running

The simplest way to invoke apcupsd is from the command line by entering:

/sbin/apcupsd

To do so, you must be root. However, normally, you will want apcupsd started automatically when your system boots. On some systems with installation support (e.g. SUSE and Red Hat), the installation procedure will create a script ﬁle that you will be automatically invoked when your system reboots. On other systems, you will have to invoke apcupsd from your rc.local script.

On Red Hat systems, this script ﬁle that automatically invokes apcupsd on system start and stops is: /etc/rc.d/init.d/apcupsd

To start apcupsd manually (as you will probably do immediately following the installation), enter the following:

/etc/rc.d/init.d/apcupsd start

To understand how this ﬁle is automatically invoked at system startup and shutdown, see the man pages for chkconﬁg(8).

On SUSE systems, the script ﬁle that automatically invokes apcupsd on system start and stops is /etc/rc.d/apcupsd

To start apcupsd manually (as you will probably do immediately following the installation), enter the following:

/etc/rc.d/apcupsd start

Normally, when properly installed, apcupsd will be started and stopped automatically by your system. Unfortunately, the details are diﬀerent for each system. Below, we give the commands for selected systems. Alternatively, there are simple stopapcupsd and startapcupsd scripts in the examples directory, or you can modify one of the scripts in the distributions directory to meet your needs.

To stop apcupsd you can do the following:

On Red Hat systems:

/etc/rc.d/init.d/apcupsd stop

On SUSE systems:

/etc/rc.d/apcupsd stop

Please see the Testing Apcupsd (see Testing Apcupsd) chapter for more details on insuring that apcupsd is running properly.

Conﬁguration Examples

A Simple USB Conﬁguration

If you have a USB UPS, and you have apcupsd version 3.10.7 or higher, the essential elements of your apcupsd.conf ﬁle should look like the following:

## apcupsd.conf v1.1 ## UPSCABLE usb UPSTYPE usb DEVICE LOCKFILE /var/lock UPSCLASS standalone UPSMODE disable

Notice that we have not speciﬁed a device. In doing so, apcupsd will try all the well known USB ports. We strongly recommend you use this (empty device address) form unless you have a good reason to do otherwise.

An alternate way of specifying the device is to specify a range of device addressess as follows:

DEVICE /dev/usb/hid/hiddev[0-15]

If you have more than one device, you may need to specify each device individually using absolute device paths. This is not, however, recommended.

DEVICE /dev/usb/hiddev0

Please use the explicit speciﬁcations of a device only if your know exactly what you are doing. In general, it is much easier to let apcupsd ﬁnd the device itself.

If you use the range speciﬁcation, you should enter /dev/usb/hiddev[0- 15] literally as shown. The “[0-15]” expression tells apcupsd to search all hiddev devices until it ﬁnds a UPS. You can restrict the search to a subset of devices by using something like “[0-4]”, but keep in mind this will limit apcupsd’s ability to locate the UPS if the kernel relocates it to a diﬀerent device node.

On Debian systems, the hiddev devices are not automatically deﬁned. As a consequence, you will need to run the make-hiddev script in the examples directory of the source.

A Simple Conﬁguration for a SmartUPS

If you have a Smart UPS using the cable supplied by APC, or you build a CUSTOM SMART cable outlined in the cables chapter, a very simple conﬁguration ﬁle would look like the following:

## apcupsd.conf v1.1 ## UPSCABLE smart UPSTYPE smartups DEVICE /dev/ttyS0 LOCKFILE /var/lock UPSCLASS standalone UPSMODE disable

Normally you would have many more conﬁguration directives to completely customize your installation, but this example shows you the minimum required.

A Simple Conﬁguration for a Simple Signaling or Dumb

If you have a simple signaling or dumb UPS such as a BackUPS, you will need to know exactly what cable you have and specify it on the UPSCABLE directive. Please see the list of UPSes versus cables in the beginning of this document for more information. The cable number is normally stamped in the plastic at one end of the cable. If you specify the wrong cable, it is very likely that at the ﬁrst power failure, your computer will be immediately shutdown. This is an unfortunate consequence of the dumb signaling mode. To avoid this, ﬁrst replace /etc/apcupsd/apccontrol with safe.apccontrol found in the examples directory, then test until everything works correctly. Once you have the correct cable, be sure to remember to reinstall the correct apccontrol ﬁle and test that your computer is correctly shutdown during a power failure.

## apcupsd.conf v1.1 ## UPSCABLE (number of cable you have) UPSTYPE dumb DEVICE /dev/ttyS0 LOCKFILE /var/lock UPSCLASS standalone UPSMODE disable

If your cable does not have low battery detection, as is the case with some older models, you will also need to deﬁne TIMEOUT nnn where you set nn to be the number of seconds on a power failure after which a shutdown is eﬀected.

Normally you would have many more conﬁguration directives to completely customize your installation, but this example shows you the minimum required.

A Simple Master Conﬁguration

You have a Smart UPS using the cable supplied by APC and you want it to act as a master for another computer, which is powered by the same UPS. A very simple conﬁguration ﬁle would look like the following:

## apcupsd.conf v1.1 ## UPSCABLE smart UPSTYPE smartups DEVICE /dev/ttyS0 LOCKFILE /var/lock UPSCLASS netmaster UPSMODE net NETTIME 10 NETPORT 6666 SLAVE slave1.mynetwork.com SLAVE slave2.mynetwork.com

Note, the main diﬀerence from the stand alone conﬁguration is that you have speciﬁed UPSCLASS netmaster and UPSMODE net. In addition, you have speciﬁed one or more slave machines. In this mode of networking, (as opposed to using the net driver as described several sections below), your master knows the presence of all the slaves. They carry on a very explicit communication, and the slaves are explicitly notiﬁed by the master of any important changes such as a shutdown.

There is a simpler form of contolling slaves using the net driver with an apcupsd NIS server. The simpler form is much easier to conﬁgure. See: see A Sample NIS Slave Conﬁguration Using the Net Driver below for details.

A Simple Slave Conﬁguration

You have a Smart UPS using the cable supplied by APC that is connected to the master machine conﬁgured above, and the master machine is running as a netmaster and has the address of your slave machine. This slave machine has no serial port connection to the UPS, but is powered by the same UPS as the master. A very simple conﬁguration ﬁle would look like the following:

## apcupsd.conf v1.1 ## UPSCABLE ether UPSTYPE smartups LOCKFILE /var/lock UPSCLASS netslave UPSMODE net NETPORT 6666 MASTER master.mynetwork.com

The main diﬀerence from the master conﬁguration is that you have speciﬁed UPSCABLE ether and UPSCLASS netslave. In addition, you have speciﬁed a single controlling master.

Please note, there are reports that you must use UPSTYPE smartups on the slave even if the master is using UPSTYPE dumb. This is apparently some bug in the new dumb driver.

In this conﬁguration, the shutdown will be initiated by the master. It is also possible to specify BATTERYLEVEL, MINUTES, and TIMEOUT conﬁguration directives in the Slave machine that will cause the slave to shutdown before the master. This can often be useful if the slave is less important than the master and you wish to reduce battery power consumption so that the master can remain up longer during a power outage.

Variation on the Master/Slave Conﬁguration

It is also possible to have a Master/Slave conﬁguration where the Slave is powered by a diﬀerent UPS (or any other power source), but is nevertheless controlled (i.e. shutdown) by the master. The setup would be identical to the Master/Slave conﬁguration ﬁles shown above. The only diﬀerence is where the slave actually receives its power. In eﬀect, apcupsd does not know or care where the power really comes from.

A Sample NIS Slave Conﬁguration Using the Net Driver

As opposed to the old master/slave mode demonstrated above, you can turn any computer into an NIS slave by conﬁguring with the NIS network driver turned on --enable-net. The diﬀerence is that the NIS server has no explicit knowledge of the slaves. The NIS server makes its information available via the net (NIS), and the NIS slaves read it. When the NIS server is going to shutdown, it makes the information available to any NIS slave that polls it, but the NIS server does not explicitly call each NIS slave as is the case in the Master/Slave networking described several sections above.

Running in this conﬁguration, you can use any computer with apcupsd running the Network Information Server (NIS) as the server. The NIS slave simply uses the NIS information to decide when to shutdown. This is a much simpler mode than the older master/slave code mentioned above.

The main apcupsd (NIS server) is connected to the UPS and has NIS turned on, but the conﬁguration is a simple standalone as in the section A Sim- ple Conﬁguration for a SmartUPS. It doesn’t matter how the UPS is connected to the computer (serial, USB, ...).

For the NIS slave computer, you will have a conﬁguration that looks some-

thing like what follows. What is important is that you get the information from an ether cable over the network and you must specify the address of a “NIS server” that is running NIS (not the Master/Slave networking described above). The NIS slave apcupsd will then poll the NIS server at the NETTIME interval you specify to obtain the status.

Here are a few words from Adam Kropelin concerning the diﬀerence between the Master/Slave networking and the NIS-based networking:

Think of the diﬀerence as push (Master/Slave) vs. pull (NIS-based). In the case of M/S, the master makes all the shutdown decisions and notiﬁes the slaves when they are to shut down or when some other interesting event happens. The slaves just do whatever the master says, whenever the master says to. On the other hand, with the NIS-based network conﬁg you basically “publish” the UPS status from one server and then your clients view that status and make their own decisions.

Personally, I like the NIS-based approach because the master knows nothing about the slaves, thus there are fewer conﬁguration ﬁles to keep in sync. I also like the ﬂexibility of allowing each slave to make its own decision on when to shut down; some of my old clunker servers take quite a long while to shut down. There are problems reported occasionally with the M/S approach, where slaves sometimes lose contact with the master or viceversa. I know improvements have been made in that code, but I still like the simplicity of using NIS.

Another thing to think about is how you feel about running a network service like NIS on your ﬁrewall. My network is set up almost identically to yours and I chose to run the apcupsd “master” on a server in the DMZ and have the ﬁrewall just be a client of it. That way I don’t have to run NIS on the ﬁrewall apcupsd instance.

## apcupsd.conf v1.1 ## UPSCABLE ether UPSTYPE net LOCKFILE /var/lock DEVICE server-network-address:3551 UPSCLASS standalone UPSMODE disable NETTIME 10

where on the DEVICE directive you replace the server-network-address with the fully qualiﬁed domain name or IP address of a machine running apcupsd with NIS enabled (and normally, but not required, connected to a

UPS). The :3551 that follows the NIS server address is the port to use. The default is 3551, but older versions of apcupsd used port 7000.

Please do not confuse this NIS server/slave mode with the old master/slave network conﬁguration that is described above. This is a master/slave setup, but much simpler (the NIS server does not know about the slaves), and any NIS server, even a slave, can act as a server to a slave that listens to it.

The NETTIME directive deﬁnes the time interval that the slave uses to poll the NIS server. If you set this too large, your slave may not see the change in state of the NIS server before the server has shutdown. Normally, you have at least 30 seconds of grace time between the time the NIS server decides to shutdown and the time it no longer responds. Your slave must poll during this interval.

This mode works principally by reading the STATFLAG record that is sent by the NIS (present in the output of apcaccess). The low 16 bits are the standard APC status ﬂag, and the upper 16 bits represent the internal state of apcupsd, so the slave can see when the power fails and know when to shutdown.

As with the Master/Slave conﬁguration, any slave run using the Net driver will shutdown when its own timers expire or when the NIS server shuts down, whichever occurs ﬁrst. This means that if you want the slave to shutdown before the server, you need only set BATTERYLEVEL, or any of the other values on the slave for a faster shutdown than the values deﬁned on the NIS server.

Testing Apcupsd

The following testing procedures apply for the most part to apcsmart UPSes, whether USB or serial. If you have a dumb voltage-signalling UPS, your testing procedures will be somewhat diﬀerent, and you should see the section on Testing Serial UPSes (see Testing Serial-Line UPSes).

Process-Status Test

After you start apcupsd, execute the following command:

ps fax

or the equivalent for your system. If you are running on Linux and using the fork()ing version of apcupsd, you should something similar to the following output.

4492 ? S 0:00 apcmain -f /etc/apcupsd/apcupsd.conf 4496 ? S 0:00 \_ apcser -f /etc/apcupsd/apcupsd.conf 4497 ? S 0:00 \_ apcnis -f /etc/apcupsd/apcupsd.conf

This indicates that apcupsd is up and running and has started the two (default) child processes. If you are running with the pthreaded version, now the default, and 2.4.x kernels, you will still see the three processes (see below). However, under 2.6.x kernels, the threads do not have independent process ids so everything will be compressed into a single ps line.

apcmain is the main program that waits until it receives a termination

signal (SIGTERM) or one of the child processes dies.

apcser is the process that manages the serial port and takes any actions

(generates events) that are necessary as a result of a change of state of the UPS.

apcnis is the Network information server process that provides EVENTS

and STATUS information over the network. This information is used by the CGI programs.

If you are running on a non-Linux system, or using pthreads on a Linux system (recommended), your output will probably not show the names of the processes and will appear more like the following:

632 ? S 0:00 /sbin/apcupsd -f /etc/apcupsd/apcupsd.conf 841 ? S 0:00 \_ /sbin/apcupsd -f /etc/apcupsd/apcupsd.conf 842 ? S 0:00 \_ /sbin/apcupsd -f /etc/apcupsd/apcupsd.conf

If you see only one instance of apcupsd running, don’t worry about it as this is normal on most non-Linux systems, and on Linux 2.6.x kernels.

If you do not ﬁnd that apcupsd is in the above list, the most likely problem is a conﬁguration ﬁle glitch. If no messages were printed, you should check your system log (normally /var/log/messages where you will ﬁnd one or messages indicating the nature of the problem.

Logging Test

Once you have established that the proper processes are running, do a tail of the system log ﬁle, normally /var/log/messages:

tail /var/log/messages

You should see output that looks similar to the following:

Dec 5 17:01:05 matou apcupsd[5917]: apcupsd 3.7.2 startup succeeded

And if you have conﬁgured the network information server, you should also see:

Dec 5 17:01:05 polymatou apcupsd[5975]: apcserver startup succeeded

These messages should also appear in the temporary ﬁle (/etc/apcupsd/apcupsd.events) if you are using the default conﬁguration ﬁle. If you have installed the RPM, they will probably be in /var/log/apcupsd.events.

apcaccess Test

This test consists of running apcaccess to see if apcupsd is properly updating its internal variables. Please note that if you are running a pthreaded version of apcupsd, which you should be since the non-pthreaded version is no longer supported, (installed from rpm or --enable-pthreads on the ./configure line), you must enable the apcupsd Network Information Server in your conﬁguration ﬁle for apcaccess to work. This is done by setting:

NETSERVER on NISPORT 3551

in your apcupsd.conf ﬁle.

To run the apcaccess test, use the following command:

apcaccess status

Depending on the type of UPS you have, you will get slightly diﬀerent output, but an example For a Smart-UPS is as follows:

APC : 001,048,1088 DATE : Fri Dec 03 16:49:24 EST 1999 HOSTNAME : daughter RELEASE : 3.7.2 CABLE : APC Cable 940-0024C MODEL : APC Smart-UPS 600 UPSMODE : Stand Alone UPSNAME : SU600 LINEV : 122.1 Volts MAXLINEV : 123.3 Volts MINLINEV : 122.1 Volts LINEFREQ : 60.0 Hz OUTPUTV : 122.1 Volts LOADPCT : 32.7 Percent Load Capacity BATTV : 26.6 Volts BCHARGE : 095.0 Percent MBATTCHG : 15 Percent TIMELEFT : 19.0 Minutes MINTIMEL : 3 Minutes SENSE : Medium DWAKE : 000 Seconds DSHUTD : 020 Seconds LOTRANS : 106.0 Volts HITRANS : 129.0 Volts RETPCT : 010.0 Percent STATFLAG : 0x08 Status Flag STATUS : ONLINE ITEMP : 34.6 C Internal ALARMDEL : Low Battery LASTXFER : Unacceptable Utility Voltage Change SELFTEST : NO STESTI : 336 DLOWBATT : 05 Minutes DIPSW : 0x00 Dip Switch REG1 : N/A REG2 : N/A REG3 : 0x00 Register 3 MANDATE : 03/30/95 SERIALNO : 13035861 BATTDATE : 05/05/98

NOMOUTV : 115.0 NOMBATTV : 24.0 HUMIDITY : N/A AMBTEMP : N/A EXTBATTS : N/A BADBATTS : N/A FIRMWARE : N/A APCMODEL : 6TD END APC : Fri Dec 03 16:49:25 EST 1999

For a simple signaling or dumb UPS such as BackUPS, your output will be very minimal as follows:

APC : 001,012,0319 DATE : Mon Feb 18 09:11:50 CST 2002 RELEASE : 3.8.5 UPSNAME : UPS_IDEN CABLE : APC Cable 940-0128A MODEL : BackUPS UPSMODE : Stand Alone STARTTIME: Mon Feb 18 09:11:45 CST 2002 LINEFAIL : OK BATTSTAT : OK STATFLAG : 0x008 Status Flag END APC : Mon Feb 18 09:15:01 CST 2002

If you see the above output, it is a good sign that apcupsd is working. Assuming that the output looks reasonable, check the following variables:

A very disturbing tendance is for some of the newer (Mar 2004) RS and ES UPSes to have no Voltage information. This is annoying bug not serious. On the other hand, some of those UPSes now have no battery charge information (BCHARGE). If BCHARGE is zero in your listing and you are running a Smart or a USB UPS, then you will have to set the BATTERYLEVEL directive in your apcupsd.conf ﬁle to -1.

LINEV This is the line voltage and it should be a value that is appropriate

for your equipment. In the USA, it is typically about 120 Volts while in Europe, it is about 220 Volts.

BATTV Unless you have additional battery packs, this should be near 24

Volts plus or minus 5 Volts.

STATUS This is the status of the UPS and it should normally be ON-

LINE.

If you see a message to the eﬀect of:

attach_shmarea: shared memory version mismatch (or UPS not yet ready to report)

or if all the displayed values are zero, you have not waited long enough. Wait a bit longer and then re-execute the apcaccess status command.

If you see a message to the eﬀect of:

APCACCESS FATAL ERROR in apcaccess.c at line 336 tcp_open: cannot connect to server localhost on port 3551.

It means that you have probably not enabled the Network Information Server in your conﬁguration ﬁle for apcaccess to work. This is done by setting:

NETSERVER on NISPORT 3551

in your apcupsd.conf ﬁle.

Communications Test

At this point, you should ensure that apcupsd is handling the connection to the UPS correctly. This test assumes you have a UPS that speaks apcsmart protocol, over either USB or a serial port. If you have an old-style voltagesignaling UPS, please skip to the next section (Simulated Power Fail Test).

When apcupsd detects a problem, it generates an EVENT, which consists of sending a message to the system log then invoking the apccontrol script (normally in /etc/acpupsd/apccontrol) to handle the event.

In order to create an event, remove the serial port plug from the back of your computer or from the back of the UPS. Within 6 seconds, apcupsd should detect the lack of serial port communications and broadcast a wall message indicating that the serial port communications was lost:

Warning communications lost with UPS lost.

At the same time, it sends the same message to the system log and to the temporary EVENTS ﬁle (/etc/apcupsd/apcupsd.events).

Plug the serial port plug back into your computer, and within about 12 seconds, apcupsd should reestablish communications and broadcast and log the following message:

Communications with UPS restored.

If these messages are logged but not broadcast, either you have your mesg permission set to no (see man wall or man mesg), or there is a problem with apccontrol. If you are running a window manager such as GNOME and don’t have a console window open, you may not receive the wall messages. However, you should ﬁnd them in your system log ﬁle (normally /var/log/messages and in the temporary EVENTS ﬁle, /etc/apcupsd/apcupsd.events. For example, to observe these events in the temporary EVENTS ﬁle, you might do a

tail -f /etc/apcupsd/apcupsd.events

Note, if you have installed from the RPM, the proper events ﬁle may be /var/log/apcupsd.events. You can ﬁnd the actual ﬁlename by checking your apcupsd.conf ﬁle.

before running the test.

If you do not observe these messages, you should correct this problem before proceeding with additional tests.

Simulated Power Fail Test

At this point, you should verify that in the event of a power fail apcupsd properly calls apccontrol. This test is appropriate for all models of UPSes (smart or dumb).

To avoid the possibility that apcupsd might shut down your system, locate where apccontrol resides on your system (normally, /etc/apcupsd/apccontrol. Move this script to another location e.g. apccontrol.save and replace it with the script found in examples/safe.apccontrol. When that is done, ensure that your UPS battery is fully charged and that you have at least 5 minutes of remaining runtime on the batteries. This can be done by examining the values of the BATTCHG and TIMELEFT variables in the printout of apcaccess status.

Athough this should not be necessary, as an extra precaution, you can shutdown your machine, remove the plug from the UPS you are testing, and plug your machine into another UPS or directly into the wall. Doing so, will ensure that the UPS doesn’t cut the power to your machine at a bad time. Remember at the end of the testing to plug your machine back into the UPS.

You can also minimize the risk from an unexpected shutdown by using a journaling ﬁlesystem such as Linux’s EXT3. All modern disk drives park themselves safely when they power down, rather than ploughing up oxide on your disk’s recording surface. Thus, unexpected power less has to hit very narrow timing windows in order to trash an EXT3 transaction.

To begin the test, pull the power plug from the UPS. The ﬁrst time that you do this, psychologically it won’t be easy, but after you have pulled the plug a few times, you may even come to enjoy it. If all goes well, apcupsd should detect the power failure and print several warning messages. The ﬁrst should appear after 5 to 6 seconds and read:

Warning power loss detected.

Then generally 6 seconds later, apcupsd is sure that it isn’t a transient eﬀect, so it sends:

Power failure. Running on UPS batteries.

After a few more seconds (total around 15 seconds), plug the power cord back in and ensure that apcupsd is aware that the power has returned. It should print:

Power has returned...

If you do not observe the above messages, please correct the situation before proceeding. The most likely cause of problems are:

• apcupsd doesn’t recognize the power failure because the conﬁguration directives are not correct. E.g. wrong cable.

• The ﬁle /etc/apcupsd/apccontrol doesn’t exist or is not marked as executable.

At this point, we recommend that you do a simulated power down of your system. If you are adventuresome or have been through this before, skip to the next section in this manual and do the real power fail shutdown. If you continue with the simulated power down and if all goes well, apcupsd will go through all the motions without actually shutting down the system. Continue using the safe apccontrol that you installed. Edit the conﬁguration ﬁle apcupsd and change the value of TIMEOUT from 0 to something like

30. Doing so will cause apcupsd to attempt to shutdown the system 30 seconds after it detects a power failure. Once this change has been made, you must stop and restart apcupsd for the new conﬁguration value to take eﬀect.

Once again, pull the power plug, and if all goes as expected, apcupsd should attempt to shutdown the system about 30 seconds after it detects the power failure. All the messages should be displayed by wall or by the tail -f command. The precise message is determined by what is printed in /etc/apcupsd/apccontrol for the doshutdown event. Though it varies from system to system, it will generally be something like:

Beginning Shutdown Sequence

When apcupsd this message prints, reconnect the power. apcupsd should detect that the power has been restored and attempt to cancel the shutdown.

IMPORTANT after this test, please replace the changed apccontrol and apcupsd.conf with the original ﬁles.

System Shutdown Test

This is an intermediate test that you can do, for all UPS models before doing the Full Power Down Test. First modify the /etc/apcupsd/apccontrol ﬁle so that in the killpower) case, the line that re-executes apcupsd with the --killpower option is commented out. The original line probably looks something like:

${APCUPSD} --killpower

when it is commented out, it looks like:

#${APCUPSD}--killpower

Now when you pull the power plug, and either the timer expires or the batteries are exhausted (see the next section for more details), the system should be fully shutdown.

After performing this test, please be sure to restore /etc/apcupsd/apccontrol to its previous state.

Full Power Down Test

To complete the testing, you should do a power fail shutdown of your system. This test is applicable to all UPS models. Please do a backup of your system or take other precautions before attempting this to avoid the possibility of lost data due to a problem (I have been through this at least 10 times and never once had problems, but we all know that someday something will go wrong).

Before proceeding, please ensure that your halt script or the equivalent has been properly updated by the install process to contain the logic to call apcupsd --killpower when it detects a power failure situation (the presence of a /etc/powerfail ﬁle). See the Building and Installing apcupsd of this manual, or the README ﬁles for additional details about the halt modiﬁcations necessary.

When you are ready to do the test, either simply pull the plug and wait for the batteries to become exhausted, or set the TIMEOUT conﬁguration directive to something like 60 so that the system will shutdown before the batteries are exhausted. We recommend doing the full shutdown without using TIMEOUT to correctly simulate a real power failure, but the choice is yours (I did it once here, but now use TIMEOUT 30).

If all goes well, your system should be shutdown before the batteries are completely exhausted and the UPS should be powered oﬀ by apcupsd. Please be aware that if you do the full power down, you must ensure that your UPS is totally powered oﬀ. Otherwise, it may have been given the command to power oﬀ, but due to a long grace period it is still waiting. If you were to reboot your computer during the grace period, the UPS could then suddenly turn oﬀ the power (this happened to me). To avoid this problem, always wait for your UPS to power itself oﬀ, or power if oﬀ manually before restarting your computer. On my system, the UPS is conﬁgured as at the factory to have a 180 second grace period before shutting oﬀ the power. During this type of testing, 180 seconds seems like an eternity, so please take care to either wait or manually power oﬀ your UPS. To determine what grace period is programmed into your UPS EEPROM, run apcaccess eprom and

look at the “Shutdown grace delay”.

Shutdown Sequence

If you experienced so problems with the above testing procedures, or if you are porting apcupsd to another system, or you are simply curious, you may want to know exactly what is going on during the shutdown process. If so, please see the Shutdown Sequence (see Shutdown Sequence <1>) section of this manual.

apctest

apctest is a program that allows you to talk directly to your UPS and run certain low-level tests, display all know values from the UPS’s EEPROM, perform a battery runtime calibration, program the EEPROM (serial connection only), and enter in TTY mode with the UPS. Here we describe how to use it for a USB or apcsmart UPS; see Using apctest on Serial-Line UPSses for a description of how to use it with a voltage-signalling UPS.

Shutdown apcupsd if it is running. Make sure your

/etc/apcupsd/apcupsd.conf ﬁle has UPSTYPE smart and UPSCABLE has one of the smart cables that are supported.

Normally apctest will have been built but not installed, so you must execute it from the <apcupsd-source>/src directory. You can explicitly build it on Unix with:

cd <apcupsd-source-directory> make apctest ./apctest

or on Windows systems with:

make apctestwin32 ./apctest

It will read your installed apcupsd.conf conﬁguration (so it knows where to ﬁnd the UPS) and then it will present you with the following output:

2003-07-07 11:19:21 apctest 3.10.6 (07 July 2003) redhat Checking configuration ... Attached to driver: apcsmart sharenet.type = DISABLE cable.type = CUSTOM_SMART

You are using a SMART cable type, so I’m entering SMART test mode mode.type = SMART Setting up serial port ... Creating serial port lock file ... Hello, this is the apcupsd Cable Test program. This part of apctest is for testing Smart UPSes. Please select the function you want to perform.

1) Query the UPS for all known values

2) Perform a Battery Runtime Calibration

3) Abort Battery Calibration

4) Monitor Battery Calibration progress

5) Program EEPROM

6) Enter TTY mode communicating with UPS

7) Quit

Select function number: 1

Item 1 will probe the UPS for all values known to apcupsd and present them in rather raw format. This output can be useful for providing technical support if you are having problems with your UPS.

Item 2 will perform a Battery Runtime Calibration. This test will only be performed if your battery is 100% charged. Running the test will cause the batteries to be discharged to approximately 30% of capacity. The exact number depends on the UPS model. In any case, apctest will abort the test if it detects that the battery charge is 20% or less.

The advantage of doing this test is that the UPS will be able to recalibrate the remaining runtime counter that it maintains in its ﬁrmware. As your batteries age, they tend to hold less of a charge, so the runtime calibration may not be accurate after several years.

We recommend that perform a Battery Calibration about once a year. You should not perform this calibration too often since discharging the batteries tends to shorten their lifespan.

Item 3 can be used to abort a Battery Calibration in progress, if you some how became disconnected.

Item 4 can be used to restart the monitoring of a Battery Calibration if you

should some how become disconnected during the test.

Item 5 is used to program the EEPROM. Please see the Conﬁguration Directives Used to Set the UPS EPROM chapter of this manual for the details.

Item 6 will initiate a direct communication between your terminal and the UPS at which point, you can enter raw UPS commands. Please be aware that you should be careful what commands you enter because you can cause your UPS to suddenly shutdown, or you can modify the EEPROM in a way to disable your UPS. The details of the raw Smart mode UPS commands can be found in the UPS Bible (see APC smart protocol) chapter of this manual.

Item 7 will terminate apctest.

Troubleshooting Your Installation

Known Problems with USB UPSes

Some Cheaper Models Do Not Have Battery Charge:

Unfortunately, some cheaper USB models do not seem to report BCHARGE in the apcaccess output listing, which means with a standard conf ﬁle, your system will be immediately shutdown. To correct this, set the BATTERYLEVEL directive in your apcupsd.conf ﬁle to -1.

Some of these cheaper USB UPSes also do not report the Voltage. This is annoying but does not cause the unit to malfunction.

Reconnection does not clean up the lockﬁle:

If either you disconnect the UPS or it disconnects because of some electrical problem, it will most certainly reconnect with a diﬀerent device number. Apcupsd will detect this and reconnect properly. However, apcupsd does not release the old device (USB port) lock ﬁle and create a new one. This is not too serious.

Power Oﬀ (killpower) of UPS Does Not Work:

Currently (as of 3.10.6) the code to power oﬀ the UPS works only if you have a Linux kernel version 2.4.22 or greater, or you have applied the patches in the examples directory to your kernel.

apcupsd Cannot Reconnect After a Reboot:

If apcupsd does not connect to the USB port when you reboot, it is probably the appropriate kernel modules are not getting loaded correctly.

You can check this by bringing up your system, ﬁddling around until you get apcupsd to work with the UPS, then doing cat /proc/modules andnd save the output some place. Then reboot your computer and before you do anything else, do the cat /proc/modules again. Most likely you will ﬁnd some of the usb modules are missing in the second listing.

There are two solutions:

• Ensure that you have the hotplug program loaded. It should ﬁx the problem. This is a bit of magic, so we are not exactly sure how it works. The rpm I (Kern) have loaded is: hotplug-2001

02 14-15

You might want to read the man page on hotplug, and it might be necessary to cp /etc/hotplug/usb.rc /etc/init.d/hotplug to get it fully working.

• You can explicitly force the appropriate usb modules to be loaded by adding:

/sbin/modprobe <missing-module-name>

in the /etc/rc.d/init.d/apcupsd script just after the start) case (at about line 17). This will force the modules to be loaded before apcupsd is invoked.

Monitoring and Tuning your UPS

After you have veriﬁed that your UPS is working correctly, you will probably want to query the state of its health occasionally. The tools apcupsd gives

you to do this include one command-line utility (apcaccess) and a GUI you can use through a Web browser. You can also use apctest to tune some parameters of the UPS itself.

apcaccess

apcaccess is a program (normally found in /sbin/apcaccess) that permits you to print out the complete status of your UPS. Although there are a number of command line arguments (eprom, reconﬁg, status, slave, shutdown), all except eprom and status are under development and hence do not work reliably.

If you have built apcupsd with pthreads enabled (default), apcaccess will use the Network Information Server to obtain the necessary information for the status and eeprom commands. This is because in the pthreaded version, there is no IPC shared memory. In this case (pthreads enabled), you can specify a second optional argument to apcaccess in the form of host:port, where the :port is optional. The default is localhost:3551. Please note that in versions prior to 3.10.6, the default NIS port was 7000, so if you are mixing versions, you will need to take a lot of care to ensure that all components are using the same port.

To enable the apcupsd Network Information Server, which is normally the default, you set:

NETSERVER on NISPORT 3551

in your apcupsd.conf ﬁle.

apcaccess status:

As mentioned above, the full form of the command is:

apcaccess status localhost:3551

where only apcaccess status should normally be needed. localhost may be replaced by any machine name, fully qualiﬁed domain name, or IP address,

which means that apcaccess can access any UPS on the network running the Network Information Server.

The status command line option of apcaccess will produce a full printout of all the STATUS variables used by apcupsd. This can be very helpful for checking the condition of your UPS and to know whether or not apcupsd is properly connected to it. For a complete description of the variables and their meanings, please read the Status Format (see apcupsd Status Logging) section of the Technical Reference.

Please note that if you invoke apcaccess within the ﬁrst 30 seconds of launching apcupsd, you will likely get an error message such as:

APCACCESS FATAL ERROR in apcipc.c at line 325 attach_shmarea: shared memory version mismatch

This is because apcupsd is still in the process of initializing the shared memory segment used to communicate between the two processes. There is also a small window of time after which the memory segment is properly initialized but before the UPS has been completely polled. If you invoke apcaccess during this period, you will get the STATUS output, but with many of the values zero. The solution is to wait at least 30 seconds after starting apcupsd before launching apcaccess.

To invoke apcaccess, enter:

apcaccess status

For a SmartUPS 1000 apcaccess will emit the following output:

DATE : Fri Dec 03 12:34:26 CET 1999 HOSTNAME : matou RELEASE : 3.7.0-beta-1 CABLE : Custom Cable Smart MODEL : SMART-UPS 1000 UPSMODE : Stand Alone UPSNAME : UPS_IDEN LINEV : 232.7 Volts MAXLINEV : 236.6 Volts MINLINEV : 231.4 Volts LINEFREQ : 50.0 Hz OUTPUTV : 232.7 Volts

LOADPCT : 11.4 Percent Load Capacity BATTV : 27.7 Volts BCHARGE : 100.0 Percent MBATTCHG : 5 Percent TIMELEFT : 112.0 Minutes MINTIMEL : 3 Minutes SENSE : Low DWAKE : 060 Seconds DSHUTD : 180 Seconds LOTRANS : 204.0 Volts HITRANS : 253.0 Volts RETPCT : 050.0 Percent STATFLAG : 0x08 Status Flag STATUS : ONLINE ITEMP : 29.2 C Internal ALARMDEL : Low Battery LASTXFER : U command or Self Test SELFTEST : NO STESTI : 336 DLOWBATT : 02 Minutes DIPSW : 0x00 Dip Switch REG1 : 0x00 Register 1 REG2 : 0x00 Register 2 REG3 : 0x00 Register 3 MANDATE : 01/05/99 SERIALNO : GS9902009459 BATTDATE : 01/05/99 NOMOUTV : 230.0 NOMBATTV : 24.0 HUMIDITY : N/A AMBTEMP : N/A EXTBATTS : 0 BADBATTS : N/A FIRMWARE : 60.11.I APCMODEL : IWI END APC : Fri Dec 03 12:34:33 CET 1999

For the various smaller, cheaper APC USB UPSes, such as the CS, ES, ..., you will get much of the information that is presented above, but not all of it. For example, you will not get MAXLINEV, MINLINEV, LINEFREQ, ... and in particular, the LOADPCT will be zero when you are running on mains. LOADPCT will display when the UPS is on batteries. You must remember that the non-SmartUPSes are much simpler (and less expensive) and therefore produce less information.

apcaccess eprom:

The eprom command line option for apcaccess allows you to examine the current values of your UPS’ EPROM as well as to know the permit-

ted values that can be set in the EPROM. For information about changing these values, see the section on tuning EEPROM parameters (see Conﬁguring Your EEPROM).

A typical output from apcaccess eprom is:

Valid EPROM values for the SMART-UPS 1000

Config Current Permitted Description Directive Value Values =================================================================== Upper transfer voltage HITRANSFER 253 253 264 271 280 Lower transfer voltage LOTRANSFER 208 196 188 208 204 Return threshold RETURNCHARGE 15 00 15 50 90 Output voltage on batts OUTPUTVOLTS 230 230 240 220 225 Sensitivity SENSITIVITY H H M L L Low battery warning LOWBATT 2 02 05 07 10 Shutdown grace delay SLEEP 180 020 180 300 600 Alarm delay BEEPSTATE T 0 T L N Wakeup delay WAKEUP 60 000 060 180 300 Self test interval SELFTEST 336 336 168 ON OFF

Apcupsd Notiﬁcation and Events

When a major event is generated within apcupsd, control is passed to the script apccontrol normally found in /etc/apcupsd/apccontrol. The event name, and a number of other important parameters are passed to the script.

The major function of the apccontrol script is to performa a shutdown of the system (as well as the killpower operation). In addition, another major task for this script is to notify you by email when certain events such as powerfail occur.

Since apccontrol is a script, you can customize it to your own needs using any text editor. To do so, you must have a minimal knowledge of Unix shell programming. In addition, another feature is that you can write your own scripts that will be automatically called by apccontrol before any of its own code is executed. Details of the events and how to program them are contained in the Advanced topics section entitled Customizing Event Handling (see Customizing Event Handling).

hid-ups and USB Speciﬁc Information

The UPS has an internal set of timers and remaining capacity counters, which it uses to determine when to shutdown. These are in addition to the apcupsd counters BATTERYLEVEL and MINUTES. As a consequence, apcupsd will shutdown on the ﬁrst limit that triggers (either an apcupsd limit, or a UPS limit). The UPS internal counter equivalent to BATTERYLEVEL can be found in the hid-ups report as RemainingCapacityLimit, which is typically factory set to 10 percent. In addition, the Low Battery signal is normally given by the UPS when less than 2 minutes of run time remain.

apcupsd Network Monitoring (CGI) Programs

With this release, there are ﬁve CGI programs (multimon.cgi, multimoncss.cgi, upsstats.cgi, upsfstats.cgi, and upsimage.cgi). To have them properly installed, you must run the ./configure command with

--enable-cgi and you should specify an installation directory with

--with-cgi-bin= or load them manually. To install the Cascading Style

Sheet, which is used by multimoncss.cgi, you must use the --with-css-dir= option. The default directory for installation of the CGI programs is /etc/apcupsd, which is not really where you want them if you are going to use them. Normally, they should go in the cgi-bin of your Web server.

Once built and loaded, they will give you the status of your UPS or UPSes over the network.

Normally only multimon.cgi or multimoncss.cgiis directly invoked by the user. However, it is possible to directly invoke upsstats.cgi and upsfstats.cgi. upsimage.cgi should never be directly invoked as it is used by upsstats.cgi to produce the bar charts.

Setting up and Testing the CGI Programs

Network Information Server (NIS):

Before using multimon and the other CGI programs, ﬁrst ensure that apcupsd is conﬁgured to run the Network Information Server. This is done by setting NETSERVER on in /etc/apcupsd/apcupsd.conf. This switch is on by default. If you are unsure of its state, see the section at the end of this chapter concerning the Client test program.

Next you must edit the hosts ﬁle /etc/apcupsd/hosts.conf and at the end, add the name of the hosts you want to monitor and a label string for them. Kern Sibbald uses multimon.conf unmodiﬁed from what is on the source distribution. However, he has modiﬁed the hosts.conf ﬁle to contain the following three lines:

MONITOR matou "Server" MONITOR polymatou "Backup server" MONITOR deuter "Disk server"

matou, polymatou, and deuter are the network names of the three machines currently running apcupsd. Please note that the network names may either be IP addresses or fully qualiﬁed domain names. The network name (or IP address) may optionally be followed by :<port>, where the port is the NIS port address you wish to use. This is useful if you are running multiple copies of apcupsd on the same system or if you are running in a mixed vendor environment where the NIS port assignments diﬀer. An example could be the following:

MONITOR matou "Server" MONITOR polymatou "Backup server" MONITOR deuter "Disk server" MONITOR polymatou:7001 "APC USB UPS"

where the USB copy of apcupsd has been conﬁgured to use port 7001 (with --with-nis-port=7001 on the ./configure or by modifying apcupsd.conf). Note, the default NIS port is 3551 on most platforms.

To test multimon.cgi, you can execute it as non-root directly from the source cgi build directory. To do so, enter at a shell prompt:

./multimon.cgi

If everything is set up correctly, it will print a bunch of HTML with the values of the machines that you have put in the hosts.conf ﬁle. It should look something like the following (note, only a small portion of the output is reproduced here):

Content-type: text/html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"

"http://www.w3.org/TR/REC-html40/loose.dtd"> <HTML> <HEAD><TITLE>Multimon: UPS Status Page</TITLE></HEAD> <BODY BGCOLOR="#FFFFFF"> <TABLE BGCOLOR="#50A0A0" ALIGN=CENTER> <TR><TD> <TABLE CELLPADDING=5> <TR> <TH COLSPAN=10 BGCOLOR="#60B0B0"> <FONT SIZE="+2">APCUPSD UPS Network Monitor</FONT> <BR>Sun Jan 16 12:07:27 CET 2000</TH> </TR> <TR BGCOLOR="#60B0B0"> <TH COLSPAN=1>System</TH> <TH COLSPAN=1>Model</TH> <TH COLSPAN=1>Status</TH> ...

If you do not get similar output, check the permissions of the /etc/apcupsd directory and of those of /etc/apcupsd/hosts.conf to ensure that your web server can access it. At many sites such as mine, the Apache server is not running as root, so you must be careful to ensure that that /etc/apcupsd/hosts.conf and /etc/apcupsd/multimon.conf are world readable.

To invoke multimon in your Web browser, enter:

http://<your-site>/cgi-bin/multimon.cgi

You should get something similar to the screen shot shown below.

If you wish additional control over the colors, type faces, and sizes of the multimon output, you might wish to use multimoncss.cgi in place of multimon. In this case, you simply edit the multimon.css ﬁle to specify the styles you prefer. There are several sample Style Sheet ﬁles in the cgi subdirectory of the source tree.

To see a working example of the these programs, visit http://www.apcupsd.com/cgi-bin/multimon.cgi or http://www.apcupsd.com/cgi-bin/multimoncss.cgi

multimon.cgi:

This program monitors multiple UPSes at the same time. A typical output of multimon.cgi as displayed in your Web browser might look like the following:

The machines monitored as well as the values and their column headings are all conﬁgurable (see /etc/apcupsd/hosts.conf and /etc/apcupsd/multimon.conf)

upsstats.cgi:

By clicking on the system name in the multimon.cgi display, you will invoke upsstats.cgi for the speciﬁed system, which will produce a bar graph display of three of the monitored values. For example,

You can display diﬀerent bar graphs by selecting diﬀerent variables from the drop down menus at the top of each of the three bar graphs.

As with multimon, if you have your local host conﬁgured in the /etc/apcupsd/hosts.conf ﬁle, you can execute it from a Unix shell from the source cgi directory as follows:

./upsstats.cgi:

As with multimon, quite a few lines of html should then be displayed.

upsfstatus.cgi:

If you would like to see all of the STATUS variables available over the network, click on the Data ﬁeld of the desired system, and your browser will display something like the following:

APC : 001,048,1109 DATE : Thu Dec 02 17:27:21 CET 1999 HOSTNAME : matou.sibbald.com RELEASE : 3.7.0-beta-1 CABLE : Custom Cable Smart MODEL : SMART-UPS 1000 UPSMODE : Stand Alone UPSNAME : UPS_IDEN LINEV : 223.6 Volts MAXLINEV : 224.9 Volts MINLINEV : 222.3 Volts LINEFREQ : 50.0 Hz OUTPUTV : 223.6 Volts LOADPCT : 6.2 Percent Load Capacity BATTV : 27.9 Volts BCHARGE : 100.0 Percent MBATTCHG : 5 Percent TIMELEFT : 167.0 Minutes MINTIMEL : 3 Minutes SENSE : High DWAKE : 060 Seconds DSHUTD : 020 Seconds LOTRANS : 196.0 Volts HITRANS : 253.0 Volts RETPCT : 050.0 Percent STATFLAG : 0x08 Status Flag STATUS : ONLINE ITEMP : 35.1 C Internal ALARMDEL : Low Battery

LASTXFER : U command or Self Test SELFTEST : NO STESTI : 336 DLOWBATT : 02 Minutes DIPSW : 0x00 Dip Switch REG1 : 0x00 Register 1 REG2 : 0x00 Register 2 REG3 : 0x00 Register 3 MANDATE : 01/11/99 SERIALNO : GS9903001147 BATTDATE : 01/11/99 NOMOUTV : 230.0 NOMBATTV : 24.0 HUMIDITY : N/A AMBTEMP : N/A EXTBATTS : 0 BADBATTS : N/A FIRMWARE : 60.11.I APCMODEL : IWI END APC : Thu Dec 02 17:27:25 CET 1999

You should get pretty much the same output mixed in with html if you execute upsfstats.cgi directly from a Unix shell in the cgi subdirectory as explained above for upsstats.cgi and multimon.cgi.

Working Example:

To see a working example of the above programs, visit http://www.apcupsd.com/cgi-bin/multimon.cgi.

Client Test Program:

When your Network Information Server is up and running, you can test it using a simple program before attempting to access the server via your Web server. The test program is called client.c and can be found in the examples subdirectory of the source distribution. To build the program, when in the examples directory, use something like the following:

cc client.c ../lib/libapc.a -o client

Then execute it:

./client <host>[:<port>] [<command>]

Where host is the name of the host or the IP address of the host running the Network Information Server. The default is the local host. You may optionally specify a port address separated from the host name with a colon. You may also optionally specify a single command to be executed. If you specify a command, that command will be executed and the client program will exit. This is a very simple and useful way of pulling the status or events data into another program such as Perl.

If no error messages are printed, it has most likely established contact with your server. Anything that you type as standard input will be passed to the server, and anything the server sends back will be printed to standard output. There are currently two commands recognized by the server: events and status. Hence the following commands:

./client status events xyz ^D

should produce the status listing (the same as produced by apcaccess status), followed by the list of the last 10 events (in response to the events

command), and ﬁnally Invalid command in response to the xyz input, which is not a valid command. The control-D terminates the client program.

The purpose of this program is to show you how to write your own program that can determine the status of apcupsd and act any way you want (e.g. send you email messages on certain events like line voltage boost, ...).

A Tip from Carl Erhorn for Sun Systems:

It is possible to run the CGI code to monitor your UPS using the answerbook HTTP server that runs on Solaris. As long as your server has the Answerbook2 web server installed and running, you can insert the cgi scripts into the cgi directory of the web server, and access the cgi using something like:

http://hostname:8888/cgi/multimon.cgi

Credits:

Many thanks go to Russell Kroll <rkroll at exploits.org> who wrote the CGI programs to work with his UPS Monitoring system named Network UPS Tools (NUT). Thanks also to Jonathan Benson <jbenson at technologist.com> for initially adapting the upsstatus.cgi program to work with apcupsd.

We have enhanced the bar graph program and hope that our changes can be useful to the original author in his project.

Security Issues:

• apcupsd runs as root.

• If you have NETSERVER ON in your apcupsd.conf ﬁle (which is the

deault), be aware that anyone on the network can read the status of your UPS. This may or may not pose a problem. If you don’t consider this information privileged, as is the case for me, there is little risk. In addition, if you have a ﬁrewall between your servers and the Internet, crackers will not have access to your UPS information. Additionally, you can restrict who can access your apcupsd server by using inted to run the sservice and using access control lists with a TCP wrapper or by conﬁguring TCP wrappers in apcupsd (see below for TCP Wrapper details).

• If you are running master/slave networking with a single UPS powering multiple machines, be aware that it is possible for someone to simulate the master and send a shutdown request to your slaves. The slaves do check that the network address of the machine claiming to be the master is that same as the address returned by DNS corresponding to the name of the master as speciﬁed in your conﬁguration ﬁle.

Wrappers

As of apcupsd version 3.8.2, TCP Wrappers are implemented if you turn them on when conﬁguring (./configure --with-libwrap). With this code enabled, you may control who may access your apcupsd via TCP connections (the Network Information Server, and the Master/Slave code). This control is done by modifying the ﬁle: /etc/hosts.allow. This code is implemented but untested. If you use it, please send us some feedback.

Conﬁguring Your EEPROM

If you have a SmartUPS, there are depending on the UPS at least 12 diﬀerent values stored in the EEPROM that determine how the UPS reacts to various conditions such as high line voltage, low line voltage, power down grace periods, etc.

In general, for the moment, we do not recommend that you change your EEPROM values unless absolutely necessary. There have been several reported cases of problems setting the Low Transfer Voltage. Consequently, if at all possible, do not attempt to change this value.

If despite these warnings, you must change your EEPROM, we recommend connecting your UPS to a Windows or NT machine running PowerChute and making the changes.

apcupsd No Longer Conﬁgures EEPROM:

Unlike version 3.8.6, apcupsd version 3.10.x no longer has code to program the EEPROM. Instead we have implemented interactive EEPROM modiﬁcation code in the apctest program. EEPROM programming must be done with apcupsd stopped so that apctest can access the UPS. In addition, EEPROM programming is currently implemented only for UPSes using the Smart protocol running in serial mode. Perhaps at a later time when the appropriate kernel modiﬁcations are standard, we will extend EEPROM programming to USB models.

Before changing your EEPROM, you should make a printed copy of the current state of your UPS before any EEPROM changes so that you can check the changes that you have made. Do so by printing a copy of the output from apcaccess status and also print a copy of the output from apcaccess eprom.

Once this is done, choose which values of the EEPROM you want to change. Typical output from apcaccess should look like the following:

apcaccess eeprom

Valid EPROM values for the SMART-UPS 1000

Config Current Permitted Description Directive Value Values ================================================================ Upper transfer voltage HITRANSFER 253 253 264 271 280

Lower transfer voltage LOTRANSFER 196 196 188 208 204 Return threshold RETURNCHARGE 0 00 15 50 90 Output voltage on batts OUTPUTVOLTS 230 230 240 220 225 Sensitivity SENSITIVITY H H M L L Low battery warning LOWBATT 2 02 05 07 10 Shutdown grace delay SLEEP 20 020 180 300 600 Alarm delay BEEPSTATE 0 0 T L N Wakeup delay WAKEUP 0 000 060 180 300 Self test interval SELFTEST 336 336 168 ON OFF

where the Current Value will depend on how your UPS is conﬁgured, and the Permitted Values will depend on what UPS model you have.

Using apctest to Conﬁgure Your EEPROM:

To make the EEPROM changes with apctest you must ﬁrst stop the apcupsd daemon

apctest is not installed during the installation process, so to use it you will need to do the following after having built apcupsd:

cd <apcupsd-source>/src su <root-password> ./apctest

At that point, you should get output similar to the following:

2003-07-07 11:19:21 apctest 3.10.6 (07 July 2003) redhat Checking configuration ... Attached to driver: apcsmart sharenet.type = DISABLE cable.type = CUSTOM_SMART

1) Query the UPS for all known values

2) Perform a Battery Runtime Calibration

3) Abort Battery Calibration

4) Monitor Battery Calibration progress

5) Program EEPROM

6) Enter TTY mode communicating with UPS

7) Quit

Select function number:

You might want to run option 1) just to ensure that apctest is properly talking to your UPS. It will produce quite about 70 lines of output.

To program the EEPROM, select option 5), and you will get the EEPROM menu as follows:

This is the EEPROM programming section of apctest. Please select the function you want to perform.

1) Print EEPROM values

2) Change Battery date

3) Change UPS name

4) Change sensitivity

5) Change alarm delay

6) Change low battery warning delay

7) Change wakeup delay

8) Change shutdown delay

9) Change low transfer voltage

10) Change high transfer voltage

11) Change battery return threshold percent

12) Change output voltage when on batteries

13) Change the self test interval

14) Set EEPROM with conf file values

15) Quit

Select function number:

If you wish to use the old pre-3.10.x method of EEPROM programming with values speciﬁed in the apcupsd.conf ﬁle, select option 14). However, we recommend that you start with item 1) to see what EEPROM values apctest ﬁnds. This command can take a few minutes to run, so be patient. The values printed should be the same as what you got using apcaccess, but in addition, the EEPROM battery date and UPS Name should be displayed. For example:

Select function number: 1

Doing prep_device() ...

Valid EEPROM values for the SMART-UPS 1000

Config Current Permitted Description Directive Value Values =================================================================== Upper transfer voltage HITRANSFER 253 253 264 271 280 Lower transfer voltage LOTRANSFER 196 196 188 208 204 Return threshold RETURNCHARGE 0 00 15 50 90 Output voltage on batts OUTPUTVOLTS 230 230 240 220 225 Sensitivity SENSITIVITY H H M L L Low battery warning LOWBATT 2 02 05 07 10 Shutdown grace delay SLEEP 20 020 180 300 600 Alarm delay BEEPSTATE 0 0 T L N Wakeup delay WAKEUP 0 000 060 180 300 Self test interval SELFTEST 336 336 168 ON OFF =================================================================== Battery date: 07/31/99 UPS Name : UPS_IDEN

At this point, you can select any item from 2) to 13) to modify the appropriate value. You will shown the existing value and prompted for the new values.

We recommend that you change the EEPROM as little as is absolutely necessary since it is a somewhat delicate process that has occasionally produced problems (i.e. improper EEPROM values are displayed after the update). Fortunately this seems to be quite rare and was much more likely to occur with the old “batch” like process especially if incorrect values were supplied.

Maintaining Your UPS

If you have your UPS long enough, you will probably have battery problems. Below, you will ﬁnd some suggestions for replacing batteries. One important note of caution: at least one user purchased one of the non-APC batteries noted below and found out that they would not ﬁt into his unit. This required cutting and soldering and other very undesirable things, so be extremely careful in measuring the batteries including every millimeter of the terminal connections which can cause problems.

Although you can do a hot swap of your batteries while the computer is running, it may not be very satisfactory because the unit will not know that the batteries have been swapped and apcupsd will continue to show Low Battery. To correct this situation, you must do a discharge and recharge of the battery followed by a battery recalibration using apctest. At that point the battery should be calibrated better. As noted below, Carl has

found that it takes several discharge/charges before the runtime calibration is accurate. Take care not to discharge your battery too much as it tends to shorten the battery life.

What Various People Have to Say about Batteries

Here is what John Walker has to say about APC UPS batteries:

I thought I’d pass on some information I’ve obtained which you’ll probably eventually need. Besides, by writing it down I’ll be able to ﬁnd it the next time. I started installing mine in 1995-1996. Lead-acid batteries have a ﬁnite life even if not subjected to deep discharge cycles. For the batteries used by APC, this is typically four to six years. As part of the self-test cycle, the UPS measures the voltage of the battery at full charge (which falls as the battery ages), and if it’s below about 90% of the value for a new battery, it sets oﬀ the “Replace battery” alarm, which it repeats every day. [on apcupsd versions prior to 3.8.0, this message is sent once, on version 3.8.0, it is sent every 9 hours KES]. You will occasionally get a false alarm. It’s a good idea if you get an alarm to repeat the self-test the next day and see if the alarm goes away. If the alarm is persistent, you need to replace the batteries, which can be done without powering down the UPS or load-you just open up the battery door, take out the old batteries, and hook up the new ones.

APC makes “Replacement Battery Units” for each of the SmartUPS models, but they sell them directly only in the U.S.

It’s best to wait until the low battery alarm before ordering a replacement-keeping batteries on the shelf reduces their life unless you keep them fully charged.

And Andre Hendrick says:

[For replacement batteries] You need to goto you your local Yamaha SeaDoo shop. There are 35 AMP Hour deep cycle marine batteries that are direct replacements. These are gel-cel and will double the runtime and/or cut your recharge time in half.

Jet Works 1587 Monrovia Ave.

Newport Beach CA 9266? Tel: +1 714 548-5259

J-W Batteries, Inc. Tel: +1 714 548-4017

WPS 49-1200 GEL-CELL KB-35 BATTERY

For those that do not know what this means........ I found the

best battery for APCC UPS products that use In the two systems below:

SMART-UPS 3000 10.9% is running at 327W runs for 47.0 min. Smart-UPS 1250 22.3% is running at 279W runs for 54.0 min.

APCUPSD UPS Network Monitor Thu Jan 18 21:55:36 PST 2001 System Model Status Battery Chg Utility UPS Load UPS Temp Batt. Run Time Data Linux ATA Development SMART-UPS 3000 ONLINE

100.0 % 120.2 VAC 10.9 % 36.9 C 47.0 min. All data

Linux ATA Development II APC Smart-UPS 1250 ONLINE

100.0 % 119.6 VAC 22.3 % 45.9 C 54.0 min. All data

Look at the numbers and see that these batteries are better and have more total running energy than standard ones.

SMART-UPS 3000 10.9% is running at 327W runs for 47.0 min. Smart-UPS 1250 22.3% is running at 279W runs for 54.0 min.

APCUPSD UPS Network Monitor Thu Jan 18 22:00:45 PST 2001 System Model Status Battery Chg Utility UPS Load UPS Temp Batt. Run Time Data Linux ATA Development SMART-UPS 3000 ONLINE

100.0 % 120.2 VAC 19.2 % 36.9 C 27.0 min. All data

Linux ATA Development II APC Smart-UPS 1250 ONLINE

100.0 % 119.6 VAC 21.8 % 45.9 C 55.0 min. All data

SMART-UPS 3000 19.2% is running at 576W runs for 27.0 min. Smart-UPS 1250 21.8% is running at 273W runs for 55.0 min. Smart-UPS 1250 46.1% is running at 576W runs for 26.0 min.

Kind of cool.

The 1250 can outrun the 3000 by a factor of two under identical percentages, or run head to head for the same time.

SMART-UPS 3000 is a 48V based or 4 batteries. Smart-UPS 1250 is a 24V based or 2 batteries.

Cheers,

Andre Hedrick Linux ATA Development

Finally, here is what Carl Erhorn has to say about batteries:

Hi, Folks.

Well, Kern was absolutely right. The problem with my UPS was batteries. It was unexpected though, because there was no indication of a bad battery right up until the UPS failed entirely.

For those who might encounter the same thing, and don’t know what’s happening (I didn’t either), here’s what happened.

A week or so ago, I turned on one of my SmartUPS 700-NET models. The load is a small dual P-III unix server (Solaris 8, X86) and a 4MM tape drive. During the normal selftest that runs when you ﬁrst turn on any APC UPS, the UPS ’freaked out’. The alarm stuttered at about 4 or 5 beeps per second, and all the panel lights ﬂashed spasmodically, as if something was loose inside the UPS.

I turned oﬀ the UPS and it’s load, then turned the UPS on again. This time, everything seemed ﬁne. I booted the system that was attached, and there were no problems. The status monitor showed 9 minutes runtime (which indicates fairly low capacity), but the batteries showed fully charged. I began to suspect a bad inverter in the UPS.

However, Kern told me that he suspected the batteries. So I took the UPS oﬄine, put an old SU-600 in it’s place (just barely big enough to handle the startup peaks - I get an ’overload’ lamp lit for about 2 seconds during boot), and checked out the batteries. They did indicate that they were near the end of life, so I ordered a replacement set. Those came in on Friday, and after the initial charge, a complete charge/discharge cycle to recalibrate the UPS, and some testing, I put it back in service.

Surprise! (Or maybe not?) Kern was right - there is nothing wrong with the inverter or the charging circuit, and the new cells ﬁxed everything.

What confused me is that there was no ’replace battery’ indication from the UPS, even when it failed, plus a fair amount of runtime indicated with a full charge. So if you see such behavior on one of your UPS models, it makes sense to replace the batteries, even if there is no indication that the batteries have failed yet.

One of the things I learned during this process is that the UPS internal calibration will lose accuracy over the life of the battery. I always do a recalibrate when I install new cells, but rarely do it after that, as it’s time-consuming, and you really can’t use the system attached to the UPS while doing it. Since my systems are almost constantly in use, it’s a pain to schedule a recal, and I tend to put it oﬀ. This time it bit me. I’d suggest that folks do a recal at least once every six months. It will make your runtime estimates much more accurate, and also allows you to keep track of the state of your batteries.

For those who don’t know how to do this, here’s what you do. This proceedure should not be confused with the ’Recalibrate’ feature in the APC PowerchutePlus software. They do not do the same thing.

>From APC’s web site:

Perform a Runtime Calibration. This is a manual procedure and should not be confused with the runtime calibration performed through PowerChute plus. The batteries inside of the SmartUPS are controlled by a microprocessor within the UPS. Sometimes it is necessary to reset this microprocessor, especially after the installation of new batteries. Stop the PowerChute plus software from running and disconnect the serial cable. There must be at least a 30% load attached to the UPS during this procedure, but the process will cause the UPS to shut oﬀ and cut power to its outlets. Therefore, attach a non-critical load to the UPS and then force the UPS on battery by disconnecting it from utility power. Allow the unit to run on battery until it turns oﬀ completely. Make sure a 30% load is present! Plug the UPS back into the wall outlet and allow it to recharge (it will recharge more quickly turned oﬀ and with no load present). Once the unit has recharged, the “runtime remaining” calculation should be more accurate. Remember that if the unit is an older model, then the runtime will not improve signiﬁcantly.

Background:

An APC Smart-UPS has a microprocessor which calculates runtime primarily based on the load attached to the UPS and on its battery capacity. On the right side of the front display panel there is a vertical graph of ﬁve LEDs. Each LED is an indication of battery charge in increments of twenty percent: 20, 40, 60, 80, 100% (bottom to top). For example, if the battery charge is 99%, then only four of the ﬁve LEDs are illuminated.

To ensure that an operating system receives a graceful shutdown when using PowerChute plus or a SmartSlot accessory, an alert is generated by the Smart-UPS indicating that the UPS has reached a low battery condition. The alert is audible (rapid beeping), visual (ﬂashing battery LED or LEDs), and readable through the graphical interface of PowerChute plus software (or a native UPS shutdown program within a particular operating system.) In order to calculate this “low battery condition,” all Smart-UPS products have a preconﬁgured low battery signal warning time of two minutes (this is the factory default setting). There are a total of four user-changeable settings: 2, 5, 7, or 10 minutes. If the low battery signal warning time is set for 2 minutes, then the alerts will activate simultaneously two minutes prior to shutdown. Similarly, if the total runtime for a particular UPS is 30 minutes with a low battery signal warning time set at 10 minutes, then the UPS will run on battery for 20 minutes before the low battery alert begins.

Total runtime is primarily based on two factors, battery capacity and UPS load. UPS load and runtime on battery are inversely proportional: as load increases, battery runtime decreases and vice versa. When utility power is lost, the UPS begins discharging the battery in order to support the attached load. Once power returns, the Smart-UPS will automatically begin to recharge its battery.

My comments on this proceedure:

I believe this proceedure works for all APC models that calulate runtime, not just the SmartUPS. It’s important that you load the UPS to 30% of the UPS capacity, as reported by apcupsd or another UPS monitor program. I’ve found that normal house lamps of diﬀerent wattages allow me to adjust the load to almost exactly what I want, which is between 30% and 35% of the UPS capacity. This is critical te getting an accurate reading (according to the APC web documents). Always bring the UPS to 100% charge ﬁrst, as indicated by the front panel lamps, or your UPS

monitoring software.

Set the UPS shutdown time to 2 minutes, all other settings to nominal, and disconnect the serial port cable from the UPS before running the recalibration. If you leave a monitoring program running through the serial port, it will turn the UPS oﬀ early, and you don’t want to do that during a recalibration run. When the run is complete, and the UPS turns oﬀ, you can reattach the serial cable, and the normal loads, and recharge the batteries normally. If you think you might have a power outage during the recharge time, allow the UPS to recharge to 20% or so (indicated by the panel lamps) before trying to use the computer system. This will allow the UPS to handle short dropouts while it recharges. Of course, if you can leave the computer oﬀ during the recharge time, the UPS will recharge much faster.

As an aside, when the batteries failed, my total runtime at 100% charge and an idle state was 9 minutes, which is pretty bad. I replaced the batteries with extended capacity cells, which add about 15% to the stock capacity. Now, after two complete charge/ discharge cycles, 100% charge shows the available runtime to be 42 minutes on the system when it’s idle, and 33 minutes when the system is very busy. The diﬀerences are due to the load of the computer, when the disks are busy, and the cpus are not in a halted state (my system halts the cpus when they are idle, to save power and lower heat, as do other OS like Linux), when compared to an idle state. Apcupsd indicates the load is about 27% when idle, and as much as 37% when heavily loaded.

I’ve found that two charge/discharge cycles result in a more accurate recalibration when installing new cells. It appears that some batteries need to be put through a couple of complete cycles before they reach their full capacity. I’ve also noticed that the full-charge voltage is diﬀerent for each battery until they have been through two cycles. On the initial charge of my new batteries, the 100% charge voltage on the two cells was almost .5 VDC apart. After two complete cycles, the batteries measure within .01 VDC of each other!

I hope this information helps anyone who might encounter the problem I saw, and also shows folks how to recal their batteries. If you haven’t done a complete recalibration in a year or two, I’d recommend it, so that you have warning of a low battery instead of what happened to me.

Regards,

—Carl

Where Carl Suggests You Get Batteries

Hi, Folks.

I’m just replacing the batteries in one of my SmartUPS models, and it occurs to me that some of you may not know about the place I get them from. I have no relationship with this company, other than as a customer, but I feel they know what they are doing, their prices are fair, and they have some interesting batteries available that you can’t obtain from APC.

These are the reasons I use them, and I thought this information might be useful to the US list members. They will ship outside of the US. If you have questions, you can contact them through the email address listed on their web pages. They have always responded pretty quickly to my questions.

The company is called Battery Wholesale Distributors, and they are located in Georgetown, Texas. If you have questions, you can reach them by phone at (800) 365-8444, 9:00AM to 5:00PM (their local time), Monday through Friday. I’ve gotten email from them on the weekends, although the oﬃce is not open then.

I won’t post prices, as you can get current pricing from their web site. They have an entire section dedicated to APC replacement batteries, and it’s easy to ﬁnd what you need. You can order over the web, or by phone. They accept all the usual credit cards.

The web site (as you might guess) is: www.batterywholesale.com

The thing I really like is that they have found manufacturers who make batteries in the standard case sizes, but have additional capacity over the original batteries shipped with the APC UPS models. Often, the diﬀerence is as much as 15% or so, and this can result in additional runtime. It’s a nice upgrade for a minor increase in price.

They are also ’green-aware’, in that they encourage you to recycle your old batteries, and will accept the old batteries back from you if you cannot ﬁnd a local place that recycles them. You pay the shipping, but I think other than that, there is no charge. I’ve never done this, as I have a battery retailer just down the street who will accept my old batteries.

Anyway, if you didn’t know about these folks, put the info aside where you can ﬁnd it when you need replacement batteries. I won’t make any guarantees, but I’ve been very pleased with their products, service, and pricing. I hope you ﬁnd them as helpful to you as I do. I’ve been dealing with them since about 1994,

and have never been disappointed. The owner of the place also is very good on technical issues, so if you have questions on their products, he can get as technical as you need to go.

Regards,

--Carl

Here is a link to the APC Battery Store.

Frequently-Asked Questions

See the bugs section of this document for a list of known bugs and solutions.

Q: Why all the craziness with custom serial cables?

A: It was nothing more nor less than a form of customer control. For a

long time APC wanted to keep other people from talking to its UPSes so it could lock out potential competition for its PowerChute software. Scrambling the leads on its serial cables was a cheap way to accomplish this – in fact, they tended to be wired so that if you tried a straightthrough cable, opening a serial link to the UPS would be interpreted as a shutdown command!

(Hardware companies often think like this – they lock up interfaces by instinct, cornering a small market rather than growing a bigger one. It’s fundamentally stupid and self-defeating, but it’s the kind of stupid that tends to sound good at an executive meeting.)

Fortunately, APC has lost a lot of this attitude since about 2000; nowadays they even release technical information to the apcupsd maintainers.

Q: What UPS brands does apcupsd support?

A: Currently apcupsd supports only APC UPSes. However, some com-

panies such as Hewlett Packard put their own brand name on APC manufactured UPSes. Thus even if you do not have an APC branded UPS, it may work with apcupsd. You will need to know the corresponding APC model number. apcupsd supports all the popular APC models. See the installation and conﬁgurations sections of this document for more details.

Q: Does apcupsd support Windows?

A: With release 3.8.0, apcupsd now runs on Win95/98, WinMe, WinNT,

and Win2000 machines. All features of the Unix versions of apcupsd are implemented. The UPS EEPROM programming features of apcupsd have not been tested under Windows. Version 3.8.0 does not support simple signaling UPSes (BackUPS, etc). Version 3.8.1 does support most simple signaling UPSes, but not all cables (due to deﬁciencies in the Windows serial port API). Please note that we have had reports that apcupsd does not work properly on the WinXP system. If you have any information on this, please email us.

Q: I don’t have a cable, which one should I build?

A: First you must know if you have an apcsmart UPS or a voltage-signalling

UPS. See the table of supported UPSes (see type table). If you have a apcsmart UPS, we recommend building a Custom Smart (see Smart-Custom Cable for SmartUPSes) cable. If you have a voltagesignaling UPS, we recommend that you build a Custom Simple (see

Voltage-Signalling Cable for ”dumb” UPSes) cable.

Q: How much CPU resources does apcupsd use?

A: Depending on your CPU speed, you may see more or less of the CPU

consumed by apcupsd. On a 400MHz Unix system, the CPU usage should fall well below 0.1%. On slower systems, the percentage will increase proportionally to the decrease in the CPU speed. On a 400Mhz Win98 machine, the CPU usage will be on the order of 0.5-1.0%. This is higher than for Unix systems. However, compared to the 30% CPU usage by APC’s PowerChute (the version on the CDROM shipped with my UPS), apcupsd’s 0.5-1.0% is very modest.

If you conﬁgure apcupsd to run with pthreads (--with-pthreads on the ./configure line), apcupsd will run considerably faster, otherwise said, it will consume less of your CPU, and it will use approximately one third of the memory. For example, Carl Erhorn reports that on his Solaris system, “With the old 3-process version, we averaged about

4.8MB of total memory used. With the new single process, we use only about 1.7MB! That’s also a very good improvement.”

Q: What language is apcupsd written in?

A: It is written entirely in C.

Q: We are using apcupsd-3.8.1-1 in RedHat 6.2. The slave, when shutting

down, is reporting an error at line 436 of apcupsd.c. The error is initiated by apcupsd --killpower! What can we do to ﬁx this, and is it critical?

A: No, the error is not serious. Unfortunately, the documentation in the

area of master/slaves is not very detailed, and for that reason, your slave setup is not totally correct as explained below.

On master machines, we modify /etc/rc.d/init.d/halt to re-invoke apcupsd with the --killpower option (actually the script apccontrol is called). This causes the UPS to send the codes to the UPS to make it power oﬀ.

On slave machines, these modiﬁcations should not be made to the /etc/rc.d/init.d/halt script since the slave has no connection to the UPS.

To eliminate the problem, on all your slave machines, either restore the original halt ﬁle, or simply delete all the lines containing ***apcupsd***, which were inserted by the apcupsd installation process.

Q: To test apcupsd, I unplugged the UPS to simulate a power outage.

After the machine went into the shutdown process I plugged the UPS back into the commercial power source. This caused the shutdown process to hang after the daemon tried to shut-oﬀ the ups. Have you run into this problem, and if so do you have a remedy?

A: Normally, once the shutdown process has begun, we cannot stop it,

though there is some code that tries to do so, we don’t consider it a very good idea – how do you stop a shutdown that has killed oﬀ half of the daemons running on your system? Most likely you will be left with an unusable system. In addition, when apcupsd is re-executed in the halt script after the disks are synced, it tries to shut oﬀ the UPS power, but the UPS will generally refuse to do so if the AC power is on. Since we cannot be 100% sure whether or not the UPS will shut oﬀ the power, we don’t attempt to reboot the system if we detect that the power is back as it might then get caught by a delayed power oﬀ (at least for Smart UPSes).

Q: After running apcupsd for a while, I get the following error: “Serial

communications with UPS lost.” What is the problem?

A: We use standard Unix serial port read() and write() calls so once a

connection is made, we generally have few problems. However, there have been reports that APC’s SNMP Management Card can cause serial port problems. If you have such a card, we suggest that you remove it and see if the problem goes away. It is also possible that some other process such as a getty is reading the serial port.

Q: When apcupsd starts, I get the following error: “attach

not get shm area: Identiﬁer removed.” What is the problem?

shmarea: can-

A: This problem and the problem of cannot create shm area are due

to the fact that the shared memory key that apcupsd wants to use is already in use. This happens most frequently when there is an old zombie apcupsd process still in the system. The solution is to remove the old process. You can often see what is going on by doing a: ipcs command as root when apcupsd is not running. If you see a segment with the key 0x10feed01, you can be sure there is some old apcupsd process still using it. If you cannot kill the old process, you can try using ipcrm (see the man pages). Recent versions of apcupsd starting with apcupsd-3.8.2Beta6 should no longer have this problem as they will automatically try using a diﬀerent key.

Q: I get the following error: “Starting apcupsd power management. Mar 20

21:19:40 box apcupsd[297]: apcupsd FATAL ERROR in apcserial.c at line 83. Cannot open UPS tty /dev/cua01: No such ﬁle or directory.” What is the problem?

A: The two most likely causes of your problem are: 1. You have the wrong

serial port device name in the apcupsd.conf ﬁle. 2. The device name is not deﬁned on your system. Suggestions for proceeding:For the ﬁrst item, check what your serial port device should be named. You might be able to ﬁnd the name with an:

ls /dev

Normally there will be hundreds or even thousands of names that print. If that doesn’t produce anything useful, you can try step 2. Perhaps your device is not deﬁned. To get more information on your devices try man MAKEDEV or find / -name MAKEDEV. It is often located in /dev/MAKEDEV. Looking at the documentation may tell you what the correct name is, or at least allow you to create the device.

Q: How do I ensure that the slaves shutdown before the master?

A: There are several strategies for getting the slaves properly shutdown

before shutting down the master. The ﬁrst is to make the master wait a period of time for the slaves to shutdown before doing its own shutdown. Currently, the master always waits 30 seconds before starting its own shutdown. If this is insuﬃcient, you can add additional time by putting an appropriate sleep shell command in the /etc/apcupsd/apccontrol ﬁle just before the actual system shutdown command is executed (there are something like 3 places). The second strategy is to put a TIMEOUT value in the apcupsd.conf ﬁle on the

slave that is suﬃciently short that you are sure that the slave will shutdown before the master. If the shutdown is done with a poweroﬀ, this will also save power so that the master can stay up longer.

Q: How do I ensure that my database server is correctly shutdown?

A: You simply add whatever commands are necessary in the appropri-

ate case statements in /etc/apcupsd/apccontrol, which is a standard script ﬁle that is called to actually do the shutdown. Alternatively, you can add your own script ﬁle that will be called before doing the commands in apccontrol. Your script ﬁle must have the same name as the appropriate case statement in apccontrol; it must be executable; and it must be in the same directory as apccontrol.

Q: I have Win2k Advanced server, and when starting the service, get:

Could not start the Apcupsd Server service on Local Computer. Error 1067: The process terminated unexpectedly

A: The most common error causing your problem is an incorrect serial port

speciﬁcation on your DEVICE directive. It should be:

DEVICE /dev/com2

On WinNT machines, and probably Win2000 machines you MUST use /dev/com2 unless you modify the behavior of the boot process to prevent Windows from probing the port. This is documented in our manual for WinNT. Although I imagine it is the same for Win2000, I am not sure.

The second most common problem is bad placement of the ﬁles i.e. you did not install them in c:\apcupsd Unfortunately for the current release, this path is “hard coded” into the binaries.

The third most common problem is that you did not run the setup.bat script after loading the ﬁles. This is necessary to install apcupsd as a service.

If all the above fails, try starting apcupsd by hand inside a CYGWIN rxvt window if you use an rxvt window rather than a DOS window, you will see many more of the error messages.

In addition, most of the apcupsd startup errors are reported in: c:\apcupsd\etc\apcupsd\apcupsd.events

Many error messages associated with Windows services will be reported in the Windows System Log.

APC UPS control system User Manual

Specifications and Main Features

Frequently Asked Questions

User Manual

Release Notes

New Features

How To Use This Manual

Planning Your Installation

Quick Start for Beginners

Supported Operating Systems, UPSes and Cables

Apcupsd Known USB Issues

Checking Out Your USB Subsystem

Building and Installing apcupsd

Installation from Binary Packages

Installation from Source

Verifying a Source Installation

Recommended Options for most Systems

Compilers and Options

After Installation

Arranging for Reboot on Power-Up

Making sure apcupsd Is Running

Testing Apcupsd

Process-Status Test

Logging Test

apcaccess Test

Communications Test

Simulated Power Fail Test

System Shutdown Test

Full Power Down Test

Shutdown Sequence

apctest

Troubleshooting Your Installation

Known Problems with USB UPSes

Monitoring and Tuning your UPS

apcaccess

apcupsd Network Monitoring (CGI) Programs

Setting up and Testing the CGI Programs

Maintaining Your UPS

What Various People Have to Say about Batteries

Where Carl Suggests You Get Batteries

Frequently-Asked Questions