\input texinfo @c -*-texinfo-*-
@comment $Id: manual.texi,v 1.1 2005/03/13 21:43:22 kerns Exp $
@c %***start of header
@setfilename manual.info
@finalout
@settitle apcupsd User's Manual
@c %***end of header
@set VERSION 3.10.17
@set UPDATED 14 March 2005
@ifnottex
@documentdescription
Apcupsd UPS User's Manual
@end documentdescription
@end ifnottex
@documentencoding us-ascii
@direntry
* apcupsd User's Manual: (apcupsd_user's_manual).
@end direntry
@paragraphindent 2
@unnumbered
@sp 2
@center @image{apcupsd}
@sp 2
@center @titlefont{Apcupsd User's Manual}
@sp 2
@center Apcupsd Version @value{VERSION}
@center A UPS Control Program
@sp 2
@center Kern Sibbald
@sp 2
Apcupsd is a UPS
control system that permits orderly shutdown of your
computer in the event of a power failure.
@sp 2
@page
@iftex
@vskip 0pt plus 1filll
@end iftex
This document was last updated @value{UPDATED}
Copyright @copyright{} 1999-2005 Kern Sibbald
@quotation
Copying and distribution of this file, with or without
modification, are permitted in any medium without royalty provided
the name Apcupsd, the copyright notice, and this notice are
preserved.
@end quotation
Apcupsd source code is released under the GNU General Public
License version 2. Please see the file COPYING in the main source directory.
For more information on the project, please visit the main web
site at @uref{http://www.apcupsd.com, http://www.apcupsd.com}.
@titlepage
@end titlepage
@contents
@ifnottex
@node Top, Release Notes, ,
@top Apcupsd User's Manual
@end ifnottex
@menu
* Release Notes::
* How To Use This Manual::
* Basic User's Guide::
* Planning Your Installation::
* Building and Installing apcupsd::
* After Installation::
* Configuration Examples::
* Testing Apcupsd::
* Troubleshooting Your Installation::
* Monitoring and Tuning your UPS::
* Maintaining Your UPS::
* Frequently-Asked Questions::
* Apcupsd Bugs::
* Advanced topics::
* Customizing Event Handling::
* Master/Slave Configurations::
* Controlling Multiple UPSes on one Machine::
* Support for SNMP UPSes::
* Alternate Ways To Run The Network Information Server::
* apcupsd System Logging::
* Installation on Windows::
* The Windows Version of apcupsd::
* Installation on Serial-Line UPSes::
* Overview of Serial-Interface UPSes::
* Connecting a Serial-Line UPS to a USB Port::
* Connecting a APC USB UPS to either a PC USB or Serial Port::
* Cables::
* Testing Serial-Line UPSes::
* Troubleshooting Serial Line communications::
* Recalibrating the UPS Runtime::
* DATA Logging::
* Technical Reference::
* Configuration Directive Reference::
* apcupsd Status Logging::
* The Shutown Sequence and its Discontents::
* APC smart protocol::
* Apcupsd -- RPM Packaging FAQ::
* Credits: Credits <1>.
* Kernel Config::
* Index::
@detailmenu
--- The Detailed Node Listing ---
Release Notes
* New Features::
Planning Your Installation
* Quick Start for Beginners::
* Supported Operating Systems, UPSes and Cables: Supported Operating Systems; UPSes and Cables.
* Choosing a Configuration Type::
* Apcupsd Known USB Issues::
* Checking Out Your USB Subsystem::
Building and Installing apcupsd
* Installation from Binary Packages::
* Installation from Source::
* Verifying a Source Installation::
* Configure Options::
* Recommended Options for most Systems::
* Compilers and Options::
* Operating System Specifics::
After Installation
* Checking Your Configuration File::
* Arranging for Reboot on Power-Up::
* Making sure apcupsd Is Running::
Configuration Examples
* A Simple USB Configuration::
* A Simple Configuration for a SmartUPS::
* A Simple Configuration for a Simple Signaling or Dumb::
* A Simple Master Configuration::
* A Simple Slave Configuration::
* Variation on the Master/Slave Configuration::
* A Sample NIS Slave Configuration Using the Net Driver::
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 Notification and Events::
* hid-ups and USB Specific Information::
* apcupsd Network Monitoring (CGI) Programs: apcupsd Network Monitoring [CGI] Programs.
* Setting up and Testing the CGI Programs::
* Configuring Your EEPROM::
Maintaining Your UPS
* What Various People Have to Say about Batteries::
* Where Carl Suggests You Get Batteries::
Customizing Event Handling
* apccontrol Command Line Options::
Master/Slave Configurations
* Configuration Directives::
* Master/Slave Problems::
* Network Problems with Master/Slave or Server/Slave Configurations::
Controlling Multiple UPSes on one Machine
* Configuration::
Support for SNMP UPSes
* Connecting an SNMP UPS::
* Building and Installing apcupsd: Building and Installing apcupsd <1>.
* SNMP Specific Information::
* Known Problems::
Alternate Ways To Run The Network Information Server
* Running the server as a child of apcupsd::
* Running apcnisd from INETD::
* Running apcnisd Standalome::
apcupsd System Logging
* Logging Types::
* Implementation Details::
* Developers Notes::
The Windows Version of apcupsd
* Installation::
* Installation Directory::
* Testing::
* Upgrading::
* Post Installation::
* Problem Areas::
* Utility Functions::
* Disclaimer::
* Email Notification of Events::
* Killpower under Windows::
* Power Down During Shutdown::
* Command Line Options Specific to the Windows Version::
* Building the Win32 Version from the Source::
Cables
* Smart-Custom Cable for SmartUPSes::
* Smart Signalling Cable for BackUPS CS Models::
* Voltage-Signalling Cable for "dumb" UPSes::
* Other APC Cables that apcupsd Supports::
* Voltage Signalling Features Supported by Apcupsd for Various Cables::
* Voltage Signalling::
* The Back-UPS Office 500 signals::
* Analyses of APC Cables::
* Win32 Implementation Restrictions for Simple UPSes::
* Internal Apcupsd Actions for Simple Cables::
* RS232 Wiring and Signal Conventions::
* Pin Assignment for the Serial Port (RS-232C), 25-pin and 9-pin, Female End: Pin Assignment for the Serial Port [RS-232C]; 25-pin and 9-pin; Female End.
* Ioctl to RS232 Correspondence::
Testing Serial-Line UPSes
* Establishing Serial Port Connection::
* Using apctest on Serial-Line UPSses::
Troubleshooting Serial Line communications
* Determining Which Voltage-Signaling Cable You Have::
* Once you have established serial communications::
Recalibrating the UPS Runtime
* Status Logging On Serial-Line UPSes::
Configuration Directive Reference
* General Configuration Directives::
* Configuration Directives Used by the Network Information Server::
* Configuration Directives used during Power Failures::
* Configuration Directives used to Control System Logging::
* Configuration Directives for Sharing a UPS::
* Configuration Directives Used to Set the UPS EPROM::
apcupsd Status Logging
* Status report format::
* Status Report Example::
* Status Report Fields::
* Logging the STATUS Information::
The Shutown Sequence and its Discontents
* Shutdown Sequence: Shutdown Sequence <1>.
* Shutdown Problems::
* Master/Slave Shutdown: Master/Slave Shutdown <1>.
* Startup::
* Windows Considerations::
APC smart protocol
* Description::
* RS-232 differences::
* Diagram for cable hackers::
* The Smart Protocol::
* Dip switch info::
* Status bits::
* Alert messages::
* Register 1::
* Register 2::
* Register 3::
* Interpretation of the Old Firmware Revision::
* Interpretation of the New Firmware Revision::
* EEPROM Values::
* Programming the UPS EEPROM::
* Acknowledgements::
Apcupsd -- RPM Packaging FAQ
* Answers::
Credits
* Contributors::
* Disclaimer; NO WARRANTY::
@end detailmenu
@end menu
@node Release Notes, How To Use This Manual, Top, Top
@unnumbered Release Notes
@cindex Release Notes
This release contains a good number of cleanups and bug fixes to
prior 3.10.x versions, and is intended to be the official release.
See the ChangeLog below for more details.
@menu
* New Features::
@end menu
@node New Features,,,Release Notes
@section New Features
@cindex New Features
@example
- 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.
@end example
Change Log for current version
@example
----> 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.
@end example
Change Log for older versions
@example
----> 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(), ...
@end example
@node How To Use This Manual, Basic User's Guide, Release Notes, Top
@unnumbered How To Use This Manual
@cindex Using 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 (@pxref{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 (@pxref{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 (@pxref{Advanced topics}).
Finally, there is a Technical Reference (@pxref{Technical
Reference}) section which gives full details on things like
configuration file directives and event-logging formats.
You should begin by reading the Quick
Start (@pxref{Quick Start for Beginners}) instructions.
@node Basic User's Guide, Advanced topics, How To Use This Manual, Top
@majorheading Basic User's Guide
@cindex User's Guide
@menu
* Planning Your Installation::
* Building and Installing apcupsd::
* After Installation::
* Configuration Examples::
* Testing Apcupsd::
* Troubleshooting Your Installation::
* Monitoring and Tuning your UPS::
* Maintaining Your UPS::
* Frequently-Asked Questions::
* Apcupsd Bugs::
@end menu
@node Planning Your Installation, Building and Installing apcupsd, , Basic User's Guide
@chapter Planning Your Installation
@cindex Planning Installation
@cindex Installation, Planning
@menu
* Quick Start for Beginners::
* Supported Operating Systems, UPSes and Cables: Supported Operating Systems; UPSes and Cables.
* Choosing a Configuration Type::
* Apcupsd Known USB Issues::
* Checking Out Your USB Subsystem::
@end menu
@node Quick Start for Beginners, Supported Operating Systems; UPSes and Cables, , Planning Your Installation
@section Quick Start for Beginners
@cindex Quick Start
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.
@enumerate
@item
First, check to see if apcupsd supports your UPS and operating
system (@pxref{Supported Operating Systems; UPSes and Cables}).
@item
Second, plan your configuration
type (@pxref{Choosing a Configuration 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.
@item
Third, figure 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
(@pxref{Checking Out Your USB Subsystem}); if so, you can go to the
build and install step.
@item
If you have a UPS designed to communicate via SNMP
over Ethernet, that is also a relatively easy installation. It's
in Advanced Topics (@pxref{Advanced topics}) mainly because
it's an unusual situation.
@item
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.
@enumerate
@item
If you have a vendor-supplied cable, find out what cable type
you have by looking on the flat ends of the cable for a number, such
as 940-0020A, stamped in the plastic. Check the cables column of the
table of types (@pxref{type_table}) to see if it's a
supported type.
@item
If you don't have a vendor-supplied cable, or your type is
not supported, you may have to build one
yourself (@pxref{Cables}). Here is hoping you are good with a soldering
iron!
@end enumerate
@item
Now you are ready to read the Building and Installing
(@pxref{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.
@item
Tweak your @file{/etc/apcupsd/apcupd.conf} file as
necessary. Often it will not be.
@item
Change the BIOS settings (@pxref{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.)
@item
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 (@pxref{Testing Apcupsd})
section.
@item
If you run into problems, read the Troubleshooting (@pxref{Troubleshooting Your Installation}) section of this
manual.
@item
If you still need help, send a message to the developer's
email list @email{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.
@item
Read the manual sections on @uref{monitoring,monitoring} and
@uref{maintaining,maintaining} your UPS.
@end enumerate
@node Supported Operating Systems; UPSes and Cables, Choosing a Configuration Type, Quick Start for Beginners, Planning Your Installation
@section Supported Operating Systems, UPSes and Cables
@cindex Supported OSes
@cindex OSes Supported
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 @ref{Operating System Specifics} you'll find
operating-system-specific tips for building and configuring
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 APC-supplied cable.
@anchor{upstypes}The "UPSTYPE Keyword" field is the value you will
put in your @file{/etc/apcupsd/apcupd.conf} file 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.
@cindex UPSTYPE
@cindex Keywords, USBTYPE
@table @asis
@item 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 (@pxref{APC smart
protocol}) resembling modem-control codes. The different APC
UPSes all use closely related firmware, 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.
@item usb
A USB UPS speaks a universal well defined 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 different 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 configure your UPS as @strong{apcsmart}
rather than @strong{usb}.
@item 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.
@item snmp
SNMP UPSes communicate via an Ethernet NIC and firmware that
speaks Simple Network Management Protocol.
@item 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.
@end table
The table shown below lists the APC model supported, and the possible
kewords that you would use in the configuration 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 offer as many features, so
some of the example output you see elsewhere in this manual may
not be available with your unit.
@noindent
@anchor{type_table}
@cindex UPSTYPE, table
@multitable @columnfractions 0.25 0.25 0.25 0.25
@item
@strong{APC Model}@tab @emph{UPSTYPE Keyword}@tab @emph{UPSCABLE keywords for Cables Supported}@tab @emph{Status}
@item
BackUPS CS/ES (serial mode)@tab apcsmart@tab smart (note: using Smart Custom RJ45) the
new Back-UPS RS 500 models are reported NOT to work with this cable.@tab Supported
@item
BackUPS Pro, Smarter BackUPS Pro@tab apcsmart@tab 940-0095A@tab Supported
@item
SmartUPS, SmartUPS VS (It has not been confirmed that the
cable shipped with the VS is a 940-0095.), PowerStack 450, Matrix UPS, ShareUPS Advanced Port@tab apcsmart@tab smart (note: using Smart-Custom), 940-0024C @tab Supported
@item
BackUPS CS USB, Pro USB, ES USB, RS/XS 1000, RS/XS 1500, and probably
other USB models@tab usb@tab usb (note: using APC cables 940-0127A/B/C)@tab Supported in version >=3.9.8
@item
SmartUPS USB, BackUPS Office USB, and any other USB UPS@tab usb@tab usb (note: using APC cable, no number)@tab Supported, version >=3.9.8
@item
All SNMP-capable models@tab snmp@tab ether@tab Supported
@item
BackUPS@tab dumb@tab simple (note: using Simple-Custom (This cable is
not an APC product. You have to build it yourself using the
instructions in @ref{Cables}.),
940-0020B, 940-0020C, 940-0119A, 940-0023A@tab Supported
@item
BackUPS Office, BackUPS ES@tab dumb@tab 940-0119A@tab Supported
@item
BackUPS CS and possibly ES models (serial mode)@tab dumb@tab 940-0128A@tab Supported
@item
ShareUPS Basic Port@tab dumb@tab 940-0020B, 940-0020C, 940-0023A@tab Supported
@end multitable
@node Choosing a Configuration Type, Apcupsd Known USB Issues, Supported Operating Systems; UPSes and Cables, Planning Your Installation
@cindex Choosing a Configuration Type
@cindex Configuration Type
There are three major ways of running apcupsd on your system.
The first is a standalone configuration where apcupsd controls a
single UPS, which powers a single computer. This is the most
common configuration. 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 configuration is a master/slave configuration,
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 configuration may be
appropriate for a small cluster of machines. Some example
configuration files 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 configuration (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 different 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 configuration may be appropriate for large
server farms that use one dedicated machine for monitoring
and diagnostics
Here is a diagram that summarizes the possibilities:
@noindent
@anchor{Configuration types_}
@strong{Configuration types.}
@sp 1
@example
@image{main_configs}
@end example
@sp 1
If you decide to set up one of these more complex
configurations, see the Advanced Topics (@pxref{Advanced topics})
section for details.
@node Apcupsd Known USB Issues, Checking Out Your USB Subsystem, Choosing a Configuration Type, Planning Your Installation
@section Apcupsd Known USB Issues
@cindex USB problems
@cindex Problems, USB
- @strong{Problem:} USB is only supported on Linux and *BSD systems (though
the *BSD is still BETA).
Although the configuration script allows the usb driver to be
enabled on other platforms, it will only compile and run on Linux
and *BSD systems.
- @strong{Workaround:} Try using UPS in serial mode instead of USB.
- @strong{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 affects RHEL3, among others.
- @strong{Workaround:} Upgrade linux kernel to 2.4.22 or higher.
- @strong{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 @strong{hiddev0: USB HID v1.10 Device
[...]} instead of @strong{hiddev96: ...} in dmesg log.
- @strong{Workaround:} Boot standard kernel instead of kernel-secure or disable
CONFIG_USB_DYNAMIC_MINORS and rebuild kernel-secure.
- @strong{Problem:} USB driver linux-usb.c fails to compile, reporting errors about
@strong{HID_MAX_USAGES undefined}. This is due to a defect in the linux kernel
hiddev.h header file on 2.6.5 and higher kernels.
- @strong{Workaround:} Workaround: Upgrade to apcupsd-3.10.14 or
higher. These versions contain a workaround for the defect.
- @strong{Problem:} On some systems such as Slackware 10.0, no USB devices will
showup (see the next section).
- @strong{Workaround:} add the following to rc.local
@example
mount -t usbdevfs none /proc/bus/usb
@end example
- @strong{Problem:} 2.6 kernels use udev and does not autmatically
create /dev/usb/hiddev?? as it should, causing apcupsd to
- @strong{Workaround:} Edit the file /etc/udev/rules.d/50-udev.rules, and
add the following:
@example
KERNEL="hiddev*", NAME="usb/hiddev%n"
@end example
More details are provided in the following section ...
@node Checking Out Your USB Subsystem, , Apcupsd Known USB Issues, Planning Your Installation
@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 a list of known issues with the BSD USB driver and the associated
kernels.
@example
cat /proc/bus/usb/devices
@end example
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 file, please see @uref{http://www.linuxhq.com/kernel/v2.4/doc/usb/proc_usb_info.txt.html, 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:
@example
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
@end example
Note, if on the last line, @strong{Driver} is listed as
@strong{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 first
features a Back-UPS 350 direct connected USB device:
@example
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
@end example
The second features an IOgear USB-to-serial adapter that runs my
serial SmartUPS 1000:
@example
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
@end example
Note that the IOgear device is using the @strong{serial} driver (the I: line) while the Back-UPS
350 is using the @strong{hid} driver.
In general, if you see your UPS model in the S field, which
means @strong{Manufacturer=}, @strong{Product=}, and @strong{SerialNumber=},
and you see @strong{hid} in the I field (or @strong{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 @strong{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 file in the
@file{/proc} system. Here's how you can do that:
@example
esr@@grelber$ cat /proc/bus/usb/drivers
@end example
and you should get:
@example
usbdevfs
hub
96-111: hiddev
hid
@end example
On Linux-2.6.x, make sure the sysfs filesystem is mounted on /sys
and do:
@example
adk0212@@mail$ ls -l /sys/bus/usb/drivers/
@end example
where you should get
@example
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
@end example
or perhaps something like
@example
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
@end example
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 filesystem,
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
CONFIG_USB_DEVICEFS as well as at least one USB Host Controller
Driver (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 flavors running 2.6 kernels
such as Fedora FC3 use the udev filesystem,
which creates the devices in /dev (as well as some others
such as network devices) on the fly 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
file /dev/usb/hiddev# is not defined, and hence apcupsd
terminates in error. The solution to the problem is
to add a rule to the udev rules file. On Fedora FC3, this
file is found in /etc/udev/rules.d/50-udev.rules. Start
by adding the following line:
@example
BUS="usb", SYSFS[idVendor]="051d", NAME="usb/hiddev%n"
@end example
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
fine. You can use:
@example
udevinfo -a -p /sys/class/usb/hiddev0/
@end example
to get more information on the fields that can be matched.
Adam has provided the following as a more generic rule:
@example
KERNEL="hiddev*", NAME="usb/hiddev%n"
@end example
If you have several UPSes or you just want to give your
UPS a fixed name, you can use:
@example
BUS="usb", SYSFS[serial]="AS0123456789", NAME="usb/ups0"
@end example
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
CONFIG_USB_DYNAMIC_MINORS turned on. This is not ideal for
running with apcupsd, and the easiest solution is to
turn CONFIG_USB_DYNAMIC_MINORS off and rebuild your
kernel, or find a pre-built kernel with it off.
For a kernel with CONFIG_USB_DYNAMIC_MINORS turned on to
work with apcupsd, you must enable @strong{devfs}. The following
will tell you if devfs is enabled:
@example
$ ps ax | grep devs
@end example
which should give something like the following:
@example
533 ? S 0:00 devfsd /dev
@end example
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 off. 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:
@example
(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.
(c) Custom build a high security kernel with dynamic
minors disabled
(d) Use udev
@end example
For a typical USB section of a kernel .config file, please
see the end of this section.
For the IOGear serial USB connection, you need:
@example
usbcore
usbserial
pl2303
@end example
Finally, check that appropriate USB devices exist. On a Red Hat
system you can do this:
@example
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
@end example
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 different;
the hiddev devices will usually live in a
@file{/dev/usb/hid/} subdirectory. If these devices
don't exist, you may need to run
@file{<apcupsd-source>/examples/make-hiddev} to
create them.
Now build and run the hid-ups test
program. You do not have to configure and build the rest of
apcupsd to do this. To build
hid-ups enter:
@example
cd <apcupsd-source>/examples
make hid-ups
@end example
There should be no errors. Now assuming that everything has gone
well to this point and that you have connected your USB UPS, enter:
@cindex hid-ups
@example
./hid-ups
@end example
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
@file{<apcupsd-source>/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 find 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 ---
find expert help. If you are unable to list USB devices or drivers,
you kernel may not be USB-capable and that needs to be fixed.
Please check if your kernel has the three patches listed in
the @file{<apcupsd-source>/examples} directory.
Each of the files ends with the name @file{.patch}, and at the
current writing they are:
@example
linux-2.4.20-killpower.patch
linux-2.4.20-USB-reject.patch
linux-2.6.0-USB-queue-overflow.patch
@end example
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 files that you can consult in the @file{examples}
directory for additional information and details.
Finally, check your Kernel Config. You will find more information
about it at: @ref{Kernel Config}.
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 flag to configure). 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 hot-
unplugging 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:
@example
FreeBSD-5.3 (Primary development platform)
FreeBSD-4.11
NetBSD-2.0
NetBSD-1.6.2
OpenBSD-3.6
@end example
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 sufficient 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 config file (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:
@example
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
@end example
CHECKING UPS IS RECOGNIZED BY THE KERNEL
After building a properly configured 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:
@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
@end example
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 first 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 configure.
Your apcupsd.conf file needs the following hardware-related settings:
@example
UPSCABLE usb
UPSTYPE usb
DEVICE
@end example
The DEVICE setting is blank on purpose; apcupsd will automatically locate your
UPS.
The delay-, timeout-, and NIS-related settings should be configured as per
your usual preference.
@node Building and Installing apcupsd, After Installation, Planning Your Installation, Basic User's Guide
@chapter Building and Installing apcupsd
@cindex Building
@cindex Installing
@menu
* Installation from Binary Packages::
* Installation from Source::
* Verifying a Source Installation::
* Configure Options::
* Recommended Options for most Systems::
* Compilers and Options::
* Operating System Specifics::
@end menu
@node Installation from Binary Packages, Installation from Source, , Building and Installing apcupsd
@section Installation from Binary Packages
@menu
* Red Hat Linux::
* Microsoft Windows::
@end menu
@node Red Hat Linux, Microsoft Windows, , Installation from Binary Packages
@subsection Red Hat Linux
@cindex Installing, Red Hat
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 configuration, simply
install the RPM with a normal @code{rpm -ihv} command.
You're done, and can now skip the rest of this chapter and go straight
to tweaking your run-time
configuration file. (@pxref{After Installation})
If you have a previous installation, you can upgrade with a normal
@code{rpm -Uhv}, but this may not upgrade the halt script.
It may be better to do the upgrade as a remove (@code{rpm -e})
foll;owed by a fresh install (@code{rpm -ihv}).
After installation of the binary RPM, please verify carefully
that @file{/etc/rc.d/init.d/halt} was properly updated
and contains new script lines flagged with @strong{***APCUPSD***}.
Since there is no standard location for
@file{cgi-bin}, the rpm will place the binary CGI
programs in the directory @file{/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
@file{/home/httpd/cgi-bin}.
@node Microsoft Windows, , Red Hat Linux, Installation from Binary Packages
@subsection Microsoft Windows
@cindex Installing, Microsoft
If you have a binary release of the Win32
apcupsd, please see the instructions in the Advanced Topics (@pxref{Advanced topics}) section of this
manual.
@node Installation from Source, Verifying a Source Installation, Installation from Binary Packages, Building and Installing apcupsd
@section Installation from Source
Installation from source might have to be be done different ways
depending on what system you are running. The basic procedure involves
getting a source distribution, running the configuration, rebuilding,
and installing.
The basic installation from a tar source file is rather simple:
@enumerate
@item
Unpack the source code from its tar archive.
@item
Go into the directory containing the source code.
@item
Run @code{./configure} (with appropriate options
as described below)
@item
make
@item
su (i.e. become root)
@item
Stop any running instance of apcupsd. The
command to do this will look like
@code{<system-dependent-path>/apcupsd stop}
@item
uninstall any old apcupsd
This is important since the default install locations may have
changed.
@item
make install
@item
edit your @file{/etc/apcupsd/apcupsd.conf} file if
necessary
@item
ensure that your halt script is properly updated
@item
Start the new apcupsd with:
@code{<system-dependent-path>/apcupsd start}
@end enumerate
If all goes well, the @code{./configure} will
correctly determine which operating system you are running and
configure the source code appropriately. @code{configure}
currently recognizes the systems listed below in the @ref{Operating System Specifics} section of this chapter and adapts the
configuration appropriately. Check that the configuration report
printed at the end of the @code{configure} process
corresponds to your choice of directories, options, and that it has
correctly detected your operating system. If not, redo the
@code{configure} with the appropriate options until your
configuration is correct.
Please note that a number of the @code{configure}
options preset @file{apcupsd.conf} directive values in
an attempt to automatically adapt apcupsd
as best possible to your system. You can change the values in
@file{apcupsd.conf} at a later time without redoing the
configuration process by simply editing the
@file{apcupsd.conf} file.
Other configuration 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 powerflute curses-based control
panel. Still others enable features such as thread support. You
will find a complete reference later in this chapter.
In general, you will probably want to supply a more elaborate
@code{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 configuration command would
look like the following:
@example
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
@end example
By default, @code{make install} will install the
executable files in @file{/sbin}, the manuals in
@file{/usr/man}, and the configuration and script files
in @file{/etc/apcupsd}. In addition, if your system is
recognized, certain files such as the startup script and the system
halt script will be placed in appropriate system directories (usually
subdirectories of @file{/etc/rc.d}).
@node Verifying a Source Installation, Configure Options, Installation from Source, Building and Installing apcupsd
@section Verifying a Source Installation
@cindex Verifying Source
@cindex Installing, Source
There are a number of things that you can do to check if the
installation (make install) went well. The fist is to check where the
system has installed apcupsd using
@code{which} and @code{whereis}. On my Red Hat
system, you should get the following (lines preceded with a $ indicate what
you type):
@example
$ 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
@end example
If you find an apcupsd in
@file{/usr/sbin}, @file{/usr/local/sbin},
@file{/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 @code{make install} to
ensure that you haven't deleted anything needed by the new
apcupsd. Please note that the files
specified above assume the default installation locations.
As a final check that the @code{make install} went
well, you should check your halt script (in
@file{/etc/rc.d} on SUSE systems, and in
@file{/etc/rc.d/init.d} on Red Hat systems) to see that
the appropriate lines have been inserted in the correct
place. Modification 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 off the power. This should
only be done in a power failure situation as indicated by the presence
of the @file{/etc/powerfail} file, 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 @code{#
***apcupsd***} should be inserted just before the final halt
command:
@example
# 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."
fi
@end example
The purpose of modifying the system halt files 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 off
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 final system dependent
installation step by specifying the
@code{disable-install-distdir} option on the
@code{./configure} command (see below for more
details).
The above pertains to Red Hat systems only. There are significant
differences 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 specific system
dependent README files 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 off the UPS. That will be done by the
master.
@node Configure Options, Recommended Options for most Systems, Verifying a Source Installation, Building and Installing apcupsd
@section Configure Options
@cindex configure options
@cindex options, configure
All the available @code{configure} options can be
printed by entering:
@example
./configure --help
@end example
When specifying options for @code{./configure}, if
in doubt, don't put anything, since normally the configuration 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
@code{./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
@code{./configure} command.
The following command line options are available for
@code{configure} to customize your installation.
@table @asis
@cindex options, ---prefix
@item --prefix=<path>
This defines the directory for the non-executable files such as
the manuals. The default is @strong{/usr}.
@cindex options, ---sbindir
@item --sbindir=<path>
This defines the directory for the executable files such as
apcupsd. The default is
@file{/sbin}. You may be tempted to
place the executable files in @file{/usr/sbin} or
@file{/usr/local/sbin}. Please
use caution here as these directories may be unmounted during a
shutdown and thus may prevent the @code{halt} script from
calling apcupsd to turn off the UPS power.
Though your data will be protected, in this case, your system will
probably not be automatically rebooted when the power returns.
@cindex options, ---enable-powerflute
@item --enable-powerflute
This option enables the building of the
powerflute executable, which is a ncurses
based program to monitor the UPS. This program is not necessary for
the proper execution of apcupsd.
@cindex options, ---enable-cgi
@item --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.
@item --with-cgi-bin=<path>
The with-cgi-bin configuration option allows you to define the
directory where the CGI programs will be installed. The default
is @file{/etc/apcupsd}, which is probably not
what you want.
@item --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.
@item --enable-master-slave
Turns on the master/slave networking code (default). 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).
@item --enable-apcsmart
Turns on generation of the APC Smart driver (default).
@item --enable-dumb
Turns on generation of the dumb signalling driver code
(default).
@item --enable-usb
Turns on generation of the Linux (only) USB driver code. By
default this is disabled.
@item --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
configured master using the NIS (Network Information Services)
interface.
@item --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.
@item --enable-test
This turns on a test driver that is used only for debugging.
By default it is disabled.
@item --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.
@item --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 efficient that the standard version being
one third the data size and less overhead locking and coping shared
memory. This option is @emph{highly} recommended for
Windows builds.
@item --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
configure
will determine where the libraries are on most systems.
@item --with-nologin=<path>
This option allows you to specify where
apcupsd will
create the nologin file when logins are prohibited. The default is
@file{/etc}
@item --with-pid-dir=<path>
This option allows you to specify where
apcupsd will
create the process id (PID) file to prevent multiple copies from
running. The default is system dependent but usually
@file{/var/run}.
@item --with-log-dir=<path>
This option allows you to specify where
apcupsd will
create the EVENTS and STATUS log files. The default is
@file{/etc/apcupsd}. This option simply sets the default
of the appropriate path in the @file{apcupsd.conf} file,
which can be changed at any later time.
@item --with-lock-dir=<path>
This option allows you to specify where
apcupsd will create the serial port lock file.
The default is systemdependent but usually
@file{/var/lock}. This option simply sets the
appropriate path in the @file{apcupsd.conf} file,
which can be changed at any later time.
@item --with-pwrfail-dir=<path>
This option allows you to specify where
apcupsd will create the
@file{powerfail} file when a power failure occurs. The
default is system dependent but usually @file{/etc}.
@item --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 @file{/dev/ttyS0}. This option simply sets
the appropriate device name in the @file{apcupsd.conf}
file, which can be changed at any later time.
@item --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 officially assigned to
apcupsd by the IANA. This option
simply sets the appropriate port in the
@file{apcupsd.conf} file, which can be changed at
any later time.
@item --with-nisip=<IP-Address>
This option allows you to specify the value that will be placed
on then NISIP directive in the configuration file. 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.
@item --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
@file{apcupsd.conf} file, which can be changed at any
later time.
@item --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
@file{apcupsd.conf} file, which can be changed at any later
time.
@item --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
@file{apcupsd.conf}
file, which can be changed at any later time.
@item --disable-install-distdir
This option modifies the apcupsd
Makefiles disable installation of the distribution (platform) directory.
Generally, this used to do a full installation of
apcupsd except the
final modification of the operating system files (normally
@file{/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 files.
@end table
@node Recommended Options for most Systems, Compilers and Options, Configure Options, Building and Installing apcupsd
@section Recommended Options for most Systems
For most systems, we recommend the following options:
@example
./configure --prefix=/usr --sbindir=/sbin --enable-usb \
--enable-pthreads
@end example
and you can optionally build and install the CGI programs as
follows:
@example
./configure --prefix=/usr --sbindir=/sbin --enable-usb \
--enable-cgi --with-cgi-bin=/home/httpd/cgi-bin \
--enable-pthreads
@end example
@node Compilers and Options, Operating System Specifics, Recommended Options for most Systems, Building and Installing apcupsd
@section Compilers and Options
@cindex compiler options
Some systems require unusual options for compilation or linking
that the @code{./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:
@example
CFLAGS="-O2 -Wall" LDFLAGS= ./configure
@end example
Or on systems that have the @code{env} program,
you can do it like this:
@example
env CPPFLAGS=-I/usr/local/include LDFLAGS=-s ./configure
@end example
Or for example on the Sun Solaris system, you can use:
@example
setenv CFLAGS -O2
setenv LDFLAGS -O
./configure
@end example
You can get a listing of all available options by doing:
@example
./configure --help
@end example
or simply see the previous section of this manual.
@node Operating System Specifics, , Compilers and Options, Building and Installing apcupsd
@section Operating System Specifics
@cindex OSes
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
find that a lot of very valuable work has been already done to make
your installation much easier (and probably totally automatic).
Below, you will find a list of operating systems for which we
have received installation files:
@itemize
@item
Alpha (@pxref{Alpha})
@item
Debian (@pxref{Debian})
@item
FreeBSD (@pxref{FreeBSD})
@item
HPUX (@pxref{HPUX})
@item
NetBSD (@pxref{NetBSD})
@item
OpenBSD (@pxref{OpenBSD})
@item
Red Hat (@pxref{Red Hat Systems})
@item
Slackware (@pxref{Slackware})
@item
SUSE (@pxref{SUSE})
@item
Solaris (@pxref{Sun Solaris})
@item
unknown (@pxref{Unknown System})
@item
Win32 (@pxref{Windows Systems with CYGWIN Installed})
@end itemize
@menu
* Alpha::
* Debian::
* FreeBSD::
* HPUX::
* NetBSD::
* OpenBSD::
* Red Hat Systems::
* Slackware::
* SUSE::
* Sun Solaris::
* Unknown System::
* Windows Systems with CYGWIN Installed::
@end menu
@node Alpha, Debian, , Operating System Specifics
@subsection Alpha
@cindex Alpha
@cindex OS, 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
differences. Unless you are a system guru, we recommend that you
connect your UPS to the second serial port
@file{/dev/tty01} to avoid conflicts with the console
device.
@example
DEVICE /dev/tty01
@end example
In addition, you should ensure serial port lock file in
@file{apcupsd.conf} is defined as:
@example
LOCKFILE /var/spool/locks
@end example
Unlike the Linux systems, the system halt routine is located in
@file{/sbin/rc0}, so after the @code{make
install}, please check that this file has been correctly
updated.
The start/stop script can be found in:
@example
/sbin/init.d/apcupsd
@end example
@node Debian, FreeBSD, Alpha, Operating System Specifics
@subsection Debian
@cindex Debian
@cindex OS, 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:
@file{<src>/distributions/debian/examples/} and
@file{<src>/distributions/debian/packageinfo}
You can also find the official Debian packages on the Debian
site at:
@itemize
@item
@uref{http://packages.debian.org/stable/admin/apcupsd.html,http://packages.debian.org/stable/admin/apcupsd.html}
@item
@uref{http://packages.debian.org/testing/admin/apcupsd.html,http://packages.debian.org/testing/admin/apcupsd.html}
@item
@uref{http://packages.debian.org/unstable/admin/apcupsd.html,http://packages.debian.org/unstable/admin/apcupsd.html}
@end itemize
@node FreeBSD, HPUX, Debian, Operating System Specifics
@subsection FreeBSD
@cindex FreeBSD
@cindex OS, 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 efficient (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 off 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 sufficiently long so that
you system will power down (usually 2 minutes), the use the
@code{kill-on-powerfail} option on the
apcupsd command line.
Please note the concerns listed below under OpenBSD concerning
the use of pthreads.
@node HPUX, NetBSD, FreeBSD, Operating System Specifics
@subsection HPUX
@cindex HPUX
@cindex OS, HPUX
We have no reports from testing this yet on version 3.8.4, but
worked fine on 3.8.1
@node NetBSD, OpenBSD, HPUX, Operating System Specifics
@subsection NetBSD
@cindex NetBSD
@cindex OS, 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.
@node OpenBSD, Red Hat Systems, NetBSD, Operating System Specifics
@subsection OpenBSD
@cindex OpenBSD
@cindex OS, OpenBSD
Ensure that you read the
@file{distributions/openbsd/README} file before running
apcupsd. There are some critical differences 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 deficiencies or errors in the OpenBSD
pthreads libraries, if you build apcupsd on OpenBSD with pthread and a
child program is launched (i.e. mail notification 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 notification routines from
@file{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 non-blocking. So when apcupds does I/O,
the userland pthreads libarary will switch to another thread if it
wants to run. This works fine except that when a child process is
called and it exits, all the blocking/non-blocking statuses of
the open file descriptors in the parent program are reset as
blocking -- this causes chaos and an almost immediate freezing
of the program (apcupsd).
@node Red Hat Systems, Slackware, OpenBSD, Operating System Specifics
@subsection Red Hat Systems
@cindex Red Hat
@cindex OS, Red Hat
Red Hat systems are fully supported, and by following the
standard installation instructions given above, you should experience
few or no problems.
@node Slackware, SUSE, Red Hat Systems, Operating System Specifics
@subsection Slackware
@cindex Slackware
@cindex OS, Slackware
Slackware systems are fully supported, and by following the
standard installation instructions given above, you should experience
few or no problems.
@node SUSE, Sun Solaris, Slackware, Operating System Specifics
@subsection SUSE
@cindex SuSE
@cindex OS, SuSE
SUSE systems are fully supported, and by following the
standard installation instructions given above, you should experience
few or no problems.
@node Sun Solaris, Unknown System, SUSE, Operating System Specifics
@subsection Sun Solaris
@cindex Sun
@cindex Solaris
@cindex OS, Solaris
Please read this before attempting to compile or install the
beta software. It contains important information that will make your
efforts easier.
If you find 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 @emph{may contain
bugs that can damage your system and data files!} You must
accept all responsibility for running this software. An unexpected
power-off 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-specific instructions. Then
come back and read this section before attempting to build the
package.
For building the system, we suggest that you run the configure
and make processes as your normal UNIX user ID. The @code{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
configure. If you do not have an environment setup to run the
compiler first, configure will fail.
Before running @code{./configure}, please be sure
that you do not have @file{/usr/ucb} on your path. This
may cause the @code{./configure} to choose the wrong
shutdown program. If @code{./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 file, 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 off 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,
@file{/sbin} is the default. However, please be aware
that if you want to follow Sun's filesystem conventions you would use
the following:
@example
./configure \
--prefix=/opt/apcupsd \
--sbindir=/etc/opt/apcupsd/sbin \
--sysconfdir=/etc/opt/apcupsd \
--with-cgi-bin=/opt/apcupsd/cgi-bin
@end example
The way to setup the @file{/sbin} directory as the
executables directory is to pass configure the @strong{sbindir=/sbin} option. No other arguments
should be required, and your setup and platform should be detected
automatically by configure.
Once you have run configure, you will need to do a
@code{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 @code{make install} step as:
@example
/usr/ccs/bin/make install
@end example
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 final
sync, we need to modify a system script. This script is
@file{/sbin/rc0}.
We do not have access to every version of Solaris, but we
believe this file will be almost identical on every version. Please
let us know if this is not true.
At the very end of the @file{/sbin/rc0} script,
you should find lines just like the following:
@example
# 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.'
@end example
We need to insert the following lines just before the last 'echo':
@example
#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
fi
@end example
We have included these lines in a file called
@file{rc0.solaris} in the distributions/sun subdirectory
of the source tree. You can cut and paste them into the /sbin/rc0 file
at the correct place, or yank and put them using vi or any other
editor. Note that you must be root to edit this file.
You must be absolutely sure you have them in the right place. If
your @file{/sbin/rc0} file does not look like the lines
shown above, do not modify the file. Instead, email a copy of the file
to the maintainers, and we will attempt to figure out what you should
do. If you mess up this file, 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 first 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 @file{/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
@file{/etc/apcupsd/apcupsd.conf} file. This file
contains the configuration 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
@file{/dev/ttya} and @file{/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:
@example
eeprom com1-noprobe=true
@end example
or
@example
eeprom com2-noprobe=true
@end example
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
@file{/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 first 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 off if your
configuration 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.
@node Unknown System, Windows Systems with CYGWIN Installed, Sun Solaris, Operating System Specifics
@subsection Unknown System
@cindex Unknown System
@cindex OS, Unknown System
During the @code{./configure}, if
apcupsd does not find one of the systems
for which it has specific installation programs, it will set the
Operating System to @strong{unknown} and will
use the incomplete installation scripts that are in @file{
<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 file for @emph{Linux From
Scratch}, which could be helpful for other systems as
well.
@node Windows Systems with CYGWIN Installed, , Unknown System, Operating System Specifics
@subsection Windows Systems with CYGWIN Installed
@cindex Windows
@cindex OS, Windows
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 @strong{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 @code{./configure}
command with the following options:
@example
./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
@end example
After which, you can do a:
@example
make
@end example
And to install apcupsd, do:
@example
make install
@end example
Finally, you should follow the Win32 (@pxref{Installation on Windows}) installation instruction, skipping the
part that describes unZipping the binary release.
@node After Installation, Configuration Examples, Building and Installing apcupsd, Basic User's Guide
@chapter After Installation
@cindex After Installation
@cindex Installation, After installing
@menu
* Checking Your Configuration File::
* Arranging for Reboot on Power-Up::
* Making sure apcupsd Is Running::
@end menu
@node Checking Your Configuration File, Arranging for Reboot on Power-Up, , After Installation
@section Checking Your Configuration File
@cindex Checking Conf file
Once you have installed apcupsd, either
from a binary package or by building from source, your next step
should be to inspect your @file{/etc/apcupsd/apcupsd.conf}
file to make sure it is valid.
You can read the complete reference on configuration
directives (@pxref{Configuration Directive Reference}), but if you are setting up a normal standalone
configuration you should only need to check (and possibly fix) the
first 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 (@pxref{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 field blank and apcupsd
will search all the standard locations for the UPS. You
may also explicitly specify the device location as
either @file{/dev/usb/hid/hiddev[0-15]} (on non-Red-Hat
systems) or @file{/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 finds 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 different device node, which happens occasionally during
short power failures. Again, it is highly recommended to leave the
DEVICE directive blank and let apcupsd find your device automatically.
If the first time you execute apcupsd, you get
a message to the effect that the Apcupsd USB driver is missing, it means
that you most likely forgot to put @emph{--enable-usb} on
your @file{./configure} command line. If you loaded
apcupsd from an rpm file, you may have
selected the wrong one -- please ensure that the word @emph{usb}
appears in the rpm package name.
The next chapter (@pxref{Configuration Examples}) of this
manual provides you with the essential characteristics of each main type
of configuration file. After those elements are correct, apcupsd should
run, and then it is only a matter of customization of your setup.
@node Arranging for Reboot on Power-Up, Making sure apcupsd Is Running, Checking Your Configuration File, After Installation
@section Arranging for Reboot on Power-Up
@cindex Reboot on power up
@cindex Power up, reboot
The final 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 off 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 find and change the
appropriate configuration parameter to permit instant power
on.
Normally, this is located under the @strong{BOOT} menu item, and will be called something
such as @strong{Restore on AC/Power Loss} or
@strong{Full-On}. The exact words will vary
according to the ROM BIOS provider. Generally you will have three
options: @strong{Last State}, @strong{Power On}, and @strong{Power
Off}. Although @strong{Last State}
should normally work, we recommend setting your computers to @strong{Power On}. This means that whenever the power is
applied they are on. The only way to shut them off is to pull the plug
or to have a special program that powers them off
(@file{/sbin/poweroff} 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 (@file{/etc/rc.d/init.d/halt} in the case of
Red Hat Linux) and see if the final line that performs the halt or
reboot contains the @code{-p} option for powering down the
computer. It should not with the logic used by
apcupsd, but if it does, the
@code{-p} option could cause your computer to power off
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.
@node Making sure apcupsd Is Running, , Arranging for Reboot on Power-Up, After Installation
@section Making sure apcupsd Is Running
@cindex Checking running
The simplest way to invoke apcupsd
is from the command line by entering:
@example
/sbin/apcupsd
@end example
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 file that
you will be automatically invoked when your system reboots. On other
systems, you will have to invoke apcupsd
from your @file{rc.local} script.
On Red Hat systems, this script file that automatically invokes
apcupsd on system start and stops is:
@file{/etc/rc.d/init.d/apcupsd}
To start apcupsd manually (as you
will probably do immediately following the installation), enter the
following:
@example
/etc/rc.d/init.d/apcupsd start
@end example
To understand how this file is automatically invoked at system
startup and shutdown, see the man pages for chkconfig(8).
On SUSE systems, the script file that automatically invokes
apcupsd on system start and stops is
@file{/etc/rc.d/apcupsd}
To start apcupsd manually (as you
will probably do immediately following the installation), enter the
following:
@example
/etc/rc.d/apcupsd start
@end example
Normally, when properly installed,
apcupsd will be started and stopped
automatically by your system. Unfortunately, the details are different
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:
@example
/etc/rc.d/init.d/apcupsd stop
@end example
On SUSE systems:
@example
/etc/rc.d/apcupsd stop
@end example
Please see the Testing Apcupsd (@pxref{Testing Apcupsd}) chapter for more
details on insuring that apcupsd is running
properly.
@node Configuration Examples, Testing Apcupsd, After Installation, Basic User's Guide
@chapter Configuration Examples
@cindex Configuration, Examples
@cindex Examples, Configuration
@menu
* A Simple USB Configuration::
* A Simple Configuration for a SmartUPS::
* A Simple Configuration for a Simple Signaling or Dumb::
* A Simple Master Configuration::
* A Simple Slave Configuration::
* Variation on the Master/Slave Configuration::
* A Sample NIS Slave Configuration Using the Net Driver::
@end menu
@node A Simple USB Configuration, A Simple Configuration for a SmartUPS, , Configuration Examples
@section A Simple USB Configuration
@cindex Configuration, USB
@cindex USB, configuration
@cindex Example, USB conf
If you have a USB UPS, and you have apcupsd version 3.10.7 or higher,
the essential elements of your apcupsd.conf file should look like the
following:
@example
## apcupsd.conf v1.1 ##
UPSCABLE usb
UPSTYPE usb
DEVICE
LOCKFILE /var/lock
UPSCLASS standalone
UPSMODE disable
@end example
Notice that we have not specified 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:
@example
DEVICE /dev/usb/hid/hiddev[0-15]
@end example
If you have more than one device,
you may need to specify each device individually using
absolute device paths. This is not, however, recommended.
@example
DEVICE /dev/usb/hiddev0
@end example
Please use the explicit specifications of a device only if
your know exactly what you are doing. In general, it is much easier
to let apcupsd find the device itself.
If you use the range specification,
you should enter @strong{/dev/usb/hiddev[0-15]}
literally as shown. The "[0-15]" expression tells
apcupsd to search all hiddev devices until it finds 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 different device node.
On Debian systems, the @strong{hiddev} devices are not automatically defined.
As a consequence, you will need to run the @strong{make-hiddev} script in
the @strong{examples} directory of the source.
@node A Simple Configuration for a SmartUPS, A Simple Configuration for a Simple Signaling or Dumb, A Simple USB Configuration, Configuration Examples
@section A Simple Configuration for a SmartUPS
@cindex Configuration, SmartUPS
@cindex SmartUPS configuration
@cindex Example, SmartUPS conf
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
configuration file would look like the following:
@example
## apcupsd.conf v1.1 ##
UPSCABLE smart
UPSTYPE smartups
DEVICE /dev/ttyS0
LOCKFILE /var/lock
UPSCLASS standalone
UPSMODE disable
@end example
Normally you would have many more configuration directives to
completely customize your installation, but this example shows you
the minimum required.
@node A Simple Configuration for a Simple Signaling or Dumb, A Simple Master Configuration, A Simple Configuration for a SmartUPS, Configuration Examples
@section A Simple Configuration for a Simple Signaling or Dumb
@cindex Configuration, dumb
@cindex dumb, configuration
@cindex Example, dumb conf
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 first power failure, your
computer will be immediately shutdown. This is an unfortunate consequence
of the dumb signaling mode. To avoid this, first replace
@strong{/etc/apcupsd/apccontrol} with @strong{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 file and test that your computer is correctly
shutdown during a power failure.
@example
## apcupsd.conf v1.1 ##
UPSCABLE (number of cable you have)
UPSTYPE dumb
DEVICE /dev/ttyS0
LOCKFILE /var/lock
UPSCLASS standalone
UPSMODE disable
@end example
If your cable does not have low battery detection, as is the
case with some older models, you will also need to define
@strong{TIMEOUT nnn} where you set @strong{nn} to be the number of
seconds on a power failure after which a shutdown is effected.
Normally you would have many more configuration directives to
completely customize your installation, but this example shows you
the minimum required.
@node A Simple Master Configuration, A Simple Slave Configuration, A Simple Configuration for a Simple Signaling or Dumb, Configuration Examples
@section A Simple Master Configuration
@cindex Configuration, Master
@cindex Master, config example
@cindex Example, Master conf
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 configuration file would look like the
following:
@example
## 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
@end example
Note, the main difference from the stand alone configuration is
that you have specified @strong{UPSCLASS netmaster} and
@strong{UPSMODE net}. In addition, you have specified 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
notified 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
configure. See: @pxref{A Sample NIS Slave Configuration Using the Net Driver}
below for details.
@node A Simple Slave Configuration, Variation on the Master/Slave Configuration, A Simple Master Configuration, Configuration Examples
@section A Simple Slave Configuration
@cindex Slave Configuration
@cindex Configuration, Slave
@cindex Example, Slave conf
You have a Smart UPS using the cable supplied by APC that is
connected to the master machine configured 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 configuration file would look like the following:
@example
## apcupsd.conf v1.1 ##
UPSCABLE ether
UPSTYPE smartups
LOCKFILE /var/lock
UPSCLASS netslave
UPSMODE net
NETPORT 6666
MASTER master.mynetwork.com
@end example
The main difference from the master configuration is that you
have specified @strong{UPSCABLE ether} and
@strong{UPSCLASS netslave}. In addition, you
have specified a single controlling master.
Please note, there are reports that you @strong{must} use
@strong{UPSTYPE smartups} on the slave even if the master
is using @strong{UPSTYPE dumb}. This is apparently some bug
in the new dumb driver.
In this configuration, the shutdown will be initiated by the
master. It is also possible to specify BATTERYLEVEL, MINUTES, and
TIMEOUT configuration 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.
@node Variation on the Master/Slave Configuration, A Sample NIS Slave Configuration Using the Net Driver, A Simple Slave Configuration, Configuration Examples
@section Variation on the Master/Slave Configuration
@cindex Master/Slave variation
It is also possible to have a Master/Slave configuration where
the Slave is powered by a different 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
configuration files shown above. The only difference is where
the slave actually receives its power. In effect, apcupsd does
not know or care where the power really comes from.
@node A Sample NIS Slave Configuration Using the Net Driver, , Variation on the Master/Slave Configuration, Configuration Examples
@section A Sample NIS Slave Configuration Using the Net Driver
@cindex Example, NIS slave
@cindex NIS slave conf
@cindex Configuration, NIS slave conf
As opposed to the old master/slave mode demonstrated above, you can
turn any computer into an NIS slave by configuring with the NIS network
driver turned on @code{--enable-net}. The difference 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 configuration, 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 configuration is a simple standalone
as in the section @strong{A Simple Configuration 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 configuration that
looks something like what follows. What is important is that you
get the information from an @strong{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 difference
between the Master/Slave networking and the NIS-based networking:
Think of the difference as push (Master/Slave) vs. pull (NIS-based). In the
case of M/S, the master makes all the shutdown decisions and notifies 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 config 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 configuration files to keep in sync.
I also like the flexibility 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 vice-versa.
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 firewall. 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
firewall just be a client of it. That way I don't have to run NIS on the
firewall apcupsd instance.
@example
## apcupsd.conf v1.1 ##
UPSCABLE ether
UPSTYPE net
LOCKFILE /var/lock
DEVICE server-network-address:3551
UPSCLASS standalone
UPSMODE disable
NETTIME 10
@end example
where on the @strong{DEVICE} directive
you replace the @code{server-network-address} with the fully
qualified 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 configuration 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 @strong{NETTIME} directive defines 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 flag, 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 configuration, any slave run using
the Net driver will shutdown when its own timers expire or when
the NIS server shuts down, whichever occurs first. 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 defined on the NIS server.
@node Testing Apcupsd, Troubleshooting Your Installation, Configuration Examples, Basic User's Guide
@chapter Testing Apcupsd
@cindex Testing
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
different, and you should see the section on Testing Serial UPSes
(@pxref{Testing Serial-Line UPSes}).
@menu
* Process-Status Test::
* Logging Test::
* apcaccess Test::
* Communications Test::
* Simulated Power Fail Test::
* System Shutdown Test::
* Full Power Down Test::
* Shutdown Sequence::
* apctest::
@end menu
@node Process-Status Test, Logging Test, , Testing Apcupsd
@section Process-Status Test
@cindex Process Status Testing
@cindex Testing, Process Status
After you start apcupsd, execute the
following command:
@example
ps fax
@end example
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.
@example
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
@end example
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 @strong{ps} line.
@table @asis
@item apcmain
is the main program that waits until it receives a termination
signal (SIGTERM) or one of the child processes dies.
@item 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.
@item apcnis
is the Network information server process that provides EVENTS
and STATUS information over the network. This information is used
by the CGI programs.
@end table
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:
@example
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
@end example
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 find that apcupsd is in the above list, the most
likely problem is a configuration file glitch. If no messages
were printed, you should check your system log (normally
@file{/var/log/messages} where you will find one or messages
indicating the nature of the problem.
@node Logging Test, apcaccess Test, Process-Status Test, Testing Apcupsd
@section Logging Test
@cindex Testing, Logging
@cindex Logging, Testing
Once you have established that the proper processes are running,
do a tail of the system log file, normally
@file{/var/log/messages}:
@example
tail /var/log/messages
@end example
You should see output that looks similar to the following:
@example
Dec 5 17:01:05 matou apcupsd[5917]: apcupsd 3.7.2
startup succeeded
@end example
And if you have configured the network information server, you
should also see:
@example
Dec 5 17:01:05 polymatou apcupsd[5975]: apcserver
startup succeeded
@end example
These messages should also appear in the temporary file
(@file{/etc/apcupsd/apcupsd.events}) if you are using
the default configuration file. If you have installed the RPM, they
will probably be in @file{/var/log/apcupsd.events}.
@node apcaccess Test, Communications Test, Logging Test, Testing Apcupsd
@section apcaccess Test
@cindex Testing, apcaccess
@cindex apcaccess Test
This test consists of running @code{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 @code{--enable-pthreads} on the
@code{./configure} line), you must enable the apcupsd Network
Information Server in your configuration file for
@strong{apcaccess} to work. This is done by setting:
@example
NETSERVER on
NISPORT 3551
@end example
@noindent
in your @strong{apcupsd.conf} file.
To run the apcaccess test, use the following command:
@example
apcaccess status
@end example
Depending on the type of UPS you have, you will get slightly
different output, but an example For a Smart-UPS is as follows:
@example
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
@end example
For a simple signaling or dumb UPS such as BackUPS, your output
will be very minimal as follows:
@example
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
@end example
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
file to -1.
@table @asis
@item 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.
@item BATTV
Unless you have additional battery packs, this should be near
24 Volts plus or minus 5 Volts.
@item STATUS
This is the status of the UPS and it should normally be
@strong{ONLINE}.
@end table
If you see a message to the effect of:
@example
attach_shmarea: shared memory version mismatch (or UPS not yet ready to report)
@end example
or if all the displayed values are zero, you have not waited
long enough. Wait a bit longer and then re-execute the
@code{apcaccess status} command.
If you see a message to the effect of:
@example
APCACCESS FATAL ERROR in apcaccess.c at line 336
tcp_open: cannot connect to server localhost on port 3551.
@end example
It means that you have probably not enabled the
Network Information Server in your
configuration file for @strong{apcaccess} to
work. This is done by setting:
@example
NETSERVER on
NISPORT 3551
@end example
@noindent
in your @strong{apcupsd.conf} file.
@node Communications Test, Simulated Power Fail Test, apcaccess Test, Testing Apcupsd
@section Communications Test
@cindex Testing, Communications
@cindex Communications Testing
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
voltage-signaling 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 @strong{apccontrol}
script (normally in @file{/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 @code{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 file
(@file{/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
@emph{no} (see @strong{man
wall} or @strong{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 @code{wall} messages. However, you should
find them in your system log file (normally
@file{/var/log/messages} and in the temporary EVENTS
file, @file{/etc/apcupsd/apcupsd.events}. For example,
to observe these events in the temporary EVENTS file, you might do
a
@example
tail -f /etc/apcupsd/apcupsd.events
@end example
Note, if you have installed from the RPM, the proper events
file may be @file{/var/log/apcupsd.events}. You can
find the actual filename by checking your @file{apcupsd.conf}
file.
before running the test.
If you do not observe these messages, you should correct this
problem before proceeding with additional tests.
@node Simulated Power Fail Test, System Shutdown Test, Communications Test, Testing Apcupsd
@section Simulated Power Fail Test
@cindex Testing, Simulate Power Fail
@cindex Simulate 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, @file{/etc/apcupsd/apccontrol}. Move this
script to another location e.g. @file{apccontrol.save}
and replace it with the script found in
@file{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 @strong{BATTCHG} and @strong{TIMELEFT} variables in the printout of
@code{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 filesystem 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 first
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 first should
appear after 5 to 6 seconds and read:
@example
Warning power loss detected.
@end example
Then generally 6 seconds later,
apcupsd is sure that it isn't a transient
effect, so it sends:
@example
Power failure. Running on UPS batteries.
@end example
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:
@example
Power has returned...
@end example
If you do not observe the above messages, please correct the
situation before proceeding. The most likely cause of problems
are:
@itemize
@item
apcupsd doesn't recognize the
power failure because the configuration directives are not
correct. E.g. wrong cable.
@item
The file @file{/etc/apcupsd/apccontrol} doesn't
exist or is not marked as executable.
@end itemize
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 configuration file @file{apcupsd}
and change the value of @strong{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 configuration value to take effect.
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 @code{wall} or by the
@code{tail -f} command. The precise message is determined
by what is printed in @file{/etc/apcupsd/apccontrol} for
the @strong{doshutdown} event. Though it
varies from system to system, it will generally be something
like:
@example
Beginning Shutdown Sequence
@end example
When apcupsd this message prints,
reconnect the power. apcupsd should detect
that the power has been restored and attempt to cancel the
shutdown.
@strong{IMPORTANT} after this test,
please replace the changed apccontrol and
@file{apcupsd.conf} with the original files.
@node System Shutdown Test, Full Power Down Test, Simulated Power Fail Test, Testing Apcupsd
@section System Shutdown Test
@cindex System Shutdown test
@cindex Testing, System Shutdown
This is an intermediate test that you can do, for all UPS models
before doing the Full Power Down Test. First modify the
@file{/etc/apcupsd/apccontrol} file so that in the
@strong{killpower)} case, the line that
re-executes apcupsd with the
@code{--killpower} option is commented out. The original
line probably looks something like:
@example
$@{APCUPSD@} --killpower
@end example
when it is commented out, it looks like:
@example
#$@{APCUPSD@}--killpower
@end example
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
@file{/etc/apcupsd/apccontrol} to its previous
state.
@node Full Power Down Test, Shutdown Sequence, System Shutdown Test, Testing Apcupsd
@section Full Power Down Test
@cindex Power down test
@cindex Testing, Power down
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 @code{apcupsd --killpower} when it
detects a power failure situation (the presence of a
@file{/etc/powerfail} file). See the @ref{Building and Installing apcupsd} of this manual, or the README files for
additional details about the halt modifications 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 @strong{TIMEOUT} configuration directive to something
like 60 so that the system will shutdown before the batteries are
exhausted. We recommend doing the full shutdown without using
@strong{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 off
by apcupsd. Please be aware that if you do
the full power down, you must ensure that your UPS is totally powered
off. Otherwise, it may have been given the command to power off, 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 off the power (this happened to me). To avoid this problem,
always wait for your UPS to power itself off, or power if off manually
before restarting your computer. On my system, the UPS is configured
as at the factory to have a 180 second grace period before shutting
off the power. During this type of testing, 180 seconds @strong{seems} like an eternity, so please take care to
either wait or manually power off your UPS. To determine what grace
period is programmed into your UPS EEPROM, run @code{apcaccess
eprom} and look at the "Shutdown grace
delay".
@node Shutdown Sequence, apctest, Full Power Down Test, Testing Apcupsd
@section Shutdown Sequence
@cindex 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 (@pxref{Shutdown Sequence <1>}) section of
this manual.
@node apctest, , Shutdown Sequence, Testing Apcupsd
@section apctest
@cindex 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 @ref{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 @strong{/etc/apcupsd/apcupsd.conf} file has @strong{UPSTYPE smart} and @strong{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
@file{<apcupsd-source>/src} directory. You can
explicitly build it on Unix with:
@example
cd <apcupsd-source-directory>
make apctest
./apctest
@end example
or on Windows systems with:
@example
make apctestwin32
./apctest
@end example
It will read your installed apcupsd.conf configuration
(so it knows where to find the UPS) and then
it will present you with the following output:
@example
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
@end example
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
firmware. 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 @ref{Configuration Directives Used to Set the UPS EPROM,,Configuration 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 (@pxref{APC smart protocol}) chapter of this manual.
Item 7 will terminate apctest.
@node Troubleshooting Your Installation, Monitoring and Tuning your UPS, Testing Apcupsd, Basic User's Guide
@chapter Troubleshooting Your Installation
@cindex Troubleshooting (see problems)
@cindex Problems
@menu
* Known Problems with USB UPSes::
@end menu
@node Known Problems with USB UPSes, , , Troubleshooting Your Installation
@section Known Problems with USB UPSes
@cindex Problems, USB
@menu
* Some Cheaper Models Do Not Have Battery Charge::
* Reconnection does not clean up the lockfile::
* Power Off (killpower) of UPS Does Not Work: Power Off [killpower] of UPS Does Not Work.
* apcupsd Cannot Reconnect After a Reboot::
@end menu
@node Some Cheaper Models Do Not Have Battery Charge, Reconnection does not clean up the lockfile, , Known Problems with USB UPSes
@subsection Some Cheaper Models Do Not Have Battery Charge
@cindex Problems, no Battery charge
Unfortunately, some cheaper USB models do not seem to report
BCHARGE in the apcaccess output listing, which means with a
standard conf file, your system will be immediately shutdown.
To correct this, set the BATTERYLEVEL directive in your apcupsd.conf
file 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.
@node Reconnection does not clean up the lockfile, Power Off [killpower] of UPS Does Not Work, Some Cheaper Models Do Not Have Battery Charge, Known Problems with USB UPSes
@subsection Reconnection does not clean up the lockfile
@cindex Problems, lock file not cleaned up
If either you disconnect the UPS or it disconnects because of
some electrical problem, it will most certainly reconnect with a
different device number. Apcupsd will detect this and reconnect
properly. However, apcupsd does not release
the old device (USB port) lock file and create a new one. This is
not too serious.
@node Power Off [killpower] of UPS Does Not Work, apcupsd Cannot Reconnect After a Reboot, Reconnection does not clean up the lockfile, Known Problems with USB UPSes
@subsection Power Off (killpower) of UPS Does Not Work
@cindex Problems, Power off
@cindex Problems, killpower
Currently (as of 3.10.6) the code to power off 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.
@node apcupsd Cannot Reconnect After a Reboot, , Power Off [killpower] of UPS Does Not Work, Known Problems with USB UPSes
@subsection apcupsd Cannot Reconnect After a Reboot
@cindex Problems, reconnect
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, fiddling around
until you get apcupsd to work with the UPS,
then doing @code{cat /proc/modules} andnd save the output
some place. Then reboot your computer and before you do anything else,
do the @code{cat /proc/modules} again. Most likely you
will find some of the usb modules are missing in the second listing.
There are two solutions:
@itemize
@item
Ensure that you have the hotplug program loaded. It should fix
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 @code{cp /etc/hotplug/usb.rc
/etc/init.d/hotplug} to get it fully working.
@item
You can explicitly force the appropriate usb modules to be
loaded by adding:
@example
/sbin/modprobe <missing-module-name>
@end example
in the @file{/etc/rc.d/init.d/apcupsd} script
just after the @strong{start)} case (at about
line 17). This will force the modules to be loaded before apcupsd is
invoked.
@end itemize
@node Monitoring and Tuning your UPS, Maintaining Your UPS, Troubleshooting Your Installation, Basic User's Guide
@chapter Monitoring and Tuning your UPS
@cindex Monitoring
@cindex Tuning
After you have verified 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.
@menu
* apcaccess::
* Apcupsd Notification and Events::
* hid-ups and USB Specific Information::
* apcupsd Network Monitoring (CGI) Programs: apcupsd Network Monitoring [CGI] Programs.
* Setting up and Testing the CGI Programs::
* Configuring Your EEPROM::
@end menu
@node apcaccess, Apcupsd Notification and Events, , Monitoring and Tuning your UPS
@section apcaccess
@cindex apcaccess
apcaccess is a program (normally found
in @file{/sbin/apcaccess}) that permits you to print out
the complete status of your UPS. Although there are a number of
command line arguments (@strong{eprom, reconfig,
status, slave, shutdown}), all except @strong{eprom} and @strong{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
@strong{status} and @strong{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 @strong{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:
@example
NETSERVER on
NISPORT 3551
@end example
@noindent
in your @strong{apcupsd.conf} file.
@menu
* apcaccess status::
* apcaccess eprom::
@end menu
@node apcaccess status, apcaccess eprom, , apcaccess
@subsection apcaccess status
@cindex apcaccess status
@cindex status, apcaccess
As mentioned above, the full form of the command is:
@example
apcaccess status localhost:3551
@end example
where only apcaccess status should normally
be needed. localhost may be replaced by any machine name, fully qualified
domain name, or IP address, which means that apcaccess
can access any UPS on the network running the Network Information Server.
The @strong{status} command line option
of apcaccess will produce a full printout
of all the @strong{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 (@pxref{apcupsd Status Logging}) section of the
Technical Reference.
Please note that if you invoke
apcaccess within the first 30 seconds of
launching apcupsd, you will likely get an
error message such as:
@example
APCACCESS FATAL ERROR in apcipc.c at line 325
attach_shmarea: shared memory version mismatch
@end example
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:
@example
apcaccess status
@end example
For a SmartUPS 1000 apcaccess will
emit the following output:
@example
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
@end example
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.
@node apcaccess eprom, , apcaccess status, apcaccess
@subsection apcaccess eprom
@cindex apcaccess eeprom
@cindex eeprom, apcaccess
The @strong{eprom} command line option
for apcaccess allows you to examine the
current values of your UPS' EPROM as well as to know the permitted
values that can be set in the EPROM. For information about changing
these values, see the section on tuning EEPROM
parameters (@pxref{Configuring Your EEPROM}).
A typical output from @code{apcaccess eprom} is:
@example
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
@end example
@node Apcupsd Notification and Events, hid-ups and USB Specific Information, apcaccess, Monitoring and Tuning your UPS
@section Apcupsd Notification and Events
@cindex Notification
@cindex Events
When a major event is generated within apcupsd,
control is passed to the script @file{apccontrol} normally
found in @file{/etc/apcupsd/apccontrol}. The event name,
and a number of other important parameters are passed to the script.
The major function of the @file{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 @file{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 @file{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 (@pxref{Customizing Event Handling}).
@node hid-ups and USB Specific Information, apcupsd Network Monitoring [CGI] Programs, Apcupsd Notification and Events, Monitoring and Tuning your UPS
@section hid-ups and USB Specific Information
@cindex hid-ups
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 first 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.
@node apcupsd Network Monitoring [CGI] Programs, Setting up and Testing the CGI Programs, hid-ups and USB Specific Information, Monitoring and Tuning your UPS
@section apcupsd Network Monitoring (CGI) Programs
@cindex Network monitoring
@cindex Monitoring
@cindex CGI programs
With this release, there are five CGI programs
(multimon.cgi,
multimoncss.cgi,
upsstats.cgi,
upsfstats.cgi, and
upsimage.cgi). To have them properly
installed, you must run the @code{./configure} command
with @code{--enable-cgi} and you should specify an
installation directory with @code{--with-cgi-bin=} or load
them manually. To install the Cascading Style Sheet, which is used by
multimoncss.cgi, you must use the
@code{--with-css-dir=} option. The default directory for
installation of the CGI programs is @file{/etc/apcupsd},
which is not really where you want them if you are going to use them.
Normally, they should go in the @file{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 @code{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.
@node Setting up and Testing the CGI Programs, Configuring Your EEPROM, apcupsd Network Monitoring [CGI] Programs, Monitoring and Tuning your UPS
@section Setting up and Testing the CGI Programs
@cindex Setup CGI programs
@cindex Testing CGI programs
@menu
* Network Information Server (NIS): Network Information Server [NIS].
* multimon.cgi: multimon_cgi.
* upsstats.cgi: upsstats_cgi.
* ./upsstats.cgi: _/upsstats_cgi.
* upsfstatus.cgi: upsfstatus_cgi.
* Working Example::
* Client Test Program::
* A Tip from Carl Erhorn for Sun Systems::
* Credits::
* Security Issues::
@end menu
@node Network Information Server [NIS], multimon_cgi, , Setting up and Testing the CGI Programs
@subsection Network Information Server (NIS)
@cindex Network Information Server
@cindex NIS
Before using multimon and the other
CGI programs, first ensure that apcupsd is
configured to run the Network Information Server. This is done by
setting @strong{NETSERVER on} in
@file{/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 @file{hosts} file
@file{/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 @file{multimon.conf} unmodified from what
is on the source distribution. However, he has modified the hosts.conf
file to contain the following three lines:
@example
MONITOR matou "Server"
MONITOR polymatou "Backup server"
MONITOR deuter "Disk server"
@end example
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
qualified domain names. The network name (or IP address) may
optionally be followed by @strong{:<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 differ. An example could be the following:
@example
MONITOR matou "Server"
MONITOR polymatou "Backup server"
MONITOR deuter "Disk server"
MONITOR polymatou:7001 "APC USB UPS"
@end example
where the USB copy of apcupsd has
been configured to use port 7001 (with
@code{--with-nis-port=7001} on the
@code{./configure} or by modifying
@file{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:
@example
./multimon.cgi
@end example
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
@file{hosts.conf} file. It should look something like
the following (note, only a small portion of the output is reproduced
here):
@example
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>
...
@end example
If you do not get similar output, check the permissions of the
@file{/etc/apcupsd} directory and of those of
@file{/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
@file{/etc/apcupsd/hosts.conf} and
@file{/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 @file{multimon.css} file
to specify the styles you prefer. There are several sample Style
Sheet files in the @file{cgi} subdirectory
of the source tree.
To see a working example of the these programs, visit @uref{http://www.apcuspd.com/cgi-bin/multimon.cgi,http://www.apcupsd.com/cgi-bin/multimon.cgi}
or @uref{http://www.apcupsd.com/cgi-bin/multimoncss.cgi,http://www.apcupsd.com/cgi-bin/multimoncss.cgi}
@node multimon_cgi, upsstats_cgi, Network Information Server [NIS], Setting up and Testing the CGI Programs
@subsection multimon.cgi
@cindex multimon
@cindex CGI, multimon
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:
@image{multimon,,,,png}
The machines monitored as well as the values and their column
headings are all configurable (see
@file{/etc/apcupsd/hosts.conf} and
@file{/etc/apcupsd/multimon.conf})
@node upsstats_cgi, _/upsstats_cgi, multimon_cgi, Setting up and Testing the CGI Programs
@subsection upsstats.cgi
@cindex upsstats
@cindex CGI, upsstats
By clicking on the @strong{system} name
in the @strong{multimon.cgi} display, you will
invoke upsstats.cgi for the specified
system, which will produce a bar graph display of three of the
monitored values. For example,
@image{status,,,,png}
You can display different bar graphs by selecting different
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 configured in the
@file{/etc/apcupsd/hosts.conf} file, you can execute it
from a Unix shell from the source cgi directory as follows:
@node _/upsstats_cgi, upsfstatus_cgi, upsstats_cgi, Setting up and Testing the CGI Programs
@subsection ./upsstats.cgi
@cindex upssstats
@cindex CGI, upssstats
As with multimon, quite a few lines
of html should then be displayed.
@node upsfstatus_cgi, Working Example, _/upsstats_cgi, Setting up and Testing the CGI Programs
@subsection upsfstatus.cgi
@cindex upsfstatus
@cindex CGI, upsfstatus
If you would like to see all of the STATUS variables available
over the network, click on the @strong{Data}
field of the desired system, and your browser will display something
like the following:
@example
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
@end example
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.
@node Working Example, Client Test Program, upsfstatus_cgi, Setting up and Testing the CGI Programs
@subsection Working Example
@cindex CGI, working example
@cindex Example, CGI
To see a working example of the above programs, visit @uref{http://www.apcupsd.com/cgi-bin/multimon.cgi,http://www.apcupsd.com/cgi-bin/multimon.cgi}.
@node Client Test Program, A Tip from Carl Erhorn for Sun Systems, Working Example, Setting up and Testing the CGI Programs
@subsection Client Test Program
@cindex 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
@file{client.c} and can be found in the
@file{examples} subdirectory of the source
distribution. To build the program, when in the examples directory,
use something like the following:
@example
cc client.c ../lib/libapc.a -o client
@end example
Then execute it:
@example
./client <host>[:<port>] [<command>]
@end example
Where @strong{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 @strong{status} or @strong{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: @strong{events} and
@strong{status}. Hence the following
commands:
@example
./client
status
events
xyz
^D
@end example
should produce the status listing (the same as produced by
@code{apcaccess status}), followed by the list of the last
10 events (in response to the @strong{events}
command), and finally @strong{Invalid command}
in response to the @strong{xyz} input, which
is not a valid command. The control-D terminates the @strong{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, ...).
@node A Tip from Carl Erhorn for Sun Systems, Credits, Client Test Program, Setting up and Testing the CGI Programs
@subsection A Tip from Carl Erhorn for Sun Systems
@cindex Tip
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
@node Credits, Security Issues, A Tip from Carl Erhorn for Sun Systems, Setting up and Testing the CGI Programs
@subsection Credits
Many thanks go to Russell Kroll <rkroll at exploits.org> who
wrote the CGI programs to work with his UPS Monitoring system named
@uref{http://www.exploits.org/nut/library/apcsmart.html,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.
@node Security Issues, , Credits, Setting up and Testing the CGI Programs
@subsection Security Issues
@itemize
@item
@strong{apcupsd} runs as root.
@item
If you have @strong{NETSERVER ON}
in your @file{apcupsd.conf} file (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 firewall
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 configuring TCP
wrappers in apcupsd (see below
for TCP Wrapper details).
@item
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 specified in your
configuration file.
@end itemize
@menu
* TCP Wrappers::
@end menu
@node TCP Wrappers, , , Security Issues
@subsubsection TCP Wrappers
@cindex Wrappers, TCP
@cindex TCP wrappers
As of apcupsd version 3.8.2, TCP Wrappers are implemented if you
turn them on when configuring (@code{./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 file:
@file{/etc/hosts.allow}. This code is implemented but
untested. If you use it, please send us some feedback.
@node Configuring Your EEPROM, , Setting up and Testing the CGI Programs, Monitoring and Tuning your UPS
@section Configuring Your EEPROM
@cindex eeprom, configuring
@cindex Configuring, eeprom
If you have a SmartUPS, there are depending on the UPS at least 12
different 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.
@menu
* apcupsd No Longer Configures EEPROM::
* Using apctest to Configure Your EEPROM::
@end menu
@node apcupsd No Longer Configures EEPROM, Using apctest to Configure Your EEPROM, , Configuring Your EEPROM
@subsection apcupsd No Longer Configures 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
modification 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 modifications 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 @code{apcaccess status} and also print a copy of
the output from @code{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:
@example
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
@end example
where the Current Value will depend on how your UPS is configured,
and the Permitted Values will depend on what UPS model you have.
@node Using apctest to Configure Your EEPROM, , apcupsd No Longer Configures EEPROM, Configuring Your EEPROM
@subsection Using apctest to Configure Your EEPROM
@cindex eeprom, apctest
@cindex apctest setting eeprom
To make the EEPROM changes with
apctest you must first 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:
@example
cd <apcupsd-source>/src
su
<root-password>
./apctest
@end example
At that point, you should get output similar to the following:
@example
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:
@end example
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:
@example
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:
@end example
If you wish to use the old pre-3.10.x method of EEPROM
programming with values specified in the
@file{apcupsd.conf} file, select option 14). However, we
recommend that you start with item 1) to see what EEPROM values
apctest finds. 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:
@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
@end example
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.
@node Maintaining Your UPS, Frequently-Asked Questions, Monitoring and Tuning your UPS, Basic User's Guide
@chapter Maintaining Your UPS
@cindex Maintenance
If you have your UPS long enough, you will probably have battery
problems. Below, you will find some suggestions for replacing
batteries. One @emph{important} note of caution: at
least one user purchased one of the non-APC batteries noted below and
found out that they would not fit 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.
@menu
* What Various People Have to Say about Batteries::
* Where Carl Suggests You Get Batteries::
@end menu
@node What Various People Have to Say about Batteries, Where Carl Suggests You Get Batteries, , Maintaining Your UPS
@section What Various People Have to Say about Batteries
@cindex Batteries
Here is what John Walker has to say about APC UPS batteries:
@quotation
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 find it the next time. I started installing mine in
1995-1996. Lead-acid batteries have a finite 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 off 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.
@end quotation
And Andre Hendrick says:
@quotation
[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.
@example
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
@end example
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:
@example
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
@end example
Look at the numbers and see that these batteries are better and
have more total running energy than standard ones.
@example
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.
@end example
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,
@example
Andre Hedrick
Linux ATA Development
@end example
@end quotation
Finally, here is what Carl Erhorn has to say about
batteries:
@quotation
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 first
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 flashed
spasmodically, as if something was loose inside the UPS.
I turned off the UPS and it's load, then turned the UPS on
again. This time, everything seemed fine. 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 offline, 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
fixed 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 off. 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 Smart-UPS 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 off 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 off 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 off 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 significantly.
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 five 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 five 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
(flashing 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 preconfigured 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
different 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 first, 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 off early,
and you don't want to do that during a recalibration run. When the
run is complete, and the UPS turns off, 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 off 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 differences 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 different 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
@end quotation
@node Where Carl Suggests You Get Batteries, , What Various People Have to Say about Batteries, Maintaining Your UPS
@section Where Carl Suggests You Get Batteries
@cindex Batteries
@quotation
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 office 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 find 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: @uref{http://www.batterywholesale.com,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 difference 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 find 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 find 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 find 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.
@example
Regards,
--Carl
@end example
@end quotation
Here is a link to the
@uref{http://www.batterywholesale.com/battery-store/APC-batteries/?PHPSESSID=10ba07023457efda6a3520af1957755f,APC Battery Store}.
@node Frequently-Asked Questions, Apcupsd Bugs, Maintaining Your UPS, Basic User's Guide
@chapter Frequently-Asked Questions
@cindex FAQ
See the bugs section of this document for a list of known
bugs and solutions.
@table @asis
@item @anchor{crazy}@ @ Q:
Why all the craziness with custom serial cables?
@item @ @ 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 straight-through 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.
@item @ @ Q:
What UPS brands does apcupsd
support?
@item @ @ A:
Currently apcupsd supports only
APC UPSes. However, some companies 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 configurations
sections of this document for more details.
@item @ @ Q:
Does apcupsd support Windows?
@item @ @ 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 deficiencies 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.
@item @ @ Q:
I don't have a cable, which one should I build?
@item @ @ A:
First you must know if you have an apcsmart UPS or a
voltage-signalling UPS. See the table of supported UPSes (@pxref{type_table}). If you
have a apcsmart UPS, we recommend building a Custom Smart (@pxref{Smart-Custom Cable for SmartUPSes}) cable. If you have a
voltage-signaling UPS, we recommend that you build a Custom Simple (@pxref{Voltage-Signalling Cable for "dumb" UPSes}) cable.
@item @ @ Q:
How much CPU resources does apcupsd use?
@item @ @ 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 configure
apcupsd to run with pthreads
(@code{--with-pthreads} on the
@code{./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."
@item @ @ Q:
What language is apcupsd written in?
@item @ @ A:
It is written entirely in C.
@item @ @ 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 @code{apcupsd --killpower}! What
can we do to fix this, and is it critical?
@item @ @ 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
@file{/etc/rc.d/init.d/halt} to re-invoke apcupsd
with the @code{--killpower} option (actually the
script apccontrol is called). This causes the UPS to send the
codes to the UPS to make it power off.
On slave machines, these modifications should not be made
to the @file{/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 file, or simply delete all the lines
containing ***apcupsd***, which were inserted by the apcupsd
installation process.
@item @ @ 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-off the ups. Have you run into this problem, and if so
do you have a remedy?
@item @ @ A:
Normally, once the shutdown process has begun, we cannot
stop it, though there @emph{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 off 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 off 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 off 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 off (at least for
Smart UPSes).
@item @ @ Q:
After running apcupsd for a while, I get the following
error: "Serial communications with UPS lost." What is
the problem?
@item @ @ 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.
@item @ @ Q:
When apcupsd starts, I get the following error:
"attach_shmarea: cannot get shm area: Identifier
removed." What is the problem?
@item @ @ A:
This problem and the problem of @strong{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: @code{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
@code{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 different key.
@item @ @ 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
file or directory." What is the problem?
@item @ @ A:
The two most likely causes of your problem are: 1. You have the
wrong serial port device name in the apcupsd.conf file.
2. The device name is not defined on your system.
Suggestions for proceeding:For the first item, check what your
serial port device should be named. You might be able to find the
name with an:
@example
ls /dev
@end example
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 defined. To get more
information on your devices try man @code{MAKEDEV}
or @code{find / -name MAKEDEV}. It is often located
in @code{/dev/MAKEDEV}. Looking at the
documentation may tell you what the correct name is, or at least
allow you to create the device.
@item @ @ Q:
How do I ensure that the slaves shutdown before the master?
@item @ @ A:
There are several strategies for getting the slaves
properly shutdown before shutting down the master. The first 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 insufficient, you can add additional time by putting an
appropriate @strong{sleep} shell command
in the @file{/etc/apcupsd/apccontrol} file 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 file on the slave that is
sufficiently short that you are sure that the slave will
shutdown before the master. If the shutdown is done with a
poweroff, this will also save power so that the master can stay
up longer.
@item @ @ Q:
How do I ensure that my database server is correctly shutdown?
@item @ @ A:
You simply add whatever commands are necessary in the
appropriate case statements in
@file{/etc/apcupsd/apccontrol}, which is a
standard script file that is called to actually do the
shutdown. Alternatively, you can add your own script file that
will be called before doing the commands in
apccontrol. Your script file 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.
@item @ @ 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
@item @ @ A:
The most common error causing your problem is an incorrect
serial port specification on your DEVICE directive. It should be:
@example
DEVICE /dev/com2
@end example
On WinNT machines, and probably Win2000 machines you MUST
use @file{/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
files 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
@file{setup.bat} script after loading the
files. 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:
@file{c:\apcupsd\etc\apcupsd\apcupsd.events}
Many error messages associated with Windows services will
be reported in the Windows System Log.
@item @ @ Q:
When using USB, I get the following log messages: usb-uhci.c:
interrupt, status 3, frame# 826. What does it mean?
@item @ @ A:
It means one transfer worked (bit 0 in status) and another
one (after that) failed (bit 1) at time frame 826. This kind of
soft error is common on USB and if everything seems to be
working, you can ignore it.
@item @ @ Q:
apcnisd doesn't work. It always
gives: FATAL ERROR in apcipc.c at line 497. attach_shmarea: shared
memory version mismatch (or UPS not yet ready to report)
@item @ @ A:
Unfortunately apcnisd does not
work with pthreads enabled. You have the following options:
@enumerate
@item
If you build with pthreads enabled,
apcnisd will not work no matter
what you do.
@item
If you build with pthreads enabled, and you want
to have network information from apcupsd, you must
set NETSERVER ON. This is the configuration we
recommend (i.e. using pthreads and NETSERVER ON).
@item
If you build with pthreads disabled, you have the choice
of using apcnisd or the NETSERVER
code. If you wish to use apcnisd, you
must set NETSERVER OFF
@item
If you build with pthreads disabled, and you do not use
apcnisd, you must set NETSERVER ON if
you wish to have network information from apcupsd.
@end enumerate
Concerning the names one sees with "ps".
@enumerate
@item
With pthreads enabled, on Linux machines, you will
see multiple copies of apcupsd running, but they
will all be called apcupsd rather than apcmain,
apcser, ... They will still run as LWP, but we
are unable to set the names on threads (LWP). Note,
though ps shows "multiple copies" of apcupsd running,
it is really one memory image but with multiple threads.
@item
With pthreads disabled, we are able to set the
child process names (at least on Linux) so you
will see apcmain, apcser, apcnis, ... in the
ps output. In this case, they are really different
processes each with its own memory image (the
code image is most likely shared).
@end enumerate
@end table
@node Apcupsd Bugs, , Frequently-Asked Questions, Basic User's Guide
@chapter Apcupsd Bugs
@cindex Bugs
Unfortunately, it seems that every program has some bugs. We do
our best to keep the bugs to a minimum by extensive testing. However,
because of our inherent nature to occasionally overlook things and the
fact that we don't have all the UPS models nor the APC documentation
on those models, apcupsd will have
some bugs.
As the bugs become known to us, we will post them on
the bug tracking system at SourceForge.
@node Advanced topics, Installation on Windows, Basic User's Guide, Top
@majorheading Advanced topics
@cindex Advanced
@menu
* Customizing Event Handling::
* Master/Slave Configurations::
* Controlling Multiple UPSes on one Machine::
* Support for SNMP UPSes::
* Alternate Ways To Run The Network Information Server::
* apcupsd System Logging::
@end menu
@node Customizing Event Handling, Master/Slave Configurations, , Advanced topics
@chapter Customizing Event Handling
@cindex Event handling
@cindex Customizing event handling
When apcupsd detects anomalies from
your UPS device, it will make some decisions that usually result in
one or more calls to the script located in
@file{/etc/apcupsd/apccontrol}. The @strong{apccontrol} file is a shell script that acts on
the first argument that apcupsd passes to
it. These actions are set up by default to sane behavior for all
psituations apcupsd is likely to
detect from the UPS. However, you can change the
apccontrol behavior for every single
action.
To customize, so create a file with the same name as the action,
which is passed as a command line argument. Put your script in the
@file{/etc/apcupsd} directory.
These events are sent to the system log, optionally sent to the
temporary events file
(@file{/etc/apcupsd/apcupsd.events}), and they also
generate a call to @file{/etc/apcupsd/apccontrol} which
in turn will call any scripts you have placed in the
@file{/etc/apcupsd} directory.
Normally, @file{/etc/apcupsd/acpcontrol} is called
only by apcupsd. Consequently, you should
not invoke it directly. However, it is important to understand how it
functions, and in some cases, you may want to change the messages that
it prints using @code{wall}. We recommend that you do so
by writing your own script to be invoked by
@code{apccontrol} rather than by modifying
apccontrol directly. This makes it easier
for you to upgrade to the next version of
apcupsd
In other case, you may want to write your own shell scripts that
will be invoked by apccontrol. For example,
when a power fail occurs, you may want to send an email message to
root. At present the arguments that
apccontrol recognizes are:
When apcupsd detects an event, it
calls the apccontrol script with four
arguments as:
apccontrol <event> <ups-name> <connected>
<powered>
where:
@table @asis
@item event
is the event that occurred and it may be any one of the values
described in the next section.
@item ups-name
is the name of the UPS as specified in the configuration file
(not the name in the EEPROM). For version 3.8.2, this is always set
to @strong{Default}
@item connected
is 1 if apcupsd is connected to
the UPS via a serial port (or a USB port). In most
configurations, this will be the case. In the case of a Slave
machine where apcupsd is not directly
connected to the UPS, this value will be 0.
@item powered
is 1 if the computer on which
apcupsd is running is powered by the
UPS and 0 if not. At the moment, this value is unimplemented and
always 0.
@end table
@menu
* apccontrol Command Line Options::
@end menu
@node apccontrol Command Line Options, , , Customizing Event Handling
@section apccontrol Command Line Options
apccontrol accepts the following
command line options:
@table @asis
@item annoyme
When a shutdown is scheduled, and the time
specified on the ANNOYME directive in the apcupsd.conf file
expires, this event is generated.
Default -- does a @code{printf
"Power problems please logoff." | wall}
then exits.
@item changeme
When apcupsd detects that the mains are on, but the
battery is not functioning correctly, this event is generated.
It is repeated every x hours.
Default -- does a @code{printf
"Emergency! UPS batteries have failed\nChange them NOW" |
wall} then exits.
@item commfailure
This event is generated each time the communications line
with the computer is severed. This event is not detected on
dumb signaling UPSes.
Default -does a @code{printf
"Warning serial port communications with UPS lost." |
wall} then exits.
@item commok
After a commfailure event is issued, when the communications
to the computer is re-established, this event will be generated.
Default -- does a @code{printf
"Serial communications with UPS restored." | wall}
then exits.
@item doreboot
This event is depreciated and should not be used.
Default - does a reboot of the system by calling
@code{shutdown -h now}
@item doshutdown
When the UPS is running on batteries and one of the limits
expires (time, run, load), this event is generated to cause
the machine to shutdown.
Default does a shutdown of the system by calling
@code{shutdown -h now}
@item emergency
Does an emergency shutdown of the system by calling
@code{shutdown -h now}
@item failing
This event is generated when the UPS is running on
batteries and the battery power is exhausted. The event following
this one will be a shutdown.
Default -- does a @code{printf "UPS battery power
exhausted. Doing shutdown.\n" | wall} then
exits.
@item loadlimit
This event is generated when the battery charge is
below the low limit specified in the apcupsd.conf file.
Default -- does a @code{printf "UPS battery
discharge limit reached. Doing shutdown.\n" | wall}
then exits. After completing this event,
apcupsd will immediately initiate a
@code{doshutdown} event.
@item mainsback
This event is generated when the mains power returns
after a powerout condition. The shutdown event may or
may not have been generated depending on the paramaters
you have defined and the length of the power outage.
A cancel of a shutdown should never be attempted as it
is very unlikely to succeed and will almost surely leave
your machine in a indeterminate state.
Default -- attempts to cancel the shutdown with a
@code{shutdown -c} (not sure about that!!!!)
@item onbattery
This event is generated 5 or 6 seconds after an
initial powerfailure is detected. It means that apcupsd definitely
considers the UPS to be on batteries. The onset of this
event can be delayed by the ONBATTERYDELAY apcupsd.conf
configuration directive.
Default -- does a @code{printf "Power
failure. Running on UPS batteries." | wall}
then exits.
@item offbattery
This event is generated when the mains return only
if the onbattery event has been generated.
Default -- does nothing.
@item powerout
This event is generated immediately when apcupsd detects
that the UPS has switched to batteries. It may be due to a
short powerfailure, an automatic selftest of the UPS, or
a longer powerfailure. In many cases, you may want to
inhibit the normal message sent/emailed by this event to
avoid being annoyed by short power failures.
Default -- does a @code{printf "Warning power
loss detected." | wall} then exits.
@item remotedown
This event is generated on a slave machine when it detects
either that the master has shutdown, or that a onbattery situation
exists and the communications line has been severed.
Despite the name, you should never reboot the machine -- instead
always shut it down.
Does a @code{shutdown -h now}
@item restartme
This event is depreciated and should not be used.
Terminates the currently running
apcupsd and then restarts it.
@item runlimit
This event is generated when the MINUTES value defined
in the apcupsd.conf file expires while in a power fail condition.
The MINUTES is the remaining runtime as internally calculated
by the UPS and monitored by apcuspd.
Does a @code{printf "UPS battery
runtime percent reached. Doing shutdown.\n" |
wall} then exits. After completing this
event, apcupsd will immediately
initiate a @code{doshutdown} event.
@item timeout
This event is generated when the TIMOUT value defined
in the apcupsd.conf file expires while in a power fail condition.
It indicates that the total time in a power failure has been
exeeded and the machine should be shutdown. Normally, with
smart UPSes, this value is not used, but rather one relies
on the remaining runtime (MINUTES) or the battery level
(BATTERYLEVEL) values specified in the conf file.
Does a @code{printf "UPS battery
runtime limit exceeded. Doing shutdown.\n" | wall}
then exits. After completing this event,
apcupsd will immediately initiate a
@code{doshutdown} event.
@item startselftest
This event is generated when apcupsd detects a
self test by the UPS. Normally due to the 6 second onbattery
delay default time, self test events are not detected.
This is called when apcupsd
detects that the UPS is doing a self test. No action is taken.
@item endselftest
This event is generated when the end of a self test
is detected.
This is called when apcupsd
determines that a self test has been completed. No action is
taken.
@item mastertimeout
This event is generated when a slave detects that
a master has not contacted it in a reasonable time, or
when a slave polls a master and gets no response in 30 seconds.
This event applies only to the old master/slave networking code and
not to the NIS server/slave mode.
No action is taken.
@item masterconnect
This event is generated when the slave and the
master reconnect.
This event applies only to the old master/slave networking code and
not to the NIS server/slave mode.
No action is taken.
@end table
To write your own routine for the @strong{powerout} action, you
create shell script named @strong{powerout} and put it in the lib
directory (normally @file{/etc/apcupsd}). When the
@strong{powerout} action is invoked by apcupsd, apccontrol will
first give control to your script. If you want apccontrol to
continue with the default action, simply exit your script with an
exit status of zero. If you do not want apccontrol to continue
with the default action, your script should exit with the special
exit code of @strong{99}. However, in this case, please be aware
that you must ensure proper shutdown of your machine if
necessary.
Some sample scripts (onbattery and mainsback) that email power
failure messages can be found in the @file{examples}
directory of the source code.
@node Master/Slave Configurations, Controlling Multiple UPSes on one Machine, Customizing Event Handling, Advanced topics
@chapter Master/Slave Configurations
@cindex Master/Slave
If you have two or more computers that are powered by the same UPS
and they are connected by a network, you can configure
apcupsd so that the computer that controls the UPS
(connected by the serial port or USB port), which is called the
master, can provide information to other machines powered by the
UPS, called slaves. When the master detects a power failure, it
will notify all the slaves (maximum of twenty). If the master
detects that the battery is low, it will also notify the slave so
that the slave may perform a shutdown.
In addition, in cases where you wish to keep the master up
longer than the slave, you can configure the slave to shut down in a
predetermined time after the UPS goes on batteries.
If a picture is worth a thousand words for you, please see
@ref{Configuration types_,,Configuration types.}.
@menu
* Configuration Directives::
* Master/Slave Problems::
* Network Problems with Master/Slave or Server/Slave Configurations::
@end menu
@node Configuration Directives, Master/Slave Problems, , Master/Slave Configurations
@section Configuration Directives
@cindex Directives
@cindex Configuration, Directives
If you are setting up a master/slave configuration, you will be
required to make some modifications to the
@file{apcupsd.conf} files after the build is
done.
The minimum set of configuration directive changes needed to
create a proper master and slave configuration files is described in
the @ref{Configuration Examples} section of this
manual.
The details of these directives are explained in the @ref{Configuration Directives for Sharing a UPS,,Configuration Directives for Sharing a UPS} section of the Configuration chapter of this
document.
In addition, sample master and slave configuration files can be
found in the @file{<src>/examples} directory
(@file{apcupsd.master.conf} and
@file{apcupsd.slave.conf}).
@node Master/Slave Problems, Network Problems with Master/Slave or Server/Slave Configurations, Configuration Directives, Master/Slave Configurations
@section Master/Slave Problems
@cindex Master/Slave
@cindex Problems, Master/slave
@menu
* Master/Slave Shutdown::
* Server/Slave Networking using NIS and the NET Driver::
@end menu
@node Master/Slave Shutdown, Server/Slave Networking using NIS and the NET Driver, , Master/Slave Problems
@subsection Master/Slave Shutdown
For additional details of shutting down a master/slave
configuration, please see the Master/Slave Shutdown
section of the Shutdown chapter (@pxref{Shutdown Sequence <1>}) of
the Technical Reference.
@node Server/Slave Networking using NIS and the NET Driver, , Master/Slave Shutdown, Master/Slave Problems
@subsection Server/Slave Networking using NIS and the NET Driver
@cindex NIS networking
@cindex Net driver
It is also possible to implement a network of NIS server/slave
apcupsds using the new 3.10.x code and the @strong{net} driver. This mode of NIS server/slave
networking is considerably different from the old method described at
the beginning of this chapter. In the old code, there is a lot of
configuration on both the master and slave side, and the master polls
or sends info to the slave. Using the @strong{net} driver is much simpler. However, you should
carefully check that the NIS slave does a proper shutdown. In the
master/slave code, the master ensures the best it can that the slave
is shutdown or notified before it shuts down itself. On the other
hand, using the net driver, the NIS server knows nothing about the NIS slaves
that may be listening and thus takes no special precautions to ensure
that the NIS slaves receive the shutdown signal. Since the NIS slave reads the
master's data once per second there should be no shutdown problems,
and our experience confirms this. This question can only be answered
by carefully testing the shutdown.
In this NIS server/slave mode, the NIS server is a standard stand alone
configuration except that it must have @strong{NETSERVER
on} in the configuration file and have an @strong{NISPORT nnn} defined. Thus any
apcupsd running in this mode then becomes
the NIS server.
The NIS slave then uses the net driver to connect to the server's
NIS output. In this mode, the NIS slave decides how often to poll the
server for the NIS information. The NIS slave's conf file has
@strong{UPSTYPE net}, which will invoke the
"network" driver. By setting this machine's @strong{DEVICE} to be @strong{server-ip:server-NIS-port} it will automatically
connect to the NIS server and use the server's signals to shutdown the
computer. In the example net slave configuration file below, the
slave uses the NIS information provided by the computer @strong{tibs} on port @strong{3551}.
@example
## apcupsd.conf v1.1 ##
UPSCABLE ether
UPSTYPE net
# Specify the server name:port where NIS is running
DEVICE tibs:3551
LOCKFILE /var/lock
BATTERYLEVEL 5
MINUTES 3
TIMEOUT 0
ANNOY 300
ANNOYDELAY 60
NOLOGON disable
EVENTSFILE /etc/apcupsd/apcupsd.events
UPSCLASS standalone
UPSMODE disable
#
# Use this to control the poll time.
# the default is 60 or 1 minute
#
NETTIME 30
@end example
@node Network Problems with Master/Slave or Server/Slave Configurations, , Master/Slave Problems, Master/Slave Configurations
@section Network Problems with Master/Slave or Server/Slave Configurations
@cindex Problems, Master/Slave
@cindex Problems, networking
When working with a master/slave or server/slave configurations (one UPS powering
more than one computer), the master/server and slave communicate via the
network. In many configurations, apcupsd is
started before the network is initialized. In this case, it is
possible that the master will be unable to contact the slave. On
apcupsd versions prior to 3.8.0, this could
cause apcupsd to error off. The solution to
this problem is to either force apcupsd to
be started after the network and the DNS (fiddle the symbolic links in
/etc/rc.d), or put the names of the slave machines in your
@file{/etc/hosts} file, or even more preferable, use IP
addresses rather than machine names. On some configurations, you may
need to use fully qualified names (host.domain.xxx) rather than simple
host names.
@menu
* Error Messages from a Master Configuration::
* Error Messages from a Slave Configuration::
* Master/Slave Connection Not Working::
@end menu
@node Error Messages from a Master Configuration, Error Messages from a Slave Configuration, , Network Problems with Master/Slave or Server/Slave Configurations
@subsection Error Messages from a Master Configuration
In a master/slave configuration, you can get the following error
messages from a master. The error message is followed by a possible
explanation:
@menu
* Cannot resolve slave name XXX::
* Got slave shutdown from SSS::
* Cannot write to slave SSS::
* Cannot read magic from slave SSS::
* Connect to slave SSS failed::
* Cannot open stream socket::
@end menu
@node Cannot resolve slave name XXX, Got slave shutdown from SSS, , Error Messages from a Master Configuration
@subsubsection Cannot resolve slave name XXX
To contact the slave, the slave name given in the configuration
file must be resolved to an IP address. In this case,
apcupsd could not get the IP
address. Either the slave name is incorrect, your DNS may not be
working, or you have started apcupsd during
the boot process before the network is operational.
@node Got slave shutdown from SSS, Cannot write to slave SSS, Cannot resolve slave name XXX, Error Messages from a Master Configuration
@subsubsection Got slave shutdown from SSS
This message should not be printed as it is not yet used.
@node Cannot write to slave SSS, Cannot read magic from slave SSS, Got slave shutdown from SSS, Error Messages from a Master Configuration
@subsubsection Cannot write to slave SSS
This message occurs when the master attempts to send a message
to the slave SSS and gets an error. It indicates that either the slave
machine is not responding (apcupsd died,
the system crashed, ...) or that the network is down.
@node Cannot read magic from slave SSS, Connect to slave SSS failed, Cannot write to slave SSS, Error Messages from a Master Configuration
@subsubsection Cannot read magic from slave SSS
This message indicates that the master attempted to read the
code key from the slave SSS and it did not match the value expected. A
common cause of this problem is that the master and slave versions of
apcupsd are not the same. Please be sure
you are running the same version of apcupsd
on all your master and slave machines.
@node Connect to slave SSS failed, Cannot open stream socket, Cannot read magic from slave SSS, Error Messages from a Master Configuration
@subsubsection Connect to slave SSS failed
This message is logged when the master attempts to connect to
slave SSS and no connection is accepted. The most common cause of this
problem is that the slave copy of apcuspd
is not yet ready to accept connections or is not running. Generally,
apcupsd will retry the connection a bit
later. If the problem is persistent, it can indicate a network problem
or the slave name on the SLAVE directive of the master's configuration
file is incorrect.
@node Cannot open stream socket, , Connect to slave SSS failed, Error Messages from a Master Configuration
@subsubsection Cannot open stream socket
This indicates a fundamental networking problem on your system ---
either a lack of sufficient resources or you have not configured
TCP/IP operations.
@node Error Messages from a Slave Configuration, Master/Slave Connection Not Working, Error Messages from a Master Configuration, Network Problems with Master/Slave or Server/Slave Configurations
@subsection Error Messages from a Slave Configuration
In a master/slave configuration, you can get the following error
messages from a slave. The error message is followed by a possible
explanation:
@menu
* Cannot resolve master name MMM::
* Cannot bind local address, probably already in use: Cannot bind local address; probably already in use.
* Socket accept error::
* Unauthorized attempt from master MMM::
* Read failure from socket::
* Bad APC magic from master; MMM::
* Bad user magic from master; MMM::
@end menu
@node Cannot resolve master name MMM, Cannot bind local address; probably already in use, , Error Messages from a Slave Configuration
@subsubsection Cannot resolve master name MMM
This message is logged when the slave attempts to resolve the
name given on the MASTER configuration directive to an IP address. It
probably means that the master name MMM is not defined, your DNS is
not properly working, or you have started
apcupsd in the boot process before the
network is initialized. Check the name MMM, or use an explicit IP
address on the MASTER configuration directive in the slave's
configuration file.
@node Cannot bind local address; probably already in use, Socket accept error, Cannot resolve master name MMM, Error Messages from a Slave Configuration
@subsubsection Cannot bind local address, probably already in use
This means that the slave has attempted to bind the port number
so that it can listen for messages from the master. This can occur if
already have a copy of apcupsd running, or
you have previously run apcupsd in the past
5 or 10 minutes, because occasionally the operating system will not
shutdown a port correctly for 5 to 10 minutes after a program
exits. In this case, you can either wait a few minutes for the problem
to go away, or use a different port in both your master and slave
configuration files.
@node Socket accept error, Unauthorized attempt from master MMM, Cannot bind local address; probably already in use, Error Messages from a Slave Configuration
@subsubsection Socket accept error
The slave got an error waiting on the accept() system call. This is
probably due to a fundamental networking problem.
@node Unauthorized attempt from master MMM, Read failure from socket, Socket accept error, Error Messages from a Slave Configuration
@subsubsection Unauthorized attempt from master MMM
The master named MMM (probably an IP address) contacted the slave
but MMM is not the master that was listed on the MASTER
configuration directive in /etc/apcupsd.conf, and consequently, it
is not authorized to communicate with the slave. Please check that
your MASTER and SLAVE names in your slave and master configuration
files respectively are correct.
@node Read failure from socket, Bad APC magic from master; MMM, Unauthorized attempt from master MMM, Error Messages from a Slave Configuration
@subsubsection Read failure from socket
The slave got an error reading the socket open to the master. This
indicates a fundamental networking problem.
@node Bad APC magic from master; MMM, Bad user magic from master; MMM, Read failure from socket, Error Messages from a Slave Configuration
@subsubsection Bad APC magic from master: MMM
The slave received a code key from the master that does not
correspond to the one expected by the slave. The most common cause of
this problem is that you are running a different version of
apcupsd on the master and the slave. Please
ensure that you are running the same version of
apcupsd on all your master and
slaves.
@node Bad user magic from master; MMM, , Bad APC magic from master; MMM, Error Messages from a Slave Configuration
@subsubsection Bad user magic from master: MMM
This message indicates that the master and slave have previously
communicated, but that the code key transmitted with the most
recent message from the master does not correspond to what the
slave expects. This problem is probably due to a network error or
some other user or machine contacting the slave on the network
port.
@node Master/Slave Connection Not Working, , Error Messages from a Slave Configuration, Network Problems with Master/Slave or Server/Slave Configurations
@subsection Master/Slave Connection Not Working
Master/slave problems are usually related to one of the following
items:
@enumerate
@item
Improper apcupsd.conf files. A good starting point are the
master/slave example files in the examples subdirectory of the
source.
@item
Master or slave IP address or name incorrect. Try ping'ing each
machine from the other using the names or addresses that you have
put in the respective apcupsd.conf files.
@item
Make sure no other program is using socket number 6666 or
change the NETPORT directive in both apcupsd.conf files.
@item
Make sure you are using the same version of apcupsd on both the
master and slave machines.
@end enumerate
@node Controlling Multiple UPSes on one Machine, Support for SNMP UPSes, Master/Slave Configurations, Advanced topics
@chapter Controlling Multiple UPSes on one Machine
You may want to use your server to control multiple UPSes. This
is possible by proper configuration and by running one copy of
apcupsd for each UPS to be
controlled (recall the @ref{Configuration types_,,Configuration types.}).
@menu
* Configuration::
@end menu
@node Configuration, , , Controlling Multiple UPSes on one Machine
@section Configuration
The way to accomplish the above is to ensure that none of the
critical files used by each of the two copies of
apcupsd are the same. By using suitable
configuration options, this is possible.
@menu
* The First Copy of apcupsd::
* The Second Copy of apcupsd::
* Important Steps after Installation of the Second Copy::
@end menu
@node The First Copy of apcupsd, The Second Copy of apcupsd, , Configuration
@subsection The First Copy of apcupsd
For example, assuming you have SmartUPSes in both cases, to
configure and install the first copy of
apcupsd, which controls a UPS and Computer
A, one could use the following configuration:
@example
./configure \
--prefix=/usr \
--sbindir=/sbin \
--with-cgi-bin=/home/http/cgi-bin \
--enable-cgi \
--with-css-dir=/home/http/css \
--with-log-dir=/etc/apcupsd \
--with-serial-dev=/dev/ttyS0 \
--enable-pthreads \
--with-nis-port=3551 \
--enable-powerflute
@end example
This is pretty much a "normal" installation using many
of the defaults. Once built and installed, this would control the
first UPS and cause a shutdown of the system when the batteries are
low. This copy of apcupsd will be started
and stopped automatically when the system is booted and halted.
@node The Second Copy of apcupsd, Important Steps after Installation of the Second Copy, The First Copy of apcupsd, Configuration
@subsection The Second Copy of apcupsd
@cindex Two apcupsds
To configure and install the second copy of
apcupsd, which controls the second UPS and
Computer B, you could use the following configuration:
@example
./configure \
--prefix=$HOME/apcupsd/bin \
--sbindir=$HOME/apcupsd/bin \
--enable-cgi \
--with-cgi-bin=$HOME/apcupsd/bin \
--with-log-dir=$HOME/apcupsd/bin \
--with-pid-dir=$HOME/apcupsd/bin \
--sysconfdir=$HOME/apcupsd/bin \
--with-lock-dir=$HOME/apcupsd/bin \
--with-pwrfail-dir=$HOME/apcupsd/bin \
--with-serial-dev=/dev/ttyS1 \
--enable-pthreads \
--with-nis-port=7001 \
--disable-install-distdir
@end example
Note, in this case, we use considerably more configuration options
to ensure that the system files are placed in a different directory
(@file{$HOME/apcupsd/bin}). We have also selected a different serial port
and a different NIS (Network Information Server) port. And finally,
we have used the @code{--disable-install-distdir} option, which
prevents @code{make install} from doing the final system
installation (i.e. the modification of the halt script) since this
was previously done.
@node Important Steps after Installation of the Second Copy, , The Second Copy of apcupsd, Configuration
@subsection Important Steps after Installation of the Second Copy
After the @code{make install} of the second copy of
apcupsd there are a number important steps
to complete. You must either remove or modify the file
@file{$HOME/apcupsd/bin/apccontrol}, so that it will not
shutdown Computer A when the battery of UPS 2 is low. One suggestion
is to copy @file{examples/safe.apccontrol} into
@file{$HOME/apcupsd/bin/apccontrol}. Alternatively, you
could edit the @file{$HOME/apcupsd/bin/apccontrol} and
delete all statements that attempt to shutdown the machine. Another
important step is to find a way to shutdown Computer B when UPS 2's
battery is low. Probably the simplest way to do this is to edit
@file{$HOME/apcupsd/bin/apcupsd.conf} on Computer A so
that this second copy of apcupsd becomes a
network master. Then install a standard slave configuration on
Computer B. Please remember that if UPS 1's batteries are exhausted
before UPS 2's batteries, Computer B may not be properly shutdown. And
at the current time, there is no simple means to make the two copies
of apcupsd running on Computer A
communicate. Thus there are certain risks in such a
configuration. However, these configurations can be very useful for
powering electronic equipment and such.
If Computer B is vitally important, it would probably be better
to purchase a serial port card for it, or perhaps use a USB UPS.
To ensure that it is properly shutdown if Computer A goes down,
you could run a second copy of apcupsd on Computer B as a slave
connected to the main copy of apcupsd on Computer A. Thus
Computer B would be running two slaves, one driven by the master
controlling UPS 1 and the other by the master controlling UPS 2,
and Computer B could be shutdown by the first master that
signaled it to do so.
@node Support for SNMP UPSes, Alternate Ways To Run The Network Information Server, Controlling Multiple UPSes on one Machine, Advanced topics
@chapter Support for SNMP UPSes
@cindex SNMP
@uref{snmp,snmp}
To run apcupsd with an SNMP UPS, you need the
following things:
@itemize
@item
An SNMP UPS, for example a Web/SNMP card installed into the
SmartSlot.
@item
apcupsd version 3.10.0 or higher
@item
@uref{http://www.net-snmp.org/,Net-SNMP} library
(previously known as ucd-snmp) installed
@end itemize
@menu
* Connecting an SNMP UPS::
* Building and Installing apcupsd: Building and Installing apcupsd <1>.
* SNMP Specific Information::
* Known Problems::
@end menu
@node Connecting an SNMP UPS, Building and Installing apcupsd <1>, , Support for SNMP UPSes
@section Connecting an SNMP UPS
@cindex SNMP, Connecting
The Simple Network Management Protocol provides an interface to
connect to remote devices through the
network. apcupsd is now capable of using
the SNMP interface of an SNMP-enabled UPS to communicate with an
UPS. Currently apcupsd supports only APC's
PowerNet MIB. To enable the SNMP support it is enough to configure the
correct device in your apcupsd.conf configuration file. The directive
needed for this configuration is:
@example
DEVICE 192.168.100.2:161:APC:private
@end example
where the directive is made by four parts:
@itemize
@item
IP address of the remote UPS
@item
Remote SNMP port
@item
Kind of remote SNMP agent, currently can only be "APC" for
APC's powernet MIB
@item
The read-write community string, usually it is
"private" for read-write access.
@end itemize
@node Building and Installing apcupsd <1>, SNMP Specific Information, Connecting an SNMP UPS, Support for SNMP UPSes
@section Building and Installing apcupsd
Follow the instructions in @ref{Building and Installing apcupsd}l,
being sure to include the following options (in addition to any others
you need) on the @strong{./configure}
line:
@example
./configure \
--with-serial-dev=<your-SNMP-device> \
--with-upstype=snmp \
--with-upscable=smart \
--enable-pthreads \
--enable-snmp
@end example
@node SNMP Specific Information, Known Problems, Building and Installing apcupsd <1>, Support for SNMP UPSes
@section SNMP Specific Information
@cindex SNMP
The SNMP connection gives less information compared to a serial
smart cable. This is not a problem as the most useful information
is given, together with a number of secondary parameters that are
informative enough to run safely your UPS.
@node Known Problems, , SNMP Specific Information, Support for SNMP UPSes
@section Known Problems
Currently (as of 3.10.0) the code to power off the UPS needs
special configuration. The killpower command for SNMP UPSes can not be
issued during shutdown as typically at some time during shutdown
operations the network stack is stopped. To overcome this problem it
is needed to modify the @file{/etc/rc.d/apcupsd} system
control script to tell apcupsd to issue the
power down command (killpower) to the UPS immediately before apcupsd
initiates the system shutdown. For this reason it is paramount to set
your UPS grace time to a value greater than 120 seconds to allow for
clean shutdown operations before the UPS removes the power from its
plugs. To enable correct shutdown operation during powerdown do the
following:
@itemize
@item
Connect to your Web/SNMP card using your favorite web browser,
go to the UPS configuration menu and change the "Shutdown Delay"
parameter to 180 seconds or more, depending on how much time your
system shutdown requires to umount all the filesystems.
@item
Change /etc/rc.d/apcupsd script adding the
'--kill-on-powerfail' to the apcupsd invocation.
@item
Restart your apcupsd
@end itemize
With this setup your UPS operations should be safe.
@node Alternate Ways To Run The Network Information Server, apcupsd System Logging, Support for SNMP UPSes, Advanced topics
@chapter Alternate Ways To Run The Network Information Server
@cindex NIS alternate was of running
apcupsd maintains STATUS and EVENTS
data concerning the UPS and its operation. This information can be
obtained over the network using either
apcnisd or
apcupsd's internal network information
server, which is essentially the same code as
apcnisd but compiled into
apcupsd. Clients on the network make a
connection to the information server and send requests for status or
events data, which the server then transmits to them.
The information served to the network by this interface should
not be confused with master/slave mode that shares a UPS between two
or more computers. That code is described in @ref{Configuration Directives for Sharing a UPS,,Configuration Directives for Sharing a UPS} of this documentation.
There are three different ways to run the information server
depending on your requirements and preferences. It can be run as 1. a
standalone program, 2. a standalone program invoked by the inetd
daemon, or 3. as a thread (or child process) of
apcupsd (default configuration). We
recommend option 3 unless you have specific reasons to do
otherwise. Option 3 is what is configured in by default.
@menu
* Running the server as a child of apcupsd::
* Running apcnisd from INETD::
* Running apcnisd Standalome::
@end menu
@node Running the server as a child of apcupsd, Running apcnisd from INETD, , Alternate Ways To Run The Network Information Server
@section Running the server as a child of apcupsd
This is probably the simplest way to run the network information
server. To do so, you simply make sure the @strong{NETSERVER} directive in
@file{/etc/apcupsd/apcupsd.conf} is @strong{on}, and then stop and restart
apcupsd. It will automatically create the
server thread (or spawn an additional child process named
apcnis) to handle network clients. In the
case where pthreads are enabled, a new thread will be created rather
than a child process to handle the network information requests. Note,
the above modification should not be necessary if you use the default
@file{apcupsd.conf}, since it is already turned
on.
Although this method is simple, it affords no protection from
the outside world accessing your network server unless you
are behind a firewall. In addition, if there is a bug in the network
server code, or if a malicious user sends bad data, it may be possible
for apcnis to die, in which case, though it
is not supposed to, apcupsd may also exit,
thus leaving your machine without shutdown protection. In addition,
since apcupsd is running at root level, all
threads or any child process will do so also. That being said, most of
us prefer to run the server this way.
With apcupsd version 3.8.2 and later,
you may enable the TCP Libwrap subroutines to add additional
security. In this case, access to the network server will be
controlled by the statements you put in
@file{/etc/hosts.allow}.
@node Running apcnisd from INETD, Running apcnisd Standalome, Running the server as a child of apcupsd, Alternate Ways To Run The Network Information Server
@section Running apcnisd from INETD
This is probably the most secure and most desirable way of
running the network information server. Unfortunately, it is a bit
more complicated to set up. However, once running, the server remains
unexecuted until a connection is attempted, at which point, inetd will
invoke apcnisd. Once
apcnisd has responded to the client's
requests, it will exit. None of the disadvantages of running it
standalone apply since apcnisd runs only
when a client is requesting data. Note, running in this manner works
only if you are using the old forking code and have pthreads
explicitly turned off. The pthreads version of
apcupsd does not support the shared memory
calls that are necessary for apcnisd to
access the internal state of
apcupsd.
An additional advantage of this method of running the network
information server is that you can call it with a TCP wrapper and thus
use access control lists (ACL) such as
@file{hosts.allow}. See the man pages for
@file{hosts.allow} for more details.
To configure apcnisd to run from
INETD, you must first put an entry in
@file{/etc/services} as follows:
@example
apcnisd 3551/tcp
@end example
This defines the port number (3551) and the service (TCP) that
apcnisd will be using. This statement can
go anywhere in the services file. Normally, one adds local changes
such as these to the end of the file.
Next, you must modify @file{/etc/inetd.conf} to have the
following line:
@example
apcnisd stream tcp nowait root /usr/sbin/tcpd /sbin/apcnisd -i
@end example
If you do not want to run the TCP wrapper, then the line should
be entered as follows (not tested):
@example
apcnisd stream tcp nowait root /sbin/apcnisd -i
@end example
Please check that the file locations are correct for your
system. Also, note that the @code{-i} option is necessary so
that apcnisd knows that it was called by
INETD. Before restarting INETD, first ensure that the @strong{NETSERVER} directive in
@file{/etc/apcupsd/apcupsd.conf} is set to @strong{off}. This is necessary to prevent
apcupsd from starting a child process that
acts as a server. If you change @strong{NETSERVER}, you must stop and restart
apcupsd for the configuration change to be
effective.
Finally, you must restart INETD for it to listen on port 3551.
On a Red Hat system, you can do so by:
@example
/etc/rc.d/init.d/inet reload
@end example
At this point, when a client attempts to make a connection on
port 3551, INETD will automatically invoke
apcnisd.
@node Running apcnisd Standalome, , Running apcnisd from INETD, Alternate Ways To Run The Network Information Server
@section Running apcnisd Standalome
This is probably the least desirable of the three ways to run an
apcupsd network information server because
if apcupsd is stopped, you must also stop
apcnisd before you can restart
apcupsd. This is because
apcnisd, when run standalone, holds the
shared memory buffer by which apcnisd and
apcupsd communicate. This prevents a new
execution of apcupsd from creating
it.
To execute apcnisd in standalone
mode, first ensure that the @strong{NETSERVER}
directive in @strong{/etc/apcupsd/apcupsd.conf} is set to @strong{off}. This is necessary to prevent
apcupsd from starting a child process that
acts as a server. Restart apcupsd normally,
then:
@example
/sbin/apcnisd
@end example
The advantage of running the network information server
standalone is that if for some reason, a client causes the network
server to crash, it will not affect the operation of
apcupsd.
@node apcupsd System Logging, , Alternate Ways To Run The Network Information Server, Advanced topics
@chapter apcupsd System Logging
@cindex Logging, System
@cindex System Logging
The apcupsd philosophy is that all
logging should be done through the @strong{syslog} facility (see: @code{man
syslog}). This is now implemented with the exceptions that
@strong{STATUS} logging, for compatibility,
with prior versions is still done to a file, and @strong{EVENTS} logging can be directed to a
"temporary" file so that it can be reported by the network
information server.
@menu
* Logging Types::
* Implementation Details::
* Developers Notes::
@end menu
@node Logging Types, Implementation Details, , apcupsd System Logging
@section Logging Types
@cindex Logging, types
apcupsd splits its logging into four
separate types called:
@enumerate
@item
DEBUG
@item
DATA
@item
STATUS
@item
EVENTS
@end enumerate
Debug logging consists of debug messages. Normally these are
turned on only by developers, and currently there exist very few of
these debug messages.
@unnumberedsubsubsec DATA Logging
Data logging consists of periodically logging important data
concerning the operation of the UPS. See the Data Logging (@pxref{DATA Logging}) section of this manual for
more details.
@unnumberedsubsubsec STATUS Logging
Status logging consists of logging all available information known
about your UPS as a series of ASCII records. This information is
also made available by the apcupsd network
information server.
For more details on STATUS logging, see the Status (@pxref{apcupsd Status Logging}) section of the Technical
Reference.
@unnumberedsubsubsec EVENTS Logging
Events logging consists of logging events as they happen. For
example, successful startup, power fail, battery failure, system
shutdown, ...
See the manual section on customizing event
handling (@pxref{Customizing Event Handling}) for more details.
@node Implementation Details, Developers Notes, Logging Types, apcupsd System Logging
@section Implementation Details
In order to ensure that the data logged to syslog() can be directed
to different files, I have assigned syslog() levels to each of our
four types of data as follows:
@enumerate
@item
1. DEBUG logging has level LOG_DEBUG
@item
2. DATA logging has level LOG_INFO
@item
3. STATUS logging has level LOG_NOTICE
@item
4. EVENTS logging has levels LOG_WARNING, LOG_ERR,
LOG_CRIT, and LOG_ALERT
@end enumerate
It should be noted that more work needs to be done on the
precise definitions of each of the levels for EVENTS logging.
Currently, it is roughly broken down as follows:
LOG_WARNING general information such as startup, etc.
LOG_ERR an error condition detected, e.g. communications problem
with the UPS.
LOG_CRIT a serious problem has occurred such as power failure,
running on UPS batteries, ...
LOG_ALERT a condition that needs immediate attention such as
pending system shutdown, ...
The default Facility for syslog() logging is DAEMON, although this
can be changed with the FACILITY directive in apcupsd.conf. In the
following example, we should the facility as local0.
More work needs to be done to the code to ensure that it
corresponds to the above levels.
As a practical example of how to setup your syslog() to use the
new logging feature, suppose you wish to direct all DATA logging to a
file named @file{/var/log/apcupsd.data}, all EVENTS to
the standard @file{/var/log/messages} file (to be mixed
with other system messages), and at the same time send all EVENTS to
@file{/var/log/apcupsd.events}, and finally, you want to
send all STATUS logging to the named pipe
@file{/var/log/apcupsd.status}
First as root, you create the named pipe:
@example
mkfifo /var/log/apcupsd.status
@end example
Change its permissions as necessary or use the -m option to set
them when creating the pipe.
Then you modify your @file{/etc/syslog.conf} file
to direct the appropriate levels of messages where you want them. To
accomplish the above, my syslog.conf file looks like:
@example
# exclude all apcupsd info by default
*.info;local0.none /var/log/messages
# Everything for apcupsd goes here
local0.info;local0.!notice /var/log/apcupsd.data
local0.notice;local0.!warn |/var/log/apcupsd.status
local0.warn /var/log/apcupsd.events
local0.warn /var/log/messages
@end example
@node Developers Notes, , Implementation Details, apcupsd System Logging
@section Developers Notes
@cindex Developers Notes
All logging functions and all error reporting are now done
through the log_event() subroutine call. Exceptions to this are:
initialization code where printf's are done, and writing to the
status file. Once the initialization code has completed and the
fork() to become a daemon is done, no printf's are used.
log_event() has exactly the same format as syslog(). In fact, the
subroutine consists of only a syslog() call. If anyone really
wishes to log to a file, the code to do so can easily be done by
adding code to log_event() in apclog.c.
@node Installation on Windows, Installation on Serial-Line UPSes, Advanced topics, Top
@majorheading Installation: Windows
@cindex Installation, Windows
@cindex Windows, Installation
@menu
* The Windows Version of apcupsd::
@end menu
@node The Windows Version of apcupsd, , , Installation on Windows
@chapter The Windows Version of apcupsd
The Windows version of apcupsd has
been tested on Win95, Win98, WinMe, WinNT, WinXP, and Win2000
systems. This version of apcupsd has been
built to run under the CYGWIN environment, which provides many of the
features of Unix on Windows systems. It also permitted a rapid port
with very few source code changes, which means that the Windows
version is for the most part running code that has long proved stable
on Unix systems. Even though the Win32 version of
apcupsd is a port that relies on many Unix
features, it is just the same a true Windows program. When running, it
is perfectly integrated with Windows and displays its icon in the
system icon tray, and provides a system tray menu to obtain additional
information on how apcupsd is running
(status and events dialogue boxes). If so desired, it can also be
stopped by using the system tray menu, though this should normally
never be necessary.
Once installed apcupsd normally runs
as a system service. This means that it is immediately started by the
operating system when the system is booted, and runs in the background
even if there is no user logged into the system.
@menu
* Installation::
* Installation Directory::
* Testing::
* Upgrading::
* Post Installation::
* Problem Areas::
* Utility Functions::
* Disclaimer::
* Email Notification of Events::
* Killpower under Windows::
* Power Down During Shutdown::
* Command Line Options Specific to the Windows Version::
* Building the Win32 Version from the Source::
@end menu
@node Installation, Installation Directory, , The Windows Version of apcupsd
@section Installation
Normally, you will install the Windows version of
apcupsd from the binaries. This install is
somewhat Unix like since you do many parts of the installation by
hand. To install the binaries, you need @strong{WinZip}.
@itemize
@item
Simply double click on the
@file{winapcupsd-3.8.5.tar.gz} icon. The actual name
of the icon will vary from one release version to another.
@sp 1
@image{wininstall3,,,,png}
@sp 1
@item
When Zip says that it has one file and asks if it should unpack
it into a temporary file, respond with @strong{Yes}.
@sp 1
@image{wininstall4,,,,png}
@sp 1
@item
Ensure that you extract all files and that the extraction will
go into @file{C:\}
@sp 1
@image{wininstall5,,,,png}
@sp 1
@end itemize
If you wish to install the package elsewhere, please note that you
will need to proceed with a manual installation, which is not
particularly easy as you must rebuild the source and change the
configuration file as well.
This installation assumes that you do @strong{not} have CYGWIN installed on your computer. If
you do, and you use mount points, you may need to do a special manual
installation.
Once you have unzipped the binaries, open a window pointing to
the binary installation folder (normally
@file{c:\apcupsd}). This folder should contain folders
with the name bin, etc, examples, and manual. If and when you no
longer need them, the examples and manual sub-folders of the
@file{c:\apcupsd} directory may be removed.
Continuing the installation process:
@itemize
@item
Open the directory @file{c:\apcupsd\etc\apcupsd}
in the Windows Explorer by Clicking on the apcupsd folder then on the
@file{etc} folder, then on the apcupsd folder. Finally
double click on the file @file{apcupsd.conf} and edit it
to contain the values appropriate for your site. In most cases, no
changes will be needed, but if you are not using COM1 for your serial
port, you will need to set the @strong{DEVICE}
configuration directive to the correct serial port. Note, if you are
using WinNT or Win2000, the operating system may probe the port
attempting to attach a serial mouse. This will cause
apcupsd to be unable to communicate with
the serial port. If this happens, or out of precaution, you can edit
the @file{c:\boot.ini} file. Find the line that looks
something like the following:
multi(0)disk(0)rdisk(0)partition(1)\WINNT="Windows NT
Workstation Version 4.00"
and add the following to the end of the line: /NoSerialMice:COM1
(or COM2 depending on what you want to use). The new line should
look similar to:
multi(0)disk(0)rdisk(0)partition(1)\WINNT="Windows NT
Workstation Version 4.00" /NoSerialMice:COM1
where the only thing you have changed is to append to the end of
the line. This addition will prevent the operating system from
interferring with apcupsd
@item
Then return to @file{c:\apcupsd} and open on the
@file{bin} folder so that you see its contents.
@item
To do the final step of installation, double click on the
@file{setup.bat} program. This script will setup the
appropriate mount points for the directories that
apcupsd uses, it will install
apcupsd in the system registry, and on
Windows 98, it will start apcupsd
running.
If everything went well, you will get something similar to the
following output in a DOS shell window:
@sp 1
@image{wininstall1,,,,png}
@sp 1
What is important to verify in the DOS window is that the root
directory @file{\} is mounted on device
@file{c:\}.
The DOS window will be followed immediately by a Windows
dialogue box as follows:
@sp 1
@image{wininstall2,,,,png}
@sp 1
@item
On Windows 98, to actually start the service, either reboot the
machine, which is not necessary, or open a DOS shell window, and
type the following commands:
@example
cd c:\apcupsd\bin
apcupsd /service
@end example
Alternatively, you can go to the
@file{c:\apcupsd\bin} folder with the Explorer and
double click on the @strong{Start}
icon.
@item
On Windows NT, to start the service, either reboot the machine,
which is not necessary, or go to the Control Panel, open the Services
folder and start the apcupsd daemon program
by selecting the apcupsd UPS Server and
then clicking on the Start button as shown below:
@sp 1
@image{wininstall6,,,,png}
@sp 1
If the Services dialog reports a problem, it is normally
because your DEVICE statement does not contain the correct serial
port name.
@end itemize
You probably should also click on the @strong{Startup...} button to ensure that the correct
defaults are set. The dialogue box that appears should have @strong{Startup Type} set to @strong{Automatic} and @strong{Logon} should be set to @strong{System Account} with @strong{Allow
Service to Interact with Desktop} checked. If these values
are not set correctly by default, please change them otherwise
apcupsd will not work.
For WinXP systems (and probably Win2K), the dialogs are a bit
different from those shown here for WinNT, but he concept is the
same. You get to the Services dialog by clicking on: @strong{Control Panel -> Administrative Tools -> Component
Services}. The apcupsd service
should appear in the right hand window when you click on @strong{Services (Local)} in the left hand menu
window.
That should complete the installation process. When the system
tray icon turns from a battery
@image{onbatt,,,,png} into a plug
@image{online,,,,png}, right click
on it and a menu will appear. Select the @strong{Events} item, and the Events dialogue box should
appear. There should be no error messages. By right clicking again on
the system tray plug and selecting the @strong{Status} item, you can verify that all the values
for your UPS are correct.
When the UPS switches to the battery, the battery icon will
reappear in the system tray. While the UPS is online, if the battery
is not at least 99% charged, the plug icon will become a plug with a
lightning bolt in the middle
@image{charging,,,,png} to indicate
that the battery is charging.
@node Installation Directory, Testing, Installation, The Windows Version of apcupsd
@section Installation Directory
@cindex Windows, Installation Directory
The Win32 version of apcupsd must
reside in the @file{c:\apcupsd\} directory, and there
must be a @file{c:\tmp} directory on your machine. The
installation will do this automatically, and we recommend that you do
not attempt to place apcupsd in another
directory. If you do so, you are on your own, and you will need to do
a rebuild of the source.
@node Testing, Upgrading, Installation Directory, The Windows Version of apcupsd
@section Testing
@cindex Windows, Testing
@cindex Testing, Windows
It would be hard to overemphasize the need to do a full testing
of your installation of apcupsd as there
are a number of reasons why it may not behave properly in a real power
failure situation.
Please read @ref{Testing Apcupsd} of
this document for general instructions on testing the Win32
version. However, on Win32 systems, there is no Unix system log
file, so if something goes wrong, look in the file
@file{c:\apcupsd\etc\apcupsd\apcupsd.events} where apcupsd
normally logs its events, and you will generally find more detailed
information on why the program is not working. The most common
cause of problems is either improper configuration of the cable
type, or an incorrect address for the serial port.
@node Upgrading, Post Installation, Testing, The Windows Version of apcupsd
@section Upgrading
@cindex Windows, Upgrading
@cindex Upgrading Windows
On Win98 and Win95 systems, to upgrade to a new release, simply
stop apcupsd by using the tray icon and
selecting the @strong{Close
apcupsd} menu item, or by double
clicking on the @strong{Stop} icon located in
the @file{c:\apcupsd\bin} directory, then apply the
upgrade and restart apcupsd.
On WinNT systems (and Win2000 systems), you may stop
apcupsd as indicated abover or
alternatively you may stop apcupsd by using
the @strong{Services} item in the @strong{Control Panel}. In addition, at least on my
system, there seems to be a WinNT bug that causes the system to
prevent @strong{apcupsd.exe} from being
overwritten even though the file is no longer being used. This is
manifested by an error message when attempting load a new version and
overwrite the old apcupsd.exe (the extract
part of WinZip as described above). To circumvent this problem (if it
happens to you), after shutting down the running version of
apcupsd, through the @strong{Services} dialogue in the @strong{Control Panel}, first click on the @strong{Stop button}:
@image{wininstall6,,,,png}
then click on the @strong{Startup ...}
button, and in the Startup dialogue select the @strong{Disabled} button to disable
apcupsd:
@image{wininstall7,,,,png}
After closing the dialogues, reboot the system, typical of
Microsoft :-(. When the system comes back up,
apcupsd will not be automatically launched
as a service, and you can install the new version. To reinstate
apcupsd as an automatic service, using the
@strong{Control Panel}: reset
apcupsd to @strong{Automatic} startup in the Startup dialogue, then
restart apcupsd in the @strong{Services} dialogue as shown above in the
installation instructions. Frequently after an upgrade, you will click
on the @strong{Start} button and after a few
seconds, the system reports that it failed to start. The cause of this
problem is unknown, but the solution is simply to click again on the
@strong{Start} button.
@node Post Installation, Problem Areas, Upgrading, The Windows Version of apcupsd
@section Post Installation
@cindex Windows, Post Installation
After installing apcupsd and before
running it, you should check the contents of two files to ensure that
it is configured properly for your system. The first is
@file{c:\apcupsd\etc\apcupsd\apcupsd.conf}. You will
probably need to change your UPSCABLE directive, your UPSTYPE and
possibly your DEVICE directives. Please refer to the configuration
section of this manual for more details.
The second file that you should examine is
@file{c:\apcupsd\etc\apcupsd\apccontrol}. This file is
called by apcupsd when events (power loss,
etc) are generated. It permits the user to program handling the
event. In particular, it permits the user to be notified of the
events. For the Win32 version, each event is programmed to display a
Windows popup dialogue box. If your machine is mostly unattended, you
may want to comment out some of these popup dialogue boxes by putting
a pound sign (#) in column one of the appropriate line.
@node Problem Areas, Utility Functions, Post Installation, The Windows Version of apcupsd
@section Problem Areas
@cindex Problems, Windows
@cindex Windows, Problems
In addition to possible problems of reinstallation or upgrade on
WinNT systems, as noted above, we have discovered the following
problem: On some Windows systems, the domain resolution does not seem
to work if you have not configured a DNS server in the Network section
of the Control Panel. This problem should be apparent only when
running a master or a slave configuration. In this case, when you
specify the name of the master or the slave machine(s) in your
@file{apcupsd.conf} file, apcupsd will be unable to
resolve the name to a valid IP address. To circumvent this problem,
simply enter all machine addresses as an IP address rather than a
domain name, or alternatively, ensure that you have a valid DNS server
configured on your system (often not the case on Win32 systems). For
example, instead of using the directive "MASTER
my.master.com" use something like "MASTER 192.168.1.54"
where you replace the IP address with your actual IP address.
Also, on WinNT systems, the PIF files in
@file{/apcupsd/bin} used for starting and stopping
apcupsd do not work. Use the services
control panel instead.
On Win95 systems, there are reports that the PIF files do not
work. If you find that to be the case, the simplest solution is to use
the batch files that we have supplied in the
@file{c:/apcupsd/bin} directory. Also, on Win95 systems,
we have an unconfirmed report that indicates that
apcupsd does not start automatically as a
service even though the Registry has been properly updated. If you
experience this problem, a work around is to put a shortcut to
apcupsd in the StartUp folder.
As noted above, after an upgrade, you may need to start
apcupsd several times before it will
actually run.
On WinNT, WinXP, and Win2K systems, you can examine the System
Applications log to which apcupsd writes
Windows error messages during startup.
Regardless of which Windows system you are running,
apcupsd logs most error messages to
@file{c:\apcupsd\etc\apcupsd\apcupsd.events}. This type
error messages such as configuration file not found, etc are written
to this file.
@node Utility Functions, Disclaimer, Problem Areas, The Windows Version of apcupsd
@section Utility Functions
The directory @file{c:\apcupsd\bin} contains six
utility routines (actually .pif files) that you may find useful. They
are:
@example
Start
Stop
Install
Uninstall
ups-events
ups-status
@end example
Any of these utilities may be used on any system, with the
exception of the Start utility, which cannot be used on WinNT and
Win2000 systems. On those systems, the apcupsd service must always be
started through the @strong{Services}
sub-dialogue of the @strong{Control
Panel}.
The @strong{Install} and @strong{Uninstall} utilities install and uninstall
apcupsd from the system registry only. All other pieces (files) of
apcupsd remain intact. It is not absolutely necessary for apcupsd to
be installed in the registry as it can run as a regular
program. However, if it is not installed in the registry, it cannot be
run as a service.
The functions of @strong{Stop},
@strong{ups-events}, and @strong{ups-status} can be more easily invoked by right
clicking on the apcupsd icon in the system tray and selecting the
desired function from the popup menu.
@node Disclaimer, Email Notification of Events, Utility Functions, The Windows Version of apcupsd
@section Disclaimer
@cindex Disclaimer
Some of the features such as EEPROM programming have not been
exhaustively tested on Win32 systems. If at all possible, we
recommend not to use it as a network master on Win95, Win98, and
WinMe due to the instability of those operating systems.
Some items to note:
@itemize
@item
This version of apcupsd will not attempt to shut off the
UPS power when the battery is exhausted. Thus if the power returns
before the UPS completely shuts down, your computer may not reboot
automatically. This is because we do not know how to regain control
after the disks have been synced in order to shut off the UPS
power.
Nevertheless, it is possible to use the
@code{--kill-on-powerfail} option on the apcupsd command
line, but the use of this option could cause the power to be cut
off while your machine is still running. See @ref{Shutdown Sequence <1>,,Shutdown Sequence} of this document for a more complete
discussion of this subject. If you are still interested in trying
to get this to work, please look at the code that is commented out
in @file{c:\apcupsd\etc\apcupsd\apccontrol} under
the @strong{doshutdown} case.
An alternative to the @code{--kill-on-powerfail}
option is to use the KILLDELAY (@pxref{KILLDELAY <time in seconds>})
configuration directive.
This configuration directive is appropriate on Windows machines
where apcupsd continues to run even when the machine is
halted (as is the case on most NT machines).
@item
When apcupsd detects important events, it calls
@file{c:\apcupsd\etc\apcupsd\apccontrol}, which is a
Unix shell script. You may modify this script to suit your
particular needs. Currently, it puts a Windows dialogue on the
screen with a brief explanation of the event. If these dialogues
annoy you, you can remove or comment out the calls to @strong{popup} from this file.
@end itemize
@node Email Notification of Events, Killpower under Windows, Disclaimer, The Windows Version of apcupsd
@section Email Notification of Events
@cindex Email
@cindex Notification, Email
On Win95/98 systems, it is possible to receive notification of
apcupsd events that are passed to
apccontrol. This is possible using a simple
email program that unfortunately is not functioning 100% correctly. In
addition, I (Kern) was not able to make this program work on WinNT
while apcupsd is running as a service under the system account (it
works fine with any user account).
If you wish to try this program on Win95/98 systems, look at the
files named @strong{changeme, commfailure, commok,
onbattery, and mainsback} in the directory
@file{c:\apcupsd\examples}. To use them, you must modify
the SYSADMIN variable to have a valid email address, then copy the
files into the directory
@file{c:\apcupsd\etc\apcupsd}.
@node Killpower under Windows, Power Down During Shutdown, Email Notification of Events, The Windows Version of apcupsd
@section Killpower under Windows
@cindex Windows, Killpower
If your batteries become exhausted during a power failure and
you want your machine to automatically reboot when the power comes
back, it is useful to implement the
killpower feature of the UPS where apcupsd
sends the UPS the command to shut off the power. In doing so, the
power will be cut to your PC and if your BIOS is properly setup, the
machine will automatically reboot when the power comes back. This is
important for servers.
This feature is implemented on Unix systems by first requesting
a system shutdown. As a part of the shutdown, apcupsd is terminated
by the system, but the shutdown process executes a script where
apcupsd is recalled after the disks are synced and the machine is
idle. Apcupsd then requests the UPS to shut off the power
(killpower).
Unfortunately on Windows, there is no such shutdown script that
we are aware of and no way for apcupsd to get control after the
machine is idled. If this feature is important to you, it is
possible to do it by telling apcupsd to immediately issue the
killpower command after issuing the shutdown request. The danger in
doing so is that if the machine is not sufficiently idled when the
killpower takes place, the disks will need to be rescanned (and
there is a possibility of lost data however small). Generally,
UPSes have a shutdown grace period which gives sufficient time for
the OS to shutdown before the power is cut.
To implement this feature, you need to add the
@code{-p} option to the apcupsd command line that is
executed by the system. Currently the procedure is manual. You do so
by editing the registry and changing the line:
@example
c:\apcupsd\apcupsd.exe /service
@end example
found under the key:
@example
HKEY_LOCAL_MACHINE Software\Microsoft\Windows\CurrentVersion\RunServices
@end example
to
@example
c:\apcupsd\apcupsd.exe /service -p
@end example
If you have a Smart UPS, you can configure the kill power grace
period, and you might want to set it to 3 minutes. If you have a
dumb UPS, there is no grace period and you should not use this
procedure. If you have a Back-UPS CS or ES, these UPSes generally
have a fixed grace period of 2 minutes, which is probably
sufficient.
@node Power Down During Shutdown, Command Line Options Specific to the Windows Version, Killpower under Windows, The Windows Version of apcupsd
@section Power Down During Shutdown
@cindex Windows, Power down
@cindex Power down, Windows
Our philosophy is to shutdown a computer but not to power it down
itself (as opposed to having the UPS cut the power as described
above). That is we prefer to idle a computer but leave it running.
This has the advantage that in a power fail situation, if the
killpower function described above does not work, the computer will
continue to draw down the batteries and the UPS will hopefully
shutoff before the power is restore thus permitting an automatic
reboot.
Nevertheless some people prefer to do a full power down. To do
so, you might want to get a copy of PsShutdown, which does have a
power down option. You can find it and a lot more useful software at:
@uref{http://www.sysinternals.com/ntw2k/freeware/pstools.shtml,http://www.sysinternals.com/ntw2k/freeware/pstools.shtml}.
to use their shutdown program rather than the apcupsd supplied
version, you simply edit:
@example
c:\apcupsd\etc\apcupsd\apccontrol
@end example
with any text editor and change our calls to shutdown to
psshutdown.
@node Command Line Options Specific to the Windows Version, Building the Win32 Version from the Source, Power Down During Shutdown, The Windows Version of apcupsd
@section Command Line Options Specific to the Windows Version
@cindex Windows, Options
These options are not normally seen or used by the user, and are
documented here only for information purposes. At the current time,
to change the default options, you must either manually run
apcupsd or you must manually edit the system registry and
modify the appropriate entries.
In order to avoid option clashes between the options necessary
for apcupsd to run on Windows and the standard
apcupsd options, all Windows specific options are signaled
with a forward slash character (/), while as usual, the standard
apcupsd options are signaled with a minus (-), or a minus
minus (--). All the standard apcupsd options can be used on
the Windows version. In addition, the following Windows only
options are implemented:
@table @asis
@item /servicehelper
Run the service helper application
@item /service
Start apcupsdas a service
@item /run
Run the apcupsd application
@item /install
Install apcupsd as a service in the system registry
@item /remove
Uninstall apcupsd from the system registry
@item /about
Show the apcupsd about dialogue box
@item /status
Show the apcupsd status dialogue box
@item /events
Show the apcupsd events dialogue box
@item /kill
Stop any running apcupsd
@item /help
Show the apcupsd help dialogue box
@end table
It is important to note that under normal circumstances the user
should never need to use these options as they are normally handled
by the system automatically once apcupsd is installed.
However, you may note these options in some of the .pif files that
have been created for your use.
@node Building the Win32 Version from the Source, , Command Line Options Specific to the Windows Version, The Windows Version of apcupsd
@section Building the Win32 Version from the Source
@cindex Windows, Building
@cindex Building, Windows
If you have the source code, follow the standard procedures for
building apcupsd on Unix in @ref{Building and Installing apcupsd} of this manual. Please don't forget to look
at the system specifics for CYGWIN.
@node Installation on Serial-Line UPSes, Technical Reference, Installation on Windows, Top
@majorheading Installation: Serial-Line UPSes
@menu
* Overview of Serial-Interface UPSes::
* Connecting a Serial-Line UPS to a USB Port::
* Connecting a APC USB UPS to either a PC USB or Serial Port::
* Cables::
* Testing Serial-Line UPSes::
* Troubleshooting Serial Line communications::
* Recalibrating the UPS Runtime::
* DATA Logging::
@end menu
@node Overview of Serial-Interface UPSes, Connecting a Serial-Line UPS to a USB Port, , Installation on Serial-Line UPSes
@chapter Overview of Serial-Interface UPSes
@cindex Serial UPSes
If you have a UPS that communicates via serial port, you need to
do two things before you can even think about configuring the
software. First, you need to figure out whether it's a dumb
(voltage-signalling) UPS or speaks the apcsmart protocol (see this discussion (@pxref{upstypes})). Second, if you have an
interface cable from APC, you need to figure out what kind it is. If
you don't have such a cable, you need to build one. A
straight-through serial cable won't
work (@pxref{crazy}).
According to Bill Marr the Belkin F5U109, also sold as
F5U409 also works with apcupsd for kernel versions 2.4.25 or
higher and kernels 2.6.1 and higher. These newer kernels are
needed to have the patch that makes the mct_u232 (Magic
Control Technology) module and other
adapters work with RS-232 devices that do not assert the CTS
signal.
@node Connecting a Serial-Line UPS to a USB Port, Connecting a APC USB UPS to either a PC USB or Serial Port, Overview of Serial-Interface UPSes, Installation on Serial-Line UPSes
@chapter Connecting a Serial-Line UPS to a USB Port
@cindex Serial on USB
By using a special adaptor, you can connect your serial-line UPS
to a USB port. If you would like to free up your serial port and
connect your existing serial port UPS to a USB port, it is possible if
you have one of the later kernels. You simply get a serial to USB
adapter that is supported by the kernel, plug it in and make one minor
change to your @file{apcupsd.conf} file and away you
go. (Kern adds: Thanks to Joe Acosta for pointing this out to
me.)
The device that Joe Acosta and Kern are using is IOgear GUC232A USB 2
serial adapter. Bill Marr
informs us that it also works with a Back-UPS Pro 650 and the 940-0095B
cable.
At Kern's site, running Red Hat 7.1 with kernel 2.4.9-12, he
simply changed his @file{/etc/apcupsd/apcupsd.conf}
configuration line to be:
@example
DEVICE /dev/ttyUSB0
@end example
Depending on whether or not you have @strong{hotplug} working, you may need to explicitly
load the kernel modules @strong{usbserial} and
@strong{pl2303}. In Kern's case, this was not
necessary.
@node Connecting a APC USB UPS to either a PC USB or Serial Port, Cables, Connecting a Serial-Line UPS to a USB Port, Installation on Serial-Line UPSes
@chapter Connecting a APC USB UPS to either a PC USB or Serial Port
An interesting fact is that
the USB ports (actually an RJ45 connector) on APC UPSes not only speak
USB, but also serial apcsmart and dumb voltage-signalling as well!
This is something that one of our users discovered by accident. With the
Custom RJ45 cable (actually a RJ45 to serial cable)
described below plugged into the APC UPS USB socket at
one end and the other end plugged into a serial port on your PC, any
APC USB UPS (except some of the newer really low cost models)
will act as a serial-line device.
@node Cables, Testing Serial-Line UPSes, Connecting a APC USB UPS to either a PC USB or Serial Port, Installation on Serial-Line UPSes
@chapter Cables
@cindex Cables
You can either use the cable that came with your UPS
(the easiest if we support it) or you can make your own cable. We
recommend that you obtain a supported cable directly from APC.
If you already have an APC cable, you can determine what kind it
is by examining the flat sides of the two connectors where you will
find the cable number embossed into the plastic. It is generally on
one side of the male connector.
To make your own cable you must first know whether you have a
UPS that speaks the apcsmart protocol or a "dumb" UPS that
uses serial port line voltage signalling.
If you have an apcmart UPS, and you build your
own cable, build a @emph{Smart-Custom} cable. If you
have a voltage-Signalling or dumb UPS, build a
@emph{Simple-Custom} cable. If you have a BackUPS CS
with a RJ45 connector, you can build your own
@emph{Custom-RJ45} cable.
@menu
* Smart-Custom Cable for SmartUPSes::
* Smart Signalling Cable for BackUPS CS Models::
* Voltage-Signalling Cable for "dumb" UPSes::
* Other APC Cables that apcupsd Supports::
* Voltage Signalling Features Supported by Apcupsd for Various Cables::
* Voltage Signalling::
* The Back-UPS Office 500 signals::
* Analyses of APC Cables::
* Win32 Implementation Restrictions for Simple UPSes::
* Internal Apcupsd Actions for Simple Cables::
* RS232 Wiring and Signal Conventions::
* Pin Assignment for the Serial Port (RS-232C), 25-pin and 9-pin, Female End: Pin Assignment for the Serial Port [RS-232C]; 25-pin and 9-pin; Female End.
* Ioctl to RS232 Correspondence::
@end menu
@node Smart-Custom Cable for SmartUPSes, Smart Signalling Cable for BackUPS CS Models, , Cables
@section Smart-Custom Cable for SmartUPSes
@cindex Smart Custom Cable
@cindex Cables, Smart Custom
@example
SMART-CUSTOM CABLE
Signal Computer UPS
DB9F DB9M
RxD 2 -------------------- 2 TxD Send
TxD 3 -------------------- 1 RxD Receive
GND 5 -------------------- 9 Ground
@end example
When using this cable with apcupsd
specify the following in @file{apcupsd.conf}:
If you have an OS that requires DCD or RTS to be set before
you can receive input, you might try building the standard
APC Smart 940-0024C cable listed below.
@example
UPSCABLE smart
UPSTYPE apcsmart
DEVICE /dev/ttyS0 (or whatever your serial port is)
@end example
If you wish to build the standard cable furnished by
APC (940-0024C), use the following diagram.
@example
APC Smart Cable 940-0024C
Signal Computer UPS
DB9F DB9M
RxD 2 -------------------- 2 TxD Send
TxD 3 -------------------- 1 RxD Receive
DCD 1 --*
|
DTR 4 --*
GND 5 -------------------- 9 Ground
RTS 7 --*
|
CTS 8 --*
@end example
@node Smart Signalling Cable for BackUPS CS Models, Voltage-Signalling Cable for "dumb" UPSes, Smart-Custom Cable for SmartUPSes, Cables
@section Smart Signalling Cable for BackUPS CS Models
@cindex Cables, Smart Signalling
@cindex Cables, BackUPS CS
If you have a BackUPS CS, you are probably either using it with
the USB cable that is supplied or with the 940-0128A supplied by APC,
which permits running the UPS in dumb mode. By building your own
cable, you can now run the BackUPS CS models (and perhaps also the ES
models) using smart signalling and have all the same information that
is available as running it in USB mode.
The jack in the UPS is actually a 10 pin RJ45. However, you can
just as easily use a 8 pin RJ45 connector, which is more standard
(ethernet TX, and ISDN connector). It is easy to construct the cable
by cutting off one end of a standard RJ45-8 ethernet cable and wiring
the other end (three wires) into a standard DB9F female serial port
connector.
Below, you will find a diagram for the CUSTOM-RJ45 cable:
@example
CUSTOM-RJ45 CABLE
Signal Computer UPS UPS
DB9F RJ45-8 RJ45-10
RxD 2 ---------------- 1 2 TxD Send
TxD 3 ---------------- 7 8 RxD Receive
GND 5 ---------------- 6 7 Ground
FG Shield ---------------- 3 4 Frame Ground
The RJ45-8 pins are: looking at the end of the connector:
8 7 6 5 4 3 2 1
___________________
| . . . . . . . . |
| |
-------------------
|____|
The RJ45-10 pins are: looking at the end of the connector:
10 9 8 7 6 5 4 3 2 1
_______________________
| . . . . . . . . . . |
| |
-----------------------
|____|
@end example
For the serial port DB9F connector, the pin numbers are stamped
in the plastic near each pin. In addition, there is a diagram near the
end of this chapter.
Note, one user, Martin, has found that if the shield is not
connected to the Frame Ground in the above diagram (not in
our original schematic), the UPS (a BackUPS CS 500 EI) will be
unstable and likely to rapidly switch from power to batteries (i.e.
chatter).
When using this cable with apcupsd
specify the following in @file{apcupsd.conf}:
@example
UPSCABLE smart
UPSTYPE apcsmart
DEVICE /dev/ttyS0 (or whatever your serial port is)
@end example
The information for constructing this cable was discovered and
transmitted to us by slither_man. Many thanks!
@node Voltage-Signalling Cable for "dumb" UPSes, Other APC Cables that apcupsd Supports, Smart Signalling Cable for BackUPS CS Models, Cables
@section Voltage-Signalling Cable for "dumb" UPSes
@cindex Cables, dumb
@cindex dumb, Cables
@strong{NOTE. YOU DO NOT HAVE THIS CABLE UNLESS
YOU BUILT IT YOURSELF. THE SIMPLE-CUSTOM CABLE IS NOT AN APC
PRODUCT.}
For "dumb" UPSes using voltage signalling, if you are going to
build your own cable, we recommend to make the cable designed by
the apcupsd team as follows:
@example
SIMPLE-CUSTOM CABLE
Signal Computer UPS
DB9F 4.7K ohm DB9M
DTR 4 --[####]--* DTR set to +5V by Apcupsd
|
CTS 8 ----------*--------- 5 Low Battery
GND 5 -------------------- 4 Ground
DCD 1 -------------------- 2 On Battery
RTS 7 -------------------- 1 Kill UPS Power
@end example
List of components one needs to make the Simple cable:
@enumerate
@item
One (1) male DB9 connector, use solder type connector only.
@item
One (1) female DB9/25F connector, use solder type connector only.
@item
One (1) 4.7K ohm 1/4 watt 5% resistor.
@item
resin core solder.
@item
three (3) to five (5) feet of 22AWG multi-stranded four or more
conductor cable.
@end enumerate
@enumerate
@item
Solder the resistor into pin 4 of the female DB9
connector.
@item
Next bend the resistor so that it connects to pin 8 of the
female DB9 connector.
@item
Pin 8 on the female connector is also wired to pin 5 on the
male DB9 connector. Solder both ends.
@item
Solder the other pins, pin 5 on the female DB9 to pin 4 on the
male connector; pin 1 on the female connector to pin 2 on the male
connector; and pin 7 on the female connector to pin 1 on the male
connector.
@item
Double check your work.
@end enumerate
We use the DTR (pin 4 on the female connector) as our +5 volts
power for the circuit. It is used as the Vcc pull-up voltage for
testing the outputs on any "UPS by APC" in voltage-signalling
mode. This cable may not work on a BackUPS Pro if the default
communications are in apcsmart mode. This cable is also valid for
"ShareUPS" BASIC Port mode and is also reported to work on
SmartUPSes. However, the Smart Cable described above is much
simpler. To have a better idea of what is going on inside
apcupsd, for the SIMPLE cable
apcupsd reads three signals and sets
three:
@example
Reads:
CD, which apcupsd uses for the On Battery signal when high.
CTS, which apcupsd uses for the Battery Low signal when high.
RxD (SR), which apcupsd uses for the Line Down
signal when high. This signal isn't used for much.
Sets:
DTR, which apcupsd sets when it detects a power failure (generally
5 to 10 seconds after the CD signal goes high). It
clears this signal if the CD signal subsequently goes low
-- i.e. power is restored.
TxD (ST), which apcupsd clears when it detects that the CD signal
has gone low after having gone high - i.e. power is restored.
RTS, which apcupsd sets for the killpower signal -- to cause the UPS
to shut off the power.
@end example
Please note that these actions apply only to the SIMPLE cable,
the signals used on the other cables are different.
Finally, here is another way of looking at the CUSTOM-SIMPLE
cable:
@example
APCUPSD SIMPLE-CUSTOM CABLE
Computer Side | Description of Cable | UPS Side
DB9f | DB25f | | DB9m | DB25m
4 | 20 | DTR (5vcc) *below | n/c |
8 | 5 | CTS (low battery) *below | <- 5 | 7
2 | 3 | RxD (no line voltage) *below | <- 3 | 2
5 | 7 | Ground (Signal) | 4 | 20
1 | 8 | CD (on battery from UPS) | <- 2 | 3
7 | 4 | RTS (kill UPS power) | -> 1 | 8
n/c | 1 | Frame/Case Gnd (optional) | 9 | 22
Note: the <- and -> indicate the signal direction.
Optional connections of original SIMPLE-CUSTOM specification
that are not used.
4.7K ohm
DTR 4 --[####]--* Note needed
|
RxD 2 ----------*--------- 3 Not used by Apcupsd
@end example
When using this cable with apcupsd
specify the following in @file{apcupsd.conf}:
@example
UPSCABLE simple
UPSTYPE dumb
DEVICE /dev/ttyS0 (or whatever your serial port is)
@end example
@node Other APC Cables that apcupsd Supports, Voltage Signalling Features Supported by Apcupsd for Various Cables, Voltage-Signalling Cable for "dumb" UPSes, Cables
@section Other APC Cables that apcupsd Supports
apcupsd will also support the
following off the shelf cables that are supplied by APC
@itemize
@item
940-0020B/C Simple Signal Only, all models.
@item
940-0023A Simple Signal Only, all models.
@item
940-0119A Simple Signal Only, Back-UPS Office, and BackUPS ES.
@item
940-0024[B/C/G] SmartMode Only, SU and BKPro only.
@item
940-0095[A/B/C] PnP (Plug and Play), all models.
@item
940-1524C SmartMode Only
@item
940-0127A/B USB Cables
@item
940-0128A Simple Signal Only, Back-UPS CS in serial mode.
@end itemize
@node Voltage Signalling Features Supported by Apcupsd for Various Cables, Voltage Signalling, Other APC Cables that apcupsd Supports, Cables
@section Voltage Signalling Features Supported by Apcupsd for Various Cables
The following table shows the features supported by the current
version of apcupsd (3.8.5 or later) for
various cables running the UPS in voltage-signalling mode.
@multitable @columnfractions 0.2 0.2 0.2 0.2 0.2
@item
Cable@tab Power Loss@tab Low Battery@tab Kill Power@tab Cable Disconnected
@item
940-0020B@tab Yes@tab No@tab Yes@tab No
@item
940-0020C@tab Yes@tab Yes@tab Yes@tab No
@item
940-0023A@tab Yes@tab No@tab No@tab No
@item
940-0119A@tab Yes@tab Yes@tab Yes@tab No
@item
940-0127A@tab Yes@tab Yes@tab Yes@tab No
@item
940-0128A@tab Yes@tab Yes@tab Yes@tab No
@item
940-0095A/B/C@tab Yes@tab Yes@tab Yes@tab No
@item
simple@tab Yes@tab Yes@tab Yes@tab No
@end multitable
@node Voltage Signalling, The Back-UPS Office 500 signals, Voltage Signalling Features Supported by Apcupsd for Various Cables, Cables
@section Voltage Signalling
@cindex Voltage Signalling, Cables
@cindex Cables, Voltage Signalling
Apparently, all APC voltage-signalling UPSes have the same
signals on the output pins of the UPS. The difference at the computer
end is due to different cable configurations. Thus, by measuring the
connectivity of a cable, one can determine how to program the UPS.
This is to be verified.
The signals presented or accepted by the UPS on its DB9
connector using the numbering scheme listed above is:
@example
UPS Pin Signal meaning
1 <- Shutdown when set by computer for 1-5 seconds.
2 -> On battery power (this signal is normally low but
goes high when the UPS switches to batteries).
3 -> Mains down (line fail) See Note 1 below.
5 -> Low battery. See Note 1 below.
6 -> Inverse of mains down signal. See Note 2 below.
7 <- Turn on/off power (only on advanced UPSes only)
Note 1: these two lines are normally open, but close when the
appropriate signal is triggered. In fact, they are open collector
outputs which are rated for a maximum of +40VDC and 25 mA. Thus
the 4.7K ohm resistor used in the Custom Simple cable works
quite well.
Note 2: the same as note 1 except that the line is normally closed,
and opens when the line voltage fails.
@end example
@node The Back-UPS Office 500 signals, Analyses of APC Cables, Voltage Signalling, Cables
@section The Back-UPS Office 500 signals
@cindex Cables, BackUPS Office
@cindex BackUPS Office, cables
The Back-UPS Office UPS has a telephone type jack as output,
which looks like the following:
@example
Looking at the end of the connector:
6 5 4 3 2 1
_____________
| . . . . . . |
| |
| |----------|
|__|
@end example
It appears that the signals work as follows:
@example
UPS Signal meaning
1 (brown) <- Shutdown when set by computer for 1-5 seconds.
2 (black) -> On battery power
3 (blue) -> Low battery
4 (red) Signal ground
5 (yellow) <- Begin signalling on other pins
6 (none) none
@end example
@node Analyses of APC Cables, Win32 Implementation Restrictions for Simple UPSes, The Back-UPS Office 500 signals, Cables
@section Analyses of APC Cables
@cindex Cables
@menu
* 940-0020B Cable Wiring::
* 940-0020C Cable Wiring::
* 940-0023A Cable Wiring::
* 940-0095A Cable Wiring::
* 940-0095B Cable Wiring::
* 940-0119A Cable Wiring::
* BackOffice ES::
* BackUPS ES and CS in Serial mode with Cable 940-0128A::
@end menu
@node 940-0020B Cable Wiring, 940-0020C Cable Wiring, , Analyses of APC Cables
@subsection 940-0020B Cable Wiring
@cindex Cables
This diagram is for informational purposes and is not complete.
Although we do not know what the black box semi-conductor contains,
we believe that we understand its operation (many thanks to Lazar
M. Fleysher for working this out).
This cable can only be used on voltage-signalling UPSes, and
provides the On Battery signal as well as kill UPS power. Most recent
evidence (Lazar's analysis) indicates that this cable under the right
conditions may provide the Low Battery signal. This is to be
confirmed.
@example
APC Part# - 940-0020B
Signal Computer UPS
DB9F DB9M
CTS 8 -------------------- 2 On Battery
DTR 4 -------------------- 1 Kill power
GND 5 ---------------*---- 4 Ground
|
--- *---- 9 Common
DCD 1 ----|///|----------- 5 Low Battery
|\\\|
RTS 7 ----|///| (probably a
--- semi-conductor)
@end example
Thanks to Lazar M. Fleysher.
@node 940-0020C Cable Wiring, 940-0023A Cable Wiring, 940-0020B Cable Wiring, Analyses of APC Cables
@subsection 940-0020C Cable Wiring
@cindex Cables
This diagram is for informational purposes and may not be
complete, we don't recommend that use it to build you build one
yourself. This cable can only be used on voltage-signalling UPSes, and
provides the On Battery signal, the Low Battery signal as well as kill
UPS power. In apcupsd versions 3.8.2 and
prior, please set your UPSCABLE to 940-0020B. In version 3.8.3 and
later, you may specify the cable as 940-0020C. Please note that this
diagram may not be accurate.
@example
APC Part# - 940-0020C
Signal Computer UPS
DB9F DB9M
CTS 8 -------------------- 2 On Battery
DTR 4 -------------------- 1 Kill power
GND 5 ---------------*---- 4 Ground
|
*---- 9 Common
RTS 7 -----[ 93.5K ohm ]----- 5 Low Battery
or semi-conductor
@end example
@node 940-0023A Cable Wiring, 940-0095A Cable Wiring, 940-0020C Cable Wiring, Analyses of APC Cables
@subsection 940-0023A Cable Wiring
@cindex Cables
This diagram is for informational purposes and may not be
complete, we don't recommend that use it to build you build one
yourself. This cable can only be used on voltage-signalling UPSes, and
apparently only provides the On Battery signal. As a consequence, this
cable is pretty much useless, and we recommend that you find a better
cable because all APC UPSes support more than just On Battery. Please
note that we are not sure the following diagram is correct.
@example
APC Part# - 940-0023A
Signal Computer UPS
DB9F DB9M
DCD 1 -------------------- 2 On Battery
3.3K ohm
TxD 3 --[####]-*
|
DTR 4 ---------*
GND 5 ---------------*---- 4 Ground
|
*---- 9 Common
@end example
@node 940-0095A Cable Wiring, 940-0095B Cable Wiring, 940-0023A Cable Wiring, Analyses of APC Cables
@subsection 940-0095A Cable Wiring
@cindex Cables
This is the definitive wiring diagram for the 940-0095A cable
submitted by Chris Hanson <cph at zurich.ai.mit.edu>, who
disassembled the original cable, destroying it in the process. He then
built one from his diagram and it works perfectly.
@example
Construction and operation of the APC #940-0095A cable.
This cable is included with the APC Back-UPS Pro PNP series.
UPS end Computer end
------- ------------
47k 47k
BATTERY-LOW (5) >----R1----*----R2----*----< DTR,DSR,CTS (4,6,8)
| |
| |
| / E
| |/
| B |
*-------| 2N3906 PNP
|
|\
\ C
|
|
*----< DCD (1) Low Batt
|
|
R 4.7k
3
|
4.7k |
SHUTDOWN (1) >----------*----R4----*----< TxD (3)
|
| 1N4148
*----K|---------< RTS (7) Shutdown
POWER-FAIL (2) >--------------------------< RxD,RI (2,9) On Batt
GROUND (4,9) >--------------------------< GND (5)
Operation:
* DTR is "cable power" and must be held at SPACE. DSR or CTS may be
used as a loopback input to determine if the cable is plugged in.
* DCD is the "battery low" signal to the computer. A SPACE on this
line means the battery is low. This is signalled by BATTERY-LOW
being pulled down (it is probably open circuit normally).
Normally, the transistor is turned off, and DCD is held at the MARK
voltage by TxD. When BATTERY-LOW is pulled down, the voltage
divider R2/R1 biases the transistor so that it is turned on, causing
DCD to be pulled up to the SPACE voltage.
* TxD must be held at MARK; this is the default state when no data is
being transmitted. This sets the default bias for both DCD and
SHUTDOWN. If this line is an open circuit, then when BATTERY-LOW is
signalled, SHUTDOWN will be automatically signalled; this would be
true if the cable were plugged in to the UPS and not the computer,
or if the computer were turned off.
* RTS is the "shutdown" signal from the computer. A SPACE on this
line tells the UPS to shut down.
* RxD and RI are both the "power-fail" signals to the computer. A
MARK on this line means the power has failed.
* SPACE is a positive voltage, typically +12V. MARK is a negative
voltage, typically -12V. Linux appears to translate SPACE to a 1
and MARK to a 0.
@end example
@node 940-0095B Cable Wiring, 940-0119A Cable Wiring, 940-0095A Cable Wiring, Analyses of APC Cables
@subsection 940-0095B Cable Wiring
@cindex Cables
This diagram is for informational purposes and may not be complete,
we don't recommend that use it to build one yourself.
@example
APC Part# - 940-0095B
Signal Computer UPS
DB9F DB9M
DTR 4 ----*
CTS 8 ----|
DSR 6 ----|
DCD 1 ----*
GND 5 ---------------*---- 4 Ground
|
*---- 9 Common
RI 9 ----*
|
RxD 2 ----*--------------- 2 On Battery
TxD 3 ----------[####]---- 1 Kill UPS Power
4.7K ohm
@end example
@node 940-0119A Cable Wiring, BackOffice ES, 940-0095B Cable Wiring, Analyses of APC Cables
@subsection 940-0119A Cable Wiring
@cindex Cables
This diagram is for informational purposes and may not be complete,
we don't recommend that use it to build you build one yourself.
This cable is used with the BackUPS Office UPSes.
@example
APC Part# - 940-0119A
UPS Computer
pins pins Signal Signal meaning
1 (brown) 4,6 DSR DTR <- Shutdown when set by computer for 1-5 seconds.
2 (black) 8,9 RI CTS -> On battery power
3 (blue) 1,2 CD RxD -> Low battery
4 (red) 5 Ground
5 (yellow) 7 RTS <- Begin signalling on other pins
6 (none) none
@end example
@node BackOffice ES, BackUPS ES and CS in Serial mode with Cable 940-0128A, 940-0119A Cable Wiring, Analyses of APC Cables
@subsection BackOffice ES
@cindex Cables
@cindex BackOffice ES
The BackUPS ES has a straight through serial cable with no
identification on the plugs. To make it work with
apcupsd, specify the @strong{UPSCABLE 940-0119A} and @strong{UPSTYPE backups}. The equivalent of cable
940-0119A is done on a PCB inside the unit. Thanks to William Stock
for supplying us with the information about the straight through
cable, the PCB, and the following diagram:
@example
computer ----------- BackUPS-ES -----------------
DB9-M DB-9F
pin signal pin
4 DSR -> 4 --+
| diode resistor
6 DTR -> 6 --+---->|----/\/\/\---o kill power
1 DCD <- 1 --+
|
2 RxD <- 2 --+----------------+--o low battery
|
7 RTS -> 7 --------+--/\/\/\--+
|
+--/\/\/\--+
|
8 RI <- 8 --+----------------+--o on battery
|
9 CTS <- 9 --+
5 GND --- 5 ----------------------o ground
3 TxD 3 nc
@end example
@node BackUPS ES and CS in Serial mode with Cable 940-0128A, , BackOffice ES, Analyses of APC Cables
@subsection BackUPS ES and CS in Serial mode with Cable 940-0128A
@cindex BackUPS ES
@cindex Cables
Though these UPSes are USB UPSes, APC supplies a serial cable
(typically with a green DB9 F connector) that has 940-0128A stamped
into one side of the plastic serial port connector. The other end of
the cable is a 10 pin RJ45 connector that plugs into the UPS (thanks
to Dean Waldow for sending me a cable!). Apcupsd version 3.8.5 and
later supports this cable when specified as @strong{UPSCABLE 940-0128A} and @strong{UPSTYPE backups}. However, running in this mode
much of the information that would be available in USB mode is
lost. In addition, when apcupsd attempts to
instruct the UPS to kill the power, it begins cycling about 4 times a
second between battery and line. The solution to the problem (thanks
to Tom Suzda) is to unplug the UPS and while it is still chattering,
press the power button (on the front of the unit) until the unit beeps
and the chattering stops. After that the UPS should behave normally
and power down 1-2 minutes after requested to do so.
An amazing discovery by slither_man allows one to build a
CUSTOM-RJ45 cable (documented above) and run the BackUPS CS (and
probably also the ES) in Smart mode. Running it this way provides
all the same information that you would get by running it in USB
mode. As a consequence, we recommend that you either purchase
(where I don't know) or build your own CUSTOM-RJ45 cable rather
than use the 940-0128A cable.
Thanks to all the people who have helped test this and have
provided information on the cable wiring, our best guess for the
cable schematic is the following:
@example
computer --------- Inside the Connector--------- UPS
DB9-F | | RJ45
pin - signal | | Pin - Color
| |
4 DSR ->|---+ |
| | diode resistor |
6 DTR ->|---+---->|----/\/\/\---o kill power | 8 Orange
| |
1 DCD <-|----+ |
| | |
2 RxD <-|----+----------------+--o low battery| 3 Brown
| | |
7 RTS ->|----------+--/\/\/\--+ |
| | |
| +--/\/\/\--+ |
| | |
8 RI <-|----+----------------+--o on battery | 2 Black
| | |
9 CTS <-|----+ |
| signal |
5 GND --|-----------------------o ground | 7 Red
| |
3 TxD | |
| chassis |
Chassis/GND |-----------------------o ground | 4 Black
| |
| Not connected | 1, 5, 6, 9, 10
--------------------------------------
The RJ45 pins are: looking at the end of the connector:
10 9 8 7 6 5 4 3 2 1
_______________________
| . . . . . . . . . . |
| |
-----------------------
|____|
@end example
From Jan Babinski jbabinsk at pulsarbeacon dot com: (many thanks)
The BackUPS XS1000(BX-1000) ships with the 940-0127B usb cable and the
optional 940-0128D serial cable. I'm trying to get it running under OpenBSD
so usb is out of the question. I've tried smart serial with the custom
cable, but that's not working, so I'm stuck with dumb serial over 940-0128D.
I have noticed that this cable is not supported by apcupsd so I set out to
find out how much different this cable is compared with the supported ones.
After tearing the cable apart (see schematic below) I noticed that it is
functionally similar to the 940-0128A cable except for NC on (6) DTR and (2)
RD on the computer side.
@example
Cable 940-0128D
DB9(Computer) RJ45-10(UPS)
(5) (1) ____________
( o o o o o ) [ oooooooooo ]
\ o o o o / [____________]
(9) (6) (10) [_] (1)
RI(9)<---+
|
CTS(8)<---+--- E 2N2222(NPN)
\|___
____ /| B |
| C |
| |
+---vvvv---+--[>|------<(2)OnBatt
RTS(7)>---| 2k 1N5819
+---vvvv---+--[>|------<(3)LowBatt
| |
+--- C |
\|___|
/| B
DCD(1)<------- E 2N2222(NPN)
DTR(4)>-------------------------->(8)KillPwr
GND(5)----------------------------(7)Signal GND
(Shield)--------------------------(4)Chassis GND
Cable 940-0127B
USB(Computer) RJ45-10(UPS)
_________ ____________
| = = = = | [ oooooooooo ]
|_________| [____________]
(1) (4) (10) [_] (1)
+5V(1)-----------(1)+5V
DATA+(2)-----------(9)DATA+
DATA-(3)-----------(10)DATA-
GND(4)-----------(7)Signal GND
(Shield)-----------(4)Chassis GRND
@end example
@node Win32 Implementation Restrictions for Simple UPSes, Internal Apcupsd Actions for Simple Cables, Analyses of APC Cables, Cables
@section Win32 Implementation Restrictions for Simple UPSes
@cindex Cables
@cindex Windows
Due to inadequacies in the Win32 API, it is not possible to
set/clear/get all the serial port line
signals. apcupsd can detect: CTS, DSR, RNG,
and CD. It can set and clear: RTS and DTR.
This imposes a
few minor restrictions on the functionality of some of the cables. In
particular, LineDown on the Custom Simple cable, and Low Battery on
the 0023A cable are not implemented.
@node Internal Apcupsd Actions for Simple Cables, RS232 Wiring and Signal Conventions, Win32 Implementation Restrictions for Simple UPSes, Cables
@section Internal Apcupsd Actions for Simple Cables
@cindex Cables
@example
This section describes how apcupsd 3.8.5 (March 2002)
treats the serial port line signals for simple cables.
apcaction.c:
condition = power failure detected
cable = CUSTOM_SIMPLE
action = ioctl(TIOCMBIS, DTR) set DTR (enable power bit?)
apcaction.c:
condition = power back
cable = CUSTOM_SIMPLE
action = ioctl(TIOCMBIC, DTR) clear DTR (clear power bit)
action = ioctl(TIOCMBIC, ST) clear ST (TxD)
apcserial.c:
condition = serial port initialization
cable = 0095A, 0095B, 0095C
action = ioctl(TIOMBIC, RTS) clear RTS (set PnP mode)
cable = 0119A, 0127A, 0128A
action = ioctl(TIOMBIC, DTR) clear DTR (killpower)
action = ioctl(TIOMBIS, RTS) set RTS (ready to receive)
apcserial.c:
condition = save_dumb_status
cable = CUSTOM_SIMPLE
action = ioctl(TIOMBIC, DTR) clear DTR (power bit?)
action = ioctl(TIOMBIC, RTS) clear RTS (killpower)
cable = 0020B, 0020C, 0119A, 0127A, 0128A
action = ioctl(TIOMBIC, DTR) clear DTR (killpower)
cable = 0095A, 0095B, 0095C
action = ioctl(TIOMBIC, RTS) clear RTS (killpower)
action = ioctl(TIOMBIC, CD) clear DCD (low batt)
action = ioctl(TIOMBIC, RTS) clear RTS (killpower) a second time!
apcserial.c:
condition = check_serial
cable = CUSTOM_SIMPLE
action = OnBatt = CD
action = BattLow = CTS
action = LineDown = SR
cable = 0020B, 0020C, 0119A, 0127A, 0128A
action = OnBatt = CTS
action = BattLow = CD
action = LineDown = 0
cable = 0023A
action = Onbatt = CD
action = BattLow = SR
action = LineDown = 0
cable = 0095A, 0095B, 0095C
action = OnBatt = RNG
action = BattLow = CD
action = LineDown = 0
apcserial.c
condition = killpower
cable = CUSTOM_SIMPLE, 0095A, 0095B, 0095C
action = ioctl(TIOMCBIS, RTS) set RTS (kills power)
action = ioctl(TIOMCBIS, ST) set TxD
cable = 0020B, 020C, 0119A, 0127A, 0128A
action = ioctl(TIOMCBIS, DTR) set DTR (kills power)
@end example
@node RS232 Wiring and Signal Conventions, Pin Assignment for the Serial Port [RS-232C]; 25-pin and 9-pin; Female End, Internal Apcupsd Actions for Simple Cables, Cables
@section RS232 Wiring and Signal Conventions
@cindex Cables
@multitable @columnfractions 0.25 0.25 0.25 0.25
@item
DB-25
Pin #@tab DB-9
Pin #@tab Name@tab DTE-DCE Description
@item
1@tab --@tab FG@tab --- Frame Ground/Chassis GND
@item
2@tab 3@tab TD@tab ---> Transmitted Data, TxD
@item
3@tab 2@tab RD@tab <--- Received Data, RxD
@item
4@tab 7@tab RTS@tab ---> Request To Send
@item
5@tab 8@tab CTS@tab <--- Clear To Send
@item
6@tab 6@tab DSR@tab <--- Data Set Ready
@item
7@tab 5@tab SG@tab ---- Signal Ground, GND
@item
8@tab 1@tab DCD@tab <--- Data Carrier Detect
@item
9@tab --@tab --@tab --- Positive DC test voltage
@item
10@tab --@tab --@tab --- Negative DC test voltage
@item
11@tab --@tab QM@tab <--- Equalizer mode
@item
12@tab --@tab SDCD@tab <--- Secondary Data Carrier Detect
@item
13@tab --@tab SCTS@tab <--- Secondary Clear To Send
@item
14@tab --@tab STD@tab ---> Secondary Transmitted Data
@item
15@tab --@tab TC@tab <--- Transmitter (signal) Clock
@item
16@tab --@tab SRD@tab <--- Secondary Receiver Clock
@item
17@tab --@tab RC@tab ---> Receiver (signal) Clock
@item
18@tab --@tab DCR@tab <--- Divided Clock Receiver
@item
19@tab --@tab SRTS@tab ---> Secondary Request To Send
@item
20@tab 4@tab DTR@tab ---> Data Terminal Ready
@item
21@tab --@tab SQ@tab <--- Signal Quality Detect
@item
22@tab 9@tab RI@tab <--- Ring Indicator
@item
23@tab --@tab --@tab ---> Data rate selector
@item
24@tab --@tab --@tab <--- Data rate selector
@item
25@tab --@tab TC@tab <--- Transmitted Clock
@end multitable
@node Pin Assignment for the Serial Port [RS-232C]; 25-pin and 9-pin; Female End, Ioctl to RS232 Correspondence, RS232 Wiring and Signal Conventions, Cables
@section Pin Assignment for the Serial Port (RS-232C), 25-pin and 9-pin, Female End
@cindex Cables
@example
13 1 5 1
_______________________________ _______________
\ . . . . . . . . . . . . . / \ . . . . . / RS232-connectors
\ . . . . . . . . . . . . / \ . . . . / looking into the
--------------------------- ----------- end of the cable.
25 14 9 6
The diagram above represents the Female end of the cable. The
male end is the same, but looking from inside the cable.
DTE : Data Terminal Equipment (i.e. computer)
DCE : Data Communications Equipment (i.e. UPS)
RxD : Data received; 1 is transmitted "low", 0 as "high"
TxD : Data sent; 1 is transmitted "low", 0 as "high"
DTR : DTE announces that it is powered up and ready to communicate
DSR : DCE announces that it is ready to communicate; low=modem hang-up
RTS : DTE asks DCE for permission to send data
CTS : DCE agrees on RTS
RI : DCE signals the DTE that an establishment of a connection is attempted
DCD : DCE announces that a connection is established
@end example
@node Ioctl to RS232 Correspondence, , Pin Assignment for the Serial Port [RS-232C]; 25-pin and 9-pin; Female End, Cables
@section Ioctl to RS232 Correspondence
@cindex Cables
@example
#define TIOCM_LE 0x001
#define TIOCM_DTR 0x002
#define TIOCM_RTS 0x004
#define TIOCM_ST 0x008
#define TIOCM_SR 0x010
#define TIOCM_CTS 0x020
#define TIOCM_CAR 0x040
#define TIOCM_RNG 0x080
#define TIOCM_DSR 0x100
#define TIOCM_CD TIOCM_CAR
#define TIOCM_RI TIOCM_RNG
#define TIOCM_OUT1 0x2000
#define TIOCM_OUT2 0x4000
@end example
@node Testing Serial-Line UPSes, Troubleshooting Serial Line communications, Cables, Installation on Serial-Line UPSes
@chapter Testing Serial-Line UPSes
@cindex Testing, Serial
@cindex Serial, Testing
If you have a serial-line UPS, there are some tests you should
run before the general ones described in the Testing (@pxref{Testing Apcupsd}) section.
To test your computer's connection with a serial-line UPS, you first
need to establish that the serial line is functioning, and then that the
UPS is responding to commands. This can be a bit tricky, especially
with a dumb voltage-signalling interface, because it is completely
quiescent when there are no commands being passed, and the command
repertoire doesn't include any self-tests.
Because it is easy to configure a serial cable incorrectly in
such a way as to cause premature shutdowns of the UPS power, we
@emph{strongly} recommend, especially for voltage-
signaling (dumb) UPSes, that you do most of the initial testing with
your computer plugged into the wall rather than your UPS. Thus if the
UPS power is suddenly shut off, your computer will continue to run. We
also recommend using safe-apccontrol as
described below, until you are sure that the signaling is
correct.
Also note that if you launch the execution of
apcupsd while your voltage-signaling UPS is
on battery power, it is very likely that your UPS will immediately
shut off the power. This is due to the initialization of the serial
port line signals, which often looks to the UPS like a shutdown
command.
Finally, double-check the state of your cabling and UPS
indicator lights frequently during testing. For voltage-signaling
UPSes, apcupsd is not currently able to
detect whether or not the serial cable is connected. In addition, some
simple signaling UPSes with certain cable combinations are not able to
detect the low battery condition. For more details please see
@ref{Voltage Signalling Features Supported by Apcupsd for Various Cables}.
@menu
* Establishing Serial Port Connection::
* Using apctest on Serial-Line UPSses::
@end menu
@node Establishing Serial Port Connection, Using apctest on Serial-Line UPSses, , Testing Serial-Line UPSes
@section Establishing Serial Port Connection
@cindex Testing, Serial
Once you have compiled, installed, and invoked
apcupsd, you should wait to allow
apcupsd to configure itself and establish
contact with the UPS.
If you see the following message about 30 seconds after starting
apcupsd:
@example
apcupsd FATAL ERROR in apcserial.c at line 156
PANIC! Cannot communicate with UPS via serial port.
@end example
it means that apcupsd tried for about
30 seconds to establish contact with the UPS via the serial port, but
was unable to do so. Before continuing, you must correct this
problem. Some of the possible sources of the problem are:
@itemize
@item
You have not configured the correct serial port name on the
DEVICE directive in your @file{apcupsd} configuration
file.
@item
The serial port that you have chosen has logins enabled. You must
disable logins on that port, otherwise, the system prevents
apcupsd from using it.
Normally, the file @file{/etc/inittab} specifies the
ports for which a getty process is started
(on Sun machines, the serial port program equivalent to
getty is called
ttymon). You must disable this for the port
that you wish to use.
@item
Make sure you are doing your testing as
@strong{root} otherwise, you may have permissions
problems accessing the serial port.
@item
You may have cabling problems, either with an incorrect cable, or the
incorrect cable specification directive in the configuration file.
@item
You may have a problem with the
@file{/etc/apcupsd/acpupsd.conf} file. For example, check
that you have specified the correct type of UPS and the correct networking
directives. For more details, see the
@ref{After Installation}.
@item
If you have a SmartUPS 5000 RM 15U or similar model, that comes
with a "Web/SNMP management card" in one of the "Smart
Slots", this card may interfere with the serial port operation.
If you are having problems, please remove this card and try again.
Supposedly V3.0 of the card firmware has been corrected to properly
release the serial port.
@item
Ensure that you have no other programs that are using the serial
port. One user reported that he had problems because the serial port
mouse (gpm) was using the same port as apcupsd.
This causes intermittent seemingly random problems.
@item
If you are using a WinNT or Win2000 machine, the OS is probably
attempting to attach a serial mouse to the port you are using (COM1 or
COM2). To prevent this, edit your @file{c:\boot.ini} file,
and you will find a line that looks something like the following:
@example
multi(0)disk(0)rdisk(0)partition(1)\WINNT="Windows NT Workstation Version 4.00"
@end example
@noindent
Add the following to the end of the line:
@file{/NoSerialMice:COM1} (or COM2) so that the new line
looks like:
@example
multi(0)disk(0)rdisk(0)partition(1)\WINNT="Windows NT Workstation Version 4.00" /NoSerialMice:COM1
@end example
@item
If you are using a WinNT or Win2000 machine, try connecting
apcupsd to COM2 rather than COM1 (be sure to
change your @file{c:\apcupsd\etc\apcupsd\apcupsd.conf} to
reflect the change).
@item
If you are using a Solaris machine, you may have similar problems
as described above for the WinNT machine. A possible fix is documented
in the Sun section of the Configuration chapter of this manual.
@item
Try connecting your UPS to another machine. If it works, then you
probably have a bad serial port card. As unlikely as this may sound, at
least two of our users have had to replace bad serial port cards.
@item
Try doing an @code{lsof /dev/ttyS0} where you replace
the @strong{/dev/ttyS0} with your serial port
name. If you get no output, the port is free (or there is no physical
port). If you get output, then another program is using the port, and
you should see which one.
@item
Try doing a @code{dmesg | grep tty}. This may show
you if a program has grabbed the port. (Thanks to Joe Acosta for the
suggestion.)
@item
If all else fails, make sure your system is configured for serial
port support.
@item
If you are running Linux, check your @file{/proc}
file system. For example: @code{cat /proc/devices} should
print something like @emph{4 ttyS} if you have a serial
port. If your serial port is working, a @code{cat
/proc/interrupts} should show the serial port usage (e.g.
@strong{4: 294553 XT-PIC serial}) Also,
@code{cat /proc/ioports} should show up something like
@strong{03f8-03ff : serial(auto)}. Or,
@code{cat /proc/tty} should print a line like
@strong{serial /dev/ttyS 4 64-127 serial}.
Finally, a @code{cat /proc/tty/driver/serial} should
print something like the following:
@example
serinfo:1.0 driver:5.05c revision:2001-07-08
0: uart:16550A port:3F8 irq:4 baud:9600 tx:1503168 rx:1461721 fe:8
@end example
@end itemize
The first thing to do is to look at your log file, usually
@file{/var/log/messages} because
apcupsd writes more detailed information to
the log file whenever there is an error.
If you have a UPS that uses apcsmart protcol (see table of types (@pxref{type_table}) for a list of the UPSes
using these protocols), you can manually test the serial
communications with the UPS by starting a serial port communications
program (such as minicom,
tip, or cu) with
the settings 2400 8N1 (2400 baud, 8 bits, no parity, 1 stop bit). Be
extremely careful what you send to your UPS as certain characters may
cause it to power down or may even cause damage to the UPS. Try
sending an upper case Y to the UPS (without a return at the end). It
should respond with SM. If this is not the case, review the possible
problems listed above. If you fat finger the Y and enter y instead, no
cause for alarm, you will simply get the APC copyright notice.
Once you are sure that serial port communications is working,
proceed to the next test.
@node Using apctest on Serial-Line UPSses, , Establishing Serial Port Connection, Testing Serial-Line UPSes
@section Using apctest on Serial-Line UPSses
@cindex apctest
@cindex Testing, with apctest
On an apcsmart serial-line UPS, apctest
will give you access to the battery of low-level tests we described in
@ref{apctest}. If you have a voltage-signalling UPS,
it enables a different test repertoire which is described here, Among
other things, if you are uncertain about what kind of cable you have,
you may be able to use apctest to figure
that out.
Shutdown apcupsd if it is running.
Make sure your @file{/etc/apcupsd/apcupsd.conf} file has
@strong{UPSTYPE backups} and @strong{UPSCABLE simple} Normally
apctest will have been built and installed
by default, otherwise, you can explicitly build it on Unix
with:
@example
cd <apcupsd-source-directory>
make apctest
./apctest
@end example
on Win32 systems, use:
@example
make apctestwin32
./apctest
@end example
It will present you with the following output
@example
2001-02-07 04:08:26 apctest 3.8.5 (3 January 2002) redhat
Checking configuration ...
sharenet.type = DISABLE
cable.type = CUSTOM_SIMPLE
mode.type = BK
Setting up serial port ...
Creating serial port lock file ...
Doing prep_serial() ...
Hello, this is the apcupsd Cable Test program.
This part of apctest is for testing dumb UPSes (ones that uses signaling rather than commands.
Most tests enter a loop polling every second for 10 seconds.
@end example
Then it will present you with the following list of choices:
@example
1) Test 1 - normal mode
2) Test 2 - no cable
3) Test 3 - no power
4) Test 4 - low battery (requires test 3 first)
5) Test 5 - battery exhausted
6) Test 6 - kill UPS power
7) Test 7 - run tests 1 through 5
8) Guess which is the appropriate cable
9) quit
Select test number:
@end example
Run tests 1, 2, and 3. Note, none of the currently supported cables
will indicate a change for test 2. You can then run test 8 to see
what cable it thinks you should be using. Finally run test 4.
apctest can also be run for Smart UPSes.
The print out of your testing will be written to the file
@file{apctest.output}. If you are unable to solve your
problem, you can try posting that file to the development mailing
list, and perhaps we can help you. In this case, please also include
information on your operating system, which version of
apcupsd you are using, your UPS model, and
also your @file{apcupsd.conf} file.
@menu
* Expected apctest Signals for a UPS::
* Expected apctest Signals for a BackUPS Pro::
@end menu
@node Expected apctest Signals for a UPS, Expected apctest Signals for a BackUPS Pro, Using apctest on Serial-Line UPSses, Using apctest on Serial-Line UPSses
@subsection Expected apctest Signals for a UPS
@cindex Testing
@cindex apctest
If you have configured your UPS as:
@example
UPSTYPE backups
UPSCABLE APC_940_0119A
or APC_940_0127A
or APC_940_0128A
or APC_940_0020B
or APC_940_0020C
@end example
here are typical signals you would expect to see in the output from
the various tests of apctest:
@example
Test 1 normal: RTS for cables (0119A 0127A 0128A)
Test 2 no serial cable: not important
Test 3 no AC power: CTS for all cables
Test 4 batteries exhausted: CTS and CD for all cables
@end example
Note: @strong{RTS} if set in Test 1 will
probably also be set in all the other tests. This is not important,
what counts is the appearance of @strong{CTS}
when the power fails and additionally @strong{CD} when the batteries are low.
@node Expected apctest Signals for a BackUPS Pro, , Expected apctest Signals for a UPS, Using apctest on Serial-Line UPSses
@subsection Expected apctest Signals for a BackUPS Pro
@cindex Testing
@cindex apctest
If you have configured your UPS as:
@example
UPSTYPE backupspro
UPSCABLE APC_940_0095A
or APC_940_0095C
@end example
here are the typical signals you would expect to see in the output
from the various tests of apctest:
@example
Test 1 normal: RTS not set
Test 2 no serial cable: not important
Test 3 no AC power: RNG
Test 4 batteries exhausted: RNG and CD
@end example
Note: @strong{RTS} should never be set
in any of the tests as it is the killpower signal. What is important
is the appearance of @strong{RNG} when the
power fails and additionally @strong{CD} when
the batteries are low.
@node Troubleshooting Serial Line communications, Recalibrating the UPS Runtime, Testing Serial-Line UPSes, Top
@chapter Troubleshooting Serial Line communications
@cindex Problems, Serial
@cindex Serial Problems
@menu
* Determining Which Voltage-Signaling Cable You Have::
* Once you have established serial communications::
@end menu
@node Determining Which Voltage-Signaling Cable You Have, Once you have established serial communications, Troubleshooting Serial Line communications, Troubleshooting Serial Line communications
@section Determining Which Voltage-Signaling Cable You Have
@emph{The most frequently encountered problem with
voltage-signalling UPSes (e.g. BackUPS 650) is that you have
incorrectly specified which cable is being used.} All cables
furnished by APC have the cable number stamped on the side of the
computer connector end of the cable. Using this number with
apcupsd will normally work fine. If you do
not know what cable you have, you can use the
apctest program to determine the type of
the cable.
For simple signaling UPSes, you should @emph{not}
use @strong{simple} in the cable specification
(i.e. @strong{UPSCABLE simple}) unless you
have made the cable yourself according to the wiring diagram given in
the cables chapter of this manual.
@node Once you have established serial communications, , Determining Which Voltage-Signaling Cable You Have, Troubleshooting Serial Line communications
@section Once you have established serial communications
@cindex Testing
Once you have established that
apcupsd can talk to the UPS over the serial
part, go do the series of functional tests described in the main
Testing (@pxref{Testing Apcupsd}) section.
One additional note applies:
@menu
* Bizarre Intermittent Behavior::
@end menu
@node Bizarre Intermittent Behavior, , Once you have established serial communications, Once you have established serial communications
@subsection Bizarre Intermittent Behavior
In one case, a user reported that he received random incorrect
values from the UPS in the status output. It turned out that
gpm, the mouse control program for command
windows, was using the serial port without using the standard Unix
locking mechanism. As a consequence, both
apcupsd and gpm
were reading the serial port. Please ensure that if you are running
gpm that it is not configured with a serial
port mouse on the same serial port.
@node Recalibrating the UPS Runtime, DATA Logging, Troubleshooting Serial Line communications, Top
@chapter Recalibrating the UPS Runtime
@cindex Runtime recalibration
@cindex Recalibration Runtime
Note: In a future release of apcupsd
this procedure will be replaced by a daemon operation that can be
performed on all types of UPS.
This section does not apply to voltage-signalling or dumb UPSes
such as the older BackUPS models.
Smart UPSes internally compute the remaining runtime, and
apcupsd uses the value supplied by the
UPS. As the batteries age (after say two or three years), the runtime
computation may no longer be accurate since the batteries no longer
hold the same charge. As a consequence, in the event of a power
failure, the UPS and thus apcupsd can
report a runtime of 5 minutes remaining when in fact only one minute
remains. This can lead to a shutdown before you might expect it,
because regardless of the runtime remaining that is reported, the UPS
will always correctly detect low batteries and report it, thus causing
apcupsd to correctly shutdown your
computer.
If you wish to have the UPS recalibrate the remaining runtime
calculations, you can do so manually as the current version of
apcupsd does not support this feature. To
do so,
@itemize
@item
Shutdown apcupsd
@item
contact your UPS directly using some terminal program such as
minicom, tip, or cu with the settings 2400 8N1 (2400 baud, 8 bits,
no parity, 1 stop bit). Be extremely careful what you send to your
UPS as certain characters may cause it to power down or may even
cause damage to the UPS. Try sending an upper case Y to the UPS
(without a return at the end). It should respond with SM. If this
is not the case, read the chapter on testing. If you fat finger the
Y and enter y instead, no cause for alarm, you will simply get the
APC copyright notice.
@item
when you are sure you are properly connected send an upper case
D (no cr). This will put the UPS into calibration mode, and it will
drain the battery down to 25% capacity (35% for a Matrix) at which
point it will go back on the mains. In doing so, it will recompute
the runtime calibration.
@item
If you wish to abort the calibration, enter a second D command.
@item
When you are done, restart apcupsd.
@end itemize
In principle, you should be able to do this with the computer
powered by the UPS, but if you wish to be completely safe, you should
plug your computer into the wall prior to performing the runtime
calibration. In that case, you will need to artificially load the UPS
with light bulbs or other means. You should supply a load of about 30
to 35% but not more than 50%. You can determine the load by looking at
the output of the @code{apcaccess status} command while
apcupsd is running.
You should not run the recalibration command more than once or
twice per year as discharging these kinds of batteries tends to
shorten their life span.
@menu
* Status Logging On Serial-Line UPSes::
@end menu
@node Status Logging On Serial-Line UPSes, , Recalibrating the UPS Runtime, Recalibrating the UPS Runtime
@section Status Logging On Serial-Line UPSes
Serial-line UPSes that speak the apcsmart protocol log all of
the events described in the Status
Format (@pxref{apcupsd Status Logging}) section of the Technical Reference. Voltage-signalling
UPSes, on the other hand, have a much narrower data channel. They
can only report a small handful of conditions.
The following summarizes (rather sketchily, sorry) the
data you can expect to get from this obsolete hardware. All
corrections and additions will be welcome.
From BackUPS Pro and SmartUPS v/s:
@example
LINEFAIL : OnlineStatus
BATTSTAT : BatteryStatus
MAINS : LineVoltageState
LASTEVNT : LastEventObserved
@end example
BackUPS and NetUPS Simple Signals
@example
LINEFAIL : OnlineStatus
BATTSTAT : BatteryStatus
@end example
@node DATA Logging, , Recalibrating the UPS Runtime, Installation on Serial-Line UPSes
@chapter DATA Logging
@cindex Logging, DATA
@cindex DATA Logging
This feature is somewhat outdated and not often used.
Data logging consists of periodically logging important data
concerning the operation of the UPS. For the definitive definition
of the format, see log_data() in apcreports.c. The format varies
according to the UPS model and the information available from the
UPS.
For UPS models, NBKPRO, SMART, SHARESMART, and MATRIX, the
output is written in a format very similar to what PowerChute
writes. That is:
MinLineVoltage, MaxLineVoltage, OutputVoltage, BatteryVoltage,
LineFrequency, LoadPercent,
UPSTemperature,AmbientTemperature,Humidity,LineVoltage,
BatteryCharge,toggle
Any value that is not supported by your UPS such as
AmbientTemperature and Humidity will be blank or possibly as 0.0.
In any case the commas before and after that field will still be
output. The toggle value alternates from 0 to 1 on each line. This
was added at user request so that no two adjacent samples are
identical.
An actual example from the log file is:
@example
Nov 2 12:43:05 matou apcupsd[23439]: 224.9,227.5,226.2,27.74,50.00,100.0,30.6,,,226.2,50.0,1
@end example
@node Technical Reference, Credits <1>, Installation on Serial-Line UPSes, Top
@majorheading Technical Reference
@cindex Technical Reference
@menu
* Configuration Directive Reference::
* apcupsd Status Logging::
* The Shutown Sequence and its Discontents::
* APC smart protocol::
* Apcupsd -- RPM Packaging FAQ::
@end menu
@node Configuration Directive Reference, apcupsd Status Logging, , Technical Reference
@chapter Configuration Directive Reference
@cindex Reference, Directives
@cindex Configuration, Directives
@cindex Directives
Configuration directives in
@file{/etc/apcupsd/apcupsd.conf} control the behavior
of the apcupsd daemon. For most installations
it is only necessary to set a handful of general directives. The rest
can be left at their defaults unless you have an exotic configuration.
@menu
* General Configuration Directives::
* Configuration Directives Used by the Network Information Server::
* Configuration Directives used during Power Failures::
* Configuration Directives used to Control System Logging::
* Configuration Directives for Sharing a UPS::
* Configuration Directives Used to Set the UPS EPROM::
@end menu
@node General Configuration Directives, Configuration Directives Used by the Network Information Server, , Configuration Directive Reference
@section General Configuration Directives
@cindex Directives, General
@cindex General Directives
In general, each of these directives is required (ecept that the DEVICE
directive is ignored for UPSCABLE ether).
@table @asis
@item UPSTYPE <type of APC UPS you have>
The name of a driver. Should be one of
@samp{dumb}, @samp{apcsmart},
@samp{net}, @samp{usb},
@samp{snmp}, or @samp{test}. This
describes your interface type.
The UPSTYPE directive can be defined during
installation by using the @code{--with-upstype=} option of
the @code{./configure} program.
@item UPSCABLE <type of cable you are using>>
@example
[ simple | 940-0020B | 940-0023A ]
[ smart | 940-0024B | 940-0024C ]
[ 940-1524C | 940-0024G | 940-0095A | 940-0095B | 940-0095C | 940-0119A]
[ ether | usb ]
@end example
The @code{--with-upscable=} option of
@code{./configure} can be used to set a default for
this directive during the your build.
@item DEVICE <name of device>
Specify which device is used for UPS communications.
For serial ports, it is usually something like @file{/dev/ttyS0}.
For USB ports, you may leave the name of the device blank (no
specification) and apcupsd will
automatically search the standard locations for the UPS.
Normally, the @code{./configure} program will
set an appropriate default value. You may also specify the
@code{--with-serial-dev=} option of the
@code{./configure} program to set this directive
at build time.
If you have specified
@strong{UPSTYPE net}, then the device name
to be specified consists of
@strong{hostname:port} where the hostname
is the fully qualified name or IP address of the host (NIS server)
and the port (optional) is the port to use to contact the
server.
If you specified @strong{UPSTYPE snmp},
then the device name becomes
@strong{hostname:vendor:community}. Please
see the SNMP chapter (@pxref{Support for SNMP UPSes}) in this manual
for more details.
@item LOCKFILE <path to lockfile>
This option tells apcupsd
where to create a lockfile for the USB or serial port in the
specified directory. This is important to keep two programs from
reading or writing the port at the same time. Please note
that although the directive name is LOCKFILE, you are actually
specifying the lock file path. apcupsd
automatically appends the name of the device when creating the file.
On most systems, this directive is automatically set by the
@code{./configure} program. You may also explicitly
set it during the build process by using the
@code{--with-lock-dir=} option of the
@code{./configure} program.
@end table
@node Configuration Directives Used by the Network Information Server, Configuration Directives used during Power Failures, General Configuration Directives, Configuration Directive Reference
@section Configuration Directives Used by the Network Information Server
@cindex Directives, Network
@cindex Network directives
None of these directives are required for proper operation of
apcupsd. For the Network Information Server
to work, it must be enabled in the configuration (default) with
@code{--enable-nis}
@table @asis
@item NETSERVER [on | off]
This configuration directive turns the network information
server on or off. If it is on, apcupsd
will spawn a child process that serves STATUS and EVENTS information
over the network. This information is currently used by the Web-based
CGI programs. The default is on. In some cases, for added security,
you may want to invoke a separate information server daemon from the
inetd daemon. In that case, @emph{NETSERVER} should be
@emph{off}.
@item NISIP <IP-address>
This directive specifies an IP address on which NIS server will
listen for incoming connections. Default value is 0.0.0.0 that
means any incoming request will be serviced but if you want it to
listen to a single subnet you can set it up to that subnet address,
for example 192.168.10.0. Additionally you can listen for a single
IP like 192.168.10.1. You may also use the @code{--with-nisip=}
option of the @code{./configure} program to set this
directive during the build.
This directive does not work on Win32 machines because
inet_ipton() is not implemented there.
@item NISPORT <port>
This configuration directive specifies the port to be used by
the apcupsd Network Information Server.
The default is platform dependent, but typically 3551, which we have
received from IANA as the official apcupsd
networking port. If you change this port, you must manually change the
#define SERV_TCP_PORT in cgi/upsfetch.c and rebuild the CGI programs.
An alternative is to use the @code{--with-nis-port=} option
of the @code{./configure} program during the build.
In this case, all the appropriate locations will be automatically
changed.
@item EVENTSFILE <filename>
If you want the apcupsd
network information server to provide the last 10 events via the
network, you must specify a file where apcupsd
will save these events. The default is:
@file{/etc/apcupsd/apcupsd.events}.
Currently, apcupsd will save at most the
last 50 events. Periodically (once an hour by default),
apcupsd will check the size of this file.
When more than 50 events are recorded, apcupsd
will truncate the file to the most recent 10 events. Consequently this
file will not grow indefinitely. Although we do not recommend it,
you may change these values by editing apcevents.c and changing the
appropriate defines. Be aware that if you set these values to very
large numbers, apcupsd may make excessive
memory demands on the system during the data access and file truncation
operations.
This filename may also be specified at build time by
using the @code{--with-log-dir=} option of the
@code{./configure} program.
@end table
@node Configuration Directives used during Power Failures, Configuration Directives used to Control System Logging, Configuration Directives Used by the Network Information Server, Configuration Directive Reference
@section Configuration Directives used during Power Failures
@cindex Directives, Power fail
@cindex Power fail directives
In general, none of these directives are required. However, if
you have a voltage-signalling (dumb) UPS with a cable that does not
support the Low Battery signal, you must set the TIMEOUT directive to
force a shutdown. Please see the Cables (@pxref{Cables})
section of this manual for more details.
@table @asis
@item ANNOY <time in seconds>
Specify the time in seconds between messages requesting logged
in users to get off the system during a power failure. This timer
starts only when the UPS is running on batteries. The default is
300 seconds (5 minutes). apcupsd sends
the annoy messages by invoking the apccontrol
script with the @code{annoyme} argument. The default is
to send a wall message on Unix
systems and a popup message in Windows.
The value of @strong{ANNOYDELAY} must be
greater than the value of @strong{ANNOY} in
order to receive annoy messages (this doesn't make sense, and means
that the default values do not generate annoy messages: KES).
Note that if @strong{NOLOGON}
is set to @strong{disable} the annoy messages
will also be disabled.
@item ANNOYDELAY <time in seconds>
Specify delay time in seconds before
apcupsd begins requesting logged in users
to get off the system during a power failure. This timer starts only
after the UPS is running on batteries. This timer is reset when the
power returns. The default is 60 seconds. Thus, the first warning to
log off the system occurs after 60 seconds on batteries, assuming
that @strong{NOLOGON} is not set to
@strong{disable}.
@item NOLOGON <specifies when apcupsd should prevent user logins>
[ disable | timeout | percent | minutes | always ] are valid types.
The type specified allows you define the point when
apcupsd will create the
@file{/etc/nologin} file and thus when user
logins are prohibited. Once the @file{/etc/nologin} file
is created, normal users are prevented from logging in. Control of
when this file is created is important for allowing systems with
big UPSes to run as normally until the system administrator
determines the need for preventing user logins. The feature also
allows the system administrator to hold the "ANNOY" factor until
the @file{/etc/nologin} file is created. The default is
always if no NOLOGON directive is specified.
As far as I can tell, the only useful types are disable
and always since the difference in the time when the logout
warning is given and shutdown occurs for the other types is very
short (KES).
@table @asis
@item disable
prevents apcupsd from creating
the nologin file. Consequently, any user can login during a
power failure condition. Also, the ANNOY feature is disabled so
users will not be warned to logoff the system.
@item timeout
specifies that apcupsd should
prohibit logins after the UPS is on batteries for 90% of the
time specified on the @strong{TIMEOUT}
configuration directive. Note! Normally you don't want to
specify a TIMEOUT value, so this option is probably not too
useful (KES).
@item percent
specifies that apcupsd should prohibit logins when the remaining
battery charge percentage reaches 110% or less than the value
specified on the @strong{BATTERYLEVEL} configuration directive.
Thus if the @strong{BATTERYLEVEL} is specified as 15, apcupsd
will prohibit logins when the battery charge drops below 16% (15%
X 110% = 16%).
@item minutes
specifies that apcupsd should prohibit logins when the remaining
runtime in minutes reaches 110% or less than the value specified
on the @strong{MINUTES} configuration directive. Thus if
@strong{MINUTES} is set to 3, apcupsd will prohibit logins when
the remaining runtime is less than 3 minutes (3 X 110% = 3).
@item always
causes apcupsd to immediately
prohibit logins when a power failure occurs. This will also
enable the ANNOY feature.
@end table
@item BATTERYLEVEL <percent of battery>
If BATTERYLEVEL is specified, during a power failure,
apcupsd will halt the system when the
remaining battery charge falls below the specified percentage.
The default is 5 percent. This directive is ignored for dumb
(voltage-signalling) UPSes. To totally disable this counter, set
@strong{BATTERYLEVEL -1} in your
@file{apcupsd.conf} file.
@item MINUTES <battery runtime in minutes>
If MINUTES is specified, during a power failure,
apcupsd will shutdown the system when
the remaining runtime on batteries as internally calculated by
the UPS falls below the time specified. The default is 3. This
directive is ignored for dumb (voltage-signalling) UPSes. It
should be noted that some UPSes report an incorrect value for
remaining runtime when the battery is fully charged. This can be
checked by examining the @strong{TIMELEFT} value as printed in the output
of an @code{apcaccess status} command. If the value
is zero or otherwise unreasonable, your UPS is probably broken.
In this case, we recommend that you disable this timer by
setting @strong{MINUTES -1} in your
@file{apcupsd.conf} file.
@item TIMEOUT <time in seconds>
After a power failure, apcupsd will halt the system when TIMEOUT
seconds have expired. A value of zero disables this timer.
Normally for all Smart UPS models and dumb UPSes with cables that
support low battery detection, this should be zero so that the
shutdown time will be determined by the battery level and/or
remaining runtime (see above) or in the case of a
voltage-signalling UPS, when the battery is exhausted. This
command is required for dumb UPSes that do not provide a battery
exhausted signal (only testing can determine this point). For
more information, see the Testing (@pxref{Testing Apcupsd})
section of this manual. This timer can also be useful if you
want some slave machines to shutdown before other machines to
conserve battery power. It is also useful for testing apcupsd
because you can force a rapid shutdown by setting a small value
(e.g. 60) and pulling the plug to the UPS.
When apcupsd is running in master mode (UPSCLASS
netmaster), and a shutdown condition is determined,
apcupsd will notify each of the
slaves to perform a shutdown then apcupsd will sleep for 30
seconds before issuing the shutdown of its own computer. If you
need the master to wait additional time before shutting down (to
allow for shutdown of slower slaves or of slaves running
software that requires more time to shutdown --- e.g. databases),
you can do so by adding additional sleep() commands to
@file{/etc/apcupsd/apccontrol} in each case that
causes a shutdown.
@strong{TIMEOUT}, @strong{BATTERYLEVEL}, and @strong{MINUTES} can
be set together without problems. apcupsd will react to the
first case or test that is valid. Normally SmartUPS users will
set @strong{TIMEOUT} to zero so that the system is shutdown
depending on the percentage battery charge remaining
(@strong{BATTERYLEVEL}) or the remaining battery runtime
(@strong{MINUTES}).
@anchor{KILLDELAY <time in seconds>}@item KILLDELAY <time in seconds>
If killdelay is set, apcupsd will continue running after a
shutdown has been requested, and after the specified time in
seconds, apcupsd will attempt to shut off the UPS the power.
This directive should normally be disabled by setting the value
to zero, but on some systems such as Win32 systems apcupsd cannot
regain control after a shutdown to force the UPS to shut off the
power. In this case, with proper consideration for the timing,
the @strong{KILLDELAY} directive can be useful. Please be aware,
if you cause apcupsd to kill the power to your computer too
early, the system and the disks may not have been properly
prepared. In addition, apcupsd must continue running after the
shutdown is requested, and on Unix systems, this is not normally
the case as the system will terminate all processes during the
shutdown. @end table
@node Configuration Directives used to Control System Logging, Configuration Directives for Sharing a UPS, Configuration Directives used during Power Failures, Configuration Directive Reference
@section Configuration Directives used to Control System Logging
@cindex Directives Logging
@cindex Logging, directives
@table @asis
@item STATTIME<time>
This directive supplies the time interval between writes to the
STATUS file. If set to zero, the STATUS file will not be written.
Please note that in a future version of
apcupsd the STATUS
file code will disappear since its functionality has been replaced
by the Network Information Server and by
@strong{apcaccess status}, as a consequence,
it is normally disabled by setting it to zero.
@item STATFILE <file>
This directive specifies the file to be used when writing the
STATUS information. The default is
@file{/etc/apcupsd/apcupsd.status}.
@item DATATIME<time>
This directives supplies the time interval between writes
of PowerChute&tm; like data information to the log file. See
the Data (@pxref{DATA Logging}) section of this
manual for additional details.
@item FACILITY<log-facility>
The facility directive can be used to change the system logging
class or facility. The default is
@strong{DAEMON}. This parameter can be useful
if you wish to direct the apcupsd system
logging information to other than your system default files. See
the Logging section of this manual for additional
details.
@end table
@node Configuration Directives for Sharing a UPS, Configuration Directives Used to Set the UPS EPROM, Configuration Directives used to Control System Logging, Configuration Directive Reference
@section Configuration Directives for Sharing a UPS
@cindex Directives Sharing
The following directives apply to the master/slave networking
mode of apcupsd where multiple machines can
be powered by the same UPS. One machine, the master, will have a
serial port connection to the UPS, and the other machines, the slaves,
will obtain their information via the network from the master.
Note, as of version 3.10.x, the old master/slave code is by
default turned off in the configuration. You must explicitly enable
it by including a @code{--enable-master-slave} option on your
@code{./configure} command before building the source.
In addition to the old master/slave code, there is now a new
network driver enabled with @code{--enable-net} (default
disabled) that can be used to control a slave from any version of
apcupsd running NIS. This is a much more flexible system of
controlling slaves because a slave machine that also has NIS turned on
can thus act as a master for another slave with
@code{--enable-net} turned on. With this mode turned on, the
slave obtains the address of the master from the @strong{DEVICE} directive, which takes the form
@strong{hostname[:port]} as a consequence,
none of the directives apply for this form of networking. In addition,
for this mode to work, you must specify @strong{UPSTYPE
net} so that the proper driver is loaded.
The remainder of this section presents directives that apply to
the old master/slave code that must be enabled by the @strong{enable-master-slave} configuration
option.
@table @asis
@item UPSCLASS <class of operation>
[ standalone | shareslave | sharemaster ] and
[ netslave | netmaster ] are valid types.
[ standalone | netslave | netmaster ] are tested classes.
[ shareslave | sharemaster ] classes are being tested.
The default is @strong{standalone}
and should be used for all machines powered by the UPS and having a
serial port connection to the UPS, but where there are no other
computers dependent on power from the same UPS. This is the
normal case.
Use @strong{netmaster}, if and only
if you have a serial port connection to the UPS and there are other
machines deriving power from the same UPS. This is required in all
master configuration files.
Use @strong{netslave} if and only if
you have no serial port connection to the UPS, but you derive power
from it. This is required in all slave configuration files, and in
this case, you will also have UPSCABLE set to ether.
Use @strong{shareslave} if and only
if you are using a ShareUPS and connected to a BASIC Port with
Simple Signal. This code is not fully tested.
Use @strong{sharemaster}, if and only
if you are using a ShareUPS and connected to the ADVANCED Port Smart
Signal control. This code is not fully tested.
@item UPSMODE [disable | share | net | sharenet ] are valid types.
[ disable | net ] are the only known and tested classes.
[ share | sharenet ] classes are being tested.
For normal standalone operations, you will set UPSMODE to
disable to indicate that you are disabling the master/slave
networking.
However, if you are using a single UPS to power several
computers and you have configured master and slave computers, then
set this value to net.
Use share for two or seven (2/7) additional simple signal ports
on a SmartAccessories(tm) (internal/external box) for SmartUPSes.
The share and sharenet code is not fully tested.
@item NETTIME <time in seconds>
The interval in seconds that the master uses to send
information to slave machines. This rate is automatically set to 1
second if the UPS goes on batteries and reset to your specified
value when the mains power returns. A typical value might be 60
seconds.
@item NETPORT <IP port number>
This port number is used for communications in
the master/slave networking code. Note that the master and each slave
must have the same port number specified on the NETPORT directive in
the configuration file. This port may also be specified during
installation by using the @code{--with-net-port=} option of
the @code{./configure} program.
The NETPORT should not be confused with the port number for the
Network Information Server which is specified with the
@strong{SERVERPORT} configuration
directive.
@item MASTER <name of the master> for slave machines.
Used in slave configuration files, this is the network name of
the master which is authorized to send commands to this slave. In
all cases (of which I am aware), when you specify a
@strong{MASTER} directive, you will also specify
@strong{UPSCABLE ether} since your
information about the UPS will come via the network from a master.
The slave machine will be shutdown whichever occurs first:
either at the request of the master when it does a shutdown or when
the values you have specified for TIMEOUT, BATTERYLEVEL, or MINUTES
expire (these should work but have not been fully tested).
Consequently, if you want the slaves to begin shutting down before
the master, you can do so by adjusting the values in the
configuration file. If you want the slave to remain up until the
master shuts down, you should set TIMEOUT, BATTERYLEVEL, and
MINUTES all to zero.
For proper functioning of the slave, you must specify the same
@strong{UPSTYPE} in the slave configuration
file as is in the master configuration file.
It should be noted that the master and slaves continue to
communicate over the network even after the master has issued a
shutdown command to the slaves. This is because the master
apcupsd continues to run until it receives
the shutdown signal from the system. This is important to ensure that
all the slaves have been properly notified of the shutdown.
We recommend that the machine names used on the
@strong{MASTER} and
@strong{SLAVE} directives be put in your
@file{/etc/hosts} file so that
apcupsd will be able to resolve the machine
name during startup and shutdown even if DNS is not running.
Alternatively, you can use IP addresses on the
@strong{MASTER} and
@strong{SLAVE} directives, but this is
less flexible.
@item SLAVE <name of slave(s)> used only in MASTER configuration files.
Used in master configuration files, this is the name of a slave
machine that depends on this master. There can be a maximum of 20
slaves attached to one master. Thus you can specify multiple SLAVE
directives in a master configuration file. Only one slave name can
be specified per SLAVE directive, thus for multiple slaves, specify
multiple SLAVE directives.
As noted above the master and slaves continue to communicate
over the network even after the master has issued a shutdown
command to the slaves. This is because the master
apcupsd continues to run until it receives
the shutdown signal from the
system. This is important to ensure that all the slaves have been
properly notified of the shutdown.
We recommend that the machine names used on the
@strong{MASTER} and
@strong{SLAVE} directives be put in your
@file{/etc/hosts} file
so that apcupsd will be able to resolve
the machine name during startup and shutdown even if DNS is not running.
Alternatively, you can use IP addresses on the
@strong{MASTER} and
@strong{SLAVE} directives, but this is less
flexible.
@item USERMAGIC < user defined magic> used only in SLAVE configuration files.
The USERMAGIC directive is a sort of password that gives a second
level of identification security in a slave configuration file. It is a
character string up to 17 characters in length. It should be unique for
each slave. When the slave makes initial contact with the master, this
string is passed to the master. Then on each transmission from the
master to the slave, the string is passed back to the slave, which
checks that it is the correct string before accepting the master's
information. This string should be different for each and every slave
on the network. This directive is not required.
@end table
@node Configuration Directives Used to Set the UPS EPROM, , Configuration Directives for Sharing a UPS, Configuration Directive Reference
@section Configuration Directives Used to Set the UPS EPROM
@cindex Directives EEPROM
@cindex EEPROM directives
NOTE. THESE ARE DEPRECIATED AND NO LONGER WORK IN APCUPSD
PLEASE USE APCTEST
The values specified with the following directives are only used
if the @code{--configure} option is specified on the
apcupsd command line, and the UPS is capable of
internal EPROM programming. In that case, apcupsd
attempts to set the values into the UPSes EPROM.
Under normal operations, the values for these parameters
specified in the configuration file are not used. Instead, they are
read from the UPS EPROM by apcupsd. See
@ref{Configuration Directives Used to Set the UPS EPROM,,Configuration Directives Used to Set the UPS EPROM} of this manual for further details
before attempting to reprogram your EEPROM.
@table @asis
@item SENSITIVITY <sets sensitivity level>
(H)igh, (M)edium, (L)ow
This value determine how sensitive
the UPS is to the mains quality and voltage fluctuations. The more
sensitive it is, the quicker the UPS will switch to battery power
when the mains line quality is bad. Normally, this should be set to
H, but if you find your UPS switching to batteries frequently, you
might want to try a less sensitive setting, providing that your
computer equipment tolerates the poor quality mains. This value is
written to the UPS EPROM when the configure option is
specified.
Under normal apcupsd operations (no @code{--configure}
option), apcupsd will read the value
stored in the UPS and display it in the STATUS output.
@anchor{WAKEUP <set wakeup delay>}@item WAKEUP <set wakeup delay>
The UPS power restart delay value in [0,60,180,300] in seconds
after the UPS has shut down during a power failure. This is to
prevent the power from coming back on too quickly after a power
down, and is important for those who have high rpm drives that need
to spin down before powering them up again. Some older SCSI models
are very sensitive to this problem. Default is zero. This value is
written to the UPS EPROM when the @code{--configure} option is
specified.
Under normal apcupsd operations (no
@code{--configure} option),
apcupsd will read the value stored in the
UPS and display it in the STATUS output.
@anchor{SLEEP <set sleep delay>}@item SLEEP <set sleep delay>
The UPS delay or grace period in [20,180,300,600] seconds
before the UPS cuts the power to your equipment. The default is 20
seconds. This value is written to the UPS EPROM when the
@code{--configure} option is specified.
Under normal
apcupsdoperations (no
@code{--configure} option), apcupsd
will read the value stored in the UPS and display it in the STATUS
output.
@item LOTRANSFER <lower limit of ups batt. transfer>
This sets the low line voltage point at which to switch over to
batteries. Different values are permitted based on the UPS model,
classification, and manufacture date. Use @code{apcaccess
eeprom} to show you which values are permitted. This value is
written to the UPS EPROM when the @code{--configure} option
is specified.
Under normal
apcupsdoperations (no
@code{--configure} option), apcupsd
will read the value stored in the UPS and display it in the STATUS
output.
@item HITRANSFER <upper limit of ups batt. transfer>
This sets the high line voltage point to switch over to batteries.
Different values are permitted based on the UPS model,
classification, and manufacture date. Use @code{apcaccess
eeprom} to show you which values are permitted. This value is
written to the UPS EPROM when the @code{--configure} option
is specified.
Under normal
apcupsdoperations (no
@code{--configure} option), apcupsd
will read the value stored in the UPS and display it in the STATUS
output.
@anchor{RETURNCHARGE <min_ batt_ charge level>}@item RETURNCHARGE <min. batt. charge level>
This parameter specifies what
battery percentage charge is necessary before the UPS will supply
power to your equipment after a power down. Different values are
permitted based on the UPS model, classification, and manufacture
date. Use @code{apcaccess eeprom} to show you which
values are permitted. This value is written to the UPS EPROM when the
@code{--configure} option is specified.
Under normal
apcupsdoperations (no
@code{--configure} option), apcupsd
will read the value stored in the UPS and display it in the STATUS
output.
@item BEEPSTATE <alarm beep state>
This parameter tells the UPS when it can sound its audio alarm.
These settings are based on discrete events related to the
remaining capacity of the UPS.
@table @asis
@item 0
immediately upon power failure
@item T
power failure + 30 seconds
@item L
low battery power
@item N
never
@end table
@item UPSNAME <string>
This is an eight character string.
This is the UPS name that will be stored in the UPS EPROM.
@item BATTDATE <string>
This is an eight character string that is the last date the
batteries were changed.
@end table
@node apcupsd Status Logging, The Shutown Sequence and its Discontents, Configuration Directive Reference, Top
@chapter apcupsd Status Logging
@cindex Logging, Status
@cindex Status logging
There is a good deal of information available about the UPS and
apcupsd's status. This document describes
the format of that information. Normally you will get at it via
apcaccess, but there are other ways as
well.
@menu
* Status report format::
* Status Report Example::
* Status Report Fields::
* Logging the STATUS Information::
@end menu
@node Status report format, Status Report Example, apcupsd Status Logging, apcupsd Status Logging
@section Status report format
@cindex Status Report
@cindex Report, Status
The STATUS output is in ASCII format with a single data value or
piece of information on each line output. Because not all UPSes supply
the same information, the output varies based on the type of UPS that
you are using. In general, if the information is not available for
your UPS, the data portion of the output record will contain an
@strong{N/A} indicating that the information
is not available.
Status logging consists of periodically logging ALL available
information concerning the UPS. Since the volume of data is rather
large (over 1000 bytes per status), the STATUS data is not
automatically sent to the system log file, instead, it is written
as a series of data records to a specific file (normally
@file{/etc/apcupsd/apcupsd.status}).
After each write, the file is rewound so that the size of the
file remains constant. At the current time, this file is 1135
bytes. The format of this file is very similar to the old
apcupsd procfs file. The STATUS file is
kept for backward compatibility and will be eliminated in a future
version of apcupsd. The preferred method
for obtaining this information is from
apcaccess or by using the CGI interface (@pxref{apcupsd Network Monitoring [CGI] Programs}).
To make reading the status data reliable via a named pipe, the
first record written contains a version number, the number of
records that follow the first record, and the total number of bytes
in those subsequent records. An actual example of such a status
file (/etc/apcupsd/apcupsd.status) is:
Consequently, the first record always consists of 24 bytes (23
characters followed by a newline). This record starts with APC and
as indicated in the example above is followed by 28 records
consisting of 675 bytes. The last record begins with END APC and
contains the date and time matching the DATE record.
Documentation of each record needs to be written. In the coming
weeks, I plan to add additional records and possibly change the
names of some of the fields.
When this data is written to a file, it is written as two
records, the first record, and all the other records together. In
reading the file, it can be either be read a record at a time, or
in one big read.
When this data is written to syslog(), it is written a record at
a time. The first record is the first 24 bytes. By having the
number of records and the size in the first record, the complete
status can be reliably reassembled.
@node Status Report Example, Status Report Fields, Status report format, apcupsd Status Logging
@section Status Report Example
@cindex Examples, Status Report
@cindex Status
An example of output from an international SmartUPS 1000
follows:
@example
DATE : Wed Sep 27 17:30:23 CEST 2000
HOSTNAME : polymatou.sibbald.com
RELEASE : 3.7.3-20000925
CABLE : Custom Cable Smart
MODEL : SMART-UPS 1000
UPSMODE : Stand Alone
STARTTIME: Wed Sep 27 10:39:23 CEST 2000
UPSNAME : UPS_IDEN
STATUS : ONLINE
LINEV : 235.3 Volts
LOADPCT : 9.3 Percent Load Capacity
BCHARGE : 100.0 Percent
TIMELEFT : 130.0 Minutes
MBATTCHG : 5 Percent
MINTIMEL : 3 Minutes
MAXTIME : 0 Seconds
MAXLINEV : 239.2 Volts
MINLINEV : 234.0 Volts
OUTPUTV : 236.6 Volts
SENSE : High
DWAKE : 000 Seconds
DSHUTD : 020 Seconds
DLOWBATT : 02 Minutes
LOTRANS : 196.0 Volts
HITRANS : 253.0 Volts
RETPCT : 000.0 Percent
ITEMP : 32.8 C Internal
ALARMDEL : 5 seconds
BATTV : 27.9 Volts
LINEFREQ : 50.0 Hz
LASTXFER : Line voltage notch or spike
NUMXFERS : 0
XONBATT : N/A
TONBATT : 0 seconds
CUMONBATT: 0 seconds
XOFFBATT : N/A
SELFTEST : NO
STESTI : 336
STATFLAG : 0x08 Status Flag
DIPSW : 0x00 Dip Switch
REG1 : 0x00 Register 1
REG2 : 0x00 Register 2
REG3 : 0x00 Register 3
MANDATE : 07/31/99
SERIALNO : QS9931125245
BATTDATE : 07/31/99
NOMOUTV : 230
NOMBATTV : 24.0
HUMIDITY : N/A
AMBTEMP : N/A
EXTBATTS : 0
BADBATTS : N/A
FIRMWARE : 60.11.I
APCMODEL : IWI
END APC : Wed Sep 27 17:30:31 CEST 2000
@end example
@node Status Report Fields, Logging the STATUS Information, Status Report Example, apcupsd Status Logging
@section Status Report Fields
@cindex Status
The meaning of the above variables are:
@table @asis
@item APC
is the header record indicating the STATUS format revision
level, the number of records that follow the APC statement, and the
number of bytes that follow the record.
@item DATE
is the date and time that the information was last obtained
from the UPS.
@item HOSTNAME
is the name of the machine that collected the UPS data.
@item RELEASE
is the apcupsd release number.
@item CABLE
is the cable as specified in the configuration file.
@item MODEL
is the UPS model as derived from information from the UPS.
@item UPSMODE
is the mode in which apcupsd is operating.
@item STARTTIME
is the time/date that apcupsd was started.
@item UPSNAME
is the name of the UPS as stored in the EEPROM.
@item STATUS
is the current status of the UPS (ONLINE, CHARGING,
ONBATT,...)
@item MASTERUPD
is the last time the master sent an update to the slave. This
value is present only in slave configurations.
@item LINEV
is the current line voltage as returned by the UPS.
@item LOADPCT
is the percentage of load capacity as estimated by the
UPS.
@item BCHARGE
is the percentage charge on the batteries.
@item TIMELEFT
is the remaining runtime left on batteries as estimated by the
UPS.
@item MBATTCHG
if the battery charge percentage (BCHARGE) drops below this
value, apcupsd will shutdown your system.
@item MINTIMEL
apcupsd will shutdown your system if the remaining
runtime equals or is below this point.
@item MAXTIME
apcupsd will shutdown your system if the time on
batteries exceeds this value. A value of zero disables the
feature.
@item MAXLINEV
is the maximum line voltage since the last STATUS as returned
by the UPS.
@item MINLINEV
is the minimum line voltage since the last STATUS as returned
by the UPS.
@item OUTPUTV
is the voltage the UPS is supplying to your equipment.
@item SENSE
is the sensitivity level of the UPS to line voltage
fluctuations.
@item DWAKE
is the amount of time the UPS will wait after a power off
condition when the power is restored.
@item DSHUTD
is the grace delay that the UPS gives after receiving a power
down command from apcupsd before it powers off your
equipment.
@item DLOWBATT
is the remaining runtime below which the UPS sends the low
battery signal. At this point apcupsd will force an
immediate emergency shutdown.
@item LOTRANS
is the line voltage below which the UPS will switch to
batteries.
@item HITRANS
is the line voltage above which the UPS will switch to
batteries.
@item RETPCT
is the percentage charge that the batteries must have after a
power off condition before the UPS will restore power to your
equipment.
@item STATFLAG
is a status flag indicating the UPS status. See STATUS.
@item ITEMP
is the internal UPS temperature as supplied by the UPS.
@item ALARMDEL
is the delay period for the UPS alarm.
@item BATTV
is the battery voltage as supplied by the UPS.
@item LINEFREQ
is the line frequency in Hertz as given by the UPS.
@item LASTXFER
is the reason for the last transfer to batteries.
@item NUMXFERS
the number of transfers to batteries since apcupsd
startup.
@item XONBATT
time and date of last transfer to batteries, or N/A.
@item TONBATT
time in seconds currently on batteries, or 0.
@item CUMONBATT
total (cumulative) time on batteries in seconds since
apcupsd startup.
@item XOFFBATT
time and date of last transfer from batteries, or N/A.
@item SELFTEST
is the results of the last self test, and may have the
following values:
OK - self test indicates good battery
BT - self test failed due to insufficient battery capacity
NG - self test failed due to overload
NO - No results (i.e. no self test performed in the last 5
minutes).
@item STESTI
is the interval in hours between automatic self tests.
@item STATFLAG
status flag. English version is given by STATUS.
@item DIPSW
is the dip switch settings.
@item REG1
is the value from the UPS fault register 1.
@item REG2
is the value from the UPS fault register 2.
@item REG3
is the value from the UPS fault register 3.
@item MANDATE
is the date the UPS was manufactured.
@item SERIALNO
is the UPS serial number.
@item BATTDATE
is the date that batteries were last replaced.
@item NOMOUTV
is the output voltage that the UPS will attempt to supply when
on battery power.
@item NOMBATTV
is the nominal battery voltage.
@item HUMIDITY
is the humidity as measured by the UPS.
@item AMBTEMP
is the ambient temperature as measured by the UPS.
@item EXTBATTS
is the number of external batteries as defined by the user. A
correct number here helps the UPS compute the remaining runtime
more accurately.
@item BADBATTS
is the number of bad battery packs.
@item FIRMWARE
is the firmware revision number.
@item APCMODEL
is the old APC model identification code.
@item END APC
is the time and date that the STATUS record was written.
@end table
@node Logging the STATUS Information, , Status Report Fields, apcupsd Status Logging
@section Logging the STATUS Information
@cindex Logging Status
@cindex Status, Logging
If specified in the configuration file, the STATUS data will also
be written to the system log file. Please note, that it would not
normally be wise to write this data to a normal system log file as
there is no mechanism in syslog() to rewind the file and hence the
log file would quickly become enormous. However, in two cases, it
can be very useful to use syslog() to write this information.
The first case is to set up your
@file{syslog.conf} file so that the data is written to a
named pipe. In this case, normally not more than about 8192 bytes of
data will be kept before it is discarded by the system.
The second case is to setup your syslog.conf file so that the
status data is sent to another machine, which presumably then
writes it to a named pipe. Consequently, with this mechanism,
provides a simple means of networking apcupsd STATUS
information.
Although we mention system logging of STATUS information, we
strongly recommend that you use apcaccess
or the CGI interface to get this information.
@node The Shutown Sequence and its Discontents, APC smart protocol, apcupsd Status Logging, Top
@chapter The Shutown Sequence and its Discontents
@cindex Shutdown Sequence
@menu
* Shutdown Sequence: Shutdown Sequence <1>.
* Shutdown Problems::
* Master/Slave Shutdown: Master/Slave Shutdown <1>.
* Startup::
* Windows Considerations::
@end menu
@node Shutdown Sequence <1>, Shutdown Problems, The Shutown Sequence and its Discontents, The Shutown Sequence and its Discontents
@section Shutdown Sequence
If you experienced so problems with the 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.
The shutdown sequence is as follows:
@itemize
@item
apcupsd detects that there is a
power problem and it calls @code{/etc/apcupsd/apccontrol
powerout}, which normally sends a message to all users
informing them of a potential problem.
@item
After approximately 5 seconds in the power problem mode,
apcupsd calls
@code{/etc/apcupsd/apccontrol onbattery}, which
normally sends a message to all users informing them that the UPS
is on batteries.
@item
When one of the conditions listed below occurs,
apcupsd issues a shutdown command by
calling @code{/etc/apcupsd/apccontrol doshutdown},
which should perform a shutdown of your system using the system
shutdown(8)
command. You can modify the behavior by editing the
@file{/etc/apcupsd/apccontrol} script, but doing so
will make it more complicated to upgrade to the next
apcupsd version.
The conditions that trigger the shutdown can be: running time on
batteries have expired (TIMEOUT), the battery runtime remaining is
below the configured value (BATTERYLEVEL), the estimated remaining
runtime is below the configured value (MINUTES), or the UPS signals
that the batteries are exhausted.
A shutdown could also be initiated if
apcupsd detects
that the batteries are no longer functioning correctly. This case,
though very unusual, can happen at any time even if there is proper
mains voltage, and @code{/etc/apcupsd/apccontrol emergency} is
called.
Just before initiating any shutdown through the
apccontrol
script, apcupsd will create the file
@file{/etc/apcupsd/powerfail}. This file will be
used later in the shutdown sequence to recall
apcupsd after syncing of the
disks to initiate a power off of the UPS.
If the @file{/etc/nologin} file has not
already been created, it will normally be created during the
shutdown sequence to prevent additional users from logging in
(see the NOLOGIN configuration directive).
Even though apcupsd has
requested the system to perform a shutdown, it continues
running. If it is a master with slaves, it will inform the slaves
to do a shutdown. They perform their shutdown by calling
@code{/etc/apcupsd/apccontrol remotedown}.
@item
When the system signals apcupsd
to do exit, it does so. This is part of the normal system
shutdown (at least on Unix and Linux systems) and the exact time
that apcupsd receives the termination
signal depends on how the shutdown links (usually in
@file{/etc/rc.d}) are set.
Note that on Windows NT systems,
apcupsd apparently continues to run as a
Service even though the machine is "shutdown".
@item
During the shutdown of the system after
apcupsd has been forced to exit, one
of the last things done by the system shutdown is to call the
halt script, which is usually in
@file{/etc/rc.d/halt} or
@file{/etc/rc.d/init.d/halt}, or possibly in
@file{/sbin/init.d/rc.0} depending on your
system. If apcupsd was properly installed, this standard halt
script was modified to include a bit of new logic just before the
final halt of the system. It first tests if the file
@file{/etc/apcupsd/powerfail} exists, and if it
does, it executes @code{/etc/apcupsd/apccontrol
killpower}. It is this last step that will cause
apcupsd to be re-executed with the
@code{--killpower} option on the command line. This
option tells apcupsd to inform the UPS
to kill the power.
This final step is important if you want to ensure that your
system will automatically reboot when the power comes back on. The
actual code used on the Red Hat version is:
@example
# 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***
@end example
@end itemize
The above code must be inserted as late as possible in the halt
script. On many systems, such as Red Hat, all the disk drives were
unmounted, then remounted read-only, thus permitting access to the
@file{/etc} files and the
apcupsd executable. If your system does not
explicitly remount the disks, you must remount them in read-only mode
in the code that you add. Examples of code fragments that do this can
be found in the @file{distributions/suse} subdirectory
of the source.
If you are not able to insert the above code in your halt script
because there is no halt script, or because your halt script calls the
init program as some Unix systems do, you
can either just forget about powering off the UPS, which means that
your machine will not automatically reboot after a power failure, or
there is yet another alternative, though not at all as satisfying as
inserting code in the halt script.
Only if you cannot insert the appropriate code in the halt
script, when you start apcupsd, normally
from the @file{/etc/rc.d/init.d/apcupsd} script, use the
@code{--kill-on-powerfail} option. This will cause
apcupsd to program the UPS to shutoff the
power just before it (apcupsd) does the
system shutdown. Please note that this is not the most ideal solution.
Read on to understand why.
A very important consideration is that you must set the EEPROM
in your UPS so that it waits a sufficient time for the system to
halt before it shuts off the UPS power. The current value as well
as the permitted values for your UPS can be determined by
executing:
@example
apcaccess eeprom
@end example
The output should look something like the following:
@example
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
@end example
The line of interest for you is the @strong{Shutdown grace delay}, which can be changed
using the SLEEP (@pxref{SLEEP <set sleep delay>}) directive in your @strong{apcupsd.conf} file. The default value is 20
seconds, but generally, you can set it to 180, 300, or 600 seconds
depending on your UPS. See the EEPROM (@pxref{Configuring Your EEPROM}) this
manual for further details on how to change this EPROM value.
If you use the @code{--kill-on-powerfail} option, you
run the risk of having the computer power cut before the system has
shutdown. Even if the grace period is rather long, if something goes
wrong in the shutdown, well, it is up to you to decide.
If apcupsd has successfully shutdown
your computer and powered off the UPS during a power outage, you can
control whether or not your computer is automatically rebooted when
the power returns.
The UPS contains two internal EPROM values that determine when
it will restore power to your computer after a full power shutdown.
They are the RETURNCHARGE (@pxref{RETURNCHARGE <min_ batt_ charge level>})
percentage and the WAKEUP (@pxref{WAKEUP <set wakeup delay>})
delay. Briefly, the @strong{RETURNCHARGE}
specifies what percentage charge the battery must have before the
power is restored. Higher values are recommended in regions where the
power goes up and down frequently. The @strong{WAKEUP} delay is a simple time delay. Most sites
will have both of these at zero, or perhaps the @strong{RETURNCHARGE} set to 15. Please follow the links
to the @strong{Configuration} section of this
manual for more information. See the EEPROM (@pxref{Configuring Your EEPROM}) of
this manual for further details on how to change these EPROM
values.
@node Shutdown Problems, Master/Slave Shutdown <1>, Shutdown Sequence <1>, The Shutown Sequence and its Discontents
@section Shutdown Problems
Obviously if your halt script is not properly modified,
apcupsd will not be able to shut off the
power to the UPS, and if the power returns before the batteries are
exhausted your system will not automatically reboot. In any case, your
machine should have been cleanly shut down.
@node Master/Slave Shutdown <1>, Startup, Shutdown Problems, The Shutown Sequence and its Discontents
@section Master/Slave Shutdown
In master/slave configurations, however, the master cannot be
100 percent sure that the slaves have all shutdown before it performs
the power off. As a consequence, it is possible that the master will
shut off the power before the slave has finished shutdown. If this is
the case, the best procedure is to put an appropriate sleep command in
the @file{/etc/apcupsd/apccontrol} file on the master.
For example to give the slaves 30 additional seconds to shutdown, one
would add:
@example
sleep 30
@end example
just after the line that reads
@example
doshutdown)
@end example
in the @file{apccontrol} file (approximately line
79 --- depending on your system version).
Also, on a slave machine, you do not want to use the modified
halt script since it will recall apcupsd,
which will detect that it is a slave (i.e. no connection to the UPS)
and will complain that it cannot do the killpower. This situation is
not harmful just annoying and possibly confusing.
One possible problem during shutdown can be caused by remnants
of old versions. Please be sure to delete or rename all prior versions
(@file{/usr/local/sbin/apcupsd} or
@file{/sbin/powersc}).
@node Startup, Windows Considerations, Master/Slave Shutdown <1>, The Shutown Sequence and its Discontents
@section Startup
@cindex Startup
Normally, apcupsd is automatically
started when your system is rebooted. This normally occurs because the
startup script apcupsd is linked into the
appropriate places in @file{/etc/rc.d}. On most Linux
systems, there is a program called
chkconfig(8)
that will automatically link the startup script. This program is
invoked by the @code{make install} scripts, or it is
explicitly done for those systems that do not have
chkconfig(8). If
this is not the case, you can either link it in appropriately yourself
or explicitly call it from your rc.local file. The appropriate manual
way to startup apcupsd is by
executing:
@example
<path>/apcupsd start
@end example
where <path> is normally @file{/etc/rc.d} or
@file{/etc/rc.d/init.d} depending on your system (isn't
Unix wonderful? :-)). Using this script is important so that any files
remaining around after a power failure are removed. Likewise, shutting
down apcupsd should be done with the same
script:
@example
<path>/apcupsd stop
@end example
@node Windows Considerations, , Startup, The Shutown Sequence and its Discontents
@section Windows Considerations
@cindex Windows Considerations
Please see the end of Windows chapter (@pxref{Installation on
Windows}) of this manual for conderations pertaining to shutdown
and killpower on Windows.
@node APC smart protocol, Apcupsd -- RPM Packaging FAQ, The Shutown Sequence and its Discontents, Top
@chapter APC smart protocol
@cindex Smart protocol
@cindex Protocol Smart
The APC UPS protocol was originally analyzed by Pavel Korensky
with additions from Andre H. Hendrick beginning in 1995, and we want
to give credit for good, hard work, where credit is due. After having
said that, you will see that Steven Freed built much of the orginal
apcupsd information file. [Comment inserted
by Riccardo Facchetti]
The start of this chapter of the
apcupsd manual in HTML format was pulled
from the @uref{http://www.exploits.org/nut/library/apcsmart.html,Network UPS Tools (NUT)} site. It has been an invaluable tool in improving
apcupsd, and I consider it the @strong{Bible} of APC UPS programming. In the course of
using it, I have added information gleaned from
apcupsd and information graciously supplied
by APC. Hopefully, the additions made herein can benefit the original
author and his @uref{http://www.exploits.org/nut,programming project}, and maybe some day, the
apcupsd project and the @strong{NUT} project can join forces.
@menu
* Description::
* RS-232 differences::
* Diagram for cable hackers::
* The Smart Protocol::
* Dip switch info::
* Status bits::
* Alert messages::
* Register 1::
* Register 2::
* Register 3::
* Interpretation of the Old Firmware Revision::
* Interpretation of the New Firmware Revision::
* EEPROM Values::
* Programming the UPS EEPROM::
* Acknowledgements::
@end menu
@node Description, RS-232 differences, APC smart protocol, APC smart protocol
@section Description
Here's the information on the elusive APC smart signaling protocol
used by their higher end units (Back-UPS Pro, Smart-UPS,
Matrix-UPS, etc). What you see here has been collected from a
variety of sources. Some people analyzed the chatter between
PowerChute and their hardware. Others sent various characters to
the UPS and figured out what the results meant.
@node RS-232 differences, Diagram for cable hackers, Description, APC smart protocol
@section RS-232 differences
Normal 9 pin serial connections have TxD on 3 and RxD on 2. APC's
smart serial ports put TxD on pin 1 and RxD on pin 2. This means
you go nowhere if you use a normal straight through serial cable.
In fact, you might even power down the load if you plug one of
those cables in. This is due to the odd routing of pins - DTR and
RTS from the PC usually wind up driving the on/off line. So, when
you open the port, they go high and *poof* your computer dies.
Originally this evil hack was used to connect the UPS to the PC
when this page was first being built. As you can see, I cheated and
neglected the ground (only 2 wires!) and it still worked. This
method can be used for playing around, but for professional systems
this is obviously not a viable option.
That hack didn't work out so well (damned cats), so it was
retired quite awhile back. The most practical solution was to go
out and BUY the DOS/Win version of PowerChute just for the black
(smart) cable. I recommend doing the same thing if you actually
care about this thing working properly. Of course, if you have one
of the newer packages that came with PowerChute, you already have
the cable you need.
@node Diagram for cable hackers, The Smart Protocol, RS-232 differences, APC smart protocol
@section Diagram for cable hackers
If you are handy with cable creation tools, check out the @uref{http://www.exploits.org/nut/library/940-0024C.jpg,940-0024C clone diagram}. That's the black "smart" cable
normally provided with APC models sold after 1996. The loopback pins
on that diagram are used to keep PowerChute happy by allowing cable
detection. If you use the @uref{http://www.exploits.org/nut/,NUT} apcsmart driver, those
pins don't matter.
Many thanks to Steve Draper for providing this scan.
For additional information on cables, see the section on custom cables (@pxref{Cables}) in this manual.
@node The Smart Protocol, Dip switch info, Diagram for cable hackers, APC smart protocol
@section The Smart Protocol
Despite the lack of official information from APC, this table has
been constructed. It's standard RS-232 serial communications at
2400 bps/8N1. Don't rush the UPS while transmitting or it may stop
talking to you. This isn't a problem with the normal single
character queries, but it really does matter for multi-char things
like "@@000". Sprinkle a few calls to usleep() in your code and
everything will work a lot better.
The following table describes the single character @strong{Code} or command that you can send to the UPS,
its meaning, and what sort of response the UPS will
provide. Typically, the response shown below is followed by a newline
(\n in C) and a carriage return (\r in C). If you send the UPS a
command that it does not recognize or that is not available on your
UPS, it will normally respond by "NA" for not available,
otherwise the response is given in the "Typical results"
column. >
@multitable @columnfractions 0.2 0.2 0.2 0.2 0.2
@item
Code@tab Meaning@tab Typical results@tab
@item
^A@tab Model string@tab SMART-UPS 700@tab
@item
^N@tab Turn on UPS (send twice, with > 1.5s delay between chars)
Only on 3rd gen SmartUPS and Black Back-UPS Pros@tab n/a@tab
@item
^Z@tab Permitted EEPROM Values@tab A large string (254 chars) that gives the EEPROM permitted
values for your model. For details see below.@tab
@item
A@tab Front panel test@tab Light show + "OK" (and 2s beep)@tab
@item
B@tab Battery voltage@tab Ranges - typical "27.87"@tab
@item
C@tab Internal temperature (degrees C)@tab Ranges - typical "036.0"@tab
@item
D@tab Runtime calibration - runs until battery is below 25% (35% for
Matrix) This updates the 'j' values - only works at 100% battery
charge. Can be aborted with a second "D"@tab ! when on battery, $ on line@tab
@item
E@tab Automatic self test intervals@tab Default = 336 (336 hours = 14 days) (336=14 days, 168=7 days,
ON=power on, OFF=never)@tab
@item
F@tab Line frequency, Hz@tab 60.00 (50.0 in Europe)@tab
@item
G@tab Cause of transfer@tab R = unacceptable utility voltage rate of change,
H = high utility voltage,
L = low utility voltage,
T = line voltage notch or spike,
O = no transfers yet (since turnon),
S = transfer due to serial port U command or activation of UPS test
from front panel,
NA = transfer reason still not available (read again).@tab
@item
K--K@tab Shutdown with grace period (set with 'p') - need > 1.5s
between first and second K@tab Matrix/3rd gen SmartUPS/Black Back-UPS Pros: "OK", all others:
"*"@tab
@item
L@tab Input line voltage@tab Ranges - typical "118.3" or "228.8" in Europe@tab
@item
M@tab Maximum line voltage received since last M query@tab Ranges - typical "118.9" or "230.1" in Europe@tab
@item
N@tab Minimum line voltage received since last N query@tab Ranges - typical "118.9" or "226.2" in Europe@tab
@item
O@tab Output voltage@tab Ranges - typical "118.3" or "228.8" in Europe@tab
@item
P@tab Power load %@tab Ranges - typical "011.4" depends on what you have plugged
in.@tab
@item
Q@tab Status flags@tab Bitmapped, see below@tab
@item
R@tab Turn dumb
Only on 3rd gen SmartUPS, SmartUPS v/s, BackUPS Pro@tab "BYE"@tab
@item
S@tab Soft shutdown after 'p' delay, return online when power
returns
Only works when UPS is on battery@tab OK@tab
@item
U@tab Simulate power failure@tab !! when switching to battery, then $ when back on line@tab
@item
V@tab Old firmware revision@tab "GWD" or "IWI" The last character indicates the locale
(Domestic, International).@tab
@item
W@tab Self test (battery), results stored in "X"@tab "OK"@tab
@item
X@tab Results of last self test@tab "OK" - good battery, "BT" - failed due to insufficient
capacity, "NG" - failed due to overload, "NO" - no results
available (no test performed in last 5 minutes)@tab
@item
Y@tab Enter smart mode@tab "SM"@tab
@item
Z--Z@tab Shutdown immediately (no delay) - need > 1.5s between first
and second Z@tab N/A@tab
@item
a@tab Show protocol version.alert messages.valid commands (delimited
by periods)@tab
"3.!$%+?=#|.^A^N^Z+-789<@@ABCDEFGKLMNOPQRSUVWXYZ'abcefgjklmnopqrsuvzy~^?"
- Link-Level.alert-messages.commands@tab
@item
b@tab Firmware revision@tab "50.9.D" - 50 = SKU (variable length), 9 = firmware revision, D
= country code (D=USA, I=International, A=Asia, J=Japan,
M=Canada)@tab
@item
c@tab UPS local id@tab UPS_IDEN (you can program any 8 characters here)@tab
@item
e@tab Return threshold@tab % battery charge threshold for return (00=00%, 01=15%, 02=25%,
03=90%)@tab
@item
f@tab Battery level %@tab Ranges - typical "100.0" when fully charged as should normally
be the case@tab
@item
g@tab Nominal battery voltage (not actual voltage - see B)@tab "012" or "024" or "048".@tab
@item
h@tab Measure-UPS: ambient humidity (%)@tab "nnn.n" - percentage@tab
@item
i@tab Measure-UPS: dry contacts@tab 10 = contact 1, 20 = 2, 40 = 3, 80 = 4@tab
@item
j@tab Estimated runtime at current load (minutes)@tab "0112:" (note, it is terminated with a colon)@tab
@item
k@tab Alarm delay@tab 0(zero) = 5 second delay after fail, T = 30 second delay, L =
alarm at low battery only, N = no alarm@tab
@item
l@tab Low transfer voltage@tab Default "103" or "208" in Europe@tab
@item
m@tab Manufacturing date@tab Unique within groups of UPSes (production runs)@tab
@item
n@tab Serial number@tab Unique for each UPS@tab
@item
o@tab Nominal Output Voltage@tab The Nominal Output Voltage when running on batteries. Default
"115" or "230" in Europe.@tab
@item
p@tab Shutdown grace delay, seconds@tab Default "020" (020/180/300/600)@tab
@item
q@tab Low battery warning, minutes@tab Default "02"@tab
@item
r@tab Wakeup delay (time) - seconds@tab Default "000" (000/060/180/300)@tab
@item
s@tab Sensitivity@tab "H" - highest, "M" - medium, "L" - lowest, "A" - autoadjust
(Matrix only)@tab
@item
u@tab Upper transfer voltage@tab Default "132" or "253" in Europe@tab
@item
t@tab Measure-UPS: ambient temperature (degrees C)@tab "nn.nn"@tab
@item
x@tab Last battery change@tab Eight characters. Varies typically dd/mm/yy - 31/12/99@tab
@item
y@tab Copyright notice@tab "(C) APCC" - only works if firmware letter (from "V") is later
than O@tab
@item
z@tab Reset the EEPROM to factory settings (but not ident or batt
replacement date)
Not on SmartUPS v/s or BackUPS Pro@tab "CLEAR"@tab
@item
+@tab Capability cycle@tab Cycle forward through possible values ("|" from UPS afterward
to confirm change). Do not use this unless you know how to program
your UPS EEPROM or you may damage your UPS.@tab
@item
-@tab Capability cycle@tab Cycle backward through possible values ("|" from UPS afterward
to confirm change)Do not use this unless you know how to program
your UPS EEPROM or you may damage your UPS.@tab
@item
@@nnn@tab Shutdown (after delay 'p') with delayed wakeup of nnn tenths of
an hour (after 'r' time)@tab Matrix/3rd gen UPS: "OK", others "*"@tab
@item
0x7f (DEL key)@tab Abort shutdown - use to abort @@, S, K--K@tab "OK"@tab
@item
~@tab Register #1@tab See below@tab
@item
'@tab Register #2@tab See below@tab
@item
0@tab Battery constant@tab Set to A0 on SmartUPS 1000 with new battery@tab
@item
4@tab ???@tab Prints 35 on SmartUPS 1000@tab
@item
5@tab ???@tab Prints EF on SmartUPS 1000@tab
@item
6@tab ???@tab Prints F9 on SmartUPS 1000@tab
@item
7@tab Dip switch positions (if applicable)@tab See below@tab
@item
8@tab Register #3@tab See below@tab
@item
9@tab Line quality@tab "FF" acceptable, "00" unacceptable@tab
@item
>@tab Number of external battery packs attached@tab SmartCell models: "nnn" where nnn is how many external packs
are connected
Non-SmartCell units: whatever has been set with >+ and >- by
the user@tab
@item
Matrix UPS (and possibly Symmetra) specific
commands@tab
@item
^@tab Run in bypass mode@tab If online, "BYP" is received as bypass mode starts
If already in bypass, "INV" is received and UPS goes online
"ERR" received if UPS is unable to transfer@tab
@item
<@tab Number of bad battery packs@tab "nnn" - count of bad packs connected to the UPS@tab
@item
/@tab Load current@tab "nn.nn" - true RMS load current drawn by UPS@tab
@item
\@tab Apparent load power@tab "nnn.nn" - output load as percentage of full rated load in
VA.@tab
@item
^V@tab Output voltage selection (editable)@tab "A" - automatic according to input tap, "M" - 208 VAC, "I" -
240 VAC@tab
@item
^L@tab Front panel language@tab "E" - English, "F" - French, "G" - German, "S" - Spanish, "1"
"2" "3" "4" - ?@tab
@item
w@tab Run time conservation@tab "NO" (disabled) or "02" "05" "08" - minutes of runtime to leave
in battery (UPS shuts down "early")@tab
@end multitable
@node Dip switch info, Status bits, The Smart Protocol, APC smart protocol
@section Dip switch info
@multitable @columnfractions 0.333333333333333 0.333333333333333 0.333333333333333
@item
Bit@tab Switch@tab Option when bit=1
@item
0@tab 4@tab Low battery alarm changed from 2 to 5 mins. Autostartup
disabled on SU370ci and 400
@item
1@tab 3@tab Audible alarm delayed 30 seconds
@item
2@tab 2@tab Output transfer set to 115 VAC (from 120 VAC) or to 240 VAC
(from 230 VAC)
@item
3@tab 1@tab UPS desensitized - input voltage range expanded
@item
4-7@tab -@tab Unused at this time
@end multitable
@node Status bits, Alert messages, Dip switch info, APC smart protocol
@section Status bits
This is probably the most important register of the UPS, which
indicates the overall UPS status. Some common things you'll see:
@itemize
@item
08 = On line, battery OK
@item
10 = On battery, battery OK
@item
50 = On battery, battery low
@item
SM = Status bit is still not available (retry reading)
@end itemize
@multitable @columnfractions 0.333333333333333 0.333333333333333 0.333333333333333
@item
Bit@tab Hex Bit@tab Meaning
@item
0@tab 0x01@tab 1 = Runtime calibration occurring
Not reported by Smart UPS v/s and BackUPS Pro
@item
1@tab 0x02@tab 1 = SmartTrim
Not reported by 1st and 2nd generation SmartUPS models
@item
2@tab 0x04@tab 1 = SmartBoost
@item
3@tab 0x08@tab 1 = On line (this is the normal condition)
@item
4@tab 0x10@tab 1 = On battery
@item
5@tab 0x20@tab 1 = Overloaded output
@item
6@tab 0x40@tab 1 = Battery low
@item
7@tab 0x80@tab 1 = Replace battery
@end multitable
@node Alert messages, Register 1, Status bits, APC smart protocol
@section Alert messages
These single character messages are sent by the UPS any time there
is an Alert condition. All other responses indicated above are sent
by the UPS only in response to a query or action command.
@multitable @columnfractions 0.5 0.5
@item
Character@tab Description
@item
!@tab Line Fail - sent when the UPS goes on-battery, repeated every
30 seconds until low battery condition reached. Sometimes occurs
more than once in the first 30 seconds.
@item
$@tab Return from line fail - UPS back on line power, only sent if a
! has been sent.
@item
%@tab Low battery - Sent to indicate low battery, but not on SmartUPS
v/s or BackUPS Pro models
@item
+@tab Return from low battery - Sent when the battery has been
recharged to some level only if a % has been sent previously
@item
?@tab Abnormal condition - sent for conditions such as "shutdown due
to overload" or "shutdown due to low battery capacity". Also occurs
within 10 minutes of turnon.
@item
=@tab Return from abnormal condition - Sent when the UPS returns from
an abnormal condition where ? was sent, but not a turn-on. Not
implemented on SmartUPS v/s or BackUPS Pro models.
@item
*@tab About to turn off - Sent when the UPS is about to switch off
the load. No commands are processed after this character is sent.
Not implemented on SmartUPS v/s, BackUPS Pro, or 3rd generation
SmartUPS models.
@item
#@tab Replace battery - Sent when the UPS detects that the battery
needs to be replaced. Sent every 5 hours until a new battery test
is run or the UPS is shut off. Not implemented on SmartUPS v/s or
BackUPS Pro models.
@item
&@tab Check alarm register for fault (Measure-UPS) - sent to signal
that temp or humidity out of set limits. Also sent when one of the
contact closures changes states. Sent every 2 minutes, stops when
the alarm conditions are reset. Only sent for alarms enabled with
I. Cause of alarm may be determined with J. Not on SmartUPS v/s or
BackUPS Pro.
@item
|@tab Variable change in EEPROM - Sent whenever any EEPROM variable
is changed. Only supported on Matrix UPS and 3rd generation
SmartUPS models.
@end multitable
@node Register 1, Register 2, Alert messages, APC smart protocol
@section Register 1
All bits are valid on the Matrix UPS. SmartUPS models only support
bits 6 and 7. Other models do not respond.
@multitable @columnfractions 0.333333333333333 0.333333333333333 0.333333333333333
@item
Bit@tab Hex Bit@tab Meaning
@item
0@tab 0x01@tab In wakeup mode (typically lasts < 2s)
@item
1@tab 0x02@tab In bypass mode due to internal fault - see register 2 or 3
@item
2@tab 0x04@tab Going to bypass mode due to command
@item
3@tab 0x08@tab In bypass mode due to command
@item
4@tab 0x10@tab Returning from bypass mode
@item
5@tab 0x20@tab In bypass mode due to manual bypass control
@item
6@tab 0x40@tab Ready to power load on user command
@item
7@tab 0x80@tab Ready to power load on user command or return of line
power
@end multitable
@node Register 2, Register 3, Register 1, APC smart protocol
@section Register 2
Matrix UPS models report bits 0-5. SmartUPS models only support
bits 4 and 6. SmartUPS v/s and BackUPS Pro report bits 4, 6, 7.
Unused bits are set to 0. Other models do not respond.
@multitable @columnfractions 0.5 0.5
@item
Bit@tab Meaning
@item
0@tab Fan failure in electronics, UPS in bypass
@item
1@tab Fan failure in isolation unit
@item
2@tab Bypass supply failure
@item
3@tab Output voltage select failure, UPS in bypass
@item
4@tab DC imbalance, UPS in bypass
@item
5@tab Command sent to stop bypass with no battery connected - UPS
still in bypass
@item
6@tab Relay fault in SmartTrim or SmartBoost
@item
7@tab Bad output voltage
@end multitable
@node Register 3, Interpretation of the Old Firmware Revision, Register 2, APC smart protocol
@section Register 3
All bits are valid on the Matrix UPS and 3rd generation SmartUPS
models. SmartUPS v/s and BackUPS Pro models report bits 0-5. All
others report 0-4. State change of bits 1,2,5,6,7 are reported
asynchronously with ? and = messages.
@multitable @columnfractions 0.5 0.5
@item
Bit@tab Meaning
@item
0@tab Output unpowered due to shutdown by low battery
@item
1@tab Unable to transfer to battery due to overload
@item
2@tab Main relay malfunction - UPS turned off
@item
3@tab In sleep mode from @@ (maybe others)
@item
4@tab In shutdown mode from S
@item
5@tab Battery charger failure
@item
6@tab Bypass relay malfunction
@item
7@tab Normal operating temperature exceeded
@end multitable
@node Interpretation of the Old Firmware Revision, Interpretation of the New Firmware Revision, Register 3, APC smart protocol
@section Interpretation of the Old Firmware Revision
The Old Firmware Revision is obtained with the "V"
command, which gives a typical response such as "GWD" or
"IWI", and can be interpreted as follows:
@example
Old Firmware revision and model ID String for SmartUPS & MatrixUPS
This is a three character string XYZ
where X == Smart-UPS or Matrix-UPS ID Code.
range 0-9 and A-P
1 == unknown
0 == Matrix 3000
5 == Matrix 5000
the rest are Smart-UPS and Smart-UPS-XL
2 == 250 3 == 400 4 == 400
6 == 600 7 == 900 8 == 1250
9 == 2000 A == 1400 B == 1000
C == 650 D == 420 E == 280
F == 450 G == 700 H == 700XL
I == 1000 J == 1000XL K == 1400
L == 1400XL M == 2200 N == 2200XL
O == 3000 P == 5000
where Y == Possible Level of Smart Features, unknown???
G == Stand Alone
T == Stand Alone
V == ???
W == Rack Mount
where Z == National Model Use Only Codes
D == Domestic 115 Volts
I == International 230 Volts
A == Asia ?? 100 Volts
J == Japan ?? 100 Volts
@end example
@node Interpretation of the New Firmware Revision, EEPROM Values, Interpretation of the Old Firmware Revision, APC smart protocol
@section Interpretation of the New Firmware Revision
@example
New Firmware revison and model ID String in NN.M.L is the format
where NN == UPS ID Code.
12 == Back-UPS Pro 650
13 == Back-UPS Pro 1000
52 == Smart-UPS 700
60 == SmartUPS 1000
72 == Smart-UPS 1400
where NN now Nn has possible meanings.
N == Class of UPS
1n == Back-UPS Pro
5n == Smart-UPS
7n == Smart-UPS NET
n == Level of intelligence
N1 == Simple Signal, if detectable WAG(*)
N2 == Full Set of Smart Signals
N3 == Micro Subset of Smart Signals
where M == Possible Level of Smart Features, unknown???
1 == Stand Alone
8 == Rack Mount
9 == Rack Mount
where L == National Model Use Only Codes
D == Domestic 115 Volts
I == International 230 Volts
A == Asia ?? 100 Volts
J == Japan ?? 100 Volts
M == North America 208 Volts (Servers)
@end example
@node EEPROM Values, Programming the UPS EEPROM, Interpretation of the New Firmware Revision, APC smart protocol
@section EEPROM Values
Upon sending a ^Z, your UPS will probably spit back approximately
254 characters something like the following (truncated here for the
example):
#uD43132135138129uM43229234239224uA43110112114108 ....
It looks bizarre and ugly, but is easily parsed. The # is some
kind of marker/ident character. Skip it. The rest fits this
form:
@itemize
@item
Command character - use this to select the value
@item
Locale - use 'b' to find out what yours is (the last
character), '4' applies to all
@item
Number of choices - '4' means there are 4 possibilities
coming up
@item
Choice length - '3' means they are all 3 chars long
@end itemize
Matrix-UPS models have ## between each grouping for some
reason.
Here is an example broken out to be more readable:
@example
CMD DFO RSP FSZ FVL
u D 4 3 127 130 133 136
u M 4 3 229 234 239 224
u A 4 3 108 110 112 114
u I 4 3 253 257 261 265
l D 4 3 106 103 100 097
l M 4 3 177 172 168 182
l A 4 3 092 090 088 086
l I 4 3 208 204 200 196
e 4 4 2 00 15 50 90
o D 1 3 115
o J 1 3 100
o I 1 3 230 240 220 225
o M 1 3 208
s 4 4 1 H M L L
q 4 4 2 02 05 07 10
p 4 4 3 020 180 300 600
k 4 4 1 0 T L N
r 4 4 3 000 060 180 300
E 4 4 3 336 168 ON OFF
CMD == UPSlink Command.
u = upper transfer voltage
l = lower transfer voltage
e = return threshold
o = output voltage
s = sensitivity
p = shutdown grace delay
q = low battery warning
k = alarm delay
r = wakeup delay
E = self test interval
DFO == (4)-all-countries (D)omestic (I)nternational (A)sia (J)apan
(M) North America - servers.
RSP == Total number possible answers returned by a given CMD.
FSZ == Max. number of field positions to be filled.
FVL == Values that are returned and legal.
@end example
@node Programming the UPS EEPROM, Acknowledgements, EEPROM Values, APC smart protocol
@section Programming the UPS EEPROM
There are at this time a maximum of 12 different values that can be
programmed into the UPS EEPROM. They are:
@multitable @columnfractions 0.333333333333333 0.333333333333333 0.333333333333333
@item
Item@tab Command@tab Meaning
@item
1.@tab c@tab The UPS Id or name
@item
2.@tab x@tab The last date the batteries were replaced
@item
3.@tab u@tab The Upper Transfer Voltage
@item
4.@tab l@tab The Lower Transfer Voltage
@item
5.@tab e@tab The Return Battery Charge Percentage
@item
6.@tab o@tab The Output Voltage when on Batteries
@item
7.@tab s@tab The Sensitivity to Line Quality
@item
8.@tab p@tab The Shutdown Grace Delay
@item
9.@tab q@tab The Low Battery Warning Delay
@item
10.@tab k@tab The Alarm Delay
@item
11.@tab r@tab The Wakeup Delay
@item
12.@tab E@tab The Automatic Self Test Interval
@end multitable
The first two cases (Ident and Batt date) are somewhat special
in that you tell the UPS you want to change the value, then you
supply 8 characters that are saved in the EEPROM. The last ten item
are programmed by telling the UPS that you want it to cycle to the
next permitted value.
In each case, you indicate to the UPS that you want to change
the EEPROM by first sending the appropriate query command (e.g. "c"
for the UPS ID or "u" for the Upper Transfer voltage. This command
is then immediately followed by the cycle EEPROM command or "-". In
the case of the UPS Id or the battery date, you follow the cycle
command by the eight characters that you want to put in the EEPROM.
In the case of the other ten items, there is nothing more to
enter.
The UPS will respond by "OK" and approximately 5 seconds later
by a vertical bar (|) to indicate that the EEPROM was changed.
@node Acknowledgements, , Programming the UPS EEPROM, APC smart protocol
@section Acknowledgements
The apcupsd has a rather long and tormented history. Many thanks to
the guys that, with time, contributed to the general public
knowledge.
Pavel Korensky <pavelk at dator3.anet.cz>,
Andre M. Hedrick <hedrick at suse.de>,
Christopher J. Reimer <reimer at doe.carleton.ca>,
Kevin D. Smolkowski <kevins at trigger.oslc.org>,
Werner Panocha <wpanocha at t-online.de>,
Steven Freed, @uref{http://www.exploits.org/~rkroll/contact.html,Russell Kroll}.
additions by:
@uref{http://www.apcupsd.com,Kern Sibbald <apcupsd-users at lists.sourceforge.net>}
@node Apcupsd -- RPM Packaging FAQ, , APC smart protocol, Technical Reference
@chapter Apcupsd -- RPM Packaging FAQ
@menu
* Answers::
@end menu
@node Answers, , , Apcupsd -- RPM Packaging FAQ
@section Answers
@table @asis
@item @strong{How do I build Apcupsd for platform xxx?}
The apcupsd spec file contains defines to build for
several platforms: RedHat 7.x (rh7), RedHat 8.0 (rh8),
RedHat 9 (rh9), Fedora Core 1 (fc1), and Whitebox
Enterprise Linux 3.0 (wb3). The package build is
controlled by a define set at the beginning of the file.
These defines basically just control the dependancy
information that gets coded into the finished rpm
package. So while you could technically build a package
without defining a platform, or with an incorrect
platform, and have it install and run it would not
contain correct dependancy information for the rpm
database. The platform define may be edited in the spec
file directly (by default all defines are set to 0 or
"not set"). For example, to build the RedHat 7.x package
find the line in the spec file which reads
@example
%define rh7 0
@end example
and edit it to read
@example
%define rh7 1
@end example
Alternately you may pass the define on the
command line when calling rpmbuild:
@example
rpmbuild -ba --define "build_rh7 1" apcupsd.spec
rpmbuild --rebuild --define build_rh7 1" apcupsd-x.x.x-x.src.rpm
@end example
@item @strong{How do I control whether usb support gets built?}
By default standard serial port support will be built and the
apcupsd-std package will be produced. To get the usb package and support either
set the
@example
%define usb 0
@end example
@noindent
to
@example
%define usb 1
@end example
@noindent
in the spec file directly or pass it to rpmbuild on the command line:
@example
rpmbuild -ba --define "build_rh7 1" --define "build_usb 1" apcupsd.spec
@end example
@item @strong{other defines are used?}
The only other define is for the initdir for the daemon control script.
On RedHat systems this is set to /etc/rc.d/init.d/. You would only need to edit this
if packaging for a platform with uses a different directory.
@item @strong{I'm getting errors about not having permission when
I try to build the packages. Do I need to be root?} No, you do
not need to be root and, in fact, it is better practice to build
rpm packages as a non-root user. Apcupds packages are designed to
be built by a regular user but you must make a few changes on
your system to do this. If you are building on your own system
then the simplest method is to add write permissions for all to
the build directory (/usr/src/redhat/). To accomplish this
execute the following command as root:
@example
chmod -R 777 /usr/src/redhat
@end example
@noindent
If you are working on a shared system where you can not use the method above then you need to
recreate the /usr/src/redhat directory tree with all of it's subdirectories inside your home
directory. Then create a file named
@example
.rpmmacros
@end example
@noindent
in your home directory (or edit
the file if it already exists) and add the following line:
@example
%_topdir /home/myuser/redhat
@end example
@end table
@node Credits <1>, , Technical Reference, Top
@appendix Credits
@image{thanks,,,,png}
The success of apcupsd is due to the many
people that helped in development, testing and in many other
ways.
Thank all the developers that worked hard to make
APCUPSDone of the best piece of software for
UPSmanagement.
@menu
* Contributors::
* Disclaimer; NO WARRANTY::
@end menu
@node Contributors, Disclaimer; NO WARRANTY, , Credits <1>
@section Contributors
@table @asis
@item Current Code Maintainer and Project Manager:
Kern Sibbald (kern at sibbald dot com)
@item RPM Packager:
D. Scott Barninger (barninger at fairfieldcomputers dot com)
@item Super USB bug fixer:
Adam Kropelin (akropel1 at rochester dot rr dot com)
@item CGI and HTML fixer:
William King (wrking at dadaboom dot com)
@item Project Starter and Former Code Maintainer:
Andre Hedrick (andre at linux-ide.org)
@item Former Code Maintainer and Project Manager:
Riccardo Facchetti (riccardo at master.oasi.gpa.it)
@item Serial Communications:
Andre Hedrick (andre at linux-ide.org)
@item 2.0 User's Manual:
Eric S. Raymond (esr at thyrsus.com)
@item Alpha Port:
Kern Sibbald (kern at sibbald dot com)
J. Rochate (jrochate at ualg.pt) testing and machine
loan
@item Caldera:
John Pinner (john at clocksoft.com)
@item HP-UX Port
Carl Erhorn (Carl_Erhorn at hyperion.com)
Robert K Nelson (rnelson at airflowsciences.com)
@item SOLARIS Port:
Carl Erhorn (Carl_Erhorn at hyperion.com)
@item OpenBSD Port:
Devin Reade (gdr at gno.org)
@item NetBSD Port:
Neil Darlow (neil at darlow.co.uk)
@item Win32 Port:
Kern Sibbald (kern at sibbald dot com)
Paul Z. Stagner (paul.stagner at charterco.com) testing
@item WEB Interfaces:
Kern Sibbald (kern at sibbald dot com)
Joseph Acosta (joeja at mindspring.com)
@item Apcupsd Support and Knowledge Base:
Brian Schau (Brian.Schau at compaq.com)
@item Hard Core Coders:
Riccardo Facchetti (riccardo at master.oasi.gpa.it)
Kern Sibbald (kern at sibbald dot com)
@item Part Time Coders:
Jonathan H N Chin (jc254 at newton.cam.ac.uk)
Andre Hedrick (andre at linux-ide.org)
Brian Schau (Brian.Schau at compaq.com)
Carl Erhorn (Carl_Erhorn at hyperion.com)
@item Distribution Maintainers:
Alpha: Kern Sibbald (kern at sibbald dot com) temp
Debian: Leon Breedt (ljb at debian.org)
FreeBSD/BSDi: Jeff Palmer (scorpio at drkshdw.org)
NetBSD: Neil Darlow (neil at darlow.co.uk)
HP-UX: Carl Erhorn (Carl_Erhorn at hyperion.com),
Robert K Nelson (rnelson at airflowsciences.com)
OpenBSD: Devin Reade (gdr at gno.org)
RedHat: Kern Sibbald (kern at sibbald dot com)
Slackware: Devin Reade (gdr at gno.org)
Sparc Solaris: Carl Erhorn (Carl_Erhorn at hyperion.com)
SUSE: Riccardo Facchetti (riccardo at master.oasi.gpa.it)
Win32: Kern Sibbald (kern at sibbald dot com)
@item Project Discussions:
@uref{wb_mailto:apcupsd-users@@lists.sourceforge.net,APCUPSD Mailing List}
@end table
Thanks to American Power Conversion (APC) who helped in giving
technical information on their UPSes.
A special thanks to APC who gave me (Riccardo) a Smart
UPS1400 INET when my old Back UPS v/s 650's battery died. Thank
you guys, your help has been invaluable.
Thanks to all the users that send bug reports and
suggestions:we need your help.
Thanks to every one I forgot here. If you feel Ihave
forgot your name, please don't hesitate to tell me.
Miquel van Smoorenburg, The Doctor What, Pavel Korensky,
and Russell Kroll <rkroll at exploits.org> for the CGI
programs.
Jonathan Benson <jbenson at technologist.com> for adapting
the upsstatus.cgi program to work with apcupsd
The gd 1.2 Image Library used in our CGI programs is copyright
1994, 1995, Quest Protein Database Center, Cold Spring Harbor Labs.
Permission granted to copy and distribute this work provided that
this notice remains intact. Credit for the library must be given to
the Quest Protein Database Center, Cold Spring Harbor Labs, in all
derived works. This does not affect your ownership of the derived
work itself, and the intent is to assure proper credit for Quest,
not to interfere with your use of gd.
gd 1.2 was written by Thomas Boutell and is currently
distributed by boutell.com, Inc.
Parts of the VNC project by ATT (cool code) were used as
templates for our Win32 code, see:
@uref{http://www.uk.research.att.com/vnc,http://www.uk.research.att.com/vnc}
@node Disclaimer; NO WARRANTY,Kernel Config, Contributors, Credits <1>
@section Disclaimer: NO WARRANTY
@cindex Disclaimer
BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO
WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE
LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS
AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND
PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE
DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR
OR CORRECTION.
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY
MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE
LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL,
INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR
INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU
OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY
OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN
ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
@node Kernel Config,Index, Disclaimer; NO WARRANTY,Top
@appendix Kernel Config
A typical USB section of a .config file might be:
@cindex Kernel config
@cindex config, Kernel
@example
#
# USB support
#
CONFIG_USB=m
CONFIG_USB_DEBUG=y
#
# Miscellaneous USB options
#
CONFIG_USB_DEVICEFS=y
# CONFIG_USB_BANDWIDTH is not set
# CONFIG_USB_DYNAMIC_MINORS is not set
#
# USB Host Controller Drivers
#
# CONFIG_USB_EHCI_HCD is not set
# CONFIG_USB_OHCI_HCD is not set
CONFIG_USB_UHCI_HCD=m
#
# USB Device Class drivers
#
# CONFIG_USB_BLUETOOTH_TTY is not set
# CONFIG_USB_ACM is not set
# CONFIG_USB_PRINTER is not set
CONFIG_USB_STORAGE=m
# CONFIG_USB_STORAGE_DEBUG is not set
# CONFIG_USB_STORAGE_DATAFAB is not set
# CONFIG_USB_STORAGE_FREECOM is not set
# CONFIG_USB_STORAGE_ISD200 is not set
# CONFIG_USB_STORAGE_DPCM is not set
# CONFIG_USB_STORAGE_HP8200e is not set
# CONFIG_USB_STORAGE_SDDR09 is not set
# CONFIG_USB_STORAGE_SDDR55 is not set
# CONFIG_USB_STORAGE_JUMPSHOT is not set
#
# USB Human Interface Devices (HID)
#
CONFIG_USB_HID=m
CONFIG_USB_HIDINPUT=y
# CONFIG_HID_FF is not set
CONFIG_USB_HIDDEV=y
#
# USB HID Boot Protocol drivers
#
# CONFIG_USB_KBD is not set
# CONFIG_USB_MOUSE is not set
# CONFIG_USB_AIPTEK is not set
# CONFIG_USB_WACOM is not set
# CONFIG_USB_KBTAB is not set
# CONFIG_USB_POWERMATE is not set
# CONFIG_USB_MTOUCH is not set
# CONFIG_USB_XPAD is not set
# CONFIG_USB_ATI_REMOTE is not set
#
# USB Imaging devices
#
# CONFIG_USB_MDC800 is not set
# CONFIG_USB_MICROTEK is not set
# CONFIG_USB_HPUSBSCSI is not set
#
# USB Multimedia devices
#
# CONFIG_USB_DABUSB is not set
#
# Video4Linux support is needed for USB Multimedia device support
#
#
# USB Network adaptors
#
# CONFIG_USB_CATC is not set
# CONFIG_USB_KAWETH is not set
# CONFIG_USB_PEGASUS is not set
# CONFIG_USB_RTL8150 is not set
# CONFIG_USB_USBNET is not set
#
# USB port drivers
#
# CONFIG_USB_USS720 is not set
#
# USB Serial Converter support
#
# CONFIG_USB_SERIAL is not set
#
# USB Miscellaneous drivers
#
# CONFIG_USB_EMI62 is not set
# CONFIG_USB_EMI26 is not set
# CONFIG_USB_TIGL is not set
# CONFIG_USB_AUERSWALD is not set
# CONFIG_USB_RIO500 is not set
# CONFIG_USB_LEGOTOWER is not set
# CONFIG_USB_LCD is not set
# CONFIG_USB_LED is not set
# CONFIG_USB_CYTHERM is not set
# CONFIG_USB_TEST is not set
#
# USB Gadget Support
#
# CONFIG_USB_GADGET is not set
@end example
Interpretation of /proc/usb info on 2.4 kernels:
@example
/proc/bus/usb filesystem output
===============================
(version 2002.03.18)
The /proc filesystem for USB devices provides /proc/bus/usb/drivers
and /proc/bus/usb/devices, as well as /proc/bus/usb/BBB/DDD files.
**NOTE**: If /proc/bus/usb appears empty, and a host controller
driver has been linked, then you need to mount the
filesystem. Issue the command (as root):
mount -t usbfs none /proc/bus/usb
An alternative and more permanent method would be to add
none /proc/bus/usb usbfs defaults 0 0
to /etc/fstab. This will mount usbfs at each reboot.
You can then issue `cat /proc/bus/usb/devices` to extract
USB device information, and user mode drivers can use usbfs
to interact with USB devices.
There are a number of mount options supported by usbfs.
Consult the source code (linux/drivers/usb/inode.c) for
information about those options.
**NOTE**: The filesystem has been renamed from "usbdevfs" to
"usbfs", to reduce confusion with "devfs". You may
still see references to the older "usbdevfs" name.
For more information on mounting the usbfs file system, see the
"USB Device Filesystem" section of the USB Guide. The latest copy
of the USB Guide can be found at http://www.linux-usb.org/
THE /proc/bus/usb/BBB/DDD FILES:
--------------------------------
Each connected USB device has one file. The BBB indicates the bus
number. The DDD indicates the device address on that bus. Both
of these numbers are assigned sequentially, and can be reused, so
you can't rely on them for stable access to devices. For example,
it's relatively common for devices to re-enumerate while they are
still connected (perhaps someone jostled their power supply, hub,
or USB cable), so a device might be 002/027 when you first connect
it and 002/048 sometime later.
These files can be read as binary data. The binary data consists
of first the device descriptor, then the descriptors for each
configuration of the device. That information is also shown in
text form by the /proc/bus/usb/devices file, described later.
These files may also be used to write user-level drivers for the USB
devices. You would open the /proc/bus/usb/BBB/DDD file read/write,
read its descriptors to make sure it's the device you expect, and then
bind to an interface (or perhaps several) using an ioctl call. You
would issue more ioctls to the device to communicate to it using
control, bulk, or other kinds of USB transfers. The IOCTLs are
listed in the linux/usbdevice_fs.h file, and at this writing the
source code (linux/drivers/usb/devio.c) is the primary reference
for how to access devices through those files.
Note that since by default these BBB/DDD files are writable only by
root, only root can write such user mode drivers. You can selectively
grant read/write permissions to other users by using "chmod". Also,
usbfs mount options such as "devmode=0666" may be helpful.
THE /proc/bus/usb/drivers FILE:
-------------------------------
Each of the USB device drivers linked into your kernel (statically,
or dynamically using "modprobe") is listed in the "drivers" file.
Here's an example from one system:
usbdevfs
hub
0- 15: usblp
usbnet
serial
usb-storage
pegasus
If you see this file, "usbdevfs" and "hub" will always be listed,
since those are part of the "usbcore" framework.
Drivers that use the USB major number (180) to provide character devices
will include a range of minor numbers, as shown above for the "usblp"
(actually "printer.o") module. USB device drivers can of course use any
major number, but it's easy to use the USB range since there's explicit
support for subdividing it in the USB device driver framework.
THE /proc/bus/usb/devices FILE:
-------------------------------
In /proc/bus/usb/devices, each device's output has multiple
lines of ASCII output.
I made it ASCII instead of binary on purpose, so that someone
can obtain some useful data from it without the use of an
auxiliary program. However, with an auxiliary program, the numbers
in the first 4 columns of each "T:" line (topology info:
Lev, Prnt, Port, Cnt) can be used to build a USB topology diagram.
Each line is tagged with a one-character ID for that line:
T = Topology (etc.)
B = Bandwidth (applies only to USB host controllers, which are
virtualized as root hubs)
D = Device descriptor info.
P = Product ID info. (from Device descriptor, but they won't fit
together on one line)
S = String descriptors.
C = Configuration descriptor info. (* = active configuration)
I = Interface descriptor info.
E = Endpoint descriptor info.
=======================================================================
/proc/bus/usb/devices output format:
Legend:
d = decimal number (may have leading spaces or 0's)
x = hexadecimal number (may have leading spaces or 0's)
s = string
Topology info:
T: Bus=dd Lev=dd Prnt=dd Port=dd Cnt=dd Dev#=ddd Spd=ddd MxCh=dd
| | | | | | | | |__MaxChildren
| | | | | | | |__Device Speed in Mbps
| | | | | | |__DeviceNumber
| | | | | |__Count of devices at this level
| | | | |__Connector/Port on Parent for this device
| | | |__Parent DeviceNumber
| | |__Level in topology for this bus
| |__Bus number
|__Topology info tag
Speed may be:
1.5 Mbit/s for low speed USB
12 Mbit/s for full speed USB
480 Mbit/s for high speed USB (added for USB 2.0)
Bandwidth info:
B: Alloc=ddd/ddd us (xx%), #Int=ddd, #Iso=ddd
| | | |__Number of isochronous requests
| | |__Number of interrupt requests
| |__Total Bandwidth allocated to this bus
|__Bandwidth info tag
Bandwidth allocation is an approximation of how much of one frame
(millisecond) is in use. It reflects only periodic transfers, which
are the only transfers that reserve bandwidth. Control and bulk
transfers use all other bandwidth, including reserved bandwidth that
is not used for transfers (such as for short packets).
The percentage is how much of the "reserved" bandwidth is scheduled by
those transfers. For a low or full speed bus (loosely, "USB 1.1"),
90% of the bus bandwidth is reserved. For a high speed bus (loosely,
"USB 2.0") 80% is reserved.
Device descriptor info & Product ID info:
D: Ver=x.xx Cls=xx(s) Sub=xx Prot=xx MxPS=dd #Cfgs=dd
P: Vendor=xxxx ProdID=xxxx Rev=xx.xx
where
D: Ver=x.xx Cls=xx(sssss) Sub=xx Prot=xx MxPS=dd #Cfgs=dd
| | | | | | |__NumberConfigurations
| | | | | |__MaxPacketSize of Default Endpoint
| | | | |__DeviceProtocol
| | | |__DeviceSubClass
| | |__DeviceClass
| |__Device USB version
|__Device info tag #1
where
P: Vendor=xxxx ProdID=xxxx Rev=xx.xx
| | | |__Product revision number
| | |__Product ID code
| |__Vendor ID code
|__Device info tag #2
String descriptor info:
S: Manufacturer=ssss
| |__Manufacturer of this device as read from the device.
| For USB host controller drivers (virtual root hubs) this may
| be omitted, or (for newer drivers) will identify the kernel
| version and the driver which provides this hub emulation.
|__String info tag
S: Product=ssss
| |__Product description of this device as read from the device.
| For older USB host controller drivers (virtual root hubs) this
| indicates the driver; for newer ones, it's a product (and vendor)
| description that often comes from the kernel's PCI ID database.
|__String info tag
S: SerialNumber=ssss
| |__Serial Number of this device as read from the device.
| For USB host controller drivers (virtual root hubs) this is
| some unique ID, normally a bus ID (address or slot name) that
| can't be shared with any other device.
|__String info tag
Configuration descriptor info:
C:* #Ifs=dd Cfg#=dd Atr=xx MPwr=dddmA
| | | | | |__MaxPower in mA
| | | | |__Attributes
| | | |__ConfiguratioNumber
| | |__NumberOfInterfaces
| |__ "*" indicates the active configuration (others are " ")
|__Config info tag
USB devices may have multiple configurations, each of which act
rather differently. For example, a bus-powered configuration
might be much less capable than one that is self-powered. Only
one device configuration can be active at a time; most devices
have only one configuration.
Each configuration consists of one or more interfaces. Each
interface serves a distinct "function", which is typically bound
to a different USB device driver. One common example is a USB
speaker with an audio interface for playback, and a HID interface
for use with software volume control.
Interface descriptor info (can be multiple per Config):
I: If#=dd Alt=dd #EPs=dd Cls=xx(sssss) Sub=xx Prot=xx Driver=ssss
| | | | | | | |__Driver name
| | | | | | | or "(none)"
| | | | | | |__InterfaceProtocol
| | | | | |__InterfaceSubClass
| | | | |__InterfaceClass
| | | |__NumberOfEndpoints
| | |__AlternateSettingNumber
| |__InterfaceNumber
|__Interface info tag
A given interface may have one or more "alternate" settings.
For example, default settings may not use more than a small
amount of periodic bandwidth. To use significant fractions
of bus bandwidth, drivers must select a non-default altsetting.
Only one setting for an interface may be active at a time, and
only one driver may bind to an interface at a time. Most devices
have only one alternate setting per interface.
Endpoint descriptor info (can be multiple per Interface):
E: Ad=xx(s) Atr=xx(ssss) MxPS=dddd Ivl=dddms
| | | | |__Interval (max) between transfers
| | | |__EndpointMaxPacketSize
| | |__Attributes(EndpointType)
| |__EndpointAddress(I=In,O=Out)
|__Endpoint info tag
The interval is nonzero for all periodic (interrupt or isochronous)
endpoints. For high speed endpoints the transfer interval may be
measured in microseconds rather than milliseconds.
For high speed periodic endpoints, the "MaxPacketSize" reflects
the per-microframe data transfer size. For "high bandwidth"
endpoints, that can reflect two or three packets (for up to
3KBytes every 125 usec) per endpoint.
With the Linux-USB stack, periodic bandwidth reservations use the
transfer intervals and sizes provided by URBs, which can be less
than those found in endpoint descriptor.
=======================================================================
If a user or script is interested only in Topology info, for
example, use something like "grep ^T: /proc/bus/usb/devices"
for only the Topology lines. A command like
"grep -i ^[tdp]: /proc/bus/usb/devices" can be used to list
only the lines that begin with the characters in square brackets,
where the valid characters are TDPCIE. With a slightly more able
script, it can display any selected lines (for example, only T, D,
and P lines) and change their output format. (The "procusb"
Perl script is the beginning of this idea. It will list only
selected lines [selected from TBDPSCIE] or "All" lines from
/proc/bus/usb/devices.)
The Topology lines can be used to generate a graphic/pictorial
of the USB devices on a system's root hub. (See more below
on how to do this.)
The Interface lines can be used to determine what driver is
being used for each device.
The Configuration lines could be used to list maximum power
(in milliamps) that a system's USB devices are using.
For example, "grep ^C: /proc/bus/usb/devices".
Here's an example, from a system which has a UHCI root hub,
an external hub connected to the root hub, and a mouse and
a serial converter connected to the external hub.
T: Bus=00 Lev=00 Prnt=00 Port=00 Cnt=00 Dev#= 1 Spd=12 MxCh= 2
B: Alloc= 28/900 us ( 3%), #Int= 2, #Iso= 0
D: Ver= 1.00 Cls=09(hub ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1
P: Vendor=0000 ProdID=0000 Rev= 0.00
S: Product=USB UHCI Root Hub
S: SerialNumber=dce0
C:* #Ifs= 1 Cfg#= 1 Atr=40 MxPwr= 0mA
I: If#= 0 Alt= 0 #EPs= 1 Cls=09(hub ) Sub=00 Prot=00 Driver=hub
E: Ad=81(I) Atr=03(Int.) MxPS= 8 Ivl=255ms
T: Bus=00 Lev=01 Prnt=01 Port=00 Cnt=01 Dev#= 2 Spd=12 MxCh= 4
D: Ver= 1.00 Cls=09(hub ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1
P: Vendor=0451 ProdID=1446 Rev= 1.00
C:* #Ifs= 1 Cfg#= 1 Atr=e0 MxPwr=100mA
I: If#= 0 Alt= 0 #EPs= 1 Cls=09(hub ) Sub=00 Prot=00 Driver=hub
E: Ad=81(I) Atr=03(Int.) MxPS= 1 Ivl=255ms
T: Bus=00 Lev=02 Prnt=02 Port=00 Cnt=01 Dev#= 3 Spd=1.5 MxCh= 0
D: Ver= 1.00 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1
P: Vendor=04b4 ProdID=0001 Rev= 0.00
C:* #Ifs= 1 Cfg#= 1 Atr=80 MxPwr=100mA
I: If#= 0 Alt= 0 #EPs= 1 Cls=03(HID ) Sub=01 Prot=02 Driver=mouse
E: Ad=81(I) Atr=03(Int.) MxPS= 3 Ivl= 10ms
T: Bus=00 Lev=02 Prnt=02 Port=02 Cnt=02 Dev#= 4 Spd=12 MxCh= 0
D: Ver= 1.00 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1
P: Vendor=0565 ProdID=0001 Rev= 1.08
S: Manufacturer=Peracom Networks, Inc.
S: Product=Peracom USB to Serial Converter
C:* #Ifs= 1 Cfg#= 1 Atr=a0 MxPwr=100mA
I: If#= 0 Alt= 0 #EPs= 3 Cls=00(>ifc ) Sub=00 Prot=00 Driver=serial
E: Ad=81(I) Atr=02(Bulk) MxPS= 64 Ivl= 16ms
E: Ad=01(O) Atr=02(Bulk) MxPS= 16 Ivl= 16ms
E: Ad=82(I) Atr=03(Int.) MxPS= 8 Ivl= 8ms
Selecting only the "T:" and "I:" lines from this (for example, by using
"procusb ti"), we have:
T: Bus=00 Lev=00 Prnt=00 Port=00 Cnt=00 Dev#= 1 Spd=12 MxCh= 2
T: Bus=00 Lev=01 Prnt=01 Port=00 Cnt=01 Dev#= 2 Spd=12 MxCh= 4
I: If#= 0 Alt= 0 #EPs= 1 Cls=09(hub ) Sub=00 Prot=00 Driver=hub
T: Bus=00 Lev=02 Prnt=02 Port=00 Cnt=01 Dev#= 3 Spd=1.5 MxCh= 0
I: If#= 0 Alt= 0 #EPs= 1 Cls=03(HID ) Sub=01 Prot=02 Driver=mouse
T: Bus=00 Lev=02 Prnt=02 Port=02 Cnt=02 Dev#= 4 Spd=12 MxCh= 0
I: If#= 0 Alt= 0 #EPs= 3 Cls=00(>ifc ) Sub=00 Prot=00 Driver=serial
Physically this looks like (or could be converted to):
+------------------+
| PC/root_hub (12)| Dev# = 1
+------------------+ (nn) is Mbps.
Level 0 | CN.0 | CN.1 | [CN = connector/port #]
+------------------+
/
/
+-----------------------+
Level 1 | Dev#2: 4-port hub (12)|
+-----------------------+
|CN.0 |CN.1 |CN.2 |CN.3 |
+-----------------------+
\ \____________________
\_____ \
\ \
+--------------------+ +--------------------+
Level 2 | Dev# 3: mouse (1.5)| | Dev# 4: serial (12)|
+--------------------+ +--------------------+
Or, in a more tree-like structure (ports [Connectors] without
connections could be omitted):
PC: Dev# 1, root hub, 2 ports, 12 Mbps
|_ CN.0: Dev# 2, hub, 4 ports, 12 Mbps
|_ CN.0: Dev #3, mouse, 1.5 Mbps
|_ CN.1:
|_ CN.2: Dev #4, serial, 12 Mbps
|_ CN.3:
|_ CN.1:
### END ###
@end example
Interpretation of /proc/bus/usb info on 2.6 kernels:
@example
/proc/bus/usb filesystem output
===============================
(version 2003.05.30)
The usbfs filesystem for USB devices is traditionally mounted at
/proc/bus/usb. It provides the /proc/bus/usb/devices file, as well as
the /proc/bus/usb/BBB/DDD files.
**NOTE**: If /proc/bus/usb appears empty, and a host controller
driver has been linked, then you need to mount the
filesystem. Issue the command (as root):
mount -t usbfs none /proc/bus/usb
An alternative and more permanent method would be to add
none /proc/bus/usb usbfs defaults 0 0
to /etc/fstab. This will mount usbfs at each reboot.
You can then issue `cat /proc/bus/usb/devices` to extract
USB device information, and user mode drivers can use usbfs
to interact with USB devices.
There are a number of mount options supported by usbfs.
Consult the source code (linux/drivers/usb/core/inode.c) for
information about those options.
**NOTE**: The filesystem has been renamed from "usbdevfs" to
"usbfs", to reduce confusion with "devfs". You may
still see references to the older "usbdevfs" name.
For more information on mounting the usbfs file system, see the
"USB Device Filesystem" section of the USB Guide. The latest copy
of the USB Guide can be found at http://www.linux-usb.org/
THE /proc/bus/usb/BBB/DDD FILES:
--------------------------------
Each connected USB device has one file. The BBB indicates the bus
number. The DDD indicates the device address on that bus. Both
of these numbers are assigned sequentially, and can be reused, so
you can't rely on them for stable access to devices. For example,
it's relatively common for devices to re-enumerate while they are
still connected (perhaps someone jostled their power supply, hub,
or USB cable), so a device might be 002/027 when you first connect
it and 002/048 sometime later.
These files can be read as binary data. The binary data consists
of first the device descriptor, then the descriptors for each
configuration of the device. That information is also shown in
text form by the /proc/bus/usb/devices file, described later.
These files may also be used to write user-level drivers for the USB
devices. You would open the /proc/bus/usb/BBB/DDD file read/write,
read its descriptors to make sure it's the device you expect, and then
bind to an interface (or perhaps several) using an ioctl call. You
would issue more ioctls to the device to communicate to it using
control, bulk, or other kinds of USB transfers. The IOCTLs are
listed in the linux/usbdevice_fs.h file, and at this writing the
source code (linux/drivers/usb/devio.c) is the primary reference
for how to access devices through those files.
Note that since by default these BBB/DDD files are writable only by
root, only root can write such user mode drivers. You can selectively
grant read/write permissions to other users by using "chmod". Also,
usbfs mount options such as "devmode=0666" may be helpful.
THE /proc/bus/usb/devices FILE:
-------------------------------
In /proc/bus/usb/devices, each device's output has multiple
lines of ASCII output.
I made it ASCII instead of binary on purpose, so that someone
can obtain some useful data from it without the use of an
auxiliary program. However, with an auxiliary program, the numbers
in the first 4 columns of each "T:" line (topology info:
Lev, Prnt, Port, Cnt) can be used to build a USB topology diagram.
Each line is tagged with a one-character ID for that line:
T = Topology (etc.)
B = Bandwidth (applies only to USB host controllers, which are
virtualized as root hubs)
D = Device descriptor info.
P = Product ID info. (from Device descriptor, but they won't fit
together on one line)
S = String descriptors.
C = Configuration descriptor info. (* = active configuration)
I = Interface descriptor info.
E = Endpoint descriptor info.
=======================================================================
/proc/bus/usb/devices output format:
Legend:
d = decimal number (may have leading spaces or 0's)
x = hexadecimal number (may have leading spaces or 0's)
s = string
Topology info:
T: Bus=dd Lev=dd Prnt=dd Port=dd Cnt=dd Dev#=ddd Spd=ddd MxCh=dd
| | | | | | | | |__MaxChildren
| | | | | | | |__Device Speed in Mbps
| | | | | | |__DeviceNumber
| | | | | |__Count of devices at this level
| | | | |__Connector/Port on Parent for this device
| | | |__Parent DeviceNumber
| | |__Level in topology for this bus
| |__Bus number
|__Topology info tag
Speed may be:
1.5 Mbit/s for low speed USB
12 Mbit/s for full speed USB
480 Mbit/s for high speed USB (added for USB 2.0)
Bandwidth info:
B: Alloc=ddd/ddd us (xx%), #Int=ddd, #Iso=ddd
| | | |__Number of isochronous requests
| | |__Number of interrupt requests
| |__Total Bandwidth allocated to this bus
|__Bandwidth info tag
Bandwidth allocation is an approximation of how much of one frame
(millisecond) is in use. It reflects only periodic transfers, which
are the only transfers that reserve bandwidth. Control and bulk
transfers use all other bandwidth, including reserved bandwidth that
is not used for transfers (such as for short packets).
The percentage is how much of the "reserved" bandwidth is scheduled by
those transfers. For a low or full speed bus (loosely, "USB 1.1"),
90% of the bus bandwidth is reserved. For a high speed bus (loosely,
"USB 2.0") 80% is reserved.
Device descriptor info & Product ID info:
D: Ver=x.xx Cls=xx(s) Sub=xx Prot=xx MxPS=dd #Cfgs=dd
P: Vendor=xxxx ProdID=xxxx Rev=xx.xx
where
D: Ver=x.xx Cls=xx(sssss) Sub=xx Prot=xx MxPS=dd #Cfgs=dd
| | | | | | |__NumberConfigurations
| | | | | |__MaxPacketSize of Default Endpoint
| | | | |__DeviceProtocol
| | | |__DeviceSubClass
| | |__DeviceClass
| |__Device USB version
|__Device info tag #1
where
P: Vendor=xxxx ProdID=xxxx Rev=xx.xx
| | | |__Product revision number
| | |__Product ID code
| |__Vendor ID code
|__Device info tag #2
String descriptor info:
S: Manufacturer=ssss
| |__Manufacturer of this device as read from the device.
| For USB host controller drivers (virtual root hubs) this may
| be omitted, or (for newer drivers) will identify the kernel
| version and the driver which provides this hub emulation.
|__String info tag
S: Product=ssss
| |__Product description of this device as read from the device.
| For older USB host controller drivers (virtual root hubs) this
| indicates the driver; for newer ones, it's a product (and vendor)
| description that often comes from the kernel's PCI ID database.
|__String info tag
S: SerialNumber=ssss
| |__Serial Number of this device as read from the device.
| For USB host controller drivers (virtual root hubs) this is
| some unique ID, normally a bus ID (address or slot name) that
| can't be shared with any other device.
|__String info tag
Configuration descriptor info:
C:* #Ifs=dd Cfg#=dd Atr=xx MPwr=dddmA
| | | | | |__MaxPower in mA
| | | | |__Attributes
| | | |__ConfiguratioNumber
| | |__NumberOfInterfaces
| |__ "*" indicates the active configuration (others are " ")
|__Config info tag
USB devices may have multiple configurations, each of which act
rather differently. For example, a bus-powered configuration
might be much less capable than one that is self-powered. Only
one device configuration can be active at a time; most devices
have only one configuration.
Each configuration consists of one or more interfaces. Each
interface serves a distinct "function", which is typically bound
to a different USB device driver. One common example is a USB
speaker with an audio interface for playback, and a HID interface
for use with software volume control.
Interface descriptor info (can be multiple per Config):
I: If#=dd Alt=dd #EPs=dd Cls=xx(sssss) Sub=xx Prot=xx Driver=ssss
| | | | | | | |__Driver name
| | | | | | | or "(none)"
| | | | | | |__InterfaceProtocol
| | | | | |__InterfaceSubClass
| | | | |__InterfaceClass
| | | |__NumberOfEndpoints
| | |__AlternateSettingNumber
| |__InterfaceNumber
|__Interface info tag
A given interface may have one or more "alternate" settings.
For example, default settings may not use more than a small
amount of periodic bandwidth. To use significant fractions
of bus bandwidth, drivers must select a non-default altsetting.
Only one setting for an interface may be active at a time, and
only one driver may bind to an interface at a time. Most devices
have only one alternate setting per interface.
Endpoint descriptor info (can be multiple per Interface):
E: Ad=xx(s) Atr=xx(ssss) MxPS=dddd Ivl=dddss
| | | | |__Interval (max) between transfers
| | | |__EndpointMaxPacketSize
| | |__Attributes(EndpointType)
| |__EndpointAddress(I=In,O=Out)
|__Endpoint info tag
The interval is nonzero for all periodic (interrupt or isochronous)
endpoints. For high speed endpoints the transfer interval may be
measured in microseconds rather than milliseconds.
For high speed periodic endpoints, the "MaxPacketSize" reflects
the per-microframe data transfer size. For "high bandwidth"
endpoints, that can reflect two or three packets (for up to
3KBytes every 125 usec) per endpoint.
With the Linux-USB stack, periodic bandwidth reservations use the
transfer intervals and sizes provided by URBs, which can be less
than those found in endpoint descriptor.
=======================================================================
If a user or script is interested only in Topology info, for
example, use something like "grep ^T: /proc/bus/usb/devices"
for only the Topology lines. A command like
"grep -i ^[tdp]: /proc/bus/usb/devices" can be used to list
only the lines that begin with the characters in square brackets,
where the valid characters are TDPCIE. With a slightly more able
script, it can display any selected lines (for example, only T, D,
and P lines) and change their output format. (The "procusb"
Perl script is the beginning of this idea. It will list only
selected lines [selected from TBDPSCIE] or "All" lines from
/proc/bus/usb/devices.)
The Topology lines can be used to generate a graphic/pictorial
of the USB devices on a system's root hub. (See more below
on how to do this.)
The Interface lines can be used to determine what driver is
being used for each device.
The Configuration lines could be used to list maximum power
(in milliamps) that a system's USB devices are using.
For example, "grep ^C: /proc/bus/usb/devices".
Here's an example, from a system which has a UHCI root hub,
an external hub connected to the root hub, and a mouse and
a serial converter connected to the external hub.
T: Bus=00 Lev=00 Prnt=00 Port=00 Cnt=00 Dev#= 1 Spd=12 MxCh= 2
B: Alloc= 28/900 us ( 3%), #Int= 2, #Iso= 0
D: Ver= 1.00 Cls=09(hub ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1
P: Vendor=0000 ProdID=0000 Rev= 0.00
S: Product=USB UHCI Root Hub
S: SerialNumber=dce0
C:* #Ifs= 1 Cfg#= 1 Atr=40 MxPwr= 0mA
I: If#= 0 Alt= 0 #EPs= 1 Cls=09(hub ) Sub=00 Prot=00 Driver=hub
E: Ad=81(I) Atr=03(Int.) MxPS= 8 Ivl=255ms
T: Bus=00 Lev=01 Prnt=01 Port=00 Cnt=01 Dev#= 2 Spd=12 MxCh= 4
D: Ver= 1.00 Cls=09(hub ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1
P: Vendor=0451 ProdID=1446 Rev= 1.00
C:* #Ifs= 1 Cfg#= 1 Atr=e0 MxPwr=100mA
I: If#= 0 Alt= 0 #EPs= 1 Cls=09(hub ) Sub=00 Prot=00 Driver=hub
E: Ad=81(I) Atr=03(Int.) MxPS= 1 Ivl=255ms
T: Bus=00 Lev=02 Prnt=02 Port=00 Cnt=01 Dev#= 3 Spd=1.5 MxCh= 0
D: Ver= 1.00 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1
P: Vendor=04b4 ProdID=0001 Rev= 0.00
C:* #Ifs= 1 Cfg#= 1 Atr=80 MxPwr=100mA
I: If#= 0 Alt= 0 #EPs= 1 Cls=03(HID ) Sub=01 Prot=02 Driver=mouse
E: Ad=81(I) Atr=03(Int.) MxPS= 3 Ivl= 10ms
T: Bus=00 Lev=02 Prnt=02 Port=02 Cnt=02 Dev#= 4 Spd=12 MxCh= 0
D: Ver= 1.00 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1
P: Vendor=0565 ProdID=0001 Rev= 1.08
S: Manufacturer=Peracom Networks, Inc.
S: Product=Peracom USB to Serial Converter
C:* #Ifs= 1 Cfg#= 1 Atr=a0 MxPwr=100mA
I: If#= 0 Alt= 0 #EPs= 3 Cls=00(>ifc ) Sub=00 Prot=00 Driver=serial
E: Ad=81(I) Atr=02(Bulk) MxPS= 64 Ivl= 16ms
E: Ad=01(O) Atr=02(Bulk) MxPS= 16 Ivl= 16ms
E: Ad=82(I) Atr=03(Int.) MxPS= 8 Ivl= 8ms
Selecting only the "T:" and "I:" lines from this (for example, by using
"procusb ti"), we have:
T: Bus=00 Lev=00 Prnt=00 Port=00 Cnt=00 Dev#= 1 Spd=12 MxCh= 2
T: Bus=00 Lev=01 Prnt=01 Port=00 Cnt=01 Dev#= 2 Spd=12 MxCh= 4
I: If#= 0 Alt= 0 #EPs= 1 Cls=09(hub ) Sub=00 Prot=00 Driver=hub
T: Bus=00 Lev=02 Prnt=02 Port=00 Cnt=01 Dev#= 3 Spd=1.5 MxCh= 0
I: If#= 0 Alt= 0 #EPs= 1 Cls=03(HID ) Sub=01 Prot=02 Driver=mouse
T: Bus=00 Lev=02 Prnt=02 Port=02 Cnt=02 Dev#= 4 Spd=12 MxCh= 0
I: If#= 0 Alt= 0 #EPs= 3 Cls=00(>ifc ) Sub=00 Prot=00 Driver=serial
Physically this looks like (or could be converted to):
+------------------+
| PC/root_hub (12)| Dev# = 1
+------------------+ (nn) is Mbps.
Level 0 | CN.0 | CN.1 | [CN = connector/port #]
+------------------+
/
/
+-----------------------+
Level 1 | Dev#2: 4-port hub (12)|
+-----------------------+
|CN.0 |CN.1 |CN.2 |CN.3 |
+-----------------------+
\ \____________________
\_____ \
\ \
+--------------------+ +--------------------+
Level 2 | Dev# 3: mouse (1.5)| | Dev# 4: serial (12)|
+--------------------+ +--------------------+
Or, in a more tree-like structure (ports [Connectors] without
connections could be omitted):
PC: Dev# 1, root hub, 2 ports, 12 Mbps
|_ CN.0: Dev# 2, hub, 4 ports, 12 Mbps
|_ CN.0: Dev #3, mouse, 1.5 Mbps
|_ CN.1:
|_ CN.2: Dev #4, serial, 12 Mbps
|_ CN.3:
|_ CN.1:
### END ###
@end example
@node Index, , Kernel Config, Top
@unnumbered Index
@printindex cp
@bye
