%%
%%

\label{How-To-Use-This-Manual}

\section*{How To Use This Manual}
\index{Manual!How To Use This }
\index{How To Use This Manual }
\addcontentsline{toc}{section}{How To Use This Manual}

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

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

If your operating system is older, or if you have an old-fashioned serial-line
UPS, you'll have to read about serial installation (see 
\ilink{Installation on Serial-Line
UPSes}{Installation-on-Serial_002dLine-UPSes}).  If you need more
details about administration for unusual situations (such as a master/slave or
multi-UPS setup) you'll need to read the section on advanced topics (see 
\ilink{Advanced topics}{Advanced-topics}). Finally, there is a
Technical Reference (see 
\ilink{Technical Reference}{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 (see 
\ilink{Quick Start for Beginners}{Quick-Start-for-Beginners})
instructions. 

\label{Basic-User_0027s-Guide}

\section*{Basic User's Guide}
\index{Guide!Basic User's }
\index{Basic User's Guide }
\addcontentsline{toc}{section}{Basic User's Guide}

\label{index-User_0027s-Guide-4}

\label{Planning-Your-Installation}
\section*{Planning Your Installation}
\index{Installation!Planning Your }
\index{Planning Your Installation }
\addcontentsline{toc}{section}{Planning Your Installation}

\label{index-Planning-Installation-5}
\label{index-Installation_002c-Planning-6}

\label{Quick-Start-for-Beginners}

\subsection*{Quick Start for Beginners}
\index{Quick Start for Beginners }
\index{Beginners!Quick Start for }
\addcontentsline{toc}{subsection}{Quick Start for Beginners}

\label{index-Quick-Start-7}
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.  

\begin{enumerate}
\item Check to see if apcupsd supports your UPS and cable
   (see \ilink{Supported UPSes and Cables} 
   {Supported-UPSes}).  
\item Check to see if apcupsd supports your operating system
   (see 
   \ilink{Supported Operating Systems}
   {Supported-Operating-Systems_003b}).  
\item Plan your configuration type (see 
   \ilink{Choosing a Configuration
   Type}{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 Figure out if you have one of the easy setups.  If you have a USB
   UPS, and a supported operating system and you want to use one UPS with one
   computer, that's an easy setup.  APC supplies the cable needed to talk with
   that UPS along with the UPS. All you need to do is check that your USB 
   subsystem is working (see \ilink{USB Configuration}{USB-Configuration}); 
   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 (see 
   \ilink{Advanced topics}{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.  

\begin{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 (see 
   \ilink{type\_table}{type_005ftable}) 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 (see 
   \ilink{Cables}{Cables}).  Here is hoping you are good with a
   soldering iron!  
\end{enumerate}

\item Now you are ready to read the Building and Installing (see 
   \ilink{Building and Installing
   apcupsd}{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 /etc/apcupsd/apcupd.conf file as necessary. Often it will not
   be.  
\item Change the BIOS settings (see 
   \ilink{Arranging for Reboot on
   Power-Up}{Arranging-for-Reboot-on-Power_002dUp}) 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 (see 
\ilink{Testing Apcupsd}{Testing-Apcupsd}) section.  
\item If you run into problems, read the Troubleshooting (see 
   \ilink{Troubleshooting Your
   Installation}{Troubleshooting-Your-Installation}) section of this
manual.  
\item If you still need help, send a message to the developer's email list 
   \elink{apcupsd-users at lists.sourceforge.net}{mailto: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 
   \ilink{monitoring}{Monitoring-and-Tuning-your-UPS} and 
   \ilink{maintaining}{Maintaining-Your-UPS} your UPS.  
\end{enumerate}

\input{supportedoses}

\input{supportedupses}

\label{Choosing-a-Configuration-Type}
\label{index-Choosing-a-Configuration-Type-13}
\label{index-Configuration-Type-14}
\section*{Choosing a Configuration Type}
\index{Choosing a Configuration Type} 
\index{Configuration Types}
\addcontentsline{toc}{section}{Choosing a 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 the NIS (Network Information Server)
server and client.  In this configuration, where one UPS powers several
computers, a copy of apcupsd running one one computer will act as a
server while the other(s) will act as network clients which poll the
server for information about the UPS.  Note that ``NIS" is \emph{not}
related to Sun's directory service also called ``NIS" or ``Yellow
Pages''.

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: 

\label{Configuration-types_005f}

{\bf Configuration types.}  

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

If you decide to set up one of these more complex configurations, see the
Advanced Topics (see 
\ilink{Advanced topics}{Advanced-topics}) section for details. 

\section*{USB Configuration}
\label{USB-Configuration}
\index{USB Configuration}
\index{Configuration!USB}

Apcupsd supports USB connections on all major operating systems: Linux,
FreeBSD, OpenBSD, NetBSD, Windows, Solaris, and Mac OS X Darwin. If
you plan to use a USB conenction, please read the appropriate subsection in
its entirety. You can skip this section if your UPS has a serial (RS232-C)
or Ethernet interface or if you are not running one of the platforms listed
above.

\subsection*{Linux USB Configuration}
\index{Linux USB Configuration}
\index{Linux!USB Configuration}
\index{USB!Linux Configuration}

\subsubsection*{Known Linux USB Issues}
\index{Issues!Known Linux USB}
\index{Linux!Known USB Issues}
\index{USB!Known Linux USB Issues}

\begin{description}
\item [Problem]
Linux 2.4 series kernels older than 2.4.22 (RH 9, RHEL 3) 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.  
\item [Workaround]
Upgrade linux kernel to 2.4.22 or higher. Alternately, you apply the
linux-2.4.20-killpower.patch and linux-2.4.20-USB-reject.patch patches
to your kernel and rebuild it. These patches can be found in the examples/
directory in the apcupsd source distribution.

\item [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 {\bf hiddev0: USB
HID v1.10 Device [...]} instead of {\bf hiddev96: ...} in dmesg log.  
\item [Workaround]
Boot standard kernel instead of kernel-secure or disable
CONFIG\_USB\_DYNAMIC\_MINORS and rebuild kernel-secure.  

\item [Problem]
USB driver linux-usb.c fails to compile, reporting errors
about {\bf 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.  
\item [Workaround]
Upgrade to apcupsd-3.10.14 or higher. These versions contain a workaround 
for the defect.  

\item [Problem]
On some systems such as Slackware 10.0, no USB devices will
show up (see the next section).  
\item [Workaround]
Add the following to rc.local 

\footnotesize
\begin{verbatim}
     mount -t usbdevfs none /proc/bus/usb
\end{verbatim}
\normalsize

\item [Problem]
2.6 kernels use udev and some distributions to not configure it
to automatically create /dev/usb/hiddev?? as they should, causing apcupsd to
fail to locate the UPS.
\item [Workaround]
Edit the file /etc/udev/rules.d/50-udev.rules, and add the following: 

\footnotesize
\begin{verbatim}
     KERNEL="hiddev*", NAME="usb/hiddev%n"
\end{verbatim}
\normalsize

More details are provided in the following section ... 
\end{description}

\label{Checking-Out-Your-Linux-USB-Subsystem}
\subsubsection*{Checking Out Your Linux USB Subsystem}
\index{Subsystem!Checking Out Your Linux USB}
\index{Checking Out Your Linux USB Subsystem}

You need to check three things: 
\begin{enumerate}
   \item That your USB subsystem can see the UPS
   \item That the kernel has bound the correct driver
   \item That the correct device nodes are available in /dev
\end{enumerate}

\subsubsection*{Verifying Device Detection and Driver}
\index{Linux!Verifying USB Device Detection and Driver}
\index{USB!Verifying Linux Device Detection and Driver}

To make sure that your USB subsystem can see the UPS, just do this from a
shell prompt:

\begin{verbatim}
     cat /proc/bus/usb/devices
\end{verbatim}

This information is updated by the kernel whenever a device is plugged in or
unplugged, irrespective of whether apcupsd is running or not. It contains
details on all the USB devices in your system including hubs (internal and
external), input devices, and UPSes.

You should get some output back that includes something like this, featuring
a BackUPS RS 1000: 

\begin{verbatim}
     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{verbatim}

The important things to check for are the {\bf S:} lines describing your
UPS and and the {\bf I:} line showing what driver is handling it.
If on the {\bf I:} line, {\bf Driver} is listed as {\bf 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 or RHEL 3 kernel). If this is the case for your system, please
upgrade to at least kernel version 2.4.22 and try again. If you are already
running a 2.4.22 or higher kernel, please read further for instructions for
other possible courses of action.  

For a detailed description of the contents of the /proc/bus/usb files, see
\ilink{Interpreting /proc/bus/usb (linux-2.4)}{proc_usb_info-2.4} or 
\ilink{Interpreting /proc/bus/usb (linux-2.6)}{proc_usb_info-2.6} as
appropriate for your kernel version.

Here is another example, this time featuring a Back-UPS 350:

\begin{verbatim}
     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{verbatim}

In general, if you see your UPS model in the {\bf S:} field, which means
{\bf Manufacturer=}, {\bf Product=}, and {\bf SerialNumber=}, and you see
{\bf Driver=hid} in the {\bf I:} field, you know the UPS has been recognized
and is bound to the correct driver.

If your UPS doesn't appear in the list at all, 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.)  

Also, ensure that the correct drivers are loaded. Under Linux-2.4.x, you can
check this out easily by examining the /proc/bus/usb/drivers file.  Here's
how you can do that: 

\begin{verbatim}
     cat /proc/bus/usb/drivers
\end{verbatim}

...and you should get:

\begin{verbatim}
             usbdevfs
             hub
     96-111: hiddev
             hid
\end{verbatim}

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

\begin{verbatim}
     ls -l /sys/bus/usb/drivers/
\end{verbatim}

...where you should get:

\begin{verbatim}
     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{verbatim}

...or perhaps something like:

\begin{verbatim}
     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{verbatim}

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

\begin{verbatim}
     CONFIG_USB
     CONFIG_USB_HID
     CONFIG_USB_HIDDEV
     CONFIG_USB_DEVICEFS
\end{verbatim}

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

\begin{verbatim}
     CONFIG_USB_UHCI_HCD (linux-2.6.x)
     CONFIG_USB_OHCI_HCD (linux-2.6.x)
     CONFIG_USB_UHCI     (linux-2.4.x)
     CONFIG_USB_OHCI     (linux-2.4.x)
\end{verbatim}

For a typical USB section of a kernel .config file, please see
\ilink{Typical Linux Kernel Config}{Linux-Kernel-Config}

\subsubsection*{Device Nodes}
\index{Linux!USB Device Nodes}
\index{USB!Linux Device Nodes}

Apcupsd accesses USB UPSes via the hiddev device nodes. Typically these are
located in /dev/hiddev{\it N}, /dev/usb/hiddev{\it N} or
/dev/usb/hiddev/hiddev{\it N} (where {\it N} is a digit 0 thru 9). Some 
distributions (some Debian releases, possibly others) do not provides these
device nodes for you, so you will have to make them yourself. Check /dev, 
/dev/usb, and /dev/usb/hiddev and if you  cannot find the hiddev{\it N} nodes,
run (as root) the examples/make-hiddev script from the apcupsd source distribution.

To complicate things more, many Linux flavors running 2.6 kernels such as
Fedora FC3 use the udev utility, which dynamically creates the devices in /dev
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.  

Some default udev rule sets do not include rules for creating hiddev nodes.
The bottom line for apcupsd on such a system is that if the
hiddev{\it N} is not created when you plug in your UPS, apcupsd will terminate
with an 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:

\begin{verbatim}
     BUS="usb", SYSFS{idVendor}="051d", NAME="usb/hiddev%n"
\end{verbatim}

Then either reboot your system, or unplug and replug your UPS and then restart
apcupsd. At that point a /dev/usb/hiddev{\it N} node should appear and apcupsd
should work fine.  You can use: 

\begin{verbatim}
     udevinfo -a -p /sys/class/usb/hiddev0/
\end{verbatim}

to get more information on the fields that can be matched.

You can also create a more generic rule that creates nodes for any device
using the hiddev driver, not just APC UPSes:

\begin{verbatim}
     KERNEL="hiddev*", NAME="usb/hiddev%n"
\end{verbatim}

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

\begin{verbatim}
     BUS="usb", SYSFS{serial}="AS0123456789", NAME="usb/ups0"
\end{verbatim}

where you replace the serial number in quotes with the one that correspnds to
your UPS. Then whenever you plug in your UPS it will be given a device node
called usb/ups0.

An additional device-node-related problem is the use of dynamic minors. Some
distributions, such as Mandrake 10, ship with a kernel having
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
{\bf devfs}. The following will tell you if devfs is enabled: 

\begin{verbatim}
     $ ps ax | grep devs
\end{verbatim}

...which should give something like the following: 

\begin{verbatim}
     533 ?        S      0:00 devfsd /dev
\end{verbatim}

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 completely unusable so apcupsd will not work. So, in these cases,
the choices are: 

\begin{enumerate}
    \item Reduce the security level setting of the system (not sure if 
    this is possible after the initial install).
    \item Custom build a high security kernel with devfs enabled and make
    sure devfs is mounted and devfsd is running.
    \item Custom build a high security kernel with dynamic minors disabled
    \item Use udev
\end{enumerate}

\subsubsection*{Miscellaneous}
\index{Linux!USB Miscellaneous}
\index{USB!Linux Miscellaneous}

If all these 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.


\subsection*{BSD USB Configuration}
\index{BSD USB Configuration}
\index{BSD!USB Configuration}
\index{USB!BSD Configuration}

\subsubsection*{Known BSD USB Issues}
\index{Issues!Known BSD USB}
\index{BSD!Known USB Issues}
\index{USB!Known BSD USB Issues}

\begin{description}
\item [Problem]
FreeBSD lockups: Some users have experienced lockups (apcupsd stops 
responding) on FreeBSD systems.
\item [Solution]
Recent versions of Apcupsd have addressed
this issue. Please upgrade to apcupsd-3.10.18 or higher.

\item [Problem]
FreeBSD kernel panics if USB cable is unplugged while apcupsd is running. 
\item [Solution]
This is a kernel bug and is most easily worked around by not hot- 
unplugging the UPS while apcupsd is running. This issue may be fixed in
recent FreeBSD kernels.
\end{description}

\subsubsection*{Platforms and Versions}
\index{BSD!USB Platforms and Versions}
\index{USB!BSD Platforms and Versions}

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

\subsubsection*{Kernel Configuration}
\index{BSD!USB Kernel Configuration}
\index{USB!BSD Kernel Configuration}

Users of OpenBSD, NetBSD, and some versions of FreeBSD will need to 
rebuild the kernel in order to {\bf enable the ugen driver} and 
{\bf 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 {\bf make the following changes} to your kernel config file:

\begin{description}
\item [FreeBSD (v5.4 and below, v6.0)]
(you {\bf will not} lose use of USB keyboard and mouse):
\\{\bf Disable:} uhid
\\{\bf Enable:} ugen

\item [FreeBSD (v5.5, v6.1 and above)]
(you {\bf will not} lose use of USB keyboard and mouse):
\\{\bf Disable:} (nothing)
\\{\bf Enable:} ugen

This is the default configuration for a GENERIC kernel on many platforms
so you most likely will not need to recompile.

\item [NetBSD (v3.x and below)]
(you {\bf will} lose use of USB keyboard and mouse):
\\{\bf Disable:} uhidev, ums, wsmouse, ukbd, wskbd, uhid  
\\{\bf Enable:} ugen

\item [NetBSD (v4.0 and above)]
You can use apcupsd on single USB port without disabling the USB
keyboard and mouse on other ports, though all other devices will
be disabled on the port you pick for your UPS.

First, decide which hub and port you wish to use. You can
find out the hub and port numbers for any particular physical
connector by plugging a USB device into it and looking at the
messages printed by the kernel; you should messages something
like this:

\begin{verbatim}
     uxx0 at uhub0 port 1
     uxx0: <some device name>
\end{verbatim}

To use your APC UPS on this port, configure the kernel to prefer
attachment of the ugen driver over other drivers on this hub
and port only, by adding a line like this to your kernel config
file:

\begin{verbatim}
     ugen*   at uhub0 port 1 flags 1
\end{verbatim}

(The "flags 1" forces the ugen to attach instead of anything
else detected there.)

Configure and build that kernel as per the references below, and
your UPS will now attach as a ugen device when plugged into that
port.

Don't forget to cd to /dev and "./MAKEDEV ugen1" (and 2 and so
on) if you have more than one generic usb device on your system.

\item [OpenBSD] (you {\bf will} lose use of USB keyboard and mouse):
\\{\bf Disable:} uhidev, ums, wsmouse, ukbd, wskbd, uhid  
\\{\bf Enable:} ugen
\end{description}

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

\begin{description}
\item [FreeBSD]
\elink{http://www.freebsd.org/doc/en\_US.ISO8859-1/books/handbook/kernelconfig.html}
      {http://www.freebsd.org/doc/en\_US.ISO8859-1/books/handbook/kernelconfig.html}
\item [NetBSD]
\elink{http://www.netbsd.org/guide/en/chap-kernel.html}
      {http://www.netbsd.org/guide/en/chap-kernel.html}
\item [OpenBSD]
\elink{http://www.openbsd.org/faq/faq5.html\#Building}
      {http://www.openbsd.org/faq/faq5.html\#Building}
\end{description}

\subsubsection*{Verifying Device Detection and Driver}
\index{BSD!Verifying USB Device Detection and Driver}
\index{USB!Verifying BSD Device Detection and Driver}

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: 

\begin{verbatim}
     ugen0: American Power Conversion Back-UPS RS 1500 FW:8.g6 .D USB FW:g6, rev 1.10/1.06, addr 2
\end{verbatim}

Note that the {\bf ugen} driver is called out. If you see {\bf 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: 

\begin{verbatim}
     # 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{verbatim}

\subsubsection*{Device Nodes}
\index{BSD!USB Device Nodes}
\index{USB!BSD Device Nodes}

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

\begin{description}
\item [FreeBSD]
No manual intervention needed. FreeBSD automatically creates the ugen
nodes on demand.

\item [NetBSD]
By default, NetBSD only creates nodes for the first ugen device, {\bf ugen0}.
Check "{\bf usbdevs -d}" to see which device your UPS was bound to and then
create the appropriate node by running "{\bf cd /dev ; ./MAKEDEV ugenN}",
where {\bf 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.

\item [OpenBSD]
Similar to NetBSD, OpenBSD creates nodes for {\bf ugen0} and {\bf ugen1}.
Check "{\bf usbdevs -d}" to see which device your UPS was bound to and then
create the appropriate node by running "{\bf cd /dev ; ./MAKEDEV ugenN}",
where {\bf 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.
\end{description}


\subsection*{Windows USB Configuration}
\index{Windows USB Configuration}
\index{Windows!USB Configuration}
\index{USB!Windows Configuration}

\subsubsection*{Platforms and Versions}
\index{Windows!USB Platforms and Versions}
\index{USB!Windows Platforms and Versions}

Apcupsd supports USB UPSes on Windows 98, Windows ME (untested, but
expected to work), Windows NT 4.0, Windows 2000, Windows XP, and 
Windows Server 2003. Windows Vista is untested at this time. 64-bit
platforms (x64) are also supported.

\subsubsection*{USB Driver Installation}
\index{Windows!USB Driver Installation}
\index{USB!Windows Driver Installation}

USB connected UPSes on Windows require a special driver. In most cases, 
this driver is automatically installed when you install Apcupsd. However,
if you unchecked the "USB Driver" package during installation or if you're
running Windows 98 or ME, you will need to install the driver manually.

For detailed instructions, please see the install.txt file located in
the driver\\ folder of your Apcupsd install.

\subsubsection*{Verifying Device Detection and Driver}
\index{Windows!Verifying USB Device Detection and Driver}
\index{USB!Verifying Windows Device Detection and Driver}

After installing Apcupsd (and the Apcupsd USB driver, if necessary),
plug in your UPS USB cable and open the Windows Device Manager. You 
should see a "LibUSB-Win32 Devices" section, under which is listed 
"American Power Conversion USB UPS (Apcupsd)". You should {\bf NOT}
see "HID UPS Battery" under the "Batteries" section.

If the "LibUSB-Win32 Devices" section does not appear, check that
your UPS is powered on and that the USB cable is connected at
both ends. Reinstall the driver as directed above if needed.


\subsection*{Solaris USB Configuration}
\index{Solaris USB Configuration}
\index{Solaris!USB Configuration}
\index{USB!Solaris Configuration}

\subsubsection*{Platforms and Versions}
\index{Solaris!USB Platforms and Versions}
\index{USB!Solaris Platforms and Versions}

Apcupsd supports USB UPSes on Solaris 10 and higher. Both x86 and SPARC
platforms are supported.

\subsubsection*{Building Apcupsd with USB}
\index{Solaris!Building Apcupsd with USB}
\index{USB!Solaris Building Apcupsd}

Some specific packages are necessary when building Apcupsd with USB support
on Solaris. You must install the SUNWlibusb and SUNWlibusbugen packages
{\bf BEFORE} attempting to build Apcupsd. These packages can be found on 
the Solaris installation CDROMs and should be installed with the {\bf pkgadd}
utility.

You also should build using the gcc compiler and ccs make, not Sun's
compiler. The appropriate make utility can be found in /usr/ccs/bin.
gcc can be installed from packages included on the Solaris installation
CDROMs.

Configure and build Apcupsd normally, as described in
\ilink{Building and Installing Apcupsd}{Building-and-Installing-Apcupsd}. Be
sure to include the \texttt{{---}enable-usb} flag to \texttt{configure}.

After building, install Apcupsd as root using '\texttt{make install}', then
{\bf perform a reconfigure boot ('\texttt{reboot {---} -r}')}. During 
installation, Apcupsd will automatically configure your USB subsystem to 
attach APC USB devices to the \texttt{ugen} driver. This is a critical step
and must be completed by a reconfigure boot. Note that the USB config changes
will be reversed if you remove Apcupsd using '\texttt{make uninstall}'.

\subsubsection*{Verifying Device Detection and Driver}
\index{Solaris!Verifying USB Device Detection and Driver}
\index{USB!Verifying Solaris Device Detection and Driver}

After installing Apcupsd as described above and performing a reconfigure boot,
plug in your UPS USB cable. You should see a series of dmesg log messages similar
to the following: 

\begin{verbatim}
Dec  5 17:50:50 sunblade usba: [ID 912658 kern.info] USB 1.10 device (usb51d,2) operating at low speed (USB 1.x) on USB 1.10 root hub: input@4, ugen0 at bus address 3
Dec  5 17:50:50 sunblade usba: [ID 349649 kern.info]    American Power Conversion Smart-UPS 1000 FW:600.1.D USB FW:1.2 AS0127232356
Dec  5 17:50:50 sunblade genunix: [ID 936769 kern.info] ugen0 is /pci@1f,0/usb@c,3/input@4
Dec  5 17:50:50 sunblade genunix: [ID 408114 kern.info] /pci@1f,0/usb@c,3/input@4 (ugen0) online
\end{verbatim}

Note that the {\bf ugen} driver is called out. If you do not see any dmesg entries
related to your UPS, ensure that it is turned on and that the USB cable is connected
at both ends. Also verify that you installed Apcupsd as root using the 
'\texttt{make install}' command and that you performed a reconfigure boot afterward.

\subsubsection*{Device Nodes}
\index{Solaris!USB Device Nodes}
\index{USB!Solaris Device Nodes}

Apcupsd communicates with the UPS through the USB generic device, {\bf ugen}.
The reconfigure boot performed after Apcupsd installation will ensure the
correct device nodes are created. Once your UPS has been recognized in dmesg
as shown above, you can check /dev/usb to see if the device nodes have appeared:

\begin{verbatim}
[user@sunblade /]$ ls /dev/usb/51d.2/*
cntrl0      cntrl0stat  devstat     if0in1      if0in1stat
\end{verbatim}

(\texttt{51d.2} is the vendor/product id for APC UPSes.)

\label{Darwin USB Configuration}
\subsection*{Mac OS X (Darwin) USB Configuration}
\index{Mac OS X (Darwin) USB Configuration}
\index{Darwin!USB Configuration}
\index{Mac OS X!USB Configuration}
\index{USB!Mac OS X (Darwin) Configuration}

\subsubsection*{Platforms and Versions}
\index{Darwin!USB Platforms and Versions}
\index{USB!Darwin Platforms and Versions}

Apcupsd supports USB UPSes on Mac OS X (Darwin) 10.3.x and higher. Both Intel
and PowerPC platforms are supported.

\subsubsection*{Building Apcupsd with USB}
\index{Darwin!Building Apcupsd with USB}
\index{Mac OS X!Building Apcupsd with USB}
\index{USB!Darwin Building Apcupsd}

Some specific packages are necessary when building Apcupsd with USB support
on Darwin. You must install libusb-0.1.12 or higher which can be obtained
from \elink{MacPorts}{http://www.macports.org} (formerly DarwinPorts) or 
\elink{Fink}{http://fink.sourceforge.net}. Note that Apcupsd is
sensitive to the install location of libusb, so beware if you change it
from the default.

Apcupsd should be built using gcc, preferably from the XCode development
tools. Currently the maintainer is using gcc-4.0.1 from XCode 2.4. Other
version of gcc from other sources may also work.

Configure and build Apcupsd normally, as described in
\ilink{Building and Installing Apcupsd}{Building-and-Installing-Apcupsd}.
Be sure to include the \texttt{{---}enable-usb} flag to \texttt{configure}.

After building, install Apcupsd as root using '\texttt{make install}' and
then reboot. During installation, Apcupsd will automatically install a \
simple dummy kext driver designed to prevent Apple's monitoring software
from taking over the UPS. It is necessary to reboot in order to activate
the kext. Note that this kext will be automatically removed if you
uninstall Apcupsd using '\texttt{make uninstall}', allowing Apple's
monitoring tool to once again access the UPS.

\subsubsection*{Verifying Device Detection and Driver}
\index{Darwin!Verifying USB Device Detection and Driver}
\index{Mac OS X!Verifying USB Device Detection and Driver}
\index{USB!Verifying Darwin Device Detection and Driver}

After installing Apcupsd as described above and rebooting, plug in your
UPS USB cable. You should notice that Darwin does {\bf NOT} display the
battery monitor tool in the menu bar. You can also check Apple Menu ->
About This Mac -> More Info... -> USB to ensure that your UPS
appears in the list of USB devices.


\label{Building-and-Installing-apcupsd}

\section*{Building and Installing apcupsd}
\index{Building and Installing apcupsd }
\index{Apcupsd!Building and Installing }
\addcontentsline{toc}{section}{Building and Installing apcupsd}

\label{index-Building-18}
\label{index-Installing-19}

\label{Installation-from-Binary-Packages}

\subsection*{Installation from Binary Packages}
\index{Installation from Binary Packages }
\index{Packages!Installation from Binary }
\addcontentsline{toc}{subsection}{Installation from Binary Packages}

\label{Red-Hat-Linux}

\subsubsection*{Red Hat Linux:}

\label{index-Installing_002c-Red-Hat-20}
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 {\tt 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.
(see 
\ilink{After Installation}{After-Installation})  

If you have a previous installation, you can upgrade with a normal {\tt rpm
-Uhv}, but this may not upgrade the halt script. It may be better to do the
upgrade as a remove ({\tt rpm -e}) foll;owed by a fresh install ({\tt rpm
-ihv}).  

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

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

\label{Microsoft-Windows}

\subsubsection*{Microsoft Windows:}

\label{index-Installing_002c-Microsoft-21}
If you have a binary release of the Win32 apcupsd, please see the section
describing
\ilink{the Windows version of Apcupsd}{The-Windows-Version-of-apcupsd}.

\label{Installation-from-Source}

\subsection*{Installation from Source}
\index{Source!Installation from }
\index{Installation from Source }
\addcontentsline{toc}{subsection}{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:  

\begin{enumerate}
\item Unpack the source code from its tar archive.  
\item Go into the directory containing the source code.  
\item Run {\tt ./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 {\tt \lt{}system-dependent-path\gt{}/apcupsd stop}  
\item uninstall any old apcupsd This is important since the default install
   locations may have changed.  
\item make install  
\item edit your /etc/apcupsd/apcupsd.conf file if necessary  
\item ensure that your halt script is properly updated  
\item Start the new apcupsd with: {\tt \lt{}system-dependent-path\gt{}/apcupsd
   start}  
   \end{enumerate}

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

Please note that a number of the {\tt configure} options preset apcupsd.conf
directive values in an attempt to automatically adapt apcupsd as best possible
to your system.  You can change the values in apcupsd.conf at a later time
without redoing the configuration process by simply editing the 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 {\tt 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: 

\footnotesize
\begin{verbatim}
     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-powerflute
\end{verbatim}
\normalsize

By default, {\tt make install} will install the executable files in /sbin, the
manuals in /usr/man, and the configuration and script files in /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 /etc/rc.d). 

\label{Installing-on-OSX}
\subsubsection*{Installing on OS X/Darwin}
\index{Installation!OS~X}
\index{OS~X!Installation}

On OS X (Darwin), apcupsd can be built with \texttt{configure} defaults.
The USB driver can be enabled, as per the directions on
\ilink{Darwin USB Configuration}{Darwin USB Configuration}.
Apcupsd \emph{may} be usable on OS X with a smart serial device, but
certainly \emph{does} work as a NIS client or using a USB interface.

The startup information will be installed in
\texttt{/Library/StartupItems/apcupsd} which is part of darwin's
SystemStartup.


\label{Verifying-a-Source-Installation}

\subsection*{Verifying a Source Installation}
\index{Verifying a Source Installation }
\index{Installation!Verifying a Source }
\addcontentsline{toc}{subsection}{Verifying a Source Installation}

\label{index-Verifying-Source-22}
\label{index-Installing_002c-Source-23}
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 {\tt which} and {\tt whereis}. On my Red Hat system, you should
get the following (lines preceded with a \$ indicate what you type): 

\footnotesize
\begin{verbatim}
     $ 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{verbatim}
\normalsize

If you find an apcupsd in /usr/sbin, /usr/local/sbin, /usr/lib, or another
such directory, it is probably a piece of an old version of apcupsd that you
can delete. If you are in doubt, delete it, then rerun the {\tt 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 {\tt make install} went well, you should check your
halt script (in /etc/rc.d on SUSE systems, and in /etc/rc.d/init.d on Red Hat
systems) to see that the appropriate lines have been inserted in the correct
place. 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 /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 {\tt \# ***apcupsd***} should be
inserted just before the final halt command: 

\footnotesize
\begin{verbatim}
     # 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{verbatim}
\normalsize

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 {\tt disable-install-distdir} option on
the {\tt ./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. 

\label{Configure-Options}

\subsection*{Configure Options}
\index{Options!Configure }
\index{Configure Options }
\addcontentsline{toc}{subsection}{Configure Options}

\label{index-configure-options-24}
\label{index-options_002c-configure-25}
All the available {\tt configure} options can be printed by entering: 

\footnotesize
\begin{verbatim}
     ./configure --help
\end{verbatim}
\normalsize

When specifying options for {\tt ./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 {\tt ./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 {\tt
./configure} command.  

The following command line options are available for {\tt configure} to
customize your installation. 
\label{index-options_002c-_002d_002d_002dprefix-26}

\begin{description}

\item [{---}prefix=\lt{}path\gt{}]
   \index{{---}prefix }
   This defines the directory for the non-executable files such as the manuals.
The default is {\bf /usr}.  

\label{index-options_002c-_002d_002d_002dsbindir-27}

\item [{---}sbindir=\lt{}path\gt{}]
   \index{{---}sbindir }
   This defines the directory for the executable files such as apcupsd. The
default is /sbin. You may be tempted to place the executable files in
/usr/sbin or /usr/local/sbin. Please use caution here as these directories may
be unmounted during a shutdown and thus may prevent the {\tt 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.  

\label{index-options_002c-_002d_002d_002denable_002dpowerflute-28}

\item [{---}enable-powerflute]
   \index{{---}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.  

\label{index-options_002c-_002d_002d_002denable_002dcgi-29}

\item [{---}enable-cgi]
   \index{{---}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=\lt{}path\gt{}]
   \index{{---}with-cgi-bin }
   The with-cgi-bin configuration option allows you to define the directory where
the CGI programs will be installed. The default is /etc/apcupsd, which is
probably not what you want.  

\item [{---}with-css-dir=\lt{}path\gt{}]
   \index{{---}with-css-dir }
   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-apcsmart]
   \index{{---}enable-apcsmart }
   Turns on generation of the APC Smart driver (default).  

\item [{---}enable-dumb]
   \index{{---}enable-dumb }
   Turns on generation of the dumb signalling driver code (default).  

\item [{---}enable-usb]
   \index{{---}enable-usb }
   Turns on generation of the USB driver code. By default this is disabled.  

\item [{---}enable-net]
   \index{{---}enable-net }
   Turns on generation of the NIS network driver for slaves. 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]
   \index{{---}enable-snmp }
   Turns on generation of the SNMP driver. This driver accesses the UPS over
the network using SNMP. This is compatible only with UPSes equipped with an
SNMP or Web/SNMP management card. By default this is disabled.  

\item [{---}enable-pcnet]
   \index{{---}enable-pcnet }
   Turns on generation of the PCNET (PowerChute Network Shutdown) driver.
This driver accesses the UPS over the network using APC's custom protocol.
This driver can be used as an alternative to SNMP for UPSes equipped with
a modern Web/SNMP management card.

\item [{---}enable-test]
   \index{{---}enable-test }
   This turns on a test driver that is used only for debugging. By default it is
disabled.  

\item [{---}with-libwrap=\lt{}path\gt{}]
   \index{{---}with-libwrap }
   This option when enabled causes apcupsd to be built with the TCP WRAPPER
library for enhanced security. In most cases, the \lt{}path\gt{} is optional
since configure will determine where the libraries are on most systems.  

\item [{---}with-nologin=\lt{}path\gt{}]
   \index{{---}with-nologin }
   This option allows you to specify where apcupsd will create the nologin file
when logins are prohibited. The default is /etc  

\item [{---}with-pid-dir=\lt{}path\gt{}]
   \index{{---}with-pid-dir }
   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 /var/run.  

\item [{---}with-log-dir=\lt{}path\gt{}]
   \index{{---}with-log-dir }
   This option allows you to specify where apcupsd will create the EVENTS and
STATUS log files. The default is /etc/apcupsd. This option simply sets the
default of the appropriate path in the apcupsd.conf file, which can be changed
at any later time.  

\item [{---}with-lock-dir=\lt{}path\gt{}]
   \index{{---}with-lock-dir }
   This option allows you to specify where apcupsd will create the serial port
lock file. The default is systemdependent but usually /var/lock. This option
simply sets the appropriate path in the apcupsd.conf file, which can be
changed at any later time.  

\item [{---}with-pwrfail-dir=\lt{}path\gt{}]
   \index{{---}with-pwrfail-dir }
   This option allows you to specify where apcupsd will create the powerfail file
when a power failure occurs. The default is system dependent but usually /etc.
 

\item [{---}with-serial-dev=\lt{}device-name\gt{}]
   \index{{---}with-serial-dev }
   This option allows you to specify where apcupsd will look for the serial
device that talks to the UPS. The default is system dependent, but often
/dev/ttyS0. This option simply sets the appropriate device name in the
apcupsd.conf file, which can be changed at any later time.  

\item [{---}with-nis-port=\lt{}port\gt{}]
   \index{{---}with-nis-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 apcupsd.conf file,
which can be changed at any later time.  

\item [{---}with-nisip=\lt{}IP-Address\gt{}]
   \index{{---}with-nisip }
   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=\lt{}port\gt{}]
   \index{{---}with-net-port }
   This option allows you to specify what port apcupsd will use for Master and
Slave communications. The default is system dependent but usually 6666. This
option simply sets the appropriate port in the apcupsd.conf file, which can be
changed at any later time.  

\item [{---}with-upstype=\lt{}type\gt{}]
   \index{{---}with-upstype }
   This option allows you to specify the type of UPS that will be connected to
your computer. The default is: smartups. This option simply sets the
appropriate UPS type in the apcupsd.conf file, which can be changed at any
later time.  

\item [{---}with-upscable=\lt{}path\gt{}]
   \index{{---}with-upscable }
   This option allows you to specify what cable you are using to connect to the
UPS. The default is: smart. This option simply sets the appropriate UPS cable
in the apcupsd.conf file, which can be changed at any later time.  

\item [{---}disable-install-distdir]
   \index{{---}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 /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{description}

\label{Recommended-Options-for-most-Systems}

\subsection*{Recommended Options for most Systems}
\index{Systems!Recommended Options for most }
\index{Recommended Options for most Systems }
\addcontentsline{toc}{subsection}{Recommended Options for most Systems}

For most systems, we recommend the following options: 

\footnotesize
\begin{verbatim}
     ./configure --prefix=/usr --sbindir=/sbin --enable-usb
\end{verbatim}
\normalsize

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

\footnotesize
\begin{verbatim}
     ./configure --prefix=/usr --sbindir=/sbin --enable-usb \
                 --enable-cgi --with-cgi-bin=/home/httpd/cgi-bin
\end{verbatim}
\normalsize

\label{Compilers-and-Options}

\subsection*{Compilers and Options}
\index{Options!Compilers and }
\index{Compilers and Options }
\addcontentsline{toc}{subsection}{Compilers and Options}

\label{index-compiler-options-30}
Some systems require unusual options for compilation or linking that the {\tt
./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: 

\footnotesize
\begin{verbatim}
     CFLAGS="-O2 -Wall" LDFLAGS= ./configure
\end{verbatim}
\normalsize

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

\footnotesize
\begin{verbatim}
     env CPPFLAGS=-I/usr/local/include LDFLAGS=-s ./configure
\end{verbatim}
\normalsize

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

\footnotesize
\begin{verbatim}
     setenv CFLAGS -O2
     setenv LDFLAGS -O
     ./configure
\end{verbatim}
\normalsize

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

\footnotesize
\begin{verbatim}
     ./configure --help
\end{verbatim}
\normalsize

or simply see the previous section of this manual. 

\label{Operating-System-Specifics}

\subsection*{Operating System Specifics}
\index{Operating System Specifics }
\index{Specifics!Operating System }
\addcontentsline{toc}{subsection}{Operating System Specifics}

\label{index-OSes-31}
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:  

\begin{itemize}
\item Alpha (see 
   \ilink{Alpha}{Alpha})  
\item Debian (see 
   \ilink{Debian}{Debian})  
\item FreeBSD (see 
   \ilink{FreeBSD}{FreeBSD})  
\item HPUX (see 
   \ilink{HPUX}{HPUX})  
\item NetBSD (see 
   \ilink{NetBSD}{NetBSD})  
\item OpenBSD (see 
   \ilink{OpenBSD}{OpenBSD})  
\item Red Hat (see 
   \ilink{Red Hat Systems}{Red-Hat-Systems})  
\item Slackware (see 
   \ilink{Slackware}{Slackware})  
\item SUSE (see 
   \ilink{SUSE}{SUSE})  
\item Solaris (see 
   \ilink{Sun Solaris}{Sun-Solaris})  
\item unknown (see 
   \ilink{Unknown System}{Unknown-System})  
\item Win32 (see 
   \ilink{Windows Systems}{Windows-Systems}) 
\end{itemize}

\label{Alpha}

\subsubsection*{Alpha:}

\label{index-Alpha-32}
\label{index-OS_002c-Alpha-33}
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 /dev/tty01 to avoid
conflicts with the console device. 

\footnotesize
\begin{verbatim}
     DEVICE /dev/tty01
\end{verbatim}
\normalsize

In addition, you should ensure serial port lock file in apcupsd.conf is
defined as: 

\footnotesize
\begin{verbatim}
     LOCKFILE /var/spool/locks
\end{verbatim}
\normalsize

Unlike the Linux systems, the system halt routine is located in /sbin/rc0, so
after the {\tt make install}, please check that this file has been correctly
updated.  

The start/stop script can be found in: 

\footnotesize
\begin{verbatim}
     /sbin/init.d/apcupsd
\end{verbatim}
\normalsize

\label{Debian}

\subsubsection*{Debian:}

\label{index-Debian-34}
\label{index-OS_002c-Debian-35}
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:
\lt{}src\gt{}/distributions/debian/examples/ and
\lt{}src\gt{}/distributions/debian/packageinfo  

You can also find the official Debian packages on the Debian site at:  

\begin{itemize}
\item 
   \elink{http://packages.debian.org/stable/admin/apcupsd.html}{http://packages.d%
   ebian.org/stable/admin/apcupsd.html}  
\item 
   \elink{http://packages.debian.org/testing/admin/apcupsd.html}{http://packages.%
   debian.org/testing/admin/apcupsd.html}  
\item 
   \elink{http://packages.debian.org/unstable/admin/apcupsd.html}{http://packages%
   .debian.org/unstable/admin/apcupsd.html} 
\end{itemize}

\label{FreeBSD}

\subsubsection*{FreeBSD:}

\label{index-FreeBSD-36}
\label{index-OS_002c-FreeBSD-37}
This port is complete and is being used by several users.

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 {\tt
kill-on-powerfail} option on the apcupsd command line.  

\label{HPUX}

\subsubsection*{HPUX:}

\label{index-HPUX-38}
\label{index-OS_002c-HPUX-39}
We have no reports from testing this yet on version 3.8.4, but worked fine on
3.8.1 

\label{NetBSD}

\subsubsection*{NetBSD:}

\label{index-NetBSD-40}
\label{index-OS_002c-NetBSD-41}
Submitted during development of 3.8.2, this should be a complete distribution.

\label{OpenBSD}

\subsubsection*{OpenBSD:}

\label{index-OpenBSD-42}
\label{index-OS_002c-OpenBSD-43}
Ensure that you read the 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. 

\label{Red-Hat-Systems}

\subsubsection*{Red Hat Systems:}

\label{index-Red-Hat-44}
\label{index-OS_002c-Red-Hat-45}
Red Hat systems are fully supported, and by following the standard
installation instructions given above, you should experience few or no
problems. 

\label{Slackware}

\subsubsection*{Slackware:}

\label{index-Slackware-46}
\label{index-OS_002c-Slackware-47}
Slackware systems are fully supported, and by following the standard
installation instructions given above, you should experience few or no
problems. 

\label{SUSE}

\subsubsection*{SUSE:}

\label{index-SuSE-48}
\label{index-OS_002c-SuSE-49}
SUSE systems are fully supported, and by following the standard installation
instructions given above, you should experience few or no problems. 

\label{Sun-Solaris}

\subsubsection*{Sun Solaris:}

\label{index-Sun-50}
\label{index-Solaris-51}
\label{index-OS_002c-Solaris-52}
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
{\it 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 {\tt 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 {\tt ./configure}, please be sure that you do not have /usr/ucb
on your path. This may cause the {\tt ./configure} to choose the wrong
shutdown program. If {\tt ./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, /sbin is the default. However, please be aware that if you
want to follow Sun's filesystem conventions you would use the following: 

\footnotesize
\begin{verbatim}
     ./configure \
        --prefix=/opt/apcupsd \
        --sbindir=/etc/opt/apcupsd/sbin \
        --sysconfdir=/etc/opt/apcupsd \
        --with-cgi-bin=/opt/apcupsd/cgi-bin
\end{verbatim}
\normalsize

The way to setup the /sbin directory as the executables directory is to pass
configure the {\bf 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 {\tt 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 {\tt make install} step as: 

\footnotesize
\begin{verbatim}
     /usr/ccs/bin/make install
\end{verbatim}
\normalsize

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 /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 /sbin/rc0 script, you should find lines just like the
following: 

\footnotesize
\begin{verbatim}
     # 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{verbatim}
\normalsize

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

\footnotesize
\begin{verbatim}
     #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{verbatim}
\normalsize

We have included these lines in a file called 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
/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 /etc/apcupsd. We'd be very
interested in your results, and would be glad to work with you to get this
feature working correctly with all the APC models. A detailed description of
the screen output during the shutdown would be very helpful if you see
problems.  

You will then need to make the normal changes to the /etc/apcupsd/apcupsd.conf
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
/dev/ttya and /dev/ttyb with no problems. You should be sure that logins are
disabled on the port you are going to use, otherwise you will not be able to
communicate with the UPS. If you are not sure that logins are disabled for the
port, run the 'admintool' program as root, and disable the port. The
'admintool' program is a GUI administration program, and required that you are
running CDE, OpenWindows, or another XWindows program such as KDE.  

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

\footnotesize
\begin{verbatim}
     eeprom com1-noprobe=true
\end{verbatim}
\normalsize

or 

\footnotesize
\begin{verbatim}
     eeprom com2-noprobe=true
\end{verbatim}
\normalsize

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

At this point, you should have a complete installation. The daemon will load
automatically at the next boot. Watch for any error messages during boot, and
check the event logs in /etc/apcupsd. If everything looks OK, you can try
testing the package by removing power from the UPS. NOTE! if you have a
voltage-signalling UPS, please run the 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. 

\label{Unknown-System}

\subsubsection*{Unknown System:}

\label{index-Unknown-System-53}
\label{index-OS_002c-Unknown-System-54}
During the {\tt ./configure}, if apcupsd does not find one of the systems for
which it has specific installation programs, it will set the Operating System
to {\bf unknown} and will use the incomplete installation scripts that are in
\lt{}src\gt{}/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 {\it Linux From
Scratch}, which could be helpful for other systems as well. 

\label{Windows-Systems}
\subsubsection*{Windows Systems:}
Appropriate scripts (actually Windows batch files) are included with the
Apcupsd Win32 installer package.

\label{After-Installation}

\section*{After Installation}
\index{Installation!After }
\index{After Installation }
\addcontentsline{toc}{section}{After Installation}

\label{index-After-Installation-57}
\label{index-Installation_002c-After-installing-58}

\label{Checking-Your-Configuration-File}

\subsection*{Checking Your Configuration File}
\index{File!Checking Your Configuration }
\index{Checking Your Configuration File }
\addcontentsline{toc}{subsection}{Checking Your Configuration File}

\label{index-Checking-Conf-file-59}
Once you have installed apcupsd, either from a binary package or by building
from source, your next step should be to inspect your
/etc/apcupsd/apcupsd.conf file to make sure it is valid.  

You can read the complete reference on configuration directives (see 
\ilink{Configuration Directive
Reference}{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 (see 
\ilink{type\_table}{type_005ftable}); 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 /dev/usb/hid/hiddev[0-15] (on
non-Red-Hat systems) or /dev/usb/hiddev[0-15] (on Red Hat systems), but this
is not recommended.  

Note that you should enter ``/dev/usb/hiddev[0-15]'' literally as shown.  The
``[0-15]'' expression tells apcupsd to search all hiddev devices until it
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
{\it {---}enable-usb} on your ./configure command line. If you loaded apcupsd
from an rpm file, you may have selected the wrong one {---} please ensure that
the word {\it usb} appears in the rpm package name.  

The next chapter (see 
\ilink{Configuration Examples}{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. 

\label{Arranging-for-Reboot-on-Power_002dUp}

\subsection*{Arranging for Reboot on Power-Up}
\index{Arranging for Reboot on Power-Up }
\addcontentsline{toc}{subsection}{Arranging for Reboot on Power-Up}

\label{index-Reboot-on-power-up-60}
\label{index-Power-up_002c-reboot-61}
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 {\bf BOOT} menu item, and will be called
something such as {\bf Restore on AC/Power Loss} or {\bf Full-On}. The exact
words will vary according to the ROM BIOS provider. Generally you will have
three options: {\bf Last State}, {\bf Power On}, and {\bf Power Off}. Although
{\bf Last State} should normally work, we recommend setting your computers to
{\bf 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 (/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
(/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 {\tt -p} option for powering
down the computer. It should not with the logic used by apcupsd, but if it
does, the {\tt -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. 

\label{Making-sure-apcupsd-Is-Running}

\subsection*{Making sure apcupsd Is Running}
\index{Making sure apcupsd Is Running }
\index{Running!Making sure apcupsd Is }
\addcontentsline{toc}{subsection}{Making sure apcupsd Is Running}

\label{index-Checking-running-62}
The simplest way to invoke apcupsd is from the command line by entering: 

\footnotesize
\begin{verbatim}
     /sbin/apcupsd
\end{verbatim}
\normalsize

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 rc.local script.  

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

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

\footnotesize
\begin{verbatim}
     /etc/rc.d/init.d/apcupsd start
\end{verbatim}
\normalsize

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 /etc/rc.d/apcupsd  

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

\footnotesize
\begin{verbatim}
     /etc/rc.d/apcupsd start
\end{verbatim}
\normalsize

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: 

\footnotesize
\begin{verbatim}
     /etc/rc.d/init.d/apcupsd stop
\end{verbatim}
\normalsize

On SUSE systems: 

\footnotesize
\begin{verbatim}
     /etc/rc.d/apcupsd stop
\end{verbatim}
\normalsize

Please see the Testing Apcupsd (see 
\ilink{Testing Apcupsd}{Testing-Apcupsd}) chapter for more details
on insuring that apcupsd is running properly. 

\label{Configuration-Examples}

\section*{Configuration Examples}
\index{Configuration Examples }
\index{Examples!Configuration }
\addcontentsline{toc}{section}{Configuration Examples}

\label{index-Configuration_002c-Examples-63}
\label{index-Examples_002c-Configuration-64}

\label{A-Simple-USB-Configuration}

\subsection*{A Simple USB Configuration}
\index{Configuration!Simple USB }
\index{Simple USB Configuration }
\addcontentsline{toc}{subsection}{Simple USB Configuration}

\label{index-Configuration_002c-USB-65}
\label{index-USB_002c-configuration-66}
\label{index-Example_002c-USB-conf-67}
If you have a USB UPS, and you have apcupsd version 3.10.7 (3.10.17a for *BSD)
or higher, the essential elements of your apcupsd.conf file should look like 
the following: 

\footnotesize
\begin{verbatim}
     ## apcupsd.conf v1.1 ##
     UPSCABLE usb
     UPSTYPE usb
     DEVICE
     LOCKFILE /var/lock
     UPSCLASS standalone
     UPSMODE disable
\end{verbatim}
\normalsize

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.  

Please use the explicit specifications of a device only if you know exactly
what you are doing. In general, it is much easier to let apcupsd find the
device itself.

Please see \ilink{USB Configuration}{USB-Configuration} for detailed help
on setting up your system to work with a USB UPS.

\label{A-Simple-Configuration-for-a-SmartUPS}

\subsection*{A Simple Configuration for a SmartUPS}
\index{SmartUPS!Simple Configuration for a }
\index{Simple Configuration for a SmartUPS }
\addcontentsline{toc}{subsection}{Simple Configuration for a SmartUPS}

\label{index-Configuration_002c-SmartUPS-68}
\label{index-SmartUPS-configuration-69}
\label{index-Example_002c-SmartUPS-conf-70}
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: 

\footnotesize
\begin{verbatim}
     ## apcupsd.conf v1.1 ##
     UPSCABLE smart
     UPSTYPE smartups
     DEVICE /dev/ttyS0
     LOCKFILE /var/lock
     UPSCLASS standalone
     UPSMODE disable
\end{verbatim}
\normalsize

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

\label{A-Simple-Configuration-for-a-Simple-Signaling-or-Dumb}

\subsection*{A Simple Configuration for a Simple Signaling or Dumb}
\index{Dumb!Simple Configuration for a Simple Signaling or }
\index{Simple Configuration for a Simple Signaling or Dumb }
\addcontentsline{toc}{subsection}{Simple Configuration for a Simple
Signaling or Dumb}

\label{index-Configuration_002c-dumb-71}
\label{index-dumb_002c-configuration-72}
\label{index-Example_002c-dumb-conf-73}
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 {\bf /etc/apcupsd/apccontrol} with {\bf 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. 

\footnotesize
\begin{verbatim}
     ## apcupsd.conf v1.1 ##
     UPSCABLE (number of cable you have)
     UPSTYPE dumb
     DEVICE /dev/ttyS0
     LOCKFILE /var/lock
     UPSCLASS standalone
     UPSMODE disable
\end{verbatim}
\normalsize

If your cable does not have low battery detection, as is the case with some
older models, you will also need to define {\bf TIMEOUT nnn} where you set
{\bf 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. 

\label{A-Sample-NIS-Slave-Configuration-Using-the-Net-Driver}

\subsection*{NIS Server/Client Configuration Using the Net Driver}
\index{NIS Server/Client Configuration Using the Net Driver }
\index{Driver!Sample NIS Server/Client Configuration Using the Net }
\addcontentsline{toc}{subsection}{NIS Server/Client Configuration Using the
Net Driver}

\label{index-Example_002c-NIS-slave-81}
\label{index-NIS-slave-conf-82}
\label{index-Configuration_002c-NIS-slave-conf-83}

NIS (Network Information Server) mode allows for communication between
instances of apcupsd running on different hosts.  Only one of those
hosts, the server, needs to talk to the UPS directly.  The others,
clients, optain information about the state of the UPS by querying the
server.  NIS is \emph{not} related to Sun's NIS/YP services.

NIS clients and servers require that apcupsd be compiled with the Net
Driver \texttt{{---}enable-net}.  This is typically enabled by default.

The NIS server is connected to the UPS and should be configured exactly
as a standalone configuration, but with \textbf{NETSERVER} on.  In all
other respects, the server should be configured in standalone mode.  You
may also set the NIS server specific options \textbf{NISIP} to
restict which IP address of the server which apcupsd listens on.  The
default, 0.0.0.0, means to list on all of the server host's IP addresses;
\textbf{NISPORT} (default 3551) to set which TCP port the server listens on;
and \textbf{EVENTSFILE} and \textbf{EVENTSFILEMAX} to provide information
about the last few events to clients.  You may also need to modify your
firewall rules on the server's host to allow traffic to the
\textbf{NISPORT}\@.

For the NIS client computer, you will have a configuration that looks something
like what follows.  What is important is that you get the information from an
\textbf{ether} \textbf{UPSCABLE} with \textbf{UPSTYPE} set as
\textbf{net} over the network and you must specify the address of a NIS
server using \textbf{DEVICE}\@. The client apcupsd will then poll the
NIS server specified in \textbf{DEVICE} every \textbf{NETTIME} seconds.

\footnotesize
\begin{verbatim}
     ## apcupsd.conf v1.1 ##
     UPSCABLE ether
     UPSTYPE net
     LOCKFILE /var/lock
     DEVICE server-network-address:3551
     UPSCLASS standalone
     UPSMODE disable
     NETTIME 10
\end{verbatim}
\normalsize

The \textbf{DEVICE} is set to \texttt{server-address:port}, where
\texttt{server-address} is the fully qualified domain name or IP address of
the apcupsd NIS server, and TCP port is the \textbf{NISPORT} that the server
is listening on.  The default is 3551, but older versions of apcupsd used
port 7000.  

If you set \textbf{NETTIME} 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.  

Any client 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 \textbf{BATTERYLEVEL}, \textbf{MINUTES} or \textbf{TIMEOUT} on
the client for a faster shutdown than the values defined on the NIS
server.  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. 

NIS clients work principally by reading the STATFLAG record that is sent
by the NIS server (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.  

It would be possible to have a client also work as a server, but that would
increase the delay of information getting from the UPS to the secondary
client.

\subsubsection*{Differences between NIS Client/Server and the old 
(now removed) Master/Slave modes}

The difference between the NIS mode and the removed master/slave mode
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.  

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.  


\subsection*{PowerChute Network Shutdown Driver (PCNET)}
\index{PowerChute Network Shutdown Driver (PCNET)}
\index{PCNET!PowerChute Network Shutdown Driver (PCNET)}
\addcontentsline{toc}{subsection}{PowerChute Network Shutdown Driver (PCNET)}

As of 3.14, Apcupsd supports the PowerChute Network Shutdown protocol.
This is an alternative to SNMP for use with APC's AP9617 family of 
network smartslot modules. Note that the older AP9606 modules do \textbf{not}
support PCNET.

To enable PCNET support, configure with the \texttt{{---}enable-pcnet} flag.
This is typically enabled by default.

The required apcupsd.conf settings are straightforward:

\begin{verbatim}
     ## apcupsd.conf v1.1 ##
     UPSCABLE ether
     UPSTYPE pcnet
     LOCKFILE /var/lock
     DEVICE ipaddr:user:passphrase
     UPSCLASS standalone
     UPSMODE disable
\end{verbatim}

The \textbf{DEVICE} setting specifies the IP address of the UPS as well as 
the username and authentication passphrase to use. Note that the username 
and passphrase are \textbf{not} the Web/SNMP login credentials. They are 
separate settings. The default username on a new card is "admin" and the 
default passphrase is "admin user phrase". To change the passphrase, log 
in to the Web UI and go to the UPS tab, then to PowerChute -> Configuration.
(This assumes firmware v3.3.1. Other versions may place the setting 
elsewhere.)

Note that you may leave \textbf{DEVICE} blank and Apcupsd will accept 
information from any PCNET UPS on the network, \textbf{however it will be 
very insecure since an attacker could easily send packets crafted to cause 
your server to shut down}. Using the ipaddr, user, and passphrase will \
prevent this behavior.

You may need to take steps to ensure networking stays active during your
OS's shutdown sequence in order for the PCNET driver to power off the 
UPS (the so-called "killpower" operation). On a Linux distro, you can use
commands such as...

\begin{verbatim}
   chkconfig --level 0 network on
   chkconfig --level 0 iptables on
\end{verbatim}

...to make sure networking stays up.

    
\label{Testing-Apcupsd}

\section*{Testing Apcupsd}
\index{Apcupsd!Testing }
\index{Testing Apcupsd }
\addcontentsline{toc}{section}{Testing Apcupsd}

\label{index-Testing-84}
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 (see 
\ilink{Testing Serial-Line UPSes}{Testing-Serial_002dLine-UPSes}). 

\label{Process_002dStatus-Test}

\subsection*{Process-Status Test}
\index{Process-Status Test }
\index{Test!Process-Status }
\addcontentsline{toc}{subsection}{Process-Status Test}

\label{index-Process-Status-Testing-85}
\label{index-Testing_002c-Process-Status-86}
After you start apcupsd, execute the following command: 

\footnotesize
\begin{verbatim}
     ps fax
\end{verbatim}
\normalsize

or the equivalent for your system. You should see something similar to
the following output. 

\footnotesize
\begin{verbatim}
     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{verbatim}
\normalsize

This indicates that apcupsd is up and running and has started the
two standard threads in addition to the main thread.

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 /var/log/messages where you will find one or
messages indicating the nature of the problem. 

There are three threads in apcupsd that serve the following purposes:

\begin{description}

\item [apcmain]
   \index{apcmain }
   is the main thread that waits until it receives a termination signal
(SIGTERM) or one of the child processes dies.  

\item [apcser]
   \index{apcser }
   is the thread 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]
   \index{apcnis }
   is the Network information server thread that provides EVENTS and STATUS
information over the network. This information is used by the CGI programs
and the NIS client/server networking mode. 
\end{description}


\label{Logging-Test}

\subsection*{Logging Test}
\index{Test!Logging }
\index{Logging Test }
\addcontentsline{toc}{subsection}{Logging Test}

\label{index-Testing_002c-Logging-87}
\label{index-Logging_002c-Testing-88}
Once you have established that the proper processes are running, do a tail of
the system log file, normally /var/log/messages: 

\footnotesize
\begin{verbatim}
     tail /var/log/messages
\end{verbatim}
\normalsize

You should see output that looks similar to the following: 

\footnotesize
\begin{verbatim}
     Dec 5 17:01:05 matou apcupsd[5917]: apcupsd 3.7.2
     startup succeeded
\end{verbatim}
\normalsize

And if you have configured the network information server, you should also
see: 

\footnotesize
\begin{verbatim}
     Dec 5 17:01:05 polymatou apcupsd[5975]: apcserver
     startup succeeded
\end{verbatim}
\normalsize

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

\label{apcaccess-Test}

\subsection*{apcaccess Test}
\index{Test!apcaccess }
\index{Apcaccess Test }
\addcontentsline{toc}{subsection}{apcaccess Test}

\label{index-Testing_002c-apcaccess-89}
\label{index-apcaccess-Test-90}
This test consists of running {\tt apcaccess} to see if apcupsd is properly
updating its internal variables.  Please note that you must enable the 
apcupsd Network Information Server in your configuration file for 
{\bf apcaccess} to work.  This is done by setting: 

\footnotesize
\begin{verbatim}
     NETSERVER on
     NISPORT 3551
\end{verbatim}
\normalsize

in your {\bf apcupsd.conf} file.  

To run the apcaccess test, use the following command: 

\footnotesize
\begin{verbatim}
     apcaccess status
\end{verbatim}
\normalsize

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

\footnotesize
\begin{verbatim}
     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{verbatim}
\normalsize

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

\footnotesize
\begin{verbatim}
     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{verbatim}
\normalsize

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.  

\begin{description}

\item [LINEV]
   \index{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]
   \index{BATTV }
   Unless you have additional battery packs, this should be near 24 Volts plus or
minus 5 Volts.  

\item [STATUS]
   \index{STATUS }
   This is the status of the UPS and it should normally be {\bf ONLINE}. 
\end{description}

If you see a message to the effect of: 

\footnotesize
\begin{verbatim}
     attach_shmarea: shared memory version mismatch (or UPS not yet ready to report)
\end{verbatim}
\normalsize

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

If you see a message to the effect of: 

\footnotesize
\begin{verbatim}
     APCACCESS FATAL ERROR in apcaccess.c at line 336
     tcp_open: cannot connect to server localhost on port 3551.
\end{verbatim}
\normalsize

It means that you have probably not enabled the Network Information Server in
your configuration file for {\bf apcaccess} to work. This is done by setting: 

\footnotesize
\begin{verbatim}
     NETSERVER on
     NISPORT 3551
\end{verbatim}
\normalsize

in your {\bf apcupsd.conf} file. 

\label{Communications-Test}

\subsection*{Communications Test}
\index{Test!Communications }
\index{Communications Test }
\addcontentsline{toc}{subsection}{Communications Test}

\label{index-Testing_002c-Communications-91}
\label{index-Communications-Testing-92}
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 {\bf apccontrol} script
(normally in /etc/acpupsd/apccontrol) to handle the event.  

In order to create an event, remove the serial port plug from the back of your
computer or from the back of the UPS. Within 6 seconds, apcupsd should detect
the lack of serial port communications and broadcast a {\tt 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 (/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 {\it no} (see {\bf man wall} or {\bf 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 {\tt wall}
messages. However, you should find them in your system log file (normally
/var/log/messages and in the temporary EVENTS file,
/etc/apcupsd/apcupsd.events. For example, to observe these events in the
temporary EVENTS file, you might do a 

\footnotesize
\begin{verbatim}
     tail -f /etc/apcupsd/apcupsd.events
\end{verbatim}
\normalsize

Note, if you have installed from the RPM, the proper events file may be
/var/log/apcupsd.events. You can find the actual filename by checking your
apcupsd.conf file.  

before running the test.  

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

\label{Simulated-Power-Fail-Test}

\subsection*{Simulated Power Fail Test}
\index{Simulated Power Fail Test }
\index{Test!Simulated Power Fail }
\addcontentsline{toc}{subsection}{Simulated Power Fail Test}

\label{index-Testing_002c-Simulate-Power-Fail-93}
\label{index-Simulate-Power-Fail-Test-94}
At this point, you should verify that in the event of a power fail apcupsd
properly calls apccontrol. This test is appropriate for all models of UPSes
(smart or dumb).  

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

\footnotesize
\begin{verbatim}
     Warning power loss detected.
\end{verbatim}
\normalsize

Then generally 6 seconds later, apcupsd is sure that it isn't a transient
effect, so it sends: 

\footnotesize
\begin{verbatim}
     Power failure. Running on UPS batteries.
\end{verbatim}
\normalsize

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: 

\footnotesize
\begin{verbatim}
     Power has returned...
\end{verbatim}
\normalsize

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

\begin{itemize}
\item apcupsd doesn't recognize the power failure because the configuration
   directives are not correct. E.g. wrong cable.  
\item The 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 apcupsd and
change the value of {\bf 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 {\tt wall} or by the {\tt
tail -f} command. The precise message is determined by what is printed in
/etc/apcupsd/apccontrol for the {\bf doshutdown} event.  Though it varies from
system to system, it will generally be something like: 

\footnotesize
\begin{verbatim}
     Beginning Shutdown Sequence
\end{verbatim}
\normalsize

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

{\bf IMPORTANT} after this test, please replace the changed apccontrol and
apcupsd.conf with the original files. 

\label{System-Shutdown-Test}

\subsection*{System Shutdown Test}
\index{System Shutdown Test }
\index{Test!System Shutdown }
\addcontentsline{toc}{subsection}{System Shutdown Test}

\label{index-System-Shutdown-test-95}
\label{index-Testing_002c-System-Shutdown-96}
This is an intermediate test that you can do, for all UPS models before doing
the Full Power Down Test. First modify the /etc/apcupsd/apccontrol file so
that in the {\bf killpower)} case, the line that re-executes apcupsd with the
{\tt \verb{--{killpower} option is commented out. The original line probably looks
something like: 

\footnotesize
\begin{verbatim}
     ${APCUPSD} --killpower
\end{verbatim}
\normalsize

when it is commented out, it looks like: 

\footnotesize
\begin{verbatim}
     #${APCUPSD}--killpower
\end{verbatim}
\normalsize

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

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

\label{Full-Power-Down-Test}

\subsection*{Full Power Down Test}
\index{Full Power Down Test }
\index{Test!Full Power Down }
\addcontentsline{toc}{subsection}{Full Power Down Test}

\label{index-Power-down-test-97}
\label{index-Testing_002c-Power-down-98}
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 {\tt
apcupsd \verb{--{killpower} when it detects a power failure situation (the presence
of a /etc/powerfail file). See the 
\ilink{Building and Installing
apcupsd}{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 {\bf 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
{\bf 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 {\bf 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 {\tt apcaccess eprom} and look at the
``Shutdown grace delay''. 

\label{Shutdown-Sequence}

\subsection*{Shutdown Sequence}
\index{Shutdown Sequence }
\index{Sequence!Shutdown }
\addcontentsline{toc}{subsection}{Shutdown Sequence}

\label{index-Shutdown-Sequence-99}
If you experienced so problems with the above testing procedures, or if you
are porting apcupsd to another system, or you are simply curious, you may want
to know exactly what is going on during the shutdown process. If so, please
see the Shutdown Sequence (see 
\ilink{Shutdown Sequence
\lt{}1\gt{}}{Shutdown-Sequence-_003c1_003e}) section of this
manual. 

\label{apctest}

\subsection*{apctest}
\index{Apctest }
\addcontentsline{toc}{subsection}{apctest}

\label{index-apctest-100}
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 
\ilink{Using apctest on Serial-Line
UPSses}{Using-apctest-on-Serial_002dLine-UPSses} for a description
of how to use it with a voltage-signalling UPS.  

Shutdown apcupsd if it is running. Make sure your {\bf
/etc/apcupsd/apcupsd.conf} file has {\bf UPSTYPE smart} and {\bf 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 \lt{}apcupsd-source\gt{}/src directory. You can explicitly build
it on Unix with: 

\footnotesize
\begin{verbatim}
     cd <apcupsd-source-directory>
     make apctest
     ./apctest
\end{verbatim}
\normalsize

or on Windows systems with: 

\footnotesize
\begin{verbatim}
     make apctestwin32
     ./apctest
\end{verbatim}
\normalsize

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: 

\footnotesize
\begin{verbatim}
     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{verbatim}
\normalsize

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 
\ilink{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
(see 
\ilink{APC smart protocol}{APC-smart-protocol}) chapter of this
manual.  

Item 7 will terminate apctest. 

\label{Troubleshooting-Your-Installation}

\section*{Troubleshooting Your Installation}
\index{Troubleshooting Your Installation }
\index{Installation!Troubleshooting Your }
\addcontentsline{toc}{section}{Troubleshooting Your Installation}

\label{index-Troubleshooting-_0028see-problems_0029-101}
\label{index-Problems-102}

\label{Known-Problems-with-USB-UPSes}

\subsection*{Known Problems with USB UPSes}
\index{Known Problems with USB UPSes }
\index{UPSes!Known Problems with USB }
\addcontentsline{toc}{subsection}{Known Problems with USB UPSes}

\label{index-Problems_002c-USB-103}

\label{Some-Cheaper-Models-Do-Not-Have-Battery-Charge}

\subsubsection*{Some Cheaper Models Do Not Have Battery Charge:}

\label{index-Problems_002c-no-Battery-charge-104}
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. 

\label{Reconnection-does-not-clean-up-the-lockfile}

\subsubsection*{Reconnection does not clean up the lockfile:}

\label{index-Problems_002c-lock-file-not-cleaned-up-105}
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. 

\label{Power-Off-_005bkillpower_005d-of-UPS-Does-Not-Work}

\subsubsection*{Power Off (killpower) of UPS Does Not Work:}

\label{index-Problems_002c-Power-off-106}
\label{index-Problems_002c-killpower-107}
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. 

\label{apcupsd-Cannot-Reconnect-After-a-Reboot}

\subsubsection*{apcupsd Cannot Reconnect After a Reboot:}

\label{index-Problems_002c-reconnect-108}
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 {\tt cat /proc/modules} andnd save
the output some place. Then reboot your computer and before you do anything
else, do the {\tt cat /proc/modules} again. Most likely you will find some of
the usb modules are missing in the second listing.  

There are two solutions:  

\begin{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
{\tt 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:  

\footnotesize
\begin{verbatim}
          /sbin/modprobe <missing-module-name>
     
\end{verbatim}
\normalsize

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

\label{Monitoring-and-Tuning-your-UPS}

\section*{Monitoring and Tuning your UPS}
\index{UPS!Monitoring and Tuning your }
\index{Monitoring and Tuning your UPS }
\addcontentsline{toc}{section}{Monitoring and Tuning your UPS}

\label{index-Monitoring-109}
\label{index-Tuning-110}
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. 

\label{apcaccess}

\subsection*{apcaccess}
\index{Apcaccess }
\addcontentsline{toc}{subsection}{apcaccess}

\label{index-apcaccess-111}
apcaccess is a program (normally found in /sbin/apcaccess) that permits you to
print out the complete status of your UPS. Although there are a number of
command line arguments ({\bf eprom, reconfig, status, slave, shutdown}), all
except {\bf eprom} and {\bf status} are under development and hence do not
work reliably.  

apcaccess will use the Network Information Server to obtain the necessary
information for the {\bf status} and {\bf eeprom} commands. You can specify
a second optional argument to apcaccess in the form of host:port where the
:port is optional. The default is {\bf 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: 

\footnotesize
\begin{verbatim}
     NETSERVER on
     NISPORT 3551
\end{verbatim}
\normalsize

in your {\bf apcupsd.conf} file. 

\label{apcaccess-status}

\subsubsection*{apcaccess status:}

\label{index-apcaccess-status-112}
\label{index-status_002c-apcaccess-113}
As mentioned above, the full form of the command is: 

\footnotesize
\begin{verbatim}
     apcaccess status localhost:3551
\end{verbatim}
\normalsize

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 {\bf status} command line option of apcaccess will produce a full printout
of all the {\bf STATUS} variables used by apcupsd. This can be very helpful
for checking the condition of your UPS and to know whether or not apcupsd is
properly connected to it. For a complete description of the variables and
their meanings, please read the Status Format (see 
\ilink{apcupsd Status Logging}{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: 

\footnotesize
\begin{verbatim}
     APCACCESS FATAL ERROR in apcipc.c at line 325
     attach_shmarea: shared memory version mismatch
\end{verbatim}
\normalsize

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: 

\footnotesize
\begin{verbatim}
     apcaccess status
\end{verbatim}
\normalsize

For a SmartUPS 1000 apcaccess will emit the following output: 

\footnotesize
\begin{verbatim}
     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{verbatim}
\normalsize

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. 

\label{apcaccess-eprom}

\subsubsection*{apcaccess eprom:}

\label{index-apcaccess-eeprom-114}
\label{index-eeprom_002c-apcaccess-115}
The {\bf 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 (see 
\ilink{Configuring Your EEPROM}{Configuring-Your-EEPROM}).  

A typical output from {\tt apcaccess eprom} is: 

\footnotesize
\begin{verbatim}
     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{verbatim}
\normalsize

\label{Apcupsd-Notification-and-Events}

\subsection*{Apcupsd Notification and Events}
\index{Events!Apcupsd Notification and }
\index{Apcupsd Notification and Events }
\addcontentsline{toc}{subsection}{Apcupsd Notification and Events}

\label{index-Notification-116}
\label{index-Events-117}
When a major event is generated within apcupsd, control is passed to the
script apccontrol normally found in /etc/apcupsd/apccontrol. The event name,
and a number of other important parameters are passed to the script.  

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

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

\label{hid_002dups-and-USB-Specific-Information}

\subsection*{hid-ups and USB Specific Information}
\index{Information!hid-ups and USB Specific }
\index{Hid-ups and USB Specific Information }
\addcontentsline{toc}{subsection}{hid-ups and USB Specific Information}

\label{index-hid_002dups-118}
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. 

\label{apcupsd-Network-Monitoring-_005bCGI_005d-Programs}

\subsection*{apcupsd Network Monitoring (CGI) Programs}
\index{Programs!apcupsd Network Monitoring CGI }
\index{Apcupsd Network Monitoring (CGI) Programs }
\addcontentsline{toc}{subsection}{apcupsd Network Monitoring (CGI)
Programs}

\label{index-Network-monitoring-119}
\label{index-Monitoring-120}
\label{index-CGI-programs-121}
With this release, there are four CGI programs (multimon.cgi,
upsstats.cgi, upsfstats.cgi, and upsimage.cgi). To have them properly
installed, you must run the {\tt ./configure} command with {\tt \verb{--{enable-cgi}
and you should specify an installation directory with {\tt \verb{--{with-cgi-bin=} or
load them manually. The default directory for installation of the CGI programs is
/etc/apcupsd, which is not really where you want them if you are going to use them.
Normally, they should go in the cgi-bin of your Web server.

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

Normally only {\tt multimon.cgi} is 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. 

\label{Setting-up-and-Testing-the-CGI-Programs}

\subsubsection*{Setting up and Testing the CGI Programs}
\index{Programs!Setting up and Testing the CGI }
\index{Setting up and Testing the CGI Programs }
\addcontentsline{toc}{subsection}{Setting up and Testing the CGI Programs}

\label{index-Setup-CGI-programs-122}
\label{index-Testing-CGI-programs-123}

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 {\bf
NETSERVER on} in /etc/apcupsd/apcupsd.conf.  This switch is on by default.  If
you are unsure of its state, see the section at the end of this chapter
concerning the Client test program.  

Next you must edit the hosts 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 multimon.conf unmodified from what is on the source distribution.
However, he has modified the hosts.conf file to contain the following three
lines: 

\footnotesize
\begin{verbatim}
     MONITOR matou "Server"
     MONITOR polymatou "Backup server"
     MONITOR deuter  "Disk server"
\end{verbatim}
\normalsize

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 {\bf :\lt{}port\gt{}}, 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: 

\footnotesize
\begin{verbatim}
     MONITOR matou "Server"
     MONITOR polymatou "Backup server"
     MONITOR deuter  "Disk server"
     MONITOR polymatou:7001 "APC USB UPS"
\end{verbatim}
\normalsize

where the USB copy of apcupsd has been configured to use port 7001 (with {\tt
\verb{--{with-nis-port=7001} on the {\tt ./configure} or by modifying apcupsd.conf).
Note, the default NIS port is 3551 on most platforms.  

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

\footnotesize
\begin{verbatim}
     ./multimon.cgi
\end{verbatim}
\normalsize

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

\footnotesize
\begin{verbatim}
     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{verbatim}
\normalsize

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

To invoke multimon in your Web browser, enter:  

http://\lt{}your-site\gt{}/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 may simply edit the apcupsd.css file to specify the styles 
you prefer.

\label{multimon_005fcgi}

\subsubsection*{multimon.cgi:}

\label{index-multimon-126}
\label{index-CGI_002c-multimon-127}
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:  

\addcontentsline{lof}{figure}{Multimon Main Page}
\includegraphics{./multimon.eps}  

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

\label{upsstats_005fcgi}

\subsubsection*{upsstats.cgi:}

\label{index-upsstats-128}
\label{index-CGI_002c-upsstats-129}
By clicking on the {\bf system} name in the {\bf 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,  

\addcontentsline{lof}{figure}{Multimon Statistics Display}
\includegraphics{./status.eps}  

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
/etc/apcupsd/hosts.conf file, you can execute it from a Unix shell from the
source cgi directory as follows: 

\label{_005f_002fupsstats_005fcgi}

\begin{verbatim}
     ./upsstats.cgi
\end{verbatim}

\label{index-upssstats-130}
\label{index-CGI_002c-upssstats-131}
As with multimon, quite a few lines of html should then be displayed. 

\label{upsfstatus_005fcgi}

\subsubsection*{upsfstatus.cgi:}

\label{index-upsfstatus-132}
\label{index-CGI_002c-upsfstatus-133}
If you would like to see all of the STATUS variables available over the
network, click on the {\bf Data} field of the desired system, and your browser
will display something like the following: 

\footnotesize
\begin{verbatim}
     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{verbatim}
\normalsize

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. 

\label{Working-Example}

\subsubsection*{Working Example:}

\label{index-CGI_002c-working-example-134}
\label{index-Example_002c-CGI-135}
To see a working example of the above programs, visit 
\elink{http://www.apcupsd.com/cgi-bin/multimon.cgi}{http://www.apcupsd.com/cgi%
-bin/multimon.cgi}. 

\label{Client-Test-Program}

\subsubsection*{Client Test Program:}

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

\footnotesize
\begin{verbatim}
     cc client.c ../lib/libapc.a -o client
\end{verbatim}
\normalsize

Then execute it: 

\footnotesize
\begin{verbatim}
     ./client <host>[:<port>] [<command>]
\end{verbatim}
\normalsize

Where {\bf 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 {\bf status} or {\bf
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: {\bf events} and
{\bf status}.  Hence the following commands: 

\footnotesize
\begin{verbatim}
     ./client
     status
     events
     xyz
     ^D
\end{verbatim}
\normalsize

should produce the status listing (the same as produced by {\tt apcaccess
status}), followed by the list of the last 10 events (in response to the {\bf
events} command), and finally {\bf Invalid command} in response to the {\bf
xyz} input, which is not a valid command. The control-D terminates the {\bf
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, ...). 

\label{A-Tip-from-Carl-Erhorn-for-Sun-Systems}

\subsubsection*{A Tip from Carl Erhorn for Sun Systems:}

\label{index-Tip-137}
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 

\label{Credits}

\subsubsection*{Credits:}

Many thanks go to Russell Kroll \lt{}rkroll at exploits.org\gt{} who wrote the
CGI programs to work with his UPS Monitoring system named 
\elink{Network UPS Tools
(NUT)}{http://www.exploits.org/nut/library/apcsmart.html}. Thanks also to
Jonathan Benson \lt{}jbenson at technologist.com\gt{} 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. 

\label{Security-Issues}

\subsection*{Security Issues:}

\begin{itemize}
\item {\bf apcupsd} runs as root.  

\item If you have \textbf{NETSERVER ON} in your apcupsd.conf file (which is the
   default), 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 many, there is little risk. In addition, if you
have a perimeter firewall or NATting router with typical settings
only users on your local network access to your UPS information.
You may also restrict access using using firewall settings (see below) or
TCP Wrappers (see below).
\end{itemize}

\label{Firewall-Settings}
\subsection*{Firewall Settings}
\label{Firewall-Settings}
\index{Firewall Settings}
\addcontentsline{toc}{subsubsection}{Firewall Settings}

If you are running apcupsd as an NIS server, you will need to ensure that
the clients can reach it by opening up \textbf{NISPORT} (default: TCP
3551) on any firewall running on the server.  You may wish to configure
your firewall(s) to \emph{only} allow connections from your local network
or specifically from the masters, slaves, and servers as needed.


\label{TCP-Wrappers}

\subsection*{TCP Wrappers}
\index{TCP Wrappers }
\index{Wrappers!TCP }
\addcontentsline{toc}{subsubsection}{TCP Wrappers}

\label{index-Wrappers_002c-TCP-138}
\label{index-TCP-wrappers-139}

If your operating system does not support a host based firewall (a
firewall running on the local machine) then you may try to get some of
the funtionality of such a firewall with TCP~Wrappers.
As of apcupsd version 3.8.2, TCP Wrappers are implemented if you turn them on
when configuring ({\tt ./configure \verb{--{with-libwrap}).  With this code enabled,
you may control who may access your apcupsd via TCP connections (the Network
Information Server). This control is done by modifying the file: /etc/hosts.allow.
This code is implemented but untested. If you use it, please send us some feedback. 

\label{Configuring-Your-EEPROM}

\subsection*{Configuring Your EEPROM}
\index{Configuring Your EEPROM }
\index{EEPROM!Configuring Your }
\addcontentsline{toc}{subsection}{Configuring Your EEPROM}

\label{index-eeprom_002c-configuring-140}
\label{index-Configuring_002c-eeprom-141}
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. 

\label{apcupsd-No-Longer-Configures-EEPROM}

\subsubsection*{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 {\tt apcaccess
status} and also print a copy of the output from {\tt 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: 

\footnotesize
\begin{verbatim}
     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{verbatim}
\normalsize

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

\label{Using-apctest-to-Configure-Your-EEPROM}

\subsubsection*{Using apctest to Configure Your EEPROM:}

\label{index-eeprom_002c-apctest-142}
\label{index-apctest-setting-eeprom-143}
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: 

\footnotesize
\begin{verbatim}
     cd <apcupsd-source>/src
     su
     <root-password>
     ./apctest
\end{verbatim}
\normalsize

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

\footnotesize
\begin{verbatim}
     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{verbatim}
\normalsize

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: 

\footnotesize
\begin{verbatim}
     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{verbatim}
\normalsize

If you wish to use the old pre-3.10.x method of EEPROM programming with values
specified in the 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: 

\footnotesize
\begin{verbatim}
     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{verbatim}
\normalsize

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. 

\label{Maintaining-Your-UPS}

\section*{Maintaining Your UPS}
\index{UPS!Maintaining Your }
\index{Maintaining Your UPS }
\addcontentsline{toc}{section}{Maintaining Your UPS}

\label{index-Maintenance-144}
If you have your UPS long enough, you will probably have battery problems.
Below, you will find some suggestions for replacing batteries. One {\it
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. 

\label{What-Various-People-Have-to-Say-about-Batteries}

\subsection*{What Various People Have to Say about Batteries}
\index{What Various People Have to Say about Batteries }
\index{Batteries!What Various People Have to Say about }
\addcontentsline{toc}{subsection}{What Various People Have to Say about
Batteries}

\label{index-Batteries-145}
Here is what John Walker has to say about APC UPS batteries:  

\begin{quote}

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{quote}

And Andre Hendrick says:  

\begin{quote}

[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.  

\footnotesize
\begin{verbatim}
          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{verbatim}
\normalsize

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:  

\footnotesize
\begin{verbatim}
          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{verbatim}
\normalsize

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

\footnotesize
\begin{verbatim}
          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{verbatim}
\normalsize

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,  

\footnotesize
\begin{verbatim}
          Andre Hedrick
          Linux ATA Development
     
\end{verbatim}
\normalsize

\end{quote}

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

\begin{quote}

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.  

\gt{}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{quote}

\label{Where-Carl-Suggests-You-Get-Batteries}

\subsection*{Where Carl Suggests You Get Batteries}
\index{Where Carl Suggests You Get Batteries }
\index{Batteries!Where Carl Suggests You Get }
\addcontentsline{toc}{subsection}{Where Carl Suggests You Get Batteries}

\label{index-Batteries-146}

\begin{quote}

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: 
\elink{www.batterywholesale.com}{http://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.  

\footnotesize
\begin{verbatim}
          Regards,
          --Carl
     
\end{verbatim}
\normalsize

\end{quote}

Here is a link to the 
\elink{APC Battery
Store}
{http://www.batterywholesale.com/battery-store/APC-batteries/?PHPSESSID=10ba07%
023457efda6a3520af1957755f}. 

\label{Frequently_002dAsked-Questions}

\section*{Frequently-Asked Questions}
\index{Questions!Frequently-Asked }
\index{Frequently-Asked Questions }
\addcontentsline{toc}{section}{Frequently-Asked Questions}

\label{index-FAQ-147}
See the bugs section of this document for a list of known bugs and solutions. 


\begin{description}

\item [\label{crazy}
   Q:]
   \index{a name }
Why all the craziness with custom serial cables?  

\item [A:]
   \index{ 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:]
   \index{ Q: }
   What UPS brands does apcupsd support?  

\item [A:]
   \index{ 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:]
   \index{ Q: }
   Does apcupsd support Windows?  

\item [A:]
   \index{ 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:]
   \index{ Q: }
   I don't have a cable, which one should I build?  

\item [A:]
   \index{ A: }
   First you must know if you have an apcsmart UPS or a voltage-signalling UPS.
See the table of supported UPSes (see 
\ilink{type\_table}{type_005ftable}). If you have a apcsmart UPS,
we recommend building a Custom Smart (see 
\ilink{Smart-Custom Cable for
SmartUPSes}{Smart_002dCustom-Cable-for-SmartUPSes}) cable. If you
have a voltage-signaling UPS, we recommend that you build a Custom Simple (see

\ilink{Voltage-Signalling Cable for "dumb"
UPSes}{Voltage_002dSignalling-Cable-for-_0022dumb_0022-UPSes})
cable.  

\item [Q:]
   \index{ Q: }
   How much CPU resources does apcupsd use?  

\item [A:]
   \index{ 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.  

\item [Q:]
   \index{ Q: }
   What language is apcupsd written in?  

\item [A:]
   \index{ A: }
   It is written entirely in C.  

\item [Q:]
   \index{ 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 {\tt
apcupsd \verb{--{killpower}! What can we do to fix this, and is it critical?  

\item [A:]
   \index{ A: }
   No, the error is not serious. Unfortunately, the documentation in the area of
master/slaves is not very detailed, and for that reason, your slave setup is
not totally correct as explained below.  

On master machines, we modify /etc/rc.d/init.d/halt to re-invoke apcupsd with
the {\tt \verb{--{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
/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:]
   \index{ 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:]
   \index{ A: }
   Normally, once the shutdown process has begun, we cannot stop it, though there
{\it 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:]
   \index{ Q: }
   After running apcupsd for a while, I get the following error: ``Serial
communications with UPS lost.'' What is the problem?  

\item [A:]
   \index{ 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:]
   \index{ Q: }
   When apcupsd starts, I get the following error: ``attach\_shmarea: cannot get
shm area: Identifier removed.'' What is the problem?  

\item [A:]
   \index{ A: }
   This problem and the problem of {\bf 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: {\tt 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 {\tt 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:]
   \index{ 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:]
   \index{ 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:  

\footnotesize
\begin{verbatim}
          ls /dev
     
\end{verbatim}
\normalsize

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 {\tt MAKEDEV} or
{\tt find / -name MAKEDEV}.  It is often located in {\tt /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:]
   \index{ Q: }
   How do I ensure that the slaves shutdown before the master?  

\item [A:]
   \index{ 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 {\bf
sleep} shell command in the /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:]
   \index{ Q: }
   How do I ensure that my database server is correctly shutdown?  

\item [A:]
   \index{ A: }
   You simply add whatever commands are necessary in the appropriate case
statements in /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:]
   \index{ 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:]
   \index{ A: }
   The most common error causing your problem is an incorrect serial port
specification on your DEVICE directive. It should be:  

\footnotesize
\begin{verbatim}
          DEVICE /dev/com2
     
\end{verbatim}
\normalsize

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

The second most common problem is bad placement of the files i.e. you did not
install them in c:\textbackslash{}apcupsd Unfortunately for the current
release, this path is ``hard coded'' into the binaries.  

The third most common problem is that you did not run the setup.bat script
after loading the 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:
c:\textbackslash{}apcupsd\textbackslash{}etc\textbackslash{}apcupsd\textbackslash
{}apcupsd.events  

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

\item [Q:]
   \index{ Q: }
   When using USB, I get the following log messages: usb-uhci.c: interrupt,
status 3, frame\# 826. What does it mean?  

\item [A:]
   \index{ 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.  

\end{description}

\label{Apcupsd-Bugs}

\section*{Apcupsd Bugs}
\index{Bugs!Apcupsd }
\index{Apcupsd Bugs }
\addcontentsline{toc}{section}{Apcupsd Bugs}

\label{index-Bugs-148}
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. 

\label{Advanced-topics}

\section*{Advanced topics}
\index{Advanced topics }
\index{Topics!Advanced }
\addcontentsline{toc}{section}{Advanced topics}

\label{index-Advanced-149}

\label{Customizing-Event-Handling}

\section*{Customizing Event Handling}
\index{Customizing Event Handling }
\index{Handling!Customizing Event }
\addcontentsline{toc}{section}{Customizing Event Handling}

\label{index-Event-handling-150}
\label{index-Customizing-event-handling-151}

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
/etc/apcupsd/apccontrol. The {\bf 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 /etc/apcupsd
directory.  

These events are sent to the system log, optionally sent to the temporary
events file (/etc/apcupsd/apcupsd.events), and they also generate a call to
/etc/apcupsd/apccontrol which in turn will call any scripts you have placed in
the /etc/apcupsd directory.  

Normally, /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 {\tt wall}. We recommend that you do so by writing your own
script to be invoked by {\tt 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 \lt{}event\gt{} \lt{}ups-name\gt{} \lt{}connected\gt{}
\lt{}powered\gt{}  

where:  

\begin{description}

\item [event]
   \index{event }
   is the event that occurred and it may be any one of the values described in
the next section.  

\item [ups-name]
   \index{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 {\bf Default}  

\item [connected]
   \index{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]
   \index{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{description}

\label{apccontrol-Command-Line-Options}

\subsection*{apccontrol Command Line Options}
\index{Options!apccontrol Command Line }
\index{Apccontrol Command Line Options }
\addcontentsline{toc}{subsection}{apccontrol Command Line Options}

apccontrol accepts the following command line options:  

\begin{description}

\item [annoyme]
   \index{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 {\tt printf ``Power problems please logoff.'' | wall}
then exits.  

\item [changeme]
   \index{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 {\tt printf ``Emergency! UPS batteries have
failed\textbackslash{}nChange them NOW'' | wall} then exits.  

\item [commfailure]
   \index{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 {\tt printf ``Warning serial port communications with UPS
lost.'' | wall} then exits.  

\item [commok]
   \index{commok }
   After a commfailure event is issued, when the communications to the computer
is re-established, this event will be generated.  

Default {---} does a {\tt printf ``Serial communications with UPS restored.''
| wall} then exits.  

\item [doreboot]
   \index{doreboot }
   This event is depreciated and should not be used.  

Default - does a reboot of the system by calling {\tt shutdown -h now}  

\item [doshutdown]
   \index{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 {\tt shutdown -h now}  

\item [emergency]
   \index{emergency }
   Does an emergency shutdown of the system by calling {\tt shutdown -h now}  

\item [failing]
   \index{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 {\tt printf ``UPS battery power exhausted. Doing
shutdown.\textbackslash{}n'' | wall} then exits.  

\item [loadlimit]
   \index{loadlimit }
   This event is generated when the battery charge is below the low limit
specified in the apcupsd.conf file.  

Default {---} does a {\tt printf ``UPS battery discharge limit reached. Doing
shutdown.\textbackslash{}n'' | wall} then exits.  After completing this event,
apcupsd will immediately initiate a {\tt doshutdown} event.  

\item [mainsback]
   \index{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 {\tt shutdown -c} (not
sure about that!!!!)  

\item [onbattery]
   \index{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 {\tt printf ``Power failure. Running on UPS batteries.''
| wall} then exits.  

\item [offbattery]
   \index{offbattery }
   This event is generated when the mains return only if the onbattery event has
been generated.  

Default {---} does nothing.  

\item [powerout]
   \index{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 {\tt printf ``Warning power loss detected.'' | wall} then
exits.  

\item [remotedown]
   \index{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.  

Does a {\tt shutdown -h now}  

\item [restartme]
   \index{restartme }
   This event is depreciated and should not be used.  

Terminates the currently running apcupsd and then restarts it.  

\item [runlimit]
   \index{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 {\tt printf ``UPS battery runtime percent reached. Doing
shutdown.\textbackslash{}n'' | wall} then exits.  After completing this event,
apcupsd will immediately initiate a {\tt doshutdown} event.  

\item [timeout]
   \index{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 {\tt printf ``UPS battery runtime limit exceeded. Doing
shutdown.\textbackslash{}n'' | wall} then exits. After completing this event,
apcupsd will immediately initiate a {\tt doshutdown} event.  

\item [startselftest]
   \index{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]
   \index{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 [battdetach]
   \index{battdetach}
   This event is generated when apcupsd detects that the UPS battery has been
disconnected.

\item [battattach]
   \index{battattach}
   This event is generated when apcupsd detects that the UPS battery has been
reconnected after a battdetach event.  
\end{description}

To write your own routine for the {\bf powerout} action, you create shell
script named {\bf powerout} and put it in the lib directory (normally
/etc/apcupsd).  When the {\bf 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 {\bf 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 /etc/apcupsd after an install or in the
platforms/etc directory of the source code.


\label{Controlling-Multiple-UPSes-on-one-Machine}

\section*{Controlling Multiple UPSes on one Machine}
\index{Controlling Multiple UPSes on one Machine }
\index{Machine!Controlling Multiple UPSes on one }
\addcontentsline{toc}{section}{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 
\ilink{Configuration types.}{Configuration-types_005f}). 

\label{Configuration}

\subsection*{Configuration}
\index{Configuration }
\addcontentsline{toc}{subsection}{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. 

\label{The-First-Copy-of-apcupsd}

\subsubsection*{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: 

\footnotesize
\begin{verbatim}
     ./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 \
       --with-nis-port=3551 \
       --enable-powerflute
\end{verbatim}
\normalsize

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. 

\label{The-Second-Copy-of-apcupsd}

\subsubsection*{The Second Copy of apcupsd:}

\label{index-Two-apcupsds-161}
To configure and install the second copy of apcupsd, which controls the second
UPS and Computer B, you could use the following configuration: 

\footnotesize
\begin{verbatim}
     ./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 \
       --with-nis-port=7001 \
       --disable-install-distdir
\end{verbatim}
\normalsize

Note, in this case, we use considerably more configuration options to ensure
that the system files are placed in a different directory
(\$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
{\tt \verb{--{disable-install-distdir} option, which prevents {\tt make install} from
doing the final system installation (i.e. the modification of the halt script)
since this was previously done. 

\label{Important-Steps-after-Installation-of-the-Second-Copy}

\subsubsection*{Important Steps after Installation of the Second Copy:}

After the {\tt make install} of the second copy of apcupsd there are a number
important steps to complete. You must either remove or modify the 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
examples/safe.apccontrol into \$HOME/apcupsd/bin/apccontrol. Alternatively,
you could edit the \$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 \$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. 

\label{Support-for-SNMP-UPSes}

\section*{Support for SNMP UPSes}
\index{Support for SNMP UPSes }
\index{UPSes!Support for SNMP }
\addcontentsline{toc}{section}{Support for SNMP UPSes}

\label{index-SNMP-162}
To run apcupsd with a SNMP UPS, you need the following things:  

\begin{itemize}
\item An SNMP UPS, for example a Web/SNMP (AP9716) or PowerNet SNMP (AP9605)
card installed into the SmartSlot.  
\item apcupsd version 3.10.0 or higher  
\item 
   \elink{Net-SNMP}{http://www.net-snmp.org/} library (previously known as
   ucd-snmp) installed 
\end{itemize}

\label{Planning-SNMP-Setup-Wiring}

\subsection*{Planning and Setup for SNMP Wiring}
\index{SNMP Wiring Setup}
\addcontentsline{toc}{subsection}{Planning and Setup for SNMP Wiring}

\label{index-SNMP_002d-Wiring-163}
SNMP packet requests are relayed to the UPS from monitoring APCUPSD servers over
Ethernet via a switch, hub, or router.  Protecting these Ethernet devices
with UPS supplied power is necessary to ensure reliable SNMP communication
during power failures.   Servers may fail to shutdown quietly during power failures
if SNMP communication is lost.

\label{Planning-SNMP-Setup-Configuration}

\subsection*{Planning and Setup for SNMP Configuration}
\index{SNMP Configuration Setup}
\addcontentsline{toc}{subsection}{Planning and Setup for SNMP Configuration}
To establish communication to the UPS SNMP card installed in the UPS, the
SNMP card will need the following:
\begin{itemize}
\item Assign SNMP card IP Address
\item Set SNMP card General Parameters
\item Set SNMP card Shutdown Parameters
\item Set SNMP card Event Trap Receivers (apcupsd-3.12.0 and later)
\end{itemize}

\subsubsection*{Assign SNMP Card IP Address}
\index{SNMP Configure IP Address}
\footnotesize
\begin{verbatim}
  	The following instructions come from the APC knowledge base:   
\end{verbatim}

\normalsize
The Network Management Card (AP9617, AP9618, AP9619) must be configured with
network settings before it can communicate on the network. Once the cards have been
configured with an IP address, Subnet Mask, and Default Gateway the cards can be
access, managed, and controlled from other computers on the network.

There are two ways to configure the Network Management Card (NMC) with its
initial settings: the (windows) Wizard and Address Resolution Protocol (ARP).

1.  The wizard in included on the CD that comes with the card.  The wizard must
run on a Windows operating system.  You can configure the card using the wizard over
the network via FTP.  If using the wizard please note, the un-configured NMC must
be on the same subnet as the computer running the wizard.

2.  Address resolution protocol (arp) can also be used to configure the NMC.  The MAC
Address of the NMC is needed for this method of configuration.  The MAC address is
located on the quality assurance slip that is shipped with the NMC, and is also
located on the white sticker on the NMC itself.  From a computer on the same
subnet as the un-configured NMC, follow the instructions:

Open up a command prompt and type the following (replacing <IPaddress> and <MacAddress>
with the actual values):

arp -s <IPaddress> <MacAddress>

Next, use Ping with a size of 113 bytes to assign the IP address defined by the ARP
command.

\begin{itemize}
\item Linux command format:   {\bf ping} <IPaddress> -s 113
\item Windows command format: {\bf ping} <IPaddress> -l 113
\end{itemize}


\subsubsection*{Set SNMP card General Parameters}
\index{SNMP Configure General Parameters}
After the SNMP Network Management Card is configured with an IP address, the SNMP Card
is ready for general configuration.  This is accomplished by telneting to the SNMP Card.

\footnotesize
\begin{verbatim}
     ~$ telnet <IPaddress>
\end{verbatim}
\normalsize

Login using "apc" for both the username and password and the following menu will display:





\footnotesize
\begin{verbatim}
*******************************************************************************
American Power Conversion               Network Management Card AOS      v2.6.4
(c) Copyright 2004 All Rights Reserved  Smart-UPS & Matrix-UPS APP       v2.6.1
-------------------------------------------------------------------------------
Name      : 	 	                              Date : 07/03/2006	       
Contact   :     		                      Time : 04:43:33
Location  : 			                      User : Administrator
Up Time   : 0 Days 01 Hours 57 Minutes                Stat : P+ N+ A+

Smart-UPS 1000 named  : On Line, No Alarms Present

------- Control Console -------------------------------------------------------

     1- Device Manager
     2- Network
     3- System
     4- Logout

     <ESC>- Main Menu, <ENTER>- Refresh, <CTRL-L>- Event Log
>
*******************************************************************************
\end{verbatim}







\normalsize
Select {\bf Option 2} for Network.
Next select {\bf Option 1} for TCP/IP settings.

At this point the following settings will be to be specified:

\begin{itemize}
\item Verify System IP: <IPaddress>
\item Specify Subnet Mask:  i.e. "225.225.225.0"
\item Specify Default Gateway
\item Specify Host Name
\item Specify Domain Name
\end{itemize}

Specifying these parameters will complete the General Parameters setup.  
Additionally the SNMP Network Management Card can now be connected to from 
a web browser for monitoring and additional configuration.


\subsubsection*{Set SNMP card Shutdown Parameters}
\index{SNMP Configure Shutdown Parameters}

There are two shutdown parameters that must be set in the SNMP card to ensure that
connected servers shutdown quietly.  These parameters can be set via the telnet terminal
or the web browser interface.

\begin{itemize}
\item Shutdown Delay (sec)
\item Return Battery Capacity (\%)
\end{itemize}

One of the draw-backs of SNMP communication to the UPS is that the Stand-alone or Primary
server must issue the power down command to the UPS early in server halt procedure.
This server must issue an early command to the SNMP UPS to power down before its ethernet
service is halted.  This creates a potential problem where the UPS may kill power to any
connected servers before these affected servers' halt scripts complete a successful shutdown.


The SNMP {\bf Shutdown Delay} parameter is used to delay the UPS from killing power to its load
by a prescribed period of seconds.  The delay should be long enough to ensure that the 
Stand-alone or Primary server has enough time to successfully halt.  The prescribed time should at least
be 180 seconds. Any additional computers connected to the SNMP UPS must not be configured
to issue the command to initiate UPS power down.  These servers can be thought of as secondary
stand-alone server.  The APCUPSD daemons of secondary servers should be configured to initiate server
halt a prescribed period of time before the Primary server issues the UPS power down command.


The {\bf Return on Battery Capacity} is useful during intermittent sequential power failures.
This parameter insures that the UPS will not restore power to its loads until it has
recharged it battery to a prescribed percentage. This parameter should be set to a value
greater than value that the APCUPSD daemons configured "BATTERYLEVEL" shutdown of any
connected servers.  This will ensure that when the UPS restores power, any additional power
failures will successfully re-trigger a server shutdown.



\subsubsection*{Configure Event Trap Receivers (apcupsd-3.12.0 and later)}
\index{SNMP Configure Event Trap Recievers}

By default, APCUPSD will poll the SNMP UPS card once per minute.  In this case,
server notification of UPS alarms could potentially be delayed one minute.  Event trap
catching mitigates this shortcoming.  Any UPS alarms are instantly sent to 
prescribe servers connected SNMP UPS.  These servers are referred to as Event Trap Receivers.
The SNMP UPS card can be configure to send event traps to a maximum of four 
receivers that will "catch" these events.  

Event trap receivers IP address can be set using a telnet terminal or web browser interface.

Also, be aware that servers configured to be Event Trap Receivers should have static IP set.
Severs obtaining IPs from DHCP server will not catch instantaneous Events if the IP address changes from
the address set in the SNMP UPS.

\label{Connecting-APCUPSD-to-a-SNMP-UPS}

\subsection*{Connecting APCUPSD to a SNMP UPS}
\index{Connecting APCUPSD to a SNMP UPS }
\index{UPS!Connecting APCUPSD to a SNMP }
\addcontentsline{toc}{subsection}{Connecting APCUPSD to a SNMP UPS}

\label{index-SNMP_002c-Connecting-163}

The previous sections describe configuration of the actual SNMP card.
The remaining sections describe configuration of the APCUPSD to communicate
using SNMP Protocol.


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: 

\footnotesize
\begin{verbatim}
     DEVICE 192.168.100.2:161:APC:private
\end{verbatim}
\normalsize

Where the directive is made by four parts:  

\begin{itemize}
\item {\bf host}: IP address of the remote UPS  
\item {\bf port}: Remote SNMP port, normally 161
\item {\bf vendor}: Kind of remote SNMP agent: ``APC'' for APC's PowerNet MIB, 
``APC\_NOTRAP'' for the PowerNet MIB with SNMP trap catching disabled, or "RFC"
for the IETF's rfc1628 UPS-MIB. (Note that APC\_NOTRAP is only accepted by 
apcupsd-3.12.0 and higher. See below for trap catching details.)
\item {\bf community}: The read-write community string, usually ``private''
\end{itemize}


If more than one server is connected to the UPS the following configuration
types still apply to SNMP enable UPS. (see \ilink{Choosing a Configuration Type}
{Choosing-a-Configuration-Type}).  A NIS Server/Client (Master/Slave) configuration
with multiple servers is still applicable.
 
However, an alternative configuration is possible with an SNMP enabled UPS.  In
this arrangement, all connected servers will be configured as a standalone server.
Each will independently communicate to the UPS.  One (primary) server will be 
chosen to manage the task of commanding the UPS to power down. All remaining
(secondary) servers will be configured to quietly power down before the
primary server issues the UPS power down command. 

\subsection*{Building with SNMP support}
\index{Building with SNMP support}
\index{SNMP!Building with support for}
\addcontentsline{toc}{subsection}{Building with SNMP support}

Follow the instructions in 
\ilink{Building and Installing apcupsd}{Building-and-Installing-apcupsd},
being sure to include the following options (in addition to any others you need) on the
{\bf ./configure} line: 

\footnotesize
\begin{verbatim}
     ./configure \
     --with-serial-dev=<your-SNMP-device> \
     --with-upstype=snmp \
     --with-upscable=smart \
     --enable-snmp
\end{verbatim}
\normalsize

\label{SNMP-Trap-Catching}
\subsection*{SNMP Trap Catching}
\index{Traps!SNMP}
\index{SNMP Trap Catching}
\addcontentsline{toc}{subsection}{SNMP Trap Catching}

apcupsd-3.11.14 introduces support for SNMP trap catching with the APC
PowerNet MIB driver. Previous versions polled the UPS status once per minute, 
leading to significant delays before UPS state changes were recognized. With 
SNMP trap handling, apcupsd monitors the SNMP trap port and will re-poll the
UPS whenever a trap is received. This happens, for example, when the UPS 
switches on or off battery.

In order for this feature to work, you must configure your UPS to
deliver traps to the server running apcupsd. This is generally done by 
connecting to your SNMP card via a web browser or telnet connection. You
will need to enter your server's IP address as a trap receiver and make sure
trap delivery is enabled.

Trap catching can lead to problems if you are already running another SNMP
trap daemon on your server. Only one daemon can listen to the trap port, so
whichever one is started first will succeed and the others will fail. Apcupsd
will fall back to polling behavior if it is unable to open the trap port. You
can also forcibly disable trap catching by setting your vendor string in the
{\bf apcupsd.conf} {\bf DEVICE} directive to "APC\_NOTRAP".

\label{Known-Problems}

\subsection*{Known Problems}
\index{Known Problems }
\index{Problems!Known }
\addcontentsline{toc}{subsection}{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
/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:  

\begin{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 {\bf Option 1 (non-windows)} Edit the server halt script.  Relocate the 
ups\_kill\_power() function higher in the shutdown sequence, primarily before
the command to bring down the ethernet service. This is the preferred method
for shutting down the UPS.  The UPS will power down after the prescribed
"Shut Down Delay" time (in seconds) has elapsed.
\item {\bf Option 2} Change /etc/rc.d/apcupsd script adding the '{---}kill-on-powerfail'
to the apcupsd invocation.  This method is not preferred because the UPS is
commanded to power down without delay.  This creates the potential for UPS
powering down before the server calling for UPS power down completes its shutdown.
However, in the case of Microsoft Windows OS, this is the only method available
for powering down the UPS.
\item Restart your apcupsd 
   \end{itemize}

With this setup your UPS operations should be safe. 


\label{Running-The-Network-Information-Server}

\section*{Running The Network Information Server}
\index{Server!Running The Network Information }
\index{Running The Network Information Server }
\addcontentsline{toc}{section}{Running The Network Information Server}

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.  

As of apcupsd 3.12.x, the NIS server runs only as a child of apcupsd.
It cannot be run standalone or from INETD.

This is probably the simplest way to run the network information server. To do
so, you simply make sure the {\bf NETSERVER} directive in
/etc/apcupsd/apcupsd.conf is {\bf on}, and then stop and restart apcupsd. It
will automatically create the server thread to handle network clients. 
Note, the above modification should not be necessary if you use the default
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 /etc/hosts.allow. 

\label{apcupsd-System-Logging}

\section*{apcupsd System Logging}
\index{Logging!apcupsd System }
\index{Apcupsd System Logging }
\addcontentsline{toc}{section}{apcupsd System Logging}

\label{index-Logging_002c-System-166}
\label{index-System-Logging-167}
The apcupsd philosophy is that all logging should be done through the {\bf
syslog} facility (see: {\tt man syslog}). This is now implemented with the
exceptions that {\bf STATUS} logging, for compatibility, with prior versions
is still done to a file, and {\bf EVENTS} logging can be directed to a
``temporary'' file so that it can be reported by the network information
server. 

\label{Logging-Types}

\subsection*{Logging Types}
\index{Types!Logging }
\index{Logging Types }
\addcontentsline{toc}{subsection}{Logging Types}

\label{index-Logging_002c-types-168}
apcupsd splits its logging into four separate types called:  

\begin{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. 

\small{DATA Logging}
\index{Logging!DATA }
\index{DATA Logging }
\addcontentsline{toc}{subsubsection}{DATA Logging}

Data logging consists of periodically logging important data concerning the
operation of the UPS. See the Data Logging (see 
\ilink{DATA Logging}{DATA-Logging}) section of this manual for more
details. 

\small{STATUS Logging}
\index{STATUS Logging }
\index{Logging!STATUS }
\addcontentsline{toc}{subsubsection}{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 (see 
\ilink{apcupsd Status Logging}{apcupsd-Status-Logging}) section of
the Technical Reference. 

\small{EVENTS Logging}
\index{Logging!EVENTS }
\index{EVENTS Logging }
\addcontentsline{toc}{subsubsection}{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 (see 
\ilink{Customizing Event Handling}{Customizing-Event-Handling}) for
more details. 

\label{Implementation-Details}

\subsection*{Implementation Details}
\index{Details!Implementation }
\index{Implementation Details }
\addcontentsline{toc}{subsection}{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:  

\begin{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
/var/log/apcupsd.data, all EVENTS to the standard /var/log/messages file (to
be mixed with other system messages), and at the same time send all EVENTS to
/var/log/apcupsd.events, and finally, you want to send all STATUS logging to
the named pipe /var/log/apcupsd.status  

First as root, you create the named pipe: 

\footnotesize
\begin{verbatim}
     mkfifo /var/log/apcupsd.status
\end{verbatim}
\normalsize

Change its permissions as necessary or use the -m option to set them when
creating the pipe.  

Then you modify your /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: 

\footnotesize
\begin{verbatim}
     # 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{verbatim}
\normalsize

\label{Developers-Notes}

\subsection*{Developers Notes}
\index{Developers Notes }
\index{Notes!Developers }
\addcontentsline{toc}{subsection}{Developers Notes}

\label{index-Developers-Notes-169}
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. 


\section*{The Windows Version of apcupsd}
\label{The-Windows-Version-of-apcupsd}
\index{Windows Version of apcupsd}
\addcontentsline{toc}{section}{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
natively on Windows (no Cygwin or other emulation layer needed).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. 

\label{Installation}
\subsection*{Installation}
\index{Installation }
\addcontentsline{toc}{subsection}{Installation}

Normally, you will install the Windows version of apcupsd from the binaries.
Starting with version 3.11.15, the Windows binaries are distributed with
a full GUI installer (driven by NSIS, the 
\elink{Nullsoft Scriptable Install System}{http://nsis.sourceforge.net}).

Installation is very simple and straight-forward: Simply double-click the
installer executable and follow the instructions.

\label{Configuration}
\subsection*{Configuration}
\index{Configuration}
\addcontentsline{toc}{subsection}{Configuration}

If you are installing Apcupsd for the first time, the installer will give
you an opportunity to edit the apcupsd.conf configuration file to contain
the values appropriate for your site. (Subsequent installations will
maintain your existing apcupsd.conf, so you need not edit it again unless
there are new features or syntax changes that must be accounted for.)

The default configuration calls for a USB connected UPS. This is the most
common connection for modern UPSes, especially those used with Windows
computers. All other apcupsd drivers are available (apcsmart, dumb, net,
snmp, pcnet) and can be used simply by editing the configuration file
UPSCABLE, UPSTYPE, and DEVICE settings as described elsewhere in this 
manual.

Note that on Windows, serial ports are specified using COM1, COM2, etc.
notation instead of the UNIX-style /dev/tty* notation.

Note also if you are using WinNT or Win2000, the operating system may 
probe the serial 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 c:\textbackslash{}boot.ini
file. Find the line that looks something like the following:  

\begin{verbatim}
   multi(0)disk(0)rdisk(0)partition(1)\WINNT="Windows NT Workstation Version 4.00"
\end{verbatim}

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...

\begin{verbatim}
   multi(0)disk(0)rdisk(0)partition(1)\WINNT="Windows NT Workstation Version 4.00" /NoSerialMice:COM1  
\end{verbatim}

...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


\label{Starting Apcupsd}
\subsection*{Starting Apcupsd}
\index{Starting Apcupsd}
\addcontentsline{toc}{subsection}{Starting Apcupsd}

The installer will give you an opportunity start the Apcupsd service
immediately. If you choose to start it manually, you may do so by selecting
the "Start Apcuspd" link from the Start -\gt{}Programs -\gt{} Apcupsd folder.

On Windows NT/2000/XP, you may alternatively go to the Control Panel, open
the Services folder, select Apcupsd UPS Server, and then click on the
{\bf Start} button as shown below:

\footnotesize
\begin{verbatim}
     
\end{verbatim}
\normalsize

\addcontentsline{lof}{figure}{Windows NT - Start Service}
\includegraphics{./wininstall6.eps}  

\footnotesize
\begin{verbatim}
     
\end{verbatim}
\normalsize

If the Services dialog reports a problem, it is normally because your DEVICE
statement does not contain the correct serial port name. 

You probably should also click on the {\bf Startup...} button to ensure that
the correct defaults are set. The dialogue box that appears should have {\bf
Startup Type} set to {\bf Automatic} and {\bf Logon} should be set to {\bf
System Account} with {\bf 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 and Win2K systems, 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: {\bf Control Panel -\gt{} Administrative Tools
-\gt{} Component Services}. The apcupsd service should appear in the right
hand window when you click on {\bf Services (Local)} in the left hand menu
window.  

That should complete the installation process. When the system tray icon turns
from a question mark \includegraphics{./commlost.eps} into a plug
\includegraphics{./online.eps}, right click on it and a menu will appear.
Select the {\bf 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 {\bf Status} item, you can verify that all the values for
your UPS are correct.  

When the UPS switches to the battery, the battery icon 
\includegraphics{./onbatt.eps} will appear 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 
\includegraphics{./charging.eps} to indicate that the battery is charging. 

\label{Testing}

\subsection*{Testing}
\index{Testing }
\addcontentsline{toc}{subsection}{Testing}

\label{index-Windows_002c-Testing-173}
\label{index-Testing_002c-Windows-174}
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 
\ilink{Testing Apcupsd}{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
c:\textbackslash{}apcupsd\textbackslash{}etc\textbackslash{}apcupsd\textbackslash
{}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. 

\label{Upgrading}
\subsection*{Upgrading}
\index{Upgrading }
\addcontentsline{toc}{subsection}{Upgrading}

An upgrade may be accomplished by uninstalling the old version (using
the Add/Remove Programs Control Panel or clicking the "Uninstall Apcupsd" 
link from Start -\gt{} Programs -\gt{} Apcupsd. Near the end of the
uninstall you will be prompted about removing configuration and event
files. You should answer "No" in order to preserve your existing
apcupsd.conf file.

After the uninstall completes you may install the new version of
Apcupsd as described above. If you preserved your existing apcupsd.conf
file, the new apcupsd.conf will be installed as apcupsd.conf.new.

\label{Post-Installation}
\subsection*{Post Installation}
\index{Post Installation }
\index{Installation!Post }
\addcontentsline{toc}{subsection}{Post Installation}

\label{index-Windows_002c-Post-Installation-177}
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
c:\textbackslash{}apcupsd\textbackslash{}etc\textbackslash{}apcupsd\textbackslash
{}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
c:\textbackslash{}apcupsd\textbackslash{}etc\textbackslash{}apcupsd\textbackslash
{}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. 

\label{Problem-Areas}

\subsection*{Problem Areas}
\index{Areas!Problem }
\index{Problem Areas }
\addcontentsline{toc}{subsection}{Problem Areas}

\label{index-Problems_002c-Windows-178}
\label{index-Windows_002c-Problems-179}
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 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).

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
c:\textbackslash{}apcupsd\textbackslash{}etc\textbackslash{}apcupsd\textbackslash
{}apcupsd.events. This type error messages such as configuration file not
found, etc are written to this file. Note that on some systems (WinXP, possibly
others) Apcupsd is unable to write to this file when running as a service.


\label{Disclaimer}

\subsection*{Disclaimer}
\index{Disclaimer }
\addcontentsline{toc}{subsection}{Disclaimer}

\label{index-Disclaimer-180}
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:  

\begin{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 {\tt \verb{--{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 
\ilink{Shutdown Sequence}{Shutdown-Sequence-_003c1_003e} 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
c:\textbackslash{}apcupsd\textbackslash{}etc\textbackslash{}apcupsd\textbackslash
{}apccontrol under the {\bf doshutdown} case.  

An alternative to the {\tt \verb{--{kill-on-powerfail} option is to use the KILLDELAY
(see 
\ilink{KILLDELAY \lt{}time in
seconds\gt{}}{KILLDELAY-_003ctime-in-seconds_003e}) 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
   c:\textbackslash{}apcupsd\textbackslash{}etc\textbackslash{}apcupsd\textbackslash
   {}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 {\bf popup} from this file. 
\end{itemize}

\label{Email-Notification-of-Events}

\subsection*{Email Notification of Events}
\index{Email Notification of Events }
\index{Events!Email Notification of }
\addcontentsline{toc}{subsection}{Email Notification of Events}

\label{index-Email-181}
\label{index-Notification_002c-Email-182}
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
{\bf changeme, commfailure, commok, onbattery, and mainsback} in the directory
c:\textbackslash{}apcupsd\textbackslash{}examples. To use them, you must
modify the SYSADMIN variable to have a valid email address, then copy the
files into the directory
c:\textbackslash{}apcupsd\textbackslash{}etc\textbackslash{}apcupsd. 

\label{Killpower-under-Windows}

\subsection*{Killpower under Windows}
\index{Windows!Killpower under }
\index{Killpower under Windows }
\addcontentsline{toc}{subsection}{Killpower under Windows}

\label{index-Windows_002c-Killpower-183}
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 {\tt -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: 

\footnotesize
\begin{verbatim}
     c:\apcupsd\apcupsd.exe /service
\end{verbatim}
\normalsize

found under the key: 

\footnotesize
\begin{verbatim}
     HKEY_LOCAL_MACHINE Software\Microsoft\Windows\CurrentVersion\RunServices
\end{verbatim}
\normalsize

to 

\footnotesize
\begin{verbatim}
     c:\apcupsd\apcupsd.exe /service -p
\end{verbatim}
\normalsize

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. 

\label{Power-Down-During-Shutdown}

\subsection*{Power Down During Shutdown}
\index{Shutdown!Power Down During }
\index{Power Down During Shutdown }
\addcontentsline{toc}{subsection}{Power Down During Shutdown}

\label{index-Windows_002c-Power-down-184}
\label{index-Power-down_002c-Windows-185}
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: 
\elink{http://www.sysinternals.com/ntw2k/freeware/pstools.shtml}{http://www.sy%
sinternals.com/ntw2k/freeware/pstools.shtml}. to use their shutdown program
rather than the apcupsd supplied version, you simply edit: 

\footnotesize
\begin{verbatim}
     c:\apcupsd\etc\apcupsd\apccontrol
\end{verbatim}
\normalsize

with any text editor and change our calls to shutdown to psshutdown. 

\label{Command-Line-Options-Specific-to-the-Windows-Version}

\subsection*{Command Line Options Specific to the Windows Version}
\index{Command Line Options Specific to the Windows Version }
\index{Version!Command Line Options Specific to the Windows }
\addcontentsline{toc}{subsection}{Command Line Options Specific to the
Windows Version}

\label{index-Windows_002c-Options-186}
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:  

\begin{description}

\item [/servicehelper]
   \index{/servicehelper }
   Run the service helper application  

\item [/service]
   \index{/service }
   Start apcupsdas a service  

\item [/run]
   \index{/run }
   Run the apcupsd application  

\item [/install]
   \index{/install }
   Install apcupsd as a service in the system registry  

\item [/remove]
   \index{/remove }
   Uninstall apcupsd from the system registry  

\item [/about]
   \index{/about }
   Show the apcupsd about dialogue box  

\item [/status]
   \index{/status }
   Show the apcupsd status dialogue box  

\item [/events]
   \index{/events }
   Show the apcupsd events dialogue box  

\item [/kill]
   \index{/kill }
   Stop any running apcupsd  

\item [/help]
   \index{/help }
   Show the apcupsd help dialogue box 
\end{description}

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. 

\label{Building-the-Win32-Version-from-the-Source}

\subsection*{Building the Win32 Version from the Source}
\index{Building the Win32 Version from the Source }
\index{Source!Building the Win32 Version from the }
\addcontentsline{toc}{subsection}{Building the Win32 Version from the
Source}

\label{index-Windows_002c-Building-187}
\label{index-Building_002c-Windows-188}
If you have the source code, follow the standard procedures for building
apcupsd on Unix in 
\ilink{Building and Installing
apcupsd}{Building-and-Installing-apcupsd} of this manual. Please
don't forget to look at the system specifics for CYGWIN. 

\label{Installation-on-Serial_002dLine-UPSes}

\section*{Installation: Serial-Line UPSes}
\index{Installation: Serial-Line UPSes }
\index{UPSes!Installation: Serial-Line }
\addcontentsline{toc}{section}{Installation: Serial-Line UPSes}

\label{Overview-of-Serial_002dInterface-UPSes}

\section*{Overview of Serial-Interface UPSes}
\index{UPSes!Overview of Serial-Interface }
\index{Overview of Serial-Interface UPSes }
\addcontentsline{toc}{section}{Overview of Serial-Interface UPSes}

\label{index-Serial-UPSes-189}
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 (see 
\ilink{upstypes}{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 (see 
\ilink{crazy}{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. 

\label{Connecting-a-Serial_002dLine-UPS-to-a-USB-Port}

\section*{Connecting a Serial-Line UPS to a USB Port}
\index{Port!Connecting a Serial-Line UPS to a USB }
\index{Connecting a Serial-Line UPS to a USB Port }
\addcontentsline{toc}{section}{Connecting a Serial-Line UPS to a USB Port}

\label{index-Serial-on-USB-190}
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 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 /etc/apcupsd/apcupsd.conf configuration line to be: 

\footnotesize
\begin{verbatim}
     DEVICE /dev/ttyUSB0
\end{verbatim}
\normalsize

Depending on whether or not you have {\bf hotplug} working, you may need to
explicitly load the kernel modules {\bf usbserial} and {\bf pl2303}. In Kern's
case, this was not necessary. 

\label{Connecting-a-APC-USB-UPS-to-either-a-PC-USB-or-Serial-Port}

\section*{Connecting a APC USB UPS to either a PC USB or Serial Port}
\index{Port!Connecting a APC USB UPS to either a PC USB or Serial }
\index{Connecting a APC USB UPS to either a PC USB or Serial Port }
\addcontentsline{toc}{section}{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. 

\input{cables}

\label{Testing-Serial_002dLine-UPSes}
\section*{Testing Serial-Line UPSes}
\index{Testing Serial-Line UPSes }
\index{UPSes!Testing Serial-Line }
\addcontentsline{toc}{section}{Testing Serial-Line UPSes}

\label{index-Testing_002c-Serial-219}
\label{index-Serial_002c-Testing-220}
If you have a serial-line UPS, there are some tests you should run before the
general ones described in the Testing (see 
\ilink{Testing Apcupsd}{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 {\it 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 
\ilink{Voltage Signalling Features Supported by Apcupsd for Various
Cables}
{Voltage-Signalling-Features-Supported-by-Apcupsd-for-Various-Cable%
s}. 

\label{Establishing-Serial-Port-Connection}

\subsection*{Establishing Serial Port Connection}
\index{Establishing Serial Port Connection }
\index{Connection!Establishing Serial Port }
\addcontentsline{toc}{subsection}{Establishing Serial Port Connection}

\label{index-Testing_002c-Serial-221}
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: 

\footnotesize
\begin{verbatim}
     apcupsd FATAL ERROR in apcserial.c at line 156
     PANIC! Cannot communicate with UPS via serial port.
\end{verbatim}
\normalsize

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:  

\begin{itemize}
\item You have not configured the correct serial port name on the DEVICE
   directive in your 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 /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 {\bf 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 /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 
\ilink{After Installation}{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 c:\textbackslash{}boot.ini file, and you will find
a line that looks something like the following:  

\footnotesize
\begin{verbatim}
          multi(0)disk(0)rdisk(0)partition(1)\WINNT="Windows NT Workstation Version 4.00"
     
\end{verbatim}
\normalsize

Add the following to the end of the line: /NoSerialMice:COM1 (or COM2) so that
the new line looks like:  

\footnotesize
\begin{verbatim}
          multi(0)disk(0)rdisk(0)partition(1)\WINNT="Windows NT Workstation Version 4.00" /NoSerialMice:COM1
     
\end{verbatim}
\normalsize

\item If you are using a WinNT or Win2000 machine, try connecting apcupsd to
   COM2 rather than COM1 (be sure to change your
   c:\textbackslash{}apcupsd\textbackslash{}etc\textbackslash{}apcupsd\textbackslash
{}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 {\tt lsof /dev/ttyS0} where you replace the {\bf
   /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 {\tt 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 /proc file system. For example:
   {\tt cat /proc/devices} should print something like {\it 4 ttyS} if you have a
   serial port. If your serial port is working, a {\tt cat /proc/interrupts}
should show the serial port usage (e.g. {\bf 4: 294553 XT-PIC serial}) Also,
{\tt cat /proc/ioports} should show up something like {\bf 03f8-03ff :
serial(auto)}. Or, {\tt cat /proc/tty} should print a line like {\bf serial
/dev/ttyS 4 64-127 serial}. Finally, a {\tt cat /proc/tty/driver/serial}
should print something like the following:  

\footnotesize
\begin{verbatim}
          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{verbatim}
\normalsize

\end{itemize}

The first thing to do is to look at your log file, usually /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 (see 
\ilink{type\_table}{type_005ftable}) 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. 

\label{Using-apctest-on-Serial_002dLine-UPSses}

\subsection*{Using apctest on Serial-Line UPSses}
\index{UPSses!Using apctest on Serial-Line }
\index{Using apctest on Serial-Line UPSses }
\addcontentsline{toc}{subsection}{Using apctest on Serial-Line UPSses}

\label{index-apctest-222}
\label{index-Testing_002c-with-apctest-223}
On an apcsmart serial-line UPS, apctest will give you access to the battery of
low-level tests we described in 
\ilink{apctest}{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 /etc/apcupsd/apcupsd.conf
file has {\bf UPSTYPE backups} and {\bf UPSCABLE simple} Normally apctest will
have been built and installed by default, otherwise, you can explicitly build
it on Unix with: 

\footnotesize
\begin{verbatim}
     cd <apcupsd-source-directory>
     make apctest
     ./apctest
\end{verbatim}
\normalsize

on Win32 systems, use: 

\footnotesize
\begin{verbatim}
     make apctestwin32
     ./apctest
\end{verbatim}
\normalsize

It will present you with the following output 

\footnotesize
\begin{verbatim}
     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{verbatim}
\normalsize

Then it will present you with the following list of choices: 

\footnotesize
\begin{verbatim}
     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{verbatim}
\normalsize

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 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 apcupsd.conf file. 

\label{Expected-apctest-Signals-for-a-UPS}

\subsubsection*{Expected apctest Signals for a UPS:}

\label{index-Testing-224}
\label{index-apctest-225}
If you have configured your UPS as: 

\footnotesize
\begin{verbatim}
     UPSTYPE backups
     UPSCABLE APC_940_0119A
         or APC_940_0127A
         or APC_940_0128A
         or APC_940_0020B
         or APC_940_0020C
\end{verbatim}
\normalsize

here are typical signals you would expect to see in the output from the
various tests of apctest: 

\footnotesize
\begin{verbatim}
     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{verbatim}
\normalsize

Note: {\bf 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 {\bf CTS} when
the power fails and additionally {\bf CD} when the batteries are low. 

\label{Expected-apctest-Signals-for-a-BackUPS-Pro}

\subsubsection*{Expected apctest Signals for a BackUPS Pro:}

\label{index-Testing-226}
\label{index-apctest-227}
If you have configured your UPS as: 

\footnotesize
\begin{verbatim}
     UPSTYPE backupspro
     UPSCABLE APC_940_0095A
         or APC_940_0095C
\end{verbatim}
\normalsize

here are the typical signals you would expect to see in the output from the
various tests of apctest: 

\footnotesize
\begin{verbatim}
     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{verbatim}
\normalsize

Note: {\bf RTS} should never be set in any of the tests as it is the killpower
signal. What is important is the appearance of {\bf RNG} when the power fails
and additionally {\bf CD} when the batteries are low. 

\label{Troubleshooting-Serial-Line-communications}

\section*{Troubleshooting Serial Line communications}
\index{Communications!Troubleshooting Serial Line }
\index{Troubleshooting Serial Line communications }
\addcontentsline{toc}{section}{Troubleshooting Serial Line communications}

\label{index-Problems_002c-Serial-228}
\label{index-Serial-Problems-229}

\label{Determining-Which-Voltage_002dSignaling-Cable-You-Have}

\subsection*{Determining Which Voltage-Signaling Cable You Have}
\index{Determining Which Voltage-Signaling Cable You Have }
\index{Have!Determining Which Voltage-Signaling Cable You }
\addcontentsline{toc}{subsection}{Determining Which Voltage-Signaling Cable
You Have}

{\it 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 {\it not} use {\bf simple} in the cable
specification (i.e. {\bf UPSCABLE simple}) unless you have made the cable
yourself according to the wiring diagram given in the cables chapter of this
manual. 

\label{Once-you-have-established-serial-communications}

\subsection*{Once you have established serial communications}
\index{Once you have established serial communications }
\index{Communications!Once you have established serial }
\addcontentsline{toc}{subsection}{Once you have established serial
communications}

\label{index-Testing-230}
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 (see 
\ilink{Testing Apcupsd}{Testing-Apcupsd}) section.  

One additional note applies: 

\label{Bizarre-Intermittent-Behavior}

\subsubsection*{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. 

\label{Recalibrating-the-UPS-Runtime}

\section*{Recalibrating the UPS Runtime}
\index{Runtime!Recalibrating the UPS }
\index{Recalibrating the UPS Runtime }
\addcontentsline{toc}{section}{Recalibrating the UPS Runtime}

\label{index-Runtime-recalibration-231}
\label{index-Recalibration-Runtime-232}
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,  

\begin{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 {\tt 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. 

\label{Status-Logging-On-Serial_002dLine-UPSes}

\subsection*{Status Logging On Serial-Line UPSes}
\index{UPSes!Status Logging On Serial-Line }
\index{Status Logging On Serial-Line UPSes }
\addcontentsline{toc}{subsection}{Status Logging On Serial-Line UPSes}

Serial-line UPSes that speak the apcsmart protocol log all of the events
described in the Status Format (see 
\ilink{apcupsd Status Logging}{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: 

\footnotesize
\begin{verbatim}
     LINEFAIL : OnlineStatus
     BATTSTAT : BatteryStatus
     MAINS    : LineVoltageState
     LASTEVNT : LastEventObserved
\end{verbatim}
\normalsize

BackUPS and NetUPS Simple Signals 

\footnotesize
\begin{verbatim}
     LINEFAIL : OnlineStatus
     BATTSTAT : BatteryStatus
\end{verbatim}
\normalsize

\label{DATA-Logging}

\section*{DATA Logging}
\index{Logging!DATA }
\index{DATA Logging }
\addcontentsline{toc}{section}{DATA Logging}

\label{index-Logging_002c-DATA-233}
\label{index-DATA-Logging-234}
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: 

\footnotesize
\begin{verbatim}
     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{verbatim}
\normalsize

\label{Technical-Reference}

\section*{Technical Reference}
\index{Reference!Technical }
\index{Technical Reference }
\addcontentsline{toc}{section}{Technical Reference}

\label{index-Technical-Reference-235}

\label{Configuration-Directive-Reference}

\section*{Configuration Directive Reference}
\index{Configuration Directive Reference }
\index{Reference!Configuration Directive }
\addcontentsline{toc}{section}{Configuration Directive Reference}

\label{index-Reference_002c-Directives-236}
\label{index-Configuration_002c-Directives-237}
\label{index-Directives-238}
Configuration directives in /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. 

\label{General-Configuration-Directives}

\subsection*{General Configuration Directives}
\index{General Configuration Directives }
\index{Directives!General Configuration }
\addcontentsline{toc}{subsection}{General Configuration Directives}

\label{index-Directives_002c-General-239}
\label{index-General-Directives-240}
In general, each of these directives is required (ecept that the DEVICE
directive is ignored for UPSCABLE ether).  

\begin{description}

\item [UPSTYPE \lt{}type of APC UPS you have\gt{}]
   \index{UPSTYPE \lt{}type of APC UPS you have\gt{} }
   The name of a driver.  Should be one of dumb, apcsmart, net, usb, snmp, or
test. This describes your interface type.  

The UPSTYPE directive can be defined during installation by using the {\tt
\verb{--{with-upstype=} option of the {\tt ./configure} program.  

\item [UPSCABLE \lt{}type of cable you are using\gt{}\gt{}]
   \index{UPSCABLE \lt{}type of cable you are using\gt{}\gt{} }

\footnotesize
\begin{verbatim}
                [ 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{verbatim}
\normalsize

The {\tt \verb{--{with-upscable=} option of {\tt ./configure} can be used to set a
default for this directive during the your build.  

\item [DEVICE \lt{}name of device\gt{}]
   \index{DEVICE \lt{}name of device\gt{} }
   Specify which device is used for UPS communications. For serial ports, it is
usually something like /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 {\tt ./configure} program will set an appropriate default value.
You may also specify the {\tt \verb{--{with-serial-dev=} option of the {\tt
./configure} program to set this directive at build time.  

If you have specified {\bf UPSTYPE net}, then the device name to be specified
consists of {\bf 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 {\bf UPSTYPE snmp}, then the device name becomes {\bf
hostname:vendor:community}. Please see the SNMP chapter (see 
\ilink{Support for SNMP UPSes}{Support-for-SNMP-UPSes}) in this
manual for more details.  

\item [LOCKFILE \lt{}path to lockfile\gt{}]
   \index{LOCKFILE \lt{}path to lockfile\gt{} }
   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 {\tt ./configure}
program.  You may also explicitly set it during the build process by using the
{\tt \verb{--{with-lock-dir=} option of the {\tt ./configure} program. 

\end{description}


\label{Configuration-Directives-Used-by-the-Network-Information-Server}

\subsection*{Configuration Directives Used by the Network Information
Server}
\index{Configuration Directives Used by the Network Information Server }
\index{Server!Configuration Directives Used by the Network Information }
\addcontentsline{toc}{subsection}{Configuration Directives Used by the
Network Information Server}

\label{index-Directives_002c-Network-241}
\label{index-Network-directives-242}
None of these directives are required for proper operation of apcupsd.

\begin{description}

\item [{NETSERVER [on | off]}]
   \index{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, {\it NETSERVER} should be {\it off}.  

\item [NISIP \lt{}IP-address\gt{}]
   \index{NISIP \lt{}IP-address\gt{} }
   This directive specifies the IP address of the network interface on which
the NIS server will listen for incoming connections. Default value is 0.0.0.0
which means the NIS will listen for connections on all network interfaces. If
your machine has more than one interface, you can specify the IP of a single
interface to limit connections to only that interface. Furthermore, you can
specify the loopback address (127.0.0.1) to accept connections only from the 
local machine. You may also use the {\tt \verb{--{with-nisip=} option of the
{\tt ./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 \lt{}port\gt{}]
   \index{NISPORT \lt{}port\gt{} }
   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 {\tt \verb{--{with-nis-port=} option of the {\tt ./configure} program
during the build. In this case, all the appropriate locations will be
automatically changed.  

\item [EVENTSFILE \lt{}filename\gt{}]
   \index{EVENTSFILE \lt{}filename\gt{} }
   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: /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 {\tt
\verb{--{with-log-dir=} option of the {\tt ./configure} program. 
\end{description}

\label{Configuration-Directives-used-during-Power-Failures}

\subsection*{Configuration Directives used during Power Failures}
\index{Configuration Directives used during Power Failures }
\index{Failures!Configuration Directives used during Power }
\addcontentsline{toc}{subsection}{Configuration Directives used during
Power Failures}

\label{index-Directives_002c-Power-fail-243}
\label{index-Power-fail-directives-244}
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 (see 
\ilink{Cables}{Cables}) section of this manual for more details.  

\begin{description}

\item [BATTERYLEVEL \lt{}percent of battery\gt{}]
   \index{BATTERYLEVEL \lt{}percent of battery\gt{} }
   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 {\bf
BATTERYLEVEL -1} in your apcupsd.conf file.  

\item [MINUTES \lt{}battery runtime in minutes\gt{}]
   \index{MINUTES \lt{}battery runtime in minutes\gt{} }
   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 {\bf TIMELEFT} value as
printed in the output of an {\tt 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 {\bf MINUTES -1} in your
apcupsd.conf file.  

\item [TIMEOUT \lt{}time in seconds\gt{}]
   \index{TIMEOUT \lt{}time in seconds\gt{} }
   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 (see

\ilink{Testing Apcupsd}{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.  

{\bf TIMEOUT}, {\bf BATTERYLEVEL}, and {\bf MINUTES} can be set together
without problems.  apcupsd will react to the first case or test that is valid.
Normally SmartUPS users will set {\bf TIMEOUT} to zero so that the system is
shutdown depending on the percentage battery charge remaining ({\bf
BATTERYLEVEL}) or the remaining battery runtime ({\bf MINUTES}).  

\item [ANNOY \lt{}time in seconds\gt{}]
   \index{ANNOY \lt{}time in seconds\gt{} }
   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 {\tt annoyme}
argument. The default is to send a wall message on Unix systems and a popup
message in Windows.  

The value of {\bf ANNOYDELAY} must be greater than the value of {\bf 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 {\bf NOLOGON} is set to {\bf disable} the annoy messages will
also be disabled.  

\item [ANNOYDELAY \lt{}time in seconds\gt{}]
   \index{ANNOYDELAY \lt{}time in seconds\gt{} }
   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 {\bf NOLOGON} is not set to {\bf
disable}.  

\item [NOLOGON \lt{}specifies when apcupsd should prevent user
   logins\gt{}]
   \index{NOLOGON \lt{}specifies when apcupsd should prevent user logins\gt{} }
[ disable | timeout | percent | minutes | always ] are valid types.  

The type specified allows you define the point when apcupsd will create the
'nologin' file and thus when user logins are prohibited. Once the
'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 'nologin' file is
created. The default is always disable if no NOLOGON directive is specified.  

The 'nologin' file will be created in the directory specified by the 
NOLOGINDIR directive desribed below.

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).  

\begin{description}

\item [disable]
   \index{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]
   \index{timeout }
   specifies that apcupsd should prohibit logins after the UPS is on batteries
for 90\% of the time specified on the {\bf 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]
   \index{percent }
   specifies that apcupsd should prohibit logins when the remaining battery
charge percentage reaches 110\% or less than the value specified on the {\bf
BATTERYLEVEL} configuration directive. Thus if the {\bf BATTERYLEVEL} is
specified as 15, apcupsd will prohibit logins when the battery charge drops
below 16\% (15\% X 110\% = 16\%).  

\item [minutes]
   \index{minutes }
   specifies that apcupsd should prohibit logins when the remaining runtime in
minutes reaches 110\% or less than the value specified on the {\bf MINUTES}
configuration directive.  Thus if {\bf MINUTES} is set to 3, apcupsd will
prohibit logins when the remaining runtime is less than 3 minutes (3 X 110\% =
3).  

\item [always]
   \index{always }
   causes apcupsd to immediately prohibit logins when a power failure occurs.
This will also enable the ANNOY feature. 
\end{description}

\item [NOLOGINDIR \lt{}path to nologin dir\gt{}]
   \index{NOLOGINDIR \lt{}path to nologin dir\gt{} }
   This directive configures the directory into which apcupsd will write the
nologin file, as described above for the NOLOGON directive. 

Normally, the {\tt ./configure} program will set an appropriate default 
value for your platform, often /etc. You may also specify the 
{\tt \verb{--{with-nologdir=} option of the {\tt./configure} program 
to change the default at compile time.  

\label{KILLDELAY-_003ctime-in-seconds_003e}

\item [KILLDELAY \lt{}time in seconds\gt{}]
   \index{KILLDELAY \lt{}time in seconds\gt{} }
   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 {\bf 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.  

\item [SCRIPTDIR \lt{}path to apccontrol dir\gt{}]
   \index{SCRIPTDIR \lt{}path to apccontrol dir\gt{} }
   This option configures the directory in which apccontrol and other
event scripts are located.

Normally, the {\tt ./configure} program will set an appropriate default 
value for your platform, often /etc/apcupsd.

\item [PWRFAILDIR \lt{}path to powerfail dir\gt{}]
   \index{PWRFAILDIR \lt{}path to powerfail dir\gt{} }
   When apcupsd shuts down your system, it creates a temporary "flag file"
which is used by the operating system halt scripts to know if this shutdown
is due to a power failure. This directive configures which directory the
flag file will be written into. The chosen directory must be writable by
the user apcupsd is running as (normally root) and must not be cleared 
or unmounted early in the shutdown sequence.

Normally, the {\tt ./configure} program will set an appropriate default 
value for your platform, often /etc/apcupsd. You may also specify the 
{\tt \verb{--{with-pwrfaildir=} option of the {\tt./configure} program 
to change the default at compile time.
\end{description}

\label{Configuration-Directives-used-to-Control-System-Logging}

\subsection*{Configuration Directives used to Control System Logging}
\index{Logging!Configuration Directives used to Control System }
\index{Configuration Directives used to Control System Logging }
\addcontentsline{toc}{subsection}{Configuration Directives used to Control
System Logging}

\label{index-Directives-Logging-245}
\label{index-Logging_002c-directives-246}

\begin{description}

\item [STATTIME\lt{}time\gt{}]
   \index{STATTIME\lt{}time\gt{} }
   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 {\bf
apcaccess status}, as a consequence, it is normally disabled by setting it to
zero.  

\item [STATFILE \lt{}file\gt{}]
   \index{STATFILE \lt{}file\gt{} }
   This directive specifies the file to be used when writing the STATUS
information. The default is /etc/apcupsd/apcupsd.status.  

\item [DATATIME\lt{}time\gt{}]
   \index{DATATIME\lt{}time\gt{} }
   This directives supplies the time interval between writes of PowerChute\&tm;
like data information to the log file. See the Data (see 
\ilink{DATA Logging}{DATA-Logging}) section of this manual for
additional details.  

\item [FACILITY\lt{}log-facility\gt{}]
   \index{FACILITY\lt{}log-facility\gt{} }
   The facility directive can be used to change the system logging class or
facility. The default is {\bf 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{description}

\label{Configuration-Directives-for-Sharing-a-UPS}

\subsection*{Configuration Directives for Sharing a UPS}
\index{UPS!Configuration Directives for Sharing a }
\index{Configuration Directives for Sharing a UPS }
\addcontentsline{toc}{subsection}{Configuration Directives for Sharing a
UPS}

\label{index-Directives-Sharing-247}
The following directives apply to sharing an UPS using a ShareUPS hardware
module. Most users will not use this mode.

\begin{description}

\item [UPSCLASS \lt{}class of operation\gt{}]
   \index{UPSCLASS \lt{}class of operation\gt{} }
   [ standalone | shareslave | sharemaster ] are valid types.

The default is {\bf standalone} and should be used for all machines powered by
the UPS and having a serial port or other direct connection to the UPS. 
This is the normal case.

Use {\bf 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 {\bf 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 \lt{}mode of operation\gt{}]
   \index{UPSMODE \lt{}mode of operation\gt{}}
   [disable | share ] are valid modes.

For normal standalone operations, you will set UPSMODE to disable to indicate
that you are disabling the ShareUPS support.  

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 \lt{}time in seconds\gt{}]
   \index{NETTIME \lt{}time in seconds\gt{} }
   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.  
\end{description}

\label{Configuration-Directives-Used-to-Set-the-UPS-EPROM}

\subsection*{Configuration Directives Used to Set the UPS EPROM}
\index{Configuration Directives Used to Set the UPS EPROM }
\index{EPROM!Configuration Directives Used to Set the UPS }
\addcontentsline{toc}{subsection}{Configuration Directives Used to Set the
UPS EPROM}

\label{index-Directives-EEPROM-248}
\label{index-EEPROM-directives-249}
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 {\tt
\verb{--{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 
\ilink{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.  

\begin{description}

\item [SENSITIVITY \lt{}sets sensitivity level\gt{}]
   \index{SENSITIVITY \lt{}sets sensitivity level\gt{} }
   (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 {\tt \verb{--{configure} option), apcupsd will
read the value stored in the UPS and display it in the STATUS output.  

\label{WAKEUP-_003cset-wakeup-delay_003e}

\item [WAKEUP \lt{}set wakeup delay\gt{}]
   \index{WAKEUP \lt{}set wakeup delay\gt{} }
   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 {\tt \verb{--{configure} option is
specified.  

Under normal apcupsd operations (no {\tt \verb{--{configure} option), apcupsd will
read the value stored in the UPS and display it in the STATUS output.  

\label{SLEEP-_003cset-sleep-delay_003e}

\item [SLEEP \lt{}set sleep delay\gt{}]
   \index{SLEEP \lt{}set sleep delay\gt{} }
   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 {\tt \verb{--{configure} option is specified.  

Under normal apcupsdoperations (no {\tt \verb{--{configure} option), apcupsd will
read the value stored in the UPS and display it in the STATUS output.  

\item [LOTRANSFER \lt{}lower limit of ups batt. transfer\gt{}]
   \index{LOTRANSFER \lt{}lower limit of ups batt. transfer\gt{} }
   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 {\tt apcaccess eeprom} to show you which values are
permitted. This value is written to the UPS EPROM when the {\tt \verb{--{configure}
option is specified.  

Under normal apcupsdoperations (no {\tt \verb{--{configure} option), apcupsd will
read the value stored in the UPS and display it in the STATUS output.  

\item [HITRANSFER \lt{}upper limit of ups batt. transfer\gt{}]
   \index{HITRANSFER \lt{}upper limit of ups batt. transfer\gt{} }
   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 {\tt apcaccess eeprom} to show you which values are permitted. This
value is written to the UPS EPROM when the {\tt \verb{--{configure} option is
specified.  

Under normal apcupsdoperations (no {\tt \verb{--{configure} option), apcupsd will
read the value stored in the UPS and display it in the STATUS output.  

\label{RETURNCHARGE-_003cmin_005f-batt_005f-charge-level_003e}

\item [RETURNCHARGE \lt{}min. batt. charge level\gt{}]
   \index{RETURNCHARGE \lt{}min. batt. charge level\gt{} }
   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 {\tt apcaccess eeprom} to show you which values are permitted. This
value is written to the UPS EPROM when the {\tt \verb{--{configure} option is
specified.  

Under normal apcupsdoperations (no {\tt \verb{--{configure} option), apcupsd will
read the value stored in the UPS and display it in the STATUS output.  

\item [BEEPSTATE \lt{}alarm beep state\gt{}]
   \index{BEEPSTATE \lt{}alarm beep state\gt{} }
   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.  

\begin{description}

\item [0]
   immediately upon power failure  

\item [T]
   power failure + 30 seconds  

\item [L]
   low battery power  

\item [N]
   never 
   \end{description}


\item {\bf UPSNAME \lt{}string\gt{}}
   \index{UPSNAME \lt{}string\gt{} }
   This is an eight character string. This is the UPS name that will be stored in
the UPS EPROM.  

\item {\bf BATTDATE \lt{}string\gt{}}
   \index{BATTDATE \lt{}string\gt{} }
   This is an eight character string that is the last date the batteries were
changed. 
\end{description}

\label{apcupsd-Status-Logging}

\section*{apcupsd Status Logging}
\index{Logging!apcupsd Status }
\index{Apcupsd Status Logging }
\addcontentsline{toc}{section}{apcupsd Status Logging}

\label{index-Logging_002c-Status-250}
\label{index-Status-logging-251}
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. 

\label{Status-report-format}

\subsection*{Status report format}
\index{Format!Status report }
\index{Status report format }
\addcontentsline{toc}{subsection}{Status report format}

\label{index-Status-Report-252}
\label{index-Report_002c-Status-253}
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 {\bf 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 /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 (see 
\ilink{apcupsd Network Monitoring [CGI]
Programs}{apcupsd-Network-Monitoring-_005bCGI_005d-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. 

\label{Status-Report-Example}

\subsection*{Status Report Example}
\index{Example!Status Report }
\index{Status Report Example }
\addcontentsline{toc}{subsection}{Status Report Example}

\label{index-Examples_002c-Status-Report-254}
\label{index-Status-255}
An example of output from an international SmartUPS 1000 follows: 

\footnotesize
\begin{verbatim}
     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{verbatim}
\normalsize

\label{Status-Report-Fields}

\subsection*{Status Report Fields}
\index{Fields!Status Report }
\index{Status Report Fields }
\addcontentsline{toc}{subsection}{Status Report Fields}

\label{index-Status-256}
The meaning of the above variables are:  

\begin{description}

\item [APC]
   \index{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]
   \index{DATE }
   is the date and time that the information was last obtained from the UPS.  

\item [HOSTNAME]
   \index{HOSTNAME }
   is the name of the machine that collected the UPS data.  

\item [RELEASE]
   \index{RELEASE }
   is the apcupsd release number.  

\item [CABLE]
   \index{CABLE }
   is the cable as specified in the configuration file.  

\item [MODEL]
   \index{MODEL }
   is the UPS model as derived from information from the UPS.  

\item [UPSMODE]
   \index{UPSMODE }
   is the mode in which apcupsd is operating.  

\item [STARTTIME]
   \index{STARTTIME }
   is the time/date that apcupsd was started.  

\item [UPSNAME]
   \index{UPSNAME }
   is the name of the UPS as stored in the EEPROM.  

\item [STATUS]
   \index{STATUS }
   is the current status of the UPS (ONLINE, CHARGING, ONBATT,...)  

\item [MASTERUPD]
   \index{MASTERUPD }
   is the last time the master sent an update to the slave. This value is present
only in slave configurations.  

\item [LINEV]
   \index{LINEV }
   is the current line voltage as returned by the UPS.  

\item [LOADPCT]
   \index{LOADPCT }
   is the percentage of load capacity as estimated by the UPS.  

\item [BCHARGE]
   \index{BCHARGE }
   is the percentage charge on the batteries.  

\item [TIMELEFT]
   \index{TIMELEFT }
   is the remaining runtime left on batteries as estimated by the UPS.  

\item [MBATTCHG]
   \index{MBATTCHG }
   if the battery charge percentage (BCHARGE) drops below this value, apcupsd
will shutdown your system.  

\item [MINTIMEL]
   \index{MINTIMEL }
   apcupsd will shutdown your system if the remaining runtime equals or is below
this point.  

\item [MAXTIME]
   \index{MAXTIME }
   apcupsd will shutdown your system if the time on batteries exceeds this value.
A value of zero disables the feature.  

\item [MAXLINEV]
   \index{MAXLINEV }
   is the maximum line voltage since the last STATUS as returned by the UPS.  

\item [MINLINEV]
   \index{MINLINEV }
   is the minimum line voltage since the last STATUS as returned by the UPS.  

\item [OUTPUTV]
   \index{OUTPUTV }
   is the voltage the UPS is supplying to your equipment.  

\item [SENSE]
   \index{SENSE }
   is the sensitivity level of the UPS to line voltage fluctuations.  

\item [DWAKE]
   \index{DWAKE }
   is the amount of time the UPS will wait after a power off condition when the
power is restored.  

\item [DSHUTD]
   \index{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]
   \index{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]
   \index{LOTRANS }
   is the line voltage below which the UPS will switch to batteries.  

\item [HITRANS]
   \index{HITRANS }
   is the line voltage above which the UPS will switch to batteries.  

\item [RETPCT]
   \index{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]
   \index{STATFLAG }
   is a status flag indicating the UPS status. See STATUS.  

\item [ITEMP]
   \index{ITEMP }
   is the internal UPS temperature as supplied by the UPS.  

\item [ALARMDEL]
   \index{ALARMDEL }
   is the delay period for the UPS alarm.  

\item [BATTV]
   \index{BATTV }
   is the battery voltage as supplied by the UPS.  

\item [LINEFREQ]
   \index{LINEFREQ }
   is the line frequency in Hertz as given by the UPS.  

\item [LASTXFER]
   \index{LASTXFER }
   is the reason for the last transfer to batteries.  

\item [NUMXFERS]
   \index{NUMXFERS }
   the number of transfers to batteries since apcupsd startup.  

\item [XONBATT]
   \index{XONBATT }
   time and date of last transfer to batteries, or N/A.  

\item [TONBATT]
   \index{TONBATT }
   time in seconds currently on batteries, or 0.  

\item [CUMONBATT]
   \index{CUMONBATT }
   total (cumulative) time on batteries in seconds since apcupsd startup.  

\item [XOFFBATT]
   \index{XOFFBATT }
   time and date of last transfer from batteries, or N/A.  

\item [SELFTEST]
   \index{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]
   \index{STESTI }
   is the interval in hours between automatic self tests.  

\item [STATFLAG]
   \index{STATFLAG }
   status flag. English version is given by STATUS.  

\item [DIPSW]
   \index{DIPSW }
   is the dip switch settings.  

\item [REG1]
   \index{REG1 }
   is the value from the UPS fault register 1.  

\item [REG2]
   \index{REG2 }
   is the value from the UPS fault register 2.  

\item [REG3]
   \index{REG3 }
   is the value from the UPS fault register 3.  

\item [MANDATE]
   \index{MANDATE }
   is the date the UPS was manufactured.  

\item [SERIALNO]
   \index{SERIALNO }
   is the UPS serial number.  

\item [BATTDATE]
   \index{BATTDATE }
   is the date that batteries were last replaced.  

\item [NOMOUTV]
   \index{NOMOUTV }
   is the output voltage that the UPS will attempt to supply when on battery
power.  

\item [NOMBATTV]
   \index{NOMBATTV }
   is the nominal battery voltage.  

\item [HUMIDITY]
   \index{HUMIDITY }
   is the humidity as measured by the UPS.  

\item [AMBTEMP]
   \index{AMBTEMP }
   is the ambient temperature as measured by the UPS.  

\item [EXTBATTS]
   \index{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]
   \index{BADBATTS }
   is the number of bad battery packs.  

\item [FIRMWARE]
   \index{FIRMWARE }
   is the firmware revision number.  

\item [APCMODEL]
   \index{APCMODEL }
   is the old APC model identification code.  

\item [END APC]
   \index{END APC }
   is the time and date that the STATUS record was written. 
\end{description}

\label{Logging-the-STATUS-Information}

\subsection*{Logging the STATUS Information}
\index{Logging the STATUS Information }
\index{Information!Logging the STATUS }
\addcontentsline{toc}{subsection}{Logging the STATUS Information}

\label{index-Logging-Status-257}
\label{index-Status_002c-Logging-258}
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 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.


\label{The-Shutown-Sequence-and-its-Discontents}

\section*{The Shutown Sequence and its Discontents}
\index{Shutown Sequence and its Discontents }
\index{Discontents!Shutown Sequence and its }
\addcontentsline{toc}{section}{Shutown Sequence and its Discontents}

\label{index-Shutdown-Sequence-259}

\label{Shutdown-Sequence-_003c1_003e}

\subsection*{Shutdown Sequence}
\index{Shutdown Sequence }
\index{Sequence!Shutdown }
\addcontentsline{toc}{subsection}{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:  

\begin{itemize}
\item apcupsd detects that there is a power problem and it calls {\tt
   /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
   {\tt /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 {\tt /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
   /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 {\tt
/etc/apcupsd/apccontrol emergency} is called.  

Just before initiating any shutdown through the apccontrol script, apcupsd
will create the 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 /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.  
\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 /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 /etc/rc.d/halt or /etc/rc.d/init.d/halt, or possibly in
/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
/etc/apcupsd/powerfail exists, and if it does, it executes {\tt
/etc/apcupsd/apccontrol killpower}. It is this last step that will cause
apcupsd to be re-executed with the {\tt \verb{--{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:  

\footnotesize
\begin{verbatim}
          # 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{verbatim}
\normalsize

\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 /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 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 /etc/rc.d/init.d/apcupsd script, use the {\tt
\verb{--{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: 

\footnotesize
\begin{verbatim}
     apcaccess eeprom
\end{verbatim}
\normalsize

The output should look something like the following: 

\footnotesize
\begin{verbatim}
     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{verbatim}
\normalsize

The line of interest for you is the {\bf Shutdown grace delay}, which can be
changed using the SLEEP (see 
\ilink{SLEEP \lt{}set sleep
delay\gt{}}{SLEEP-_003cset-sleep-delay_003e}) directive in your
{\bf 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
(see 
\ilink{Configuring Your EEPROM}{Configuring-Your-EEPROM}) this
manual for further details on how to change this EPROM value.  

If you use the \texttt{{---}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
(see 
\ilink{RETURNCHARGE \lt{}min\_ batt\_ charge
level\gt{}}
{RETURNCHARGE-_003cmin_005f-batt_005f-charge-level_003e})
percentage and the WAKEUP (see 
\ilink{WAKEUP \lt{}set wakeup
delay\gt{}}{WAKEUP-_003cset-wakeup-delay_003e}) delay. Briefly, the
{\bf 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 {\bf WAKEUP} delay is a simple time
delay. Most sites will have both of these at zero, or perhaps the {\bf
RETURNCHARGE} set to 15. Please follow the links to the {\bf Configuration}
section of this manual for more information.  See the EEPROM (see 
\ilink{Configuring Your EEPROM}{Configuring-Your-EEPROM}) of this
manual for further details on how to change these EPROM values. 

\label{Shutdown-Problems}

\subsection*{Shutdown Problems}
\index{Shutdown Problems }
\index{Problems!Shutdown }
\addcontentsline{toc}{subsection}{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. 

\label{Master_002fSlave-Shutdown-_003c1_003e}

\subsection*{Master/Slave Shutdown}
\index{Shutdown!Master/Slave }
\index{Master/Slave Shutdown }
\addcontentsline{toc}{subsection}{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 /etc/apcupsd/apccontrol file on the
master. For example to give the slaves 30 additional seconds to shutdown, one
would add: 

\footnotesize
\begin{verbatim}
     sleep 30
\end{verbatim}
\normalsize

just after the line that reads 

\footnotesize
\begin{verbatim}
     doshutdown)
\end{verbatim}
\normalsize

in the 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
(/usr/local/sbin/apcupsd or /sbin/powersc). 

\label{Startup}

\subsection*{Startup}
\index{Startup }
\addcontentsline{toc}{subsection}{Startup}

\label{index-Startup-260}
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 /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 {\tt 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: 

\footnotesize
\begin{verbatim}
     <path>/apcupsd start
\end{verbatim}
\normalsize

where \lt{}path\gt{} is normally /etc/rc.d or /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: 

\footnotesize
\begin{verbatim}
     <path>/apcupsd stop
\end{verbatim}
\normalsize

\label{Windows-Considerations}

\subsection*{Windows Considerations}
\index{Windows Considerations }
\index{Considerations!Windows }
\addcontentsline{toc}{subsection}{Windows Considerations}

\label{index-Windows-Considerations-261}
Please see the end of Windows chapter (see 
\ilink{Installation on Windows}{The-Windows-Version-of-apcupsd}) of this
manual for conderations pertaining to shutdown and killpower on Windows. 

\label{APC-smart-protocol}

\section*{APC smart protocol}
\index{Protocol!APC smart }
\index{APC smart protocol }
\addcontentsline{toc}{section}{APC smart protocol}

\label{index-Smart-protocol-262}
\label{index-Protocol-Smart-263}
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 
\elink{Network UPS Tools
(NUT)}{http://www.exploits.org/nut/library/apcsmart.html} site. It has been an
invaluable tool in improving apcupsd, and I consider it the {\bf 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 
\elink{programming project}{http://www.exploits.org/nut}, and maybe some day,
the apcupsd project and the {\bf NUT} project can join forces. 

\label{Description}

\subsection*{Description}
\index{Description }
\addcontentsline{toc}{subsection}{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. 

\label{RS_002d232-differences}

\subsection*{RS-232 differences}
\index{RS-232 differences }
\index{Differences!RS-232 }
\addcontentsline{toc}{subsection}{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. 

\label{Diagram-for-cable-hackers}

\subsection*{Diagram for cable hackers}
\index{Hackers!Diagram for cable }
\index{Diagram for cable hackers }
\addcontentsline{toc}{subsection}{Diagram for cable hackers}

If you are handy with cable creation tools, check out the 
\elink{940-0024C clone
diagram}{http://www.exploits.org/nut/library/940-0024C.jpg}. 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 
\elink{NUT}{http://www.exploits.org/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 (see 
\ilink{Cables}{Cables}) in this manual. 

\label{The-Smart-Protocol}

\subsection*{The Smart Protocol}
\index{Protocol!Smart }
\index{Smart Protocol }
\addcontentsline{toc}{subsection}{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 {\bf 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
(\textbackslash{}n in C) and a carriage return (\textbackslash{}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. \gt{}  

\addcontentsline{lot}{table}{Single Character Commands}
\begin{longtable}{p{0.5in}p{2.25in}p{2.25in}l}
{Code} & {Meaning} & {Typical results} & { 
 } \\
{\^{}A} & {Model string} & {SMART-UPS 700} & { 
 } \\
{\^{}N} & {Turn on UPS (send twice, with \gt{} 1.5s delay between chars) Only
on 3rd gen SmartUPS and Black Back-UPS Pros} & {n/a} & { 
 } \\
{\^{}Z} & {Permitted EEPROM Values} & {A large string (254 chars) that gives
the EEPROM permitted values for your model. For details see below.} & { 
 } \\
{A} & {Front panel test} & {Light show + ``OK'' (and 2s beep)} & { 
 } \\
{B} & {Battery voltage} & {Ranges - typical ``27.87''} & { 
 } \\
{C} & {Internal temperature (degrees C)} & {Ranges - typical ``036.0''} & { 
 } \\
{D} & {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''} & {! when on battery, \$ on line} & { 
 } \\
{E} & {Automatic self test intervals} & {Default = 336 (336 hours = 14 days)
(336=14 days, 168=7 days, ON=power on, OFF=never)} & { 
 } \\
{F} & {Line frequency, Hz} & {60.00 (50.0 in Europe)} & { 
 } \\
{G} & {Cause of transfer} & {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).} & { 
 } \\
{K{---}K} & {Shutdown with grace period (set with 'p') - need \gt{} 1.5s
between first and second K} & {Matrix/3rd gen SmartUPS/Black Back-UPS Pros:
``OK'', all others: ``*''} & { 
 } \\
{L} & {Input line voltage} & {Ranges - typical ``118.3'' or ``228.8'' in
Europe} & { 
 } \\
{M} & {Maximum line voltage received since last M query} & {Ranges - typical
``118.9'' or ``230.1'' in Europe} & { 
 } \\
{N} & {Minimum line voltage received since last N query} & {Ranges - typical
``118.9'' or ``226.2'' in Europe} & { 
 } \\
{O} & {Output voltage} & {Ranges - typical ``118.3'' or ``228.8'' in Europe} &
{ 
 } \\
{P} & {Power load \%} & {Ranges - typical ``011.4'' depends on what you have
plugged in.} & { 
 } \\
{Q} & {Status flags} & {Bitmapped, see below} & { 
 } \\
{R} & {Turn dumb Only on 3rd gen SmartUPS, SmartUPS v/s, BackUPS Pro} &
{``BYE''} & { 
 } \\
{S} & {Soft shutdown after 'p' delay, return online when power returns Only
works when UPS is on battery} & {OK} & { 
 } \\
{U} & {Simulate power failure} & {!! when switching to battery, then \$ when
back on line} & { 
 } \\
{V} & {Old firmware revision} & {``GWD'' or ``IWI'' The last character
indicates the locale (Domestic, International).} & { 
 } \\
{W} & {Self test (battery), results stored in ``X''} & {``OK''} & { 
 } \\
{X} & {Results of last self test} & {``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)} & { 
 } \\
{Y} & {Enter smart mode} & {``SM''} & { 
 } \\
{Z{---}Z} & {Shutdown immediately (no delay) - need \gt{} 1.5s between first
and second Z} & {N/A} & { 
 } \\
{a} & {Show protocol version.alert messages.valid commands (delimited by
periods)} & {
``3.!\$\%+?=\#|.\^{}A\^{}N\^{}Z+-789\lt
{}@ABCDEFGKLMNOPQRSUVWXYZ'abcefgjklmnopqrsuvzy\~{}\^{}?'' -
Link-Level.alert-messages.commands} & { 
 } \\
{b} & {Firmware revision} & {``50.9.D'' - 50 = SKU (variable length), 9 =
firmware revision, D = country code (D=USA, I=International, A=Asia, J=Japan,
M=Canada)} & { 
 } \\
{c} & {UPS local id} & {UPS\_IDEN (you can program any 8 characters here)} & {

 } \\
{e} & {Return threshold} & {\% battery charge threshold for return (00=00\%,
01=15\%, 02=25\%, 03=90\%)} & { 
 } \\
{f} & {Battery level \%} & {Ranges - typical ``100.0'' when fully charged as
should normally be the case} & { 
 } \\
{g} & {Nominal battery voltage (not actual voltage - see B)} & {``012'' or
``024'' or ``048''.} & { 
 } \\
{h} & {Measure-UPS: ambient humidity (\%)} & {``nnn.n'' - percentage} & { 
 } \\
{i} & {Measure-UPS: dry contacts} & {10 = contact 1, 20 = 2, 40 = 3, 80 = 4} &
{ 
 } \\
{j} & {Estimated runtime at current load (minutes)} & {``0112:'' (note, it is
terminated with a colon)} & { 
 } \\
{k} & {Alarm delay} & {0(zero) = 5 second delay after fail, T = 30 second
delay, L = alarm at low battery only, N = no alarm} & { 
 } \\
{l} & {Low transfer voltage} & {Default ``103'' or ``208'' in Europe} & { 
 } \\
{m} & {Manufacturing date} & {Unique within groups of UPSes (production runs)}
& { 
 } \\
{n} & {Serial number} & {Unique for each UPS} & { 
 } \\
{o} & {Nominal Output Voltage} & {The Nominal Output Voltage when running on
batteries. Default ``115'' or ``230'' in Europe.} & { 
 } \\
{p} & {Shutdown grace delay, seconds} & {Default ``020'' (020/180/300/600)} &
{ 
 } \\
{q} & {Low battery warning, minutes} & {Default ``02''} & { 
 } \\
{r} & {Wakeup delay (time) - seconds} & {Default ``000'' (000/060/180/300)} &
{ 
 } \\
{s} & {Sensitivity} & {``H'' - highest, ``M'' - medium, ``L'' - lowest, ``A''
- autoadjust (Matrix only)} & { 
 } \\
{u} & {Upper transfer voltage} & {Default ``132'' or ``253'' in Europe} & { 
 } \\
{t} & {Measure-UPS: ambient temperature (degrees C)} & {``nn.nn''} & { 
 } \\
{x} & {Last battery change} & {Eight characters. Varies typically dd/mm/yy -
31/12/99} & { 
 } \\
{y} & {Copyright notice} & {``(C) APCC'' - only works if firmware letter (from
``V'') is later than O} & { 
 } \\
{z} & {Reset the EEPROM to factory settings (but not ident or batt replacement
date) Not on SmartUPS v/s or BackUPS Pro} & {``CLEAR''} & { 
 } \\
{+} & {Capability cycle} & {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.} & { 
 } \\
{-} & {Capability cycle} & {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.} & { 
 } \\
{@nnn} & {Shutdown (after delay 'p') with delayed wakeup of nnn tenths of an
hour (after 'r' time)} & {Matrix/3rd gen UPS: ``OK'', others ``*''} & { 
 } \\
{0x7f (DEL key)} & {Abort shutdown - use to abort @, S, K{---}K} & {``OK''} &
{ 
 } \\
{\~{}} & {Register \#1} & {See below} & { 
 } \\
{'} & {Register \#2} & {See below} & { 
 } \\
{0} & {Battery constant} & {Set to A0 on SmartUPS 1000 with new battery} & { 
 } \\
{4} & {???} & {Prints 35 on SmartUPS 1000} & { 
 } \\
{5} & {???} & {Prints EF on SmartUPS 1000} & { 
 } \\
{6} & {???} & {Prints F9 on SmartUPS 1000} & { 
 } \\
{7} & {Dip switch positions (if applicable)} & {See below} & { 
 } \\
{8} & {Register \#3} & {See below} & { 
 } \\
{9} & {Line quality} & {``FF'' acceptable, ``00'' unacceptable} & { 
 } \\
{\gt{}} & {Number of external battery packs attached} & {SmartCell models:
``nnn'' where nnn is how many external packs are connected Non-SmartCell
units: whatever has been set with \gt{}+ and \gt{}- by the user} & { 
 } \\
{Matrix UPS (and possibly Symmetra) specific commands} & { 
 } & &  { } \\
{\^{}} & {Run in bypass mode} & {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} & { 
 } \\
{\lt{}} & {Number of bad battery packs} & {``nnn'' - count of bad packs
connected to the UPS} & { 
 } \\
{/} & {Load current} & {``nn.nn'' - true RMS load current drawn by UPS} & { 
 } \\
{\textbackslash{}} & {Apparent load power} & {``nnn.nn'' - output load as
percentage of full rated load in VA.} & { 
 } \\
{\^{}V} & {Output voltage selection (editable)} & {``A'' - automatic according
to input tap, ``M'' - 208 VAC, ``I'' - 240 VAC} & { 
 } \\
{\^{}L} & {Front panel language} & {``E'' - English, ``F'' - French, ``G'' -
German, ``S'' - Spanish, ``1'' ``2'' ``3'' ``4'' - ?} & { 
 } \\
{w} & {Run time conservation} & {``NO'' (disabled) or ``02'' ``05'' ``08'' -
minutes of runtime to leave in battery (UPS shuts down ``early'')} & {  
}

\end{longtable}

\label{Dip-switch-info}

\subsection*{Dip switch info}
\index{Dip switch info }
\index{Info!Dip switch }
\addcontentsline{toc}{subsection}{Dip switch info}

\addcontentsline{lot}{table}{DIP Switch Info}
\begin{longtable}{p{0.5in}p{0.5in}p{4in}}
{Bit} & {Switch} & {Option when bit=1 
 } \\
{0} & {4} & {Low battery alarm changed from 2 to 5 mins. Autostartup disabled
on SU370ci and 400 
 } \\
{1} & {3} & {Audible alarm delayed 30 seconds 
 } \\
{2} & {2} & {Output transfer set to 115 VAC (from 120 VAC) or to 240 VAC (from
230 VAC) 
 } \\
{3} & {1} & {UPS desensitized - input voltage range expanded 
 } \\
{4-7} & {-} & {Unused at this time 
}

\end{longtable}

\label{Status-bits}

\subsection*{Status bits}
\index{Status bits }
\index{Bits!Status }
\addcontentsline{toc}{subsection}{Status bits}

This is probably the most important register of the UPS, which indicates the
overall UPS status. Some common things you'll see:  

\begin{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}

\addcontentsline{lot}{table}{UPS Status Bits}
\begin{longtable}{p{0.5in}p{0.5in}p{4in}}
{Bit} & {Hex Bit} & {Meaning 
 } \\
{0} & {0x01} & {1 = Runtime calibration occurring Not reported by Smart UPS
v/s and BackUPS Pro 
 } \\
{1} & {0x02} & {1 = SmartTrim Not reported by 1st and 2nd generation SmartUPS
models 
 } \\
{2} & {0x04} & {1 = SmartBoost 
 } \\
{3} & {0x08} & {1 = On line (this is the normal condition) 
 } \\
{4} & {0x10} & {1 = On battery 
 } \\
{5} & {0x20} & {1 = Overloaded output 
 } \\
{6} & {0x40} & {1 = Battery low 
 } \\
{7} & {0x80} & {1 = Replace battery  
}

\end{longtable}

\label{Alert-messages}

\subsection*{Alert messages}
\index{Alert messages }
\index{Messages!Alert }
\addcontentsline{toc}{subsection}{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.  

\addcontentsline{lot}{table}{Alert Messages}
\begin{longtable}{p{0.7in}p{4.3in}}
{Character} & {Description 
 } \\
{!} & {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. 
 } \\
{\$} & {Return from line fail - UPS back on line power, only sent if a ! has
been sent. 
 } \\
{\%} & {Low battery - Sent to indicate low battery, but not on SmartUPS v/s or
BackUPS Pro models 
 } \\
{+} & {Return from low battery - Sent when the battery has been recharged to
some level only if a \% has been sent previously 
 } \\
{?} & {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. 
 } \\
{=} & {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. 
 } \\
{*} & {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. 
 } \\
{\#} & {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. 
 } \\
{\&} & {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. 
 } \\
{|} & {Variable change in EEPROM - Sent whenever any EEPROM variable is
changed. Only supported on Matrix UPS and 3rd generation SmartUPS models.  
}

\end{longtable}

\label{Register-1}

\subsection*{Register 1}
\index{Register 1 }
\addcontentsline{toc}{subsection}{Register 1}

All bits are valid on the Matrix UPS. SmartUPS models only support bits 6 and
7. Other models do not respond.  

\addcontentsline{lot}{table}{Register 1 Layout}
\begin{longtable}{p{0.3in}p{0.5in}p{4.2in}}
{Bit} & {Hex Bit} & {Meaning 
 } \\
{0} & {0x01} & {In wakeup mode (typically lasts \lt{} 2s) 
 } \\
{1} & {0x02} & {In bypass mode due to internal fault - see register 2 or 3 
 } \\
{2} & {0x04} & {Going to bypass mode due to command 
 } \\
{3} & {0x08} & {In bypass mode due to command 
 } \\
{4} & {0x10} & {Returning from bypass mode 
 } \\
{5} & {0x20} & {In bypass mode due to manual bypass control 
 } \\
{6} & {0x40} & {Ready to power load on user command 
 } \\
{7} & {0x80} & {Ready to power load on user command or return of line power  
}

\end{longtable}

\label{Register-2}

\subsection*{Register 2}
\index{Register 2 }
\addcontentsline{toc}{subsection}{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.  

\addcontentsline{lot}{table}{Register 2 Layout}
\begin{longtable}{p{0.3in}p{4.7in}}
{Bit} & {Meaning 
 } \\
{0} & {Fan failure in electronics, UPS in bypass 
 } \\
{1} & {Fan failure in isolation unit 
 } \\
{2} & {Bypass supply failure 
 } \\
{3} & {Output voltage select failure, UPS in bypass 
 } \\
{4} & {DC imbalance, UPS in bypass 
 } \\
{5} & {Command sent to stop bypass with no battery connected - UPS still in
bypass 
 } \\
{6} & {Relay fault in SmartTrim or SmartBoost 
 } \\
{7} & {Bad output voltage  
}

\end{longtable}

\label{Register-3}

\subsection*{Register 3}
\index{Register 3 }
\addcontentsline{toc}{subsection}{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.  

\addcontentsline{lot}{table}{Register 3 Layout}
\begin{longtable}{p{0.3in}p{4.7in}}
{Bit} & {Meaning 
 } \\
{0} & {Output unpowered due to shutdown by low battery 
 } \\
{1} & {Unable to transfer to battery due to overload 
 } \\
{2} & {Main relay malfunction - UPS turned off 
 } \\
{3} & {In sleep mode from @ (maybe others) 
 } \\
{4} & {In shutdown mode from S 
 } \\
{5} & {Battery charger failure 
 } \\
{6} & {Bypass relay malfunction 
 } \\
{7} & {Normal operating temperature exceeded  
}

\end{longtable}

\label{Interpretation-of-the-Old-Firmware-Revision}

\subsection*{Interpretation of the Old Firmware Revision}
\index{Revision!Interpretation of the Old Firmware }
\index{Interpretation of the Old Firmware Revision }
\addcontentsline{toc}{subsection}{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: 

\footnotesize
\begin{verbatim}
     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{verbatim}
\normalsize

\label{Interpretation-of-the-New-Firmware-Revision}

\subsection*{Interpretation of the New Firmware Revision}
\index{Revision!Interpretation of the New Firmware }
\index{Interpretation of the New Firmware Revision }
\addcontentsline{toc}{subsection}{Interpretation of the New Firmware
Revision}

\footnotesize
\begin{verbatim}
     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{verbatim}
\normalsize

\label{EEPROM-Values}

\subsection*{EEPROM Values}
\index{EEPROM Values }
\index{Values!EEPROM }
\addcontentsline{toc}{subsection}{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:  

\begin{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: 

\footnotesize
\begin{verbatim}
      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{verbatim}
\normalsize

\label{Programming-the-UPS-EEPROM}

\subsection*{Programming the UPS EEPROM}
\index{Programming the UPS EEPROM }
\index{EEPROM!Programming the UPS }
\addcontentsline{toc}{subsection}{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:  

\addcontentsline{lot}{table}{Programming the UPS EEPROM}
\begin{longtable}{p{0.7in}p{1in}p{3.3in}}
{Item} & {Command} & {Meaning 
 } \\
{1.} & {c} & {The UPS Id or name 
 } \\
{2.} & {x} & {The last date the batteries were replaced 
 } \\
{3.} & {u} & {The Upper Transfer Voltage 
 } \\
{4.} & {l} & {The Lower Transfer Voltage 
 } \\
{5.} & {e} & {The Return Battery Charge Percentage 
 } \\
{6.} & {o} & {The Output Voltage when on Batteries 
 } \\
{7.} & {s} & {The Sensitivity to Line Quality 
 } \\
{8.} & {p} & {The Shutdown Grace Delay 
 } \\
{9.} & {q} & {The Low Battery Warning Delay 
 } \\
{10.} & {k} & {The Alarm Delay 
 } \\
{11.} & {r} & {The Wakeup Delay 
 } \\
{12.} & {E} & {The Automatic Self Test Interval  
}

\end{longtable}

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. 

\label{Acknowledgements}

\subsection*{Acknowledgements}
\index{Acknowledgements }
\addcontentsline{toc}{subsection}{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 \lt{}pavelk at dator3.anet.cz\gt{}, Andre M. Hedrick
\lt{}hedrick at suse.de\gt{}, Christopher J. Reimer \lt{}reimer at
doe.carleton.ca\gt{}, Kevin D. Smolkowski \lt{}kevins at
trigger.oslc.org\gt{}, Werner Panocha \lt{}wpanocha at t-online.de\gt{},
Steven Freed, 
\elink{Russell Kroll}{http://www.exploits.org/~rkroll/contact.html}.  

additions by: 
\elink{Kern Sibbald \lt{}apcupsd-users at
lists.sourceforge.net\gt{}}{http://www.apcupsd.com} 

\label{Apcupsd-_002d_002d-RPM-Packaging-FAQ}

\section*{Apcupsd {---} RPM Packaging FAQ}
\index{Apcupsd {---} RPM Packaging FAQ }
\index{FAQ!Apcupsd {---} RPM Packaging }
\addcontentsline{toc}{section}{Apcupsd {---} RPM Packaging FAQ}

\label{Answers}

\subsection*{Answers}
\index{Answers }
\addcontentsline{toc}{subsection}{Answers}

\begin{description}

\item [{\bf How do I build Apcupsd for platform xxx?}]
   \index{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 (fedora\_core), RedHat
Enterprise Linux and clones (rhel3 and rhel4), SuSE 9 \& 10 (suse), and Mandrake (mdk).  
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  

\footnotesize
\begin{verbatim}
              %define rh7 0
     
\end{verbatim}
\normalsize

and edit it to read  

\footnotesize
\begin{verbatim}
              %define rh7 1
     
\end{verbatim}
\normalsize

Alternately you may pass the define on the command line when calling rpmbuild:
 

\footnotesize
\begin{verbatim}
              rpmbuild -ba --define "build_rh7 1" apcupsd.spec
              rpmbuild --rebuild --define build_rh7 1" apcupsd-x.x.x-x.src.rpm
     
\end{verbatim}
\normalsize


\item [{\bf How do I control whether usb support gets built?}]
   \index{How do I control whether usb support gets built? }
   Up through version 3.12, by default standard serial port support 
was built and the apcupsd-std package was produced.  The usb 
package pre-configured the configuration files for usb devices and 
installed a couple additional tools in /etc/apcupsd but the usb 
driver was built regardless.  To get the usb package and support 
in those versions either set the  

\footnotesize
\begin{verbatim}
              %define usb 0
     
\end{verbatim}
\normalsize

to  

\footnotesize
\begin{verbatim}
              %define usb 1
     
\end{verbatim}
\normalsize

in the spec file directly or pass it to rpmbuild on the command line:  

\footnotesize
\begin{verbatim}
              rpmbuild -ba --define "build_rh7 1" --define "build_usb 1" apcupsd.spec
     
\end{verbatim}
\normalsize

   With the release of 3.14 USB support is now considered standard and the 
apcupsd-std and apcupsd-usb packages are obsoleted in favor of a single 
apcupsd package configured for usb connected UPS's.  The serial port driver 
is still built and can be configured accordingly after installation. If you 
are performing an upgrade it will of course not replace your current config file.

   The build directive:


\footnotesize
\begin{verbatim}
              --define "build_usb 1"
     
\end{verbatim}
\normalsize

is no longer recognized.

\item [{\bf What other defines are used?}]
   \index{What other defines are used? }
   There is a define for the initdir for the daemon control script. On
RedHat or Mandrake systems this is set to /etc/rc.d/init.d/. On SuSE systems this is 
set to /etc/rc.d.  You would only need to edit this if packaging for a platform that 
uses a different directory.

   A second define controls whether the Gnome monitoring application, new in the 
3.14 release, is built.  This application requires the Gtk2 version to be >= 2.4. 
If you want to build the apcupsd-gapcmon package add:

\footnotesize
\begin{verbatim}
              --define "build_gapcmon 1"
     
\end{verbatim}
\normalsize

   A third define controls whether the SNMP driver is built. If you want to build the net-snmp driver add:

\footnotesize
\begin{verbatim}
              --define "build_snmp 1"
     
\end{verbatim}
\normalsize


\item [{\bf Can I supply packages for other platforms you do not publish?}]
   \index{Can I supply packages for other platforms you do not publish? }
   Yes, there are tools provided for contributors to supply rpm packages for platforms 
for which support is provided in the spec file but for which the development team 
chooses not to release binary packages, usually due to lack of interest or lack of an 
available platform. Please see platforms/contrib/README in the source package.  

\item [{\bf I'm getting errors about not having permission when}]
   \index{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 one of the
following commands as root depending on your distribution, RedHat, SuSE or 
Mandriva, respectively:  

\footnotesize
\begin{verbatim}
              chmod -R 777 /usr/src/redhat
              chmod -R 777 /usr/src/packages
              chmod -R 777 /usr/src/RPM
     
\end{verbatim}
\normalsize

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 (or other) directory tree with all 
of it's subdirectories inside your home directory. Then create a file named  

\footnotesize
\begin{verbatim}
              .rpmmacros
     
\end{verbatim}
\normalsize

in your home directory (or edit the file if it already exists) and add the
following line:  

\footnotesize
\begin{verbatim}
              %_topdir /home/myuser/redhat
     
\end{verbatim}
\normalsize

\end{description}

\label{Credits-_003c1_003e}

\section*{Credits}
\index{Credits }
\addcontentsline{toc}{section}{Credits}

\addcontentsline{lof}{figure}{Thanks}
\includegraphics{./thanks.eps}  

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. 

\label{Contributors}

\subsection*{Contributors}
\index{Contributors }
\addcontentsline{toc}{subsection}{Contributors}

\begin{description}

\item [Current Code Maintainer and Project Manager:]
   \index{Current Code Maintainer and Project Manager: }
   Kern Sibbald (kern at sibbald dot com)  

\item [RPM Packager:]
   \index{RPM Packager: }
   D. Scott Barninger (barninger at fairfieldcomputers dot com)  

\item [Super USB bug fixer:]
   \index{Super USB bug fixer: }
   Adam Kropelin (akropel1 at rochester dot rr dot com)  

\item [CGI and HTML fixer:]
   \index{CGI and HTML fixer: }
   William King (wrking at dadaboom dot com)  

\item [Project Starter and Former Code Maintainer:]
   \index{Project Starter and Former Code Maintainer: }
   Andre Hedrick (andre at linux-ide.org)  

\item [Former Code Maintainer and Project Manager:]
   \index{Former Code Maintainer and Project Manager: }
   Riccardo Facchetti (riccardo at master.oasi.gpa.it)  

\item [Serial Communications:]
   \index{Serial Communications: }
   Andre Hedrick (andre at linux-ide.org)  

\item [2.0 User's Manual:]
   \index{2.0 User's Manual: }
   Eric S. Raymond (esr at thyrsus.com)  

\item [Alpha Port:]
   \index{Alpha Port: }
   Kern Sibbald (kern at sibbald dot com)  

J. Rochate (jrochate at ualg.pt) testing and machine loan  

\item [Caldera:]
   \index{Caldera: }
   John Pinner (john at clocksoft.com)  

\item [HP-UX Port]
   \index{HP-UX Port }
   Carl Erhorn (Carl\_Erhorn at hyperion.com)  

Robert K Nelson (rnelson at airflowsciences.com)  

\item [SOLARIS Port:]
   \index{SOLARIS Port: }
   Carl Erhorn (Carl\_Erhorn at hyperion.com)  

\item [OpenBSD Port:]
   \index{OpenBSD Port: }
   Devin Reade (gdr at gno.org)  

\item [NetBSD Port:]
   \index{NetBSD Port: }
   Neil Darlow (neil at darlow.co.uk)  

\item [Win32 Port:]
   \index{Win32 Port: }
   Kern Sibbald (kern at sibbald dot com)  

Paul Z. Stagner (paul.stagner at charterco.com) testing  

\item [WEB Interfaces:]
   \index{WEB Interfaces: }
   Kern Sibbald (kern at sibbald dot com)  

Joseph Acosta (joeja at mindspring.com)  

\item [Apcupsd Support and Knowledge Base:]
   \index{Apcupsd Support and Knowledge Base: }
   Brian Schau (Brian.Schau at compaq.com)  

\item [Hard Core Coders:]
   \index{Hard Core Coders: }
   Riccardo Facchetti (riccardo at master.oasi.gpa.it)  

Kern Sibbald (kern at sibbald dot com)  

\item [Part Time Coders:]
   \index{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:]
   \index{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:]
   \index{Project Discussions: }
   \elink{APCUPSD Mailing
List}{http://wb_mailto:apcupsd-users@lists.sourceforge.net} 
\end{description}

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
\lt{}rkroll at exploits.org\gt{} for the CGI programs. Jonathan Benson
\lt{}jbenson at technologist.com\gt{} 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: 
\elink{http://www.uk.research.att.com/vnc}{http://www.uk.research.att.com/vnc}


\label{Disclaimer_003b-NO-WARRANTY}

\subsection*{Disclaimer: NO WARRANTY}
\index{Disclaimer: NO WARRANTY }
\index{WARRANTY!Disclaimer: NO }
\addcontentsline{toc}{subsection}{Disclaimer: NO WARRANTY}

\label{index-Disclaimer-264}
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. 

\label{Linux-Kernel-Info}
\section*{Linux-Kernel-Info}

\subsection*{Linux Kernel Config}
\index{Config!Linux Kernel}
\index{Linux Kernel Config}
\label{Linux-Kernel-Config}

A typical USB section of a .config file might be:  

\label{index-Kernel-config-265}
\label{index-config_002c-Kernel-266}

\footnotesize
\begin{verbatim}
     #
     # 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{verbatim}
\normalsize

\label{proc_usb_info-2.4}
\subsection*{Interpreting /proc/bus/usb (linux-2.4)}
Interpretation of /proc/bus/usb info on 2.4 kernels: 

\footnotesize
\begin{verbatim}
     /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{verbatim}
\normalsize

\label{proc_usb_info-2.6}
\subsection*{Interpreting /proc/bus/usb (linux-2.6)}
Interpretation of /proc/bus/usb info on 2.6 kernels: 

\footnotesize
\begin{verbatim}
     /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{verbatim}
\normalsize
