Apcupsd is a UPS control system that permits orderly shutdown of your computer in the event of a power failure. Kern Sibbald April 3, 2005 This manual documents apcupsd version 3.10.
Copying and distribution of this file, with or without modification, are permitted in any medium without royalty provided the name Apcupsd, the copyright notice, and this notice are preserved. Apcupsd source code is released under the GNU General Public License version 2. Please see the file COPYING in the main source directory. For more information on the project, please visit the main web site at http://www.apcupsd.
Contents Apcupsd User’s Manual . . . . . . . . . . . . . . . . . . . . . . . . 6 Release Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 New Features . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 How To Use This Manual . . . . . . . . . . . . . . . . . . . . . . . 9 Basic User’s Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Planning Your Installation . . . . . . . . . . . . . . . . . . . . . . . 9 Quick Start for Beginners . . . . . . . . . . . . . .
Checking Your Configuration File . . . . . . . . . . . . . . . . 44 Arranging for Reboot on Power-Up . . . . . . . . . . . . . . . 45 Making sure apcupsd Is Running . . . . . . . . . . . . . . . . 46 Configuration Examples . . . . . . . . . . . . . . . . . . . . . . . . 47 Simple USB Configuration . . . . . . . . . . . . . . . . . . . . 47 Simple Configuration for a SmartUPS . . . . . . . . . . . . . 48 Simple Configuration for a Simple Signaling or Dumb . . . .
Apcupsd Notification and Events . . . . . . . . . . . . . . . . 70 hid-ups and USB Specific Information . . . . . . . . . . . . . 71 apcupsd Network Monitoring (CGI) Programs . . . . . . . . . 71 Setting up and Testing the CGI Programs . . . . . . . . . . . 71 Configuring Your EEPROM . . . . . . . . . . . . . . . . . . . 79 Maintaining Your UPS . . . . . . . . . . . . . . . . . . . . . . . . . 82 What Various People Have to Say about Batteries . . . . . .
Running the server as a child of apcupsd . . . . . . . . . . . . 110 Running apcnisd from INETD . . . . . . . . . . . . . . . . . 111 Running apcnisd Standalome . . . . . . . . . . . . . . . . . . 112 apcupsd System Logging . . . . . . . . . . . . . . . . . . . . . . . . 113 Logging Types . . . . . . . . . . . . . . . . . . . . . . . . . . 113 Implementation Details . . . . . . . . . . . . . . . . . . . . . 114 Developers Notes . . . . . . . . . . . . . . . . . . . . . . . . . 115 Installation: Windows .
Connecting a APC USB UPS to either a PC USB or Serial Port . 131 Cables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131 Smart-Custom Cable for SmartUPSes . . . . . . . . . . . . . 131 Smart Signalling Cable for BackUPS CS Models . . . . . . . 132 Voltage-Signalling Cable for ”dumb” UPSes . . . . . . . . . . 134 Other APC Cables that apcupsd Supports . . . . . . . . . . . 136 Voltage Signalling Features Supported by Apcupsd for Various Cables 137 Voltage Signalling . . . . . . . . .
Configuration Directive Reference . . . . . . . . . . . . . . . . . . . 159 General Configuration Directives . . . . . . . . . . . . . . . . 159 Configuration Directives Used by the Network Information Server 160 Configuration Directives used during Power Failures . . . . . 161 Configuration Directives used to Control System Logging . . 164 Configuration Directives for Sharing a UPS . . . . . . . . . . 165 Configuration Directives Used to Set the UPS EPROM . . . 168 apcupsd Status Logging . . . . . . . .
Alert messages . . . . . . . . . . . . . . . . . . . . . . . . . . 189 Register 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190 Register 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190 Register 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190 Interpretation of the Old Firmware Revision . . . . . . . . . . 191 Interpretation of the New Firmware Revision . . . . . . . . . 192 EEPROM Values . . . . . . . . . . . . . . . . . . . . . . . . .
List of Figures Multimon Main Page . . . . . . . . . . . . . . . . . . . . . . . . . . 74 Multimon Statistics Display . . . . . . . . . . . . . . . . . . . . . . 74 Windows Install - Explorer Window . . . . . . . . . . . . . . . . . 116 Windows Install - Winzip Unpack . . . . . . . . . . . . . . . . . . 117 Windows Install - Winzip Extract Window . . . . . . . . . . . . . 117 Windows Install - Setup Complete . . . . . . . . . . . . . . . . . . 119 Windows NT - Start Service . . . . . . . . . . . . . .
List of Tables Supported UPS Models . . . . . . . . . . . . . . . . . . . . . . . . 13 Supported Features . . . . . . . . . . . . . . . . . . . . . . . . . . . 137 RS232 Wiring and Signal Conventions . . . . . . . . . . . . . . . . 148 Single Character Commands . . . . . . . . . . . . . . . . . . . . . 183 DIP Switch Info . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188 UPS Status Bits . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188 Alert Messages . . . . . . . . . . . . . . . . .
Apcupsd User’s Manual Release Notes This release contains a good number of cleanups and bug fixes to prior 3.10.x versions, and is intended to be the official release. See the ChangeLog below for more details. New Features - Implement USB on all *BSD systems. Note, the kernel drivers on most of these systems are still fragile. There are known problems, for example, on FreeBSD. - Fix killpower on USB UPSes to properly turn off UPS. - More killpower fixes for BackUPS Pros.
page. Change Log for older versions ----> Release 3.10.16 04Nov04 - Adam has fixed the killpower problem for USB so that the USB now properly turns off the power. Nice job. - Converted manual from docbook to texinfo format. There is some cleanup to be done, but we get an index. - Thanks to Adam for converting the .png images to .pdf - Apply patch to fix aastr... supplied by Manfred Schwarb. - Changed Solaris to use mailx by default at the suggestion of Neil Brookins. - Added Adam’s snoopdecode.
- ifdef code in apcaccess that tries to write in the shared memory buffer. - Applied Adam’s patch for fixing the pthreads dependencies in asys.c - Tweak the patch a bit hopefully so that OpenBSD will work. - Made a sweep through quite a few files updating the copyright, eliminating the disclaimer (now in DISCLAIMER), and adding as many astrncpy() and astrncat()s as I could find. There still remain some drivers and the cgi code to do. - Implemented true/false and bool.
How To Use This Manual This is the manual for apcupsd, a daemon for communicating with UPSes (Uninterruptible Power Supplies) made by American Power Corporation (APC). If you have an APC-made UPS, whether sold under the APC nameplate or OEMed (The HP PowerTrust 2997A UPS has been tested as a “smartups” with cable Hewlett Packard part number 5061-2575 equivalent to a custom-smart cable), and you want you get it working with a computer running Linux, Unix, or Windows NT, you are reading the right document.
1. First, check to see if apcupsd supports your UPS and operating system (see Supported Operating Systems; UPSes and Cables). 2. Second, plan your configuration type (see 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. 3. Third, figure out if you have one of the easy setups.
9. To verify that your UPS is communicating with your computer and will do the right thing when the power goes out, read and follow the instructions in the Testing (see Testing Apcupsd) section. 10. If you run into problems, read the Troubleshooting Troubleshooting Your Installation) section of this manual. (see 11. If you still need help, send a message to the developer’s email list apcupsd-users at lists.sourceforge.
We’ll describe the possible values here, because they’re a good way to explain your UPS’s single most important interface property – the kind of protocol it uses to talk with its computer. apcsmart An APCSmart UPS and its computer also communicate through an RS232C serial connection, but they actually use it as a character channel (2400bps, 8 data bits, 1 stop bit, no parity) and pass commands back and forth in a primitive language (see APC smart protocol) resembling modem-control codes.
of the models, particularly USB enabled models, can be run in multiple modes, so they may appear more than once in the table. APC is putting out new models at a furious rate, and so it is very likely that your model is not listed in the table. If it is USB enabled, it will probably work in USB mode.
BackUPS CS USB, Pro USB, ES USB, RS/XS 1000, RS/XS 1500, and probably other USB models SmartUPS USB, BackUPS Office USB, and any other USB UPS All SNMPcapable models BackUPS BackUPS Office, BackUPS ES BackUPS CS and possibly ES models (serial mode) ShareUPS Basic Port usb usb (note: using APC cables 9400127A/B/C) Supported in version >=3.9.8 usb usb (note: using APC cable, no number) Supported, version >=3.9.
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.
driver to be enabled on other platforms, it will only compile and run on Linux and *BSD systems. - Workaround: Try using UPS in serial mode instead of USB. - Problem: Linux 2.4 series kernels older than 2.4.22 do not bind the USB device to the proper driver. This is evidenced by /proc/bus/usb/devices listing the UPS correctly but it will have “driver=(none)” instead of “driver=(hid)”. This affects RHEL3, among others. - Workaround: Upgrade linux kernel to 2.4.22 or higher. - Problem: Mandrake 10.0 and 10.
Checking Out Your USB Subsystem You can skip this section if your UPS has an Ethernet or RS232-C interface or you are not running on a Linux kernel. If it has a USB interface, you need to make sure that your USB subsystem can see the UPS. On a Linux system this is easy, just do this from a shell prompt (please see below for 2.6 kernel considerations): Most of this section applies to Linux.
T: D: P: S: S: S: C:* I: E: Bus=01 Lev=01 Prnt=01 Port=00 Cnt=01 Dev#= 2 Spd=1.5 MxCh= 0 Ver= 1.10 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1 Vendor=051d ProdID=0002 Rev= 1.00 Manufacturer=American Power Conversion Product=Back-UPS 350 FW: 5.2.I USB FW: c1 SerialNumber=BB0115017954 #Ifs= 1 Cfg#= 1 Atr=a0 MxPwr= 30mA If#= 0 Alt= 0 #EPs= 1 Cls=03(HID ) Sub=00 Prot=00 Driver=hid Ad=81(I) Atr=03(Int.
esr@grelber$ cat /proc/bus/usb/drivers and you should get: usbdevfs hub 96-111: hiddev hid On Linux-2.6.
CONFIG USB, CONFIG USB HID, CONFIG USB HIDDEV, and CONFIG USB DEVICEFS as well as at least one USB Host Controller Driver (CONFIG USB UHCI HCD [2.6.x], CONFIG USB UHCI [2.4.x], etc.). If CONFIG USB is set as M, CONFIG USB HID must be M (if enabled at all). If CONFIG USB is set as Y, CONFIG USB HID can be M or Y. hiddev, in turn, will be built however HID is. To complicate things more many Linux flavors running 2.
where you replace the [ and ] with braces and the serial number with the one that correspnds to your UPS. Some kernels ship, such as Mandrake 10, ship with CONThis is not ideal for FIG USB DYNAMIC MINORS turned on. 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 devfs.
Finally, check that appropriate USB devices exist.
If all there things check out and you still can’t see the UPS, something is more seriously wrong than this manual can cover – find expert help. If you are unable to list USB devices or drivers, you kernel may not be USB-capable and that needs to be fixed. Please check if your kernel has the three patches listed in the /examples directory. Each of the files ends with the name .patch, and at the current writing they are: linux-2.4.20-killpower.patch linux-2.4.20-USB-reject.patch linux-2.6.
FreeBSD-4.11 NetBSD-2.0 NetBSD-1.6.2 OpenBSD-3.6 FreeBSD-5.3 has had the most testing since it is the primary platform on which the driver is developed. The other platforms and versions have had somewhat less testing. The only architecture tested so far (on any platform) is i386, althought there is no reason to think it will not work on other archs. If you run the driver on a new platform version or architecture, please report your experience to the apcupsd-users mailing list.
Note that the “ugen” driver is called out. If you see “uhid” instead, it probably means you did not properly disable the uhid driver when you compiled your kernel or perhaps you’re not running the new kernel. You can also check with ’usbdevs -d’ to get a list of USB devices recognized by the system as well as the drivers they are associated with. For example: # usbdevs -d addr 1: UHCI root hub, VIA uhub0 addr 2: Back-UPS RS 1500 FW:8.g6 .
The DEVICE setting is blank on purpose; apcupsd will automatically locate your UPS. The delay-, timeout-, and NIS-related settings should be configured as per your usual preference. Building and Installing apcupsd Installation from Binary Packages Red Hat Linux: For Red Hat systems, apcupsd is available in binary RPM format. This is the simplest way to install.
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: 1. Unpack the source code from its tar archive. 2. Go into the directory containing the source code. 3. Run ./configure (with appropriate options as described below) 4. make 5. su (i.e. become root) 6.
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 cursesbased control panel. Still others enable features such as thread support. You will find a complete reference later in this chapter.
/sbin/apcupsd $ whereis apcupsd apcupsd: /sbin/apcupsd /etc/apcupsd /etc/apcupsd.conf /etc/apcupsd.status /usr/man/man8/apcupsd.8.gz /usr/man/man8/apcupsd.8 If you 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 make install to ensure that you haven’t deleted anything needed by the new apcupsd.
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 disable-install-distdir option on the ./configure command (see below for more details).
—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 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.
—enable-test This turns on a test driver that is used only for debugging. By default it is disabled. —enable-nis Turns on the Network Information Server (NIS) code within apcupsd. This is enabled by default. If you do not want to access the status of the UPS from the network and you are not controlling any slaves via NIS (enable-net), this can be disabled. —enable-pthreads This option enables pthreads support causing apcupsd to be built as a threaded program rather than forking to create separate processes.
—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. —with-nisip= This option allows you to specify the value that will be placed on then NISIP directive in the configuration file.
./configure --prefix=/usr --sbindir=/sbin --enable-usb \ --enable-pthreads and you can optionally build and install the CGI programs as follows: ./configure --prefix=/usr --sbindir=/sbin --enable-usb \ --enable-cgi --with-cgi-bin=/home/httpd/cgi-bin \ --enable-pthreads Compilers and Options Some systems require unusual options for compilation or linking that the ./configure script does not know about. You can specify initial values for variables by setting them in the environment.
Operating System Specifics 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.
DEVICE /dev/tty01 In addition, you should ensure serial port lock file in apcupsd.conf is defined as: LOCKFILE /var/spool/locks Unlike the Linux systems, the system halt routine is located in /sbin/rc0, so after the make install, please check that this file has been correctly updated. The start/stop script can be found in: /sbin/init.d/apcupsd Debian: This port is complete and is operation by several users.
single process, and thus is less efficient (consumes more CPU time) than the forking version of apcupsd. We hope to rectify this in a future version by using the FreeBSD LinuxThreads implementation of pthreads. On the FreeBSD OS, there is no known way for a user program to get control when all the disks are synced. This is needed for apcupsd to be able to issue the killpower command to the UPS so that the UPS shuts off the power.
OpenBSD to freeze up. The best solution is probably to build without pthread. However, in doing so, you must realize that the bulk of this manual assumes that pthreads is enabled, and thus many of the comments about apcaccess will not be applicable. A second solution that seems to work is to delete all calls to the email notification routines from apccontrol. In doing so, some users have succeeded in running apcupsd with pthreads.
As always, remember testing UPSes can be hazardous to you system, and, apcupsd 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.
./configure \ --prefix=/opt/apcupsd \ --sbindir=/etc/opt/apcupsd/sbin \ --sysconfdir=/etc/opt/apcupsd \ --with-cgi-bin=/opt/apcupsd/cgi-bin The way to setup the /sbin directory as the executables directory is to pass configure the 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 make.
# 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.
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.
package. We are striving to provide a useful package that works across all platforms, and welcome your feedback. Best regards, and thanks for your interest and help, The Apcupsd Development Team. Unknown System: During the ./configure, if apcupsd does not find one of the systems for which it has specific installation programs, it will set the Operating System to unknown and will use the incomplete installation scripts that are in /distributions/unknown/.
After which, you can do a: make And to install apcupsd, do: make install Finally, you should follow the Win32 (see Installation on Windows) installation instruction, skipping the part that describes unZipping the binary release. After Installation Checking Your Configuration File Once you have installed apcupsd, either from a binary package or by building from source, your next step should be to inspect your /etc/apcupsd/apcupsd.conf file to make sure it is valid.
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.
to 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 -p option for powering down the computer.
To start apcupsd manually (as you will probably do immediately following the installation), enter the following: /etc/rc.d/apcupsd start Normally, when properly installed, apcupsd will be started and stopped automatically by your system. Unfortunately, the details are different for each system. Below, we give the commands for selected systems.
Notice that we have not specified a device. In doing so, apcupsd will try all the well known USB ports. We strongly recommend you use this (empty device address) form unless you have a good reason to do otherwise. An alternate way of specifying the device is to specify a range of device addressess as follows: DEVICE /dev/usb/hid/hiddev[0-15] If you have more than one device, you may need to specify each device individually using absolute device paths. This is not, however, recommended.
Normally you would have many more configuration directives to completely customize your installation, but this example shows you the minimum required. A Simple Configuration for a Simple Signaling or Dumb If you have a simple signaling or dumb UPS such as a BackUPS, you will need to know exactly what cable you have and specify it on the UPSCABLE directive. Please see the list of UPSes versus cables in the beginning of this document for more information.
## apcupsd.conf v1.1 ## UPSCABLE smart UPSTYPE smartups DEVICE /dev/ttyS0 LOCKFILE /var/lock UPSCLASS netmaster UPSMODE net NETTIME 10 NETPORT 6666 SLAVE slave1.mynetwork.com SLAVE slave2.mynetwork.com Note, the main difference from the stand alone configuration is that you have specified UPSCLASS netmaster and UPSMODE net. In addition, you have specified one or more slave machines.
Please note, there are reports that you must use UPSTYPE smartups on the slave even if the master is using UPSTYPE dumb. This is apparently some bug in the new dumb driver. In this configuration, the shutdown will be initiated by the master. It is also possible to specify BATTERYLEVEL, MINUTES, and TIMEOUT configuration directives in the Slave machine that will cause the slave to shutdown before the master.
thing like what follows. What is important is that you get the information from an ether cable over the network and you must specify the address of a “NIS server” that is running NIS (not the Master/Slave networking described above). The NIS slave apcupsd will then poll the NIS server at the NETTIME interval you specify to obtain the status.
UPS). The :3551 that follows the NIS server address is the port to use. The default is 3551, but older versions of apcupsd used port 7000. Please do not confuse this NIS server/slave mode with the old master/slave network configuration that is described above. This is a master/slave setup, but much simpler (the NIS server does not know about the slaves), and any NIS server, even a slave, can act as a server to a slave that listens to it.
or the equivalent for your system. If you are running on Linux and using the fork()ing version of apcupsd, you should something similar to the following output. 4492 ? 4496 ? 4497 ? S S S 0:00 apcmain 0:00 \_ apcser 0:00 \_ apcnis -f /etc/apcupsd/apcupsd.conf -f /etc/apcupsd/apcupsd.conf -f /etc/apcupsd/apcupsd.conf This indicates that apcupsd is up and running and has started the two (default) child processes. If you are running with the pthreaded version, now the default, and 2.4.
Logging Test Once you have established that the proper processes are running, do a tail of the system log file, normally /var/log/messages: tail /var/log/messages You should see output that looks similar to the following: Dec 5 17:01:05 matou apcupsd[5917]: apcupsd 3.7.
in your apcupsd.conf file.
NOMOUTV NOMBATTV HUMIDITY AMBTEMP EXTBATTS BADBATTS FIRMWARE APCMODEL END APC : : : : : : : : : 115.0 24.0 N/A N/A N/A N/A N/A 6TD Fri Dec 03 16:49:25 EST 1999 For a simple signaling or dumb UPS such as BackUPS, your output will be very minimal as follows: APC : DATE : RELEASE : UPSNAME : CABLE : MODEL : UPSMODE : STARTTIME: LINEFAIL : BATTSTAT : STATFLAG : END APC : 001,012,0319 Mon Feb 18 09:11:50 CST 2002 3.8.
If you see a message to the effect of: attach_shmarea: shared memory version mismatch (or UPS not yet ready to report) or if all the displayed values are zero, you have not waited long enough. Wait a bit longer and then re-execute the apcaccess status command. If you see a message to the effect of: APCACCESS FATAL ERROR in apcaccess.c at line 336 tcp_open: cannot connect to server localhost on port 3551.
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 no (see man wall or man mesg), or there is a problem with apccontrol.
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.
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.
Now when you pull the power plug, and either the timer expires or the batteries are exhausted (see the next section for more details), the system should be fully shutdown. After performing this test, please be sure to restore /etc/apcupsd/apccontrol to its previous state. Full Power Down Test To complete the testing, you should do a power fail shutdown of your system. This test is applicable to all UPS models.
look at the “Shutdown grace delay”. Shutdown Sequence If you experienced so problems with the above testing procedures, or if you are porting apcupsd to another system, or you are simply curious, you may want to know exactly what is going on during the shutdown process. If so, please see the Shutdown Sequence (see Shutdown Sequence <1>) section of this manual.
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.
should some how become disconnected during the test. Item 5 is used to program the EEPROM. Please see the 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.
Power Off (killpower) of UPS Does Not Work: 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. apcupsd Cannot Reconnect After a Reboot: If apcupsd does not connect to the USB port when you reboot, it is probably the appropriate kernel modules are not getting loaded correctly.
you to do this include one command-line utility (apcaccess) and a GUI you can use through a Web browser. You can also use apctest to tune some parameters of the UPS itself. apcaccess apcaccess is a program (normally found in /sbin/apcaccess) that permits you to print out the complete status of your UPS. Although there are a number of command line arguments (eprom, reconfig, status, slave, shutdown), all except eprom and status are under development and hence do not work reliably.
which means that apcaccess can access any UPS on the network running the Network Information Server. The status command line option of apcaccess will produce a full printout of all the STATUS variables used by apcupsd. This can be very helpful for checking the condition of your UPS and to know whether or not apcupsd is properly connected to it. For a complete description of the variables and their meanings, please read the Status Format (see apcupsd Status Logging) section of the Technical Reference.
LOADPCT BATTV BCHARGE MBATTCHG TIMELEFT MINTIMEL SENSE DWAKE DSHUTD LOTRANS HITRANS RETPCT STATFLAG STATUS ITEMP ALARMDEL LASTXFER SELFTEST STESTI DLOWBATT DIPSW REG1 REG2 REG3 MANDATE SERIALNO BATTDATE NOMOUTV NOMBATTV HUMIDITY AMBTEMP EXTBATTS BADBATTS FIRMWARE APCMODEL END APC : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : 11.4 Percent Load Capacity 27.7 Volts 100.0 Percent 5 Percent 112.0 Minutes 3 Minutes Low 060 Seconds 180 Seconds 204.0 Volts 253.0 Volts 050.
ted values that can be set in the EPROM. For information about changing these values, see the section on tuning EEPROM parameters (see Configuring Your EEPROM).
hid-ups and USB Specific Information The UPS has an internal set of timers and remaining capacity counters, which it uses to determine when to shutdown. These are in addition to the apcupsd counters BATTERYLEVEL and MINUTES. As a consequence, apcupsd will shutdown on the 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.
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: MONITOR matou "Server" MONITOR polymatou "Backup server" MONITOR deuter "Disk server" matou, polymatou, and deuter are the network names of the three machines currently running apcupsd.
Content-type: text/html
multimon.cgi: This program monitors multiple UPSes at the same time. A typical output of multimon.cgi as displayed in your Web browser might look like the following: The machines monitored as well as the values and their column headings are all configurable (see /etc/apcupsd/hosts.conf and /etc/apcupsd/multimon.conf) upsstats.cgi: By clicking on the system name in the multimon.cgi display, you will invoke upsstats.
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: ./upsstats.cgi: As with multimon, quite a few lines of html should then be displayed. upsfstatus.
LASTXFER SELFTEST STESTI DLOWBATT DIPSW REG1 REG2 REG3 MANDATE SERIALNO BATTDATE NOMOUTV NOMBATTV HUMIDITY AMBTEMP EXTBATTS BADBATTS FIRMWARE APCMODEL END APC : : : : : : : : : : : : : : : : : : : : U command or Self Test NO 336 02 Minutes 0x00 Dip Switch 0x00 Register 1 0x00 Register 2 0x00 Register 3 01/11/99 GS9903001147 01/11/99 230.0 24.0 N/A N/A 0 N/A 60.11.I IWI Thu Dec 02 17:27:25 CET 1999 You should get pretty much the same output mixed in with html if you execute upsfstats.
Where host is the name of the host or the IP address of the host running the Network Information Server. The default is the local host. You may optionally specify a port address separated from the host name with a colon. You may also optionally specify a single command to be executed. If you specify a command, that command will be executed and the client program will exit. This is a very simple and useful way of pulling the status or events data into another program such as Perl.
Credits: Many thanks go to Russell Kroll who wrote the CGI programs to work with his UPS Monitoring system named Network UPS Tools (NUT). Thanks also to Jonathan Benson for initially adapting the upsstatus.cgi program to work with apcupsd. We have enhanced the bar graph program and hope that our changes can be useful to the original author in his project. Security Issues: • apcupsd runs as root. • If you have NETSERVER ON in your apcupsd.
Configuring Your EEPROM If you have a SmartUPS, there are depending on the UPS at least 12 different values stored in the EEPROM that determine how the UPS reacts to various conditions such as high line voltage, low line voltage, power down grace periods, etc. In general, for the moment, we do not recommend that you change your EEPROM values unless absolutely necessary. There have been several reported cases of problems setting the Low Transfer Voltage.
Lower transfer voltage Return threshold Output voltage on batts Sensitivity Low battery warning Shutdown grace delay Alarm delay Wakeup delay Self test interval LOTRANSFER RETURNCHARGE OUTPUTVOLTS SENSITIVITY LOWBATT SLEEP BEEPSTATE WAKEUP SELFTEST 196 0 230 H 2 20 0 0 336 196 188 208 00 15 50 90 230 240 220 H M L L 02 05 07 10 020 180 300 0 T L N 000 060 180 336 168 ON 204 225 600 300 OFF where the Current Value will depend on how your UPS is configured, and the Permitted Values will depend on what U
4) 5) 6) 7) Monitor Battery Calibration progress Program EEPROM Enter TTY mode communicating with UPS Quit Select function number: You might want to run option 1) just to ensure that apctest is properly talking to your UPS. It will produce quite about 70 lines of output. To program the EEPROM, select option 5), and you will get the EEPROM menu as follows: This is the EEPROM programming section of apctest. Please select the function you want to perform.
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
found that it takes several discharge/charges before the runtime calibration is accurate. Take care not to discharge your battery too much as it tends to shorten the battery life. What Various People Have to Say about Batteries Here is what John Walker has to say about APC UPS batteries: I thought I’d pass on some information I’ve obtained which you’ll probably eventually need. Besides, by writing it down I’ll be able to find it the next time. I started installing mine in 1995-1996.
Newport Beach CA 9266? Tel: +1 714 548-5259 J-W Batteries, Inc. Tel: +1 714 548-4017 WPS 49-1200 GEL-CELL KB-35 BATTERY For those that do not know what this means........ I found the best battery for APCC UPS products that use In the two systems below: SMART-UPS 3000 10.9% is running at 327W runs for 47.0 min. Smart-UPS 1250 22.3% is running at 279W runs for 54.0 min. APCUPSD UPS Network Monitor Thu Jan 18 21:55:36 PST 2001 System Model Status Battery Chg Utility UPS Load UPS Temp Batt.
The 1250 can outrun the 3000 by a factor of two under identical percentages, or run head to head for the same time. SMART-UPS 3000 is a 48V based or 4 batteries. Smart-UPS 1250 is a 24V based or 2 batteries. Cheers, Andre Hedrick Linux ATA Development Finally, here is what Carl Erhorn has to say about batteries: Hi, Folks. Well, Kern was absolutely right. The problem with my UPS was batteries.
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.
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.
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.
Where Carl Suggests You Get Batteries Hi, Folks. I’m just replacing the batteries in one of my SmartUPS models, and it occurs to me that some of you may not know about the place I get them from. I have no relationship with this company, other than as a customer, but I feel they know what they are doing, their prices are fair, and they have some interesting batteries available that you can’t obtain from APC.
and have never been disappointed. The owner of the place also is very good on technical issues, so if you have questions on their products, he can get as technical as you need to go. Regards, --Carl Here is a link to the APC Battery Store. Frequently-Asked Questions See the bugs section of this document for a list of known bugs and solutions. Q: Why all the craziness with custom serial cables? A: It was nothing more nor less than a form of customer control.
Q: Does apcupsd support Windows? A: With release 3.8.0, apcupsd now runs on Win95/98, WinMe, WinNT, and Win2000 machines. All features of the Unix versions of apcupsd are implemented. The UPS EEPROM programming features of apcupsd have not been tested under Windows. Version 3.8.0 does not support simple signaling UPSes (BackUPS, etc). Version 3.8.1 does support most simple signaling UPSes, but not all cables (due to deficiencies in the Windows serial port API).
A: No, the error is not serious. Unfortunately, the documentation in the area of master/slaves is not very detailed, and for that reason, your slave setup is not totally correct as explained below. On master machines, we modify /etc/rc.d/init.d/halt to re-invoke apcupsd with the --killpower option (actually the script apccontrol is called). This causes the UPS to send the codes to the UPS to make it power off. On slave machines, these modifications should not be made to the /etc/rc.d/init.
A: This problem and the problem of cannot create shm area are due to the fact that the shared memory key that apcupsd wants to use is already in use. This happens most frequently when there is an old zombie apcupsd process still in the system. The solution is to remove the old process. You can often see what is going on by doing a: ipcs command as root when apcupsd is not running. If you see a segment with the key 0x10feed01, you can be sure there is some old apcupsd process still using it.
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. Q: How do I ensure that my database server is correctly shutdown? 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.
Q: When using USB, I get the following log messages: usb-uhci.c: interrupt, status 3, frame# 826. What does it mean? 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. Q: apcnisd doesn’t work. It always gives: FATAL ERROR in apcipc.c at line 497.
Apcupsd Bugs Unfortunately, it seems that every program has some bugs. We do our best to keep the bugs to a minimum by extensive testing. However, because of our inherent nature to occasionally overlook things and the fact that we don’t have all the UPS models nor the APC documentation on those models, apcupsd will have some bugs. As the bugs become known to us, we will post them on the bug tracking system at SourceForge.
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 where: event is the event that occurred and it may be any one of the values described in the next section. ups-name is the name of the UPS as specified in the configuration file (not the name in the EEPROM). For version 3.8.
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 printf ‘‘Warning serial port communications with UPS lost.’’ | wall then exits. commok After a commfailure event is issued, when the communications to the computer is re-established, this event will be generated. Default — does a printf ‘‘Serial communications with UPS restored.’’ | wall then exits.
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 printf ‘‘Power failure. batteries.’’ | wall then exits. Running on UPS offbattery This event is generated when the mains return only if the onbattery event has been generated. Default — does nothing.
Does a printf ‘‘UPS battery runtime limit exceeded. Doing shutdown.\n’’ | wall then exits. After completing this event, apcupsd will immediately initiate a doshutdown event. 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.
port), which is called the master, can provide information to other machines powered by the UPS, called slaves. When the master detects a power failure, it will notify all the slaves (maximum of twenty). If the master detects that the battery is low, it will also notify the slave so that the slave may perform a shutdown. In addition, in cases where you wish to keep the master up longer than the slave, you can configure the slave to shut down in a predetermined time after the UPS goes on batteries.
networking is considerably different from the old method described at the beginning of this chapter. In the old code, there is a lot of configuration on both the master and slave side, and the master polls or sends info to the slave. Using the net driver is much simpler. However, you should carefully check that the NIS slave does a proper shutdown. In the master/slave code, the master ensures the best it can that the slave is shutdown or notified before it shuts down itself.
Network Problems with Master/Slave or Server/Slave Configurations When working with a master/slave or server/slave configurations (one UPS powering more than one computer), the master/server and slave communicate via the network. In many configurations, apcupsd is started before the network is initialized. In this case, it is possible that the master will be unable to contact the slave. On apcupsd versions prior to 3.8.0, this could cause apcupsd to error off.
same. Please be sure you are running the same version of apcupsd on all your master and slave machines. to slave SSS failed This message is logged when the master attempts to connect to slave SSS and no connection is accepted. The most common cause of this problem is that the slave copy of apcuspd is not yet ready to accept connections or is not running. Generally, apcupsd will retry the connection a bit later.
attempt from master MMM The master named MMM (probably an IP address) contacted the slave but MMM is not the master that was listed on the MASTER configuration directive in /etc/apcupsd.conf, and consequently, it is not authorized to communicate with the slave. Please check that your MASTER and SLAVE names in your slave and master configuration files respectively are correct. failure from socket The slave got an error reading the socket open to the master. This indicates a fundamental networking problem.
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 Configuration types.). 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.
./configure \ --prefix=$HOME/apcupsd/bin \ --sbindir=$HOME/apcupsd/bin \ --enable-cgi \ --with-cgi-bin=$HOME/apcupsd/bin \ --with-log-dir=$HOME/apcupsd/bin \ --with-pid-dir=$HOME/apcupsd/bin \ --sysconfdir=$HOME/apcupsd/bin \ --with-lock-dir=$HOME/apcupsd/bin \ --with-pwrfail-dir=$HOME/apcupsd/bin \ --with-serial-dev=/dev/ttyS1 \ --enable-pthreads \ --with-nis-port=7001 \ --disable-install-distdir Note, in this case, we use considerably more configuration options to ensure that the system files are placed
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.
• The read-write community string, usually it is “private” for read-write access. Building and Installing apcupsd Follow the instructions in Building and Installing apcupsdl, being sure to include the following options (in addition to any others you need) on the ./configure line: .
parameter to 180 seconds or more, depending on how much time your system shutdown requires to umount all the filesystems. • Change /etc/rc.d/apcupsd script adding the ’—kill-on-powerfail’ to the apcupsd invocation. • Restart your apcupsd With this setup your UPS operations should be safe. Alternate Ways To Run The Network Information Server apcupsd maintains STATUS and EVENTS data concerning the UPS and its operation.
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.
Next, you must modify /etc/inetd.conf to have the following line: apcnisd stream tcp nowait root /usr/sbin/tcpd /sbin/apcnisd -i If you do not want to run the TCP wrapper, then the line should be entered as follows (not tested): apcnisd stream tcp nowait root /sbin/apcnisd -i Please check that the file locations are correct for your system. Also, note that the -i option is necessary so that apcnisd knows that it was called by INETD.
/sbin/apcnisd The advantage of running the network information server standalone is that if for some reason, a client causes the network server to crash, it will not affect the operation of apcupsd. apcupsd System Logging The apcupsd philosophy is that all logging should be done through the syslog facility (see: man syslog).
For more details on STATUS logging, see the Status apcupsd Status Logging) section of the Technical Reference. (see 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 Customizing Event Handling) for more details.
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.
Installation: Windows The Windows Version of apcupsd The Windows version of apcupsd has been tested on Win95, Win98, WinMe, WinNT, WinXP, and Win2000 systems. This version of apcupsd has been built to run under the CYGWIN environment, which provides many of the features of Unix on Windows systems. It also permitted a rapid port with very few source code changes, which means that the Windows version is for the most part running code that has long proved stable on Unix systems.
• When Zip says that it has one file and asks if it should unpack it into a temporary file, respond with Yes.
If you wish to install the package elsewhere, please note that you will need to proceed with a manual installation, which is not particularly easy as you must rebuild the source and change the configuration file as well. This installation assumes that you do not have CYGWIN installed on your computer. If you do, and you use mount points, you may need to do a special manual installation. Once you have unzipped the binaries, open a window pointing to the binary installation folder (normally c:\apcupsd).
multi(0)disk(0)rdisk(0)partition(1)\WINNT=“Windows NT Workstation Version 4.00” and add the following to the end of the line: /NoSerialMice:COM1 (or COM2 depending on what you want to use). The new line should look similar to: multi(0)disk(0)rdisk(0)partition(1)\WINNT=“Windows NT Workstation Version 4.00” /NoSerialMice:COM1 where the only thing you have changed is to append to the end of the line.
What is important to verify in the DOS window is that the root directory \ is mounted on device c:\.
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 Startup... button to ensure that the correct defaults are set. The dialogue box that appears should have Startup Type set to Automatic and Logon should be set to System Account with Allow Service to Interact with Desktop checked. If these values are not set correctly by default, please change them otherwise apcupsd will not work.
charged, the plug icon will become a plug with a lightning bolt in the middle to indicate that the battery is charging. Installation Directory The Win32 version of apcupsd must reside in the c:\apcupsd\ directory, and there must be a c:\tmp directory on your machine. The installation will do this automatically, and we recommend that you do not attempt to place apcupsd in another directory. If you do so, you are on your own, and you will need to do a rebuild of the source.
running version of apcupsd, through the Services dialogue in the Control Panel, first click on the Stop button: then click on the Startup ... button, and in the Startup dialogue select the Disabled button to disable apcupsd: After closing the dialogues, reboot the system, typical of Microsoft :-(. When the system comes back up, apcupsd will not be automatically launched as a service, and you can install the new version.
automatic service, using the Control Panel: reset apcupsd to Automatic startup in the Startup dialogue, then restart apcupsd in the Services dialogue as shown above in the installation instructions. Frequently after an upgrade, you will click on the Start button and after a few seconds, the system reports that it failed to start. The cause of this problem is unknown, but the solution is simply to click again on the Start button.
and stopping apcupsd do not work. Use the services control panel instead. On Win95 systems, there are reports that the PIF files do not work. If you find that to be the case, the simplest solution is to use the batch files that we have supplied in the c:/apcupsd/bin directory. Also, on Win95 systems, we have an unconfirmed report that indicates that apcupsd does not start automatically as a service even though the Registry has been properly updated.
The functions of Stop, ups-events, and ups-status can be more easily invoked by right clicking on the apcupsd icon in the system tray and selecting the desired function from the popup menu. Disclaimer Some of the features such as EEPROM programming have not been exhaustively tested on Win32 systems. If at all possible, we recommend not to use it as a network master on Win95, Win98, and WinMe due to the instability of those operating systems.
Email Notification of Events 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).
c:\apcupsd\apcupsd.exe /service found under the key: HKEY_LOCAL_MACHINE Software\Microsoft\Windows\CurrentVersion\RunServices to c:\apcupsd\apcupsd.exe /service -p 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.
Command Line Options Specific to the Windows Version 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.
Installation: Serial-Line UPSes Overview of Serial-Interface UPSes If you have a UPS that communicates via serial port, you need to do two things before you can even think about configuring the software. First, you need to figure out whether it’s a dumb (voltage-signalling) UPS or speaks the apcsmart protocol (see this discussion (see 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.
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.
When using this cable with apcupsd specify the following in apcupsd.conf: If you have an OS that requires DCD or RTS to be set before you can receive input, you might try building the standard APC Smart 940-0024C cable listed below. UPSCABLE smart UPSTYPE apcsmart DEVICE /dev/ttyS0 (or whatever your serial port is) If you wish to build the standard cable furnished by APC (940-0024C), use the following diagram.
CUSTOM-RJ45 CABLE Signal Computer UPS DB9F RJ45-8 RxD 2 ---------------- 1 TxD 3 ---------------- 7 GND 5 ---------------- 6 FG Shield ---------------- 3 UPS RJ45-10 2 TxD Send 8 RxD Receive 7 Ground 4 Frame Ground The RJ45-8 pins are: looking at the end of the connector: 8 7 6 5 4 3 2 1 ___________________ | . . . . . . . . | | | ------------------|____| The RJ45-10 pins are: looking at the end of the connector: 10 9 8 7 6 5 4 3 2 1 _______________________ | . . . . . . . . . .
Voltage-Signalling Cable for “dumb” UPSes NOTE. YOU DO NOT HAVE THIS CABLE UNLESS YOU BUILT IT YOURSELF. THE SIMPLE-CUSTOM CABLE IS NOT AN APC PRODUCT. For “dumb” UPSes using voltage signalling, if you are going to build your own cable, we recommend to make the cable designed by the apcupsd team as follows: SIMPLE-CUSTOM CABLE Signal Computer UPS DB9F 4.
5. Double check your work. We use the DTR (pin 4 on the female connector) as our +5 volts power for the circuit. It is used as the Vcc pull-up voltage for testing the outputs on any “UPS by APC” in voltage-signalling mode. This cable may not work on a BackUPS Pro if the default communications are in apcsmart mode. This cable is also valid for “ShareUPS” BASIC Port mode and is also reported to work on SmartUPSes. However, the Smart Cable described above is much simpler.
n/c | 1 | Frame/Case Gnd (optional) | 9 | 22 Note: the <- and -> indicate the signal direction. Optional connections of original SIMPLE-CUSTOM specification that are not used. DTR 4 RxD 2 4.7K ohm --[####]--* | ----------*--------- Note needed 3 Not used by Apcupsd When using this cable with apcupsd specify the following in apcupsd.
Voltage Signalling Features Supported by Apcupsd for Various Cables The following table shows the features supported by the current version of apcupsd (3.8.5 or later) for various cables running the UPS in voltagesignalling mode.
Note 2: the same as note 1 except that the line is normally closed, and opens when the line voltage fails. The Back-UPS Office 500 signals The Back-UPS Office UPS has a telephone type jack as output, which looks like the following: Looking at the end of the connector: 6 5 4 3 2 1 _____________ | . . . . . .
analysis) indicates that this cable under the right conditions may provide the Low Battery signal. This is to be confirmed. APC Part# - 940-0020B Signal Computer UPS DB9F DB9M CTS 8 -------------------- 2 On Battery DTR 4 -------------------- 1 Kill power GND 5 ---------------*---- 4 Ground | --*---- 9 Common DCD 1 ----|///|----------5 Low Battery |\\\| RTS 7 ----|///| (probably a --semi-conductor) Thanks to Lazar M. Fleysher.
940-0023A Cable Wiring: This diagram is for informational purposes and may not be complete, we don’t recommend that use it to build you build one yourself. This cable can only be used on voltage-signalling UPSes, and apparently only provides the On Battery signal. As a consequence, this cable is pretty much useless, and we recommend that you find a better cable because all APC UPSes support more than just On Battery. Please note that we are not sure the following diagram is correct.
SHUTDOWN (1) | B | *-------| 2N3906 PNP | |\ \ C | | *----< DCD (1) | | R 4.7k 3 | 4.7k | >----------*----R4----*----< TxD (3) | | 1N4148 *----K|---------< RTS (7) Low Batt Shutdown POWER-FAIL (2) >--------------------------< RxD,RI (2,9) On Batt GROUND (4,9) >--------------------------< GND (5) Operation: * DTR is "cable power" and must be held at SPACE. DSR or CTS may be used as a loopback input to determine if the cable is plugged in. * DCD is the "battery low" signal to the computer.
940-0095B Cable Wiring: This diagram is for informational purposes and may not be complete, we don’t recommend that use it to build one yourself. APC Part# - 940-0095B Signal Computer UPS DB9F DB9M DTR 4 ----* CTS 8 ----| DSR 6 ----| DCD 1 ----* GND 5 ---------------*---- 4 | *---- 9 RI 9 ----* | RxD 2 ----*--------------- 2 TxD 3 ----------[####]---- 1 4.
BackOffice ES: The BackUPS ES has a straight through serial cable with no identification on the plugs. To make it work with apcupsd, specify the UPSCABLE 940-0119A and UPSTYPE backups. The equivalent of cable 940-0119A is done on a PCB inside the unit.
The solution to the problem (thanks to Tom Suzda) is to unplug the UPS and while it is still chattering, press the power button (on the front of the unit) until the unit beeps and the chattering stops. After that the UPS should behave normally and power down 1-2 minutes after requested to do so. An amazing discovery by slither man allows one to build a CUSTOM-RJ45 cable (documented above) and run the BackUPS CS (and probably also the ES) in Smart mode.
_______________________ | . . . . . . . . . . | | | ----------------------|____| From Jan Babinski jbabinsk at pulsarbeacon dot com: (many thanks) The BackUPS XS1000(BX-1000) ships with the 940-0127B usb cable and the optional 940-0128D serial cable. I’m trying to get it running under OpenBSD so usb is out of the question. I’ve tried smart serial with the custom cable, but that’s not working, so I’m stuck with dumb serial over 940-0128D.
(Shield)--------------------------(4)Chassis GND Cable 940-0127B USB(Computer) _________ | = = = = | |_________| (1) (4) RJ45-10(UPS) ____________ [ oooooooooo ] [____________] (10) [_] (1) +5V(1)-----------(1)+5V DATA+(2)-----------(9)DATA+ DATA-(3)-----------(10)DATAGND(4)-----------(7)Signal GND (Shield)-----------(4)Chassis GRND Win32 Implementation Restrictions for Simple UPSes Due to inadequacies in the Win32 API, it is not possible to set/clear/get all the serial port line signals.
condition = serial port initialization cable = 0095A, 0095B, 0095C action = ioctl(TIOMBIC, RTS) clear RTS (set PnP mode) cable = 0119A, 0127A, 0128A action = ioctl(TIOMBIC, DTR) action = ioctl(TIOMBIS, RTS) clear DTR (killpower) set RTS (ready to receive) apcserial.
action = ioctl(TIOMCBIS, DTR) set DTR (kills power) RS232 Wiring and Signal Conventions DB-25 Pin # 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 DB-9 Pin # — 3 2 7 8 6 5 1 — — — — — — — — — — — 4 — 9 — — — Name FG TD RD RTS CTS DSR SG DCD — — QM SDCD SCTS STD TC SRD RC DCR SRTS DTR SQ RI — — TC DTE-DCE Description – Frame Ground/Chassis GND –> Transmitted Data, TxD <– Received Data, RxD –> Request To Send <– Clear To Send <– Data Set Ready –— Signal Ground, GND <– Data Carrier Dete
The diagram above represents the Female end of the cable. The male end is the same, but looking from inside the cable. DTE DCE RxD TxD DTR DSR RTS CTS RI DCD : : : : : : : : : : Data Terminal Equipment (i.e. computer) Data Communications Equipment (i.e.
to cause premature shutdowns of the UPS power, we 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.
• Make sure you are doing your testing as root otherwise, you may have permissions problems accessing the serial port. • You may have cabling problems, either with an incorrect cable, or the incorrect cable specification directive in the configuration file. • 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 After Installation.
• 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. • Try doing an lsof /dev/ttyS0 where you replace the /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. • Try doing a dmesg | grep tty.
Using apctest on Serial-Line UPSses On an apcsmart serial-line UPS, apctest will give you access to the battery of low-level tests we described in 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.
3) 4) 5) 6) 7) 8) 9) Test 3 - no power Test 4 - low battery (requires test 3 first) Test 5 - battery exhausted Test 6 - kill UPS power Test 7 - run tests 1 through 5 Guess which is the appropriate cable quit Select test number: 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.
Expected apctest Signals for a BackUPS Pro: If you have configured your UPS as: UPSTYPE backupspro UPSCABLE APC_940_0095A or APC_940_0095C here are the typical signals you would expect to see in the output from the various tests of apctest: Test Test Test Test 1 2 3 4 normal: no serial cable: no AC power: batteries exhausted: RTS not set not important RNG RNG and CD Note: RTS should never be set in any of the tests as it is the killpower signal.
Testing Apcupsd) section. One additional note applies: 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.
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. • when you are sure you are properly connected send an upper case D (no cr).
MAINS : LineVoltageState LASTEVNT : LastEventObserved BackUPS and NetUPS Simple Signals LINEFAIL : OnlineStatus BATTSTAT : BatteryStatus DATA Logging This feature is somewhat outdated and not often used. Data logging consists of periodically logging important data concerning the operation of the UPS. For the definitive definition of the format, see log data() in apcreports.c. The format varies according to the UPS model and the information available from the UPS.
Technical Reference Configuration Directive Reference 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. General Configuration Directives In general, each of these directives is required (ecept that the DEVICE directive is ignored for UPSCABLE ether).
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 UPSTYPE snmp, then the device name becomes hostname:vendor:community. Please see the SNMP chapter (see Support for SNMP UPSes) in this manual for more details. LOCKFILE This option tells apcupsd where to create a lockfile for the USB or serial port in the specified directory.
NISPORT 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 --with-nis-port= option of the ./configure program during the build.
and means that the default values do not generate annoy messages: KES). Note that if NOLOGON is set to disable the annoy messages will also be disabled. ANNOYDELAY
minutes specifies that apcupsd should prohibit logins when the remaining runtime in minutes reaches 110% or less than the value specified on the MINUTES configuration directive. Thus if MINUTES is set to 3, apcupsd will prohibit logins when the remaining runtime is less than 3 minutes (3 X 110% = 3). always causes apcupsd to immediately prohibit logins when a power failure occurs. This will also enable the ANNOY feature.
the slaves to perform a shutdown then apcupsd will sleep for 30 seconds before issuing the shutdown of its own computer. If you need the master to wait additional time before shutting down (to allow for shutdown of slower slaves or of slaves running software that requires more time to shutdown – e.g. databases), you can do so by adding additional sleep() commands to /etc/apcupsd/apccontrol in each case that causes a shutdown. TIMEOUT, BATTERYLEVEL, and MINUTES can be set together without problems.
the Data (see DATA Logging) section of this manual for additional details. FACILITY The facility directive can be used to change the system logging class or facility. The default is 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.
where there are no other computers dependent on power from the same UPS. This is the normal case. Use netmaster, if and only if you have a serial port connection to the UPS and there are other machines deriving power from the same UPS. This is required in all master configuration files. Use netslave if and only if you have no serial port connection to the UPS, but you derive power from it. This is required in all slave configuration files, and in this case, you will also have UPSCABLE set to ether.
MASTER for slave machines. Used in slave configuration files, this is the network name of the master which is authorized to send commands to this slave. In all cases (of which I am aware), when you specify a MASTER directive, you will also specify UPSCABLE ether since your information about the UPS will come via the network from a master.
SLAVE directives be put in your /etc/hosts file so that apcupsd will be able to resolve the machine name during startup and shutdown even if DNS is not running. Alternatively, you can use IP addresses on the MASTER and SLAVE directives, but this is less flexible. USERMAGIC < user defined magic> used only in SLAVE configuration files. The USERMAGIC directive is a sort of password that gives a second level of identification security in a slave configuration file.
Under normal apcupsd operations (no --configure option), apcupsd will read the value stored in the UPS and display it in the STATUS output. WAKEUP 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.
RETURNCHARGE 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 apcaccess eeprom to show you which values are permitted. This value is written to the UPS EPROM when the --configure option is specified.
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.
MODEL : UPSMODE : STARTTIME: UPSNAME : STATUS : LINEV : LOADPCT : BCHARGE : TIMELEFT : MBATTCHG : MINTIMEL : MAXTIME : MAXLINEV : MINLINEV : OUTPUTV : SENSE : DWAKE : DSHUTD : DLOWBATT : LOTRANS : HITRANS : RETPCT : ITEMP : ALARMDEL : BATTV : LINEFREQ : LASTXFER : NUMXFERS : XONBATT : TONBATT : CUMONBATT: XOFFBATT : SELFTEST : STESTI : STATFLAG : DIPSW : REG1 : REG2 : REG3 : MANDATE : SERIALNO : BATTDATE : NOMOUTV : NOMBATTV : HUMIDITY : AMBTEMP : EXTBATTS : BADBATTS : FIRMWARE : APCMODEL : END APC : SMART
Status Report Fields The meaning of the above variables are: 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. DATE is the date and time that the information was last obtained from the UPS. HOSTNAME is the name of the machine that collected the UPS data. RELEASE is the apcupsd release number. CABLE is the cable as specified in the configuration file.
MAXLINEV is the maximum line voltage since the last STATUS as returned by the UPS. MINLINEV is the minimum line voltage since the last STATUS as returned by the UPS. OUTPUTV is the voltage the UPS is supplying to your equipment. SENSE is the sensitivity level of the UPS to line voltage fluctuations. DWAKE is the amount of time the UPS will wait after a power off condition when the power is restored.
XOFFBATT time and date of last transfer from batteries, or N/A. 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). STESTI is the interval in hours between automatic self tests. STATFLAG status flag. English version is given by STATUS. DIPSW is the dip switch settings.
Logging the STATUS Information 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.
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.
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: # See if this is a powerfail situation.
The output should look something like the following: apcaccess eeprom Valid EPROM values for the SMART-UPS 1000 Config Current Permitted Description Directive Value Values =================================================================== Upper transfer voltage HITRANSFER 253 253 264 271 280 Lower transfer voltage LOTRANSFER 196 196 188 208 204 Return threshold RETURNCHARGE 0 00 15 50 90 Output voltage on batts OUTPUTVOLTS 230 230 240 220 225 Sensitivity SENSITIVITY H H M L L Low battery warning LOWBATT 2
Configuration section of this manual for more information. See the EEPROM (see Configuring Your EEPROM) of this manual for further details on how to change these EPROM values. 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.
Startup Normally, apcupsd is automatically started when your system is rebooted. This normally occurs because the startup script apcupsd is linked into the appropriate places in /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 make install scripts, or it is explicitly done for those systems that do not have chkconfig(8).
and information graciously supplied by APC. Hopefully, the additions made herein can benefit the original author and his programming project, and maybe some day, the apcupsd project and the NUT project can join forces. 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.
diagram are used to keep PowerChute happy by allowing cable detection. If you use the 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 Cables) in this manual. The Smart Protocol Despite the lack of official information from APC, this table has been constructed. It’s standard RS-232 serial communications at 2400 bps/8N1.
E Automatic self test intervals F G Line frequency, Hz Cause of transfer K—K Shutdown with grace period (set with ’p’) - need > 1.
X Results of last self test Y Z—Z Enter smart mode Shutdown immediately (no delay) - need > 1.5s between first and second Z Show protocol version.alert messages.
p q r s Shutdown grace delay, seconds Low battery warning, minutes Wakeup delay (time) - seconds Sensitivity u t x Upper transfer voltage Measure-UPS: ambient temperature (degrees C) Last battery change y Copyright notice z + Reset the EEPROM to factory settings (but not ident or batt replacement date) Not on SmartUPS v/s or BackUPS Pro Capability cycle - Capability cycle @nnn Shutdown (after delay ’p’) with delayed wakeup of nnn tenths of an hour (after ’r’ time) Abort shutdown - use to abort @
7 8 9 > Dip switch positions (if applicable) Register #3 Line quality Number of external battery packs attached Matrix UPS (and possibly Symmetra) specific commands ˆ Run in bypass mode < Number of bad battery packs / Load current \ Apparent load power ˆV Output itable) ˆL Front panel language w Run time conservation voltage selection 192 (ed- See below See below “FF” acceptable, “00” unacceptable SmartCell models: “nnn” where nnn is how many external packs are connected Non-SmartCell un
Dip switch info Bit 0 Switch 4 1 2 3 2 3 4-7 1 - Option when bit=1 Low battery alarm changed from 2 to 5 mins. Autostartup disabled on SU370ci and 400 Audible alarm delayed 30 seconds Output transfer set to 115 VAC (from 120 VAC) or to 240 VAC (from 230 VAC) UPS desensitized - input voltage range expanded Unused at this time Status bits This is probably the most important register of the UPS, which indicates the overall UPS status.
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. 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.
Register 1 All bits are valid on the Matrix UPS. SmartUPS models only support bits 6 and 7. Other models do not respond.
= messages.
I == International A == Asia ?? J == Japan ?? 230 Volts 100 Volts 100 Volts Interpretation of the New Firmware Revision 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.
It looks bizarre and ugly, but is easily parsed. The # is some kind of marker/ident character. Skip it. The rest fits this form: • Command character - use this to select the value • Locale - use ’b’ to find out what yours is (the last character), ’4’ applies to all • Number of choices - ’4’ means there are 4 possibilities coming up • Choice length - ’3’ means they are all 3 chars long Matrix-UPS models have ## between each grouping for some reason.
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. 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: Item 1. 2. 3. 4. 5. 6. 7. 8. 9. 10. 11. 12.
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 , Andre M. Hedrick , Christopher J. Reimer , Kevin D. Smolkowski , Werner Panocha , Steven Freed, Russell Kroll. additions by: Kern Sibbald
rpmbuild -ba --define "build_rh7 1" apcupsd.spec rpmbuild --rebuild --define build_rh7 1" apcupsd-x.x.x-x.src.rpm How do I control whether usb support gets built? By default standard serial port support will be built and the apcupsd-std package will be produced. To get the usb package and support either set the %define usb 0 to %define usb 1 in the spec file directly or pass it to rpmbuild on the command line: rpmbuild -ba --define "build_rh7 1" --define "build_usb 1" apcupsd.
in your home directory (or edit the file if it already exists) and add the following line: %_topdir /home/myuser/redhat Credits 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. Contributors Current Code Maintainer and Project Manager: Kern Sibbald (kern at sibbald dot com) RPM Packager: D.
Caldera: John Pinner (john at clocksoft.com) HP-UX Port Carl Erhorn (Carl Erhorn at hyperion.com) Robert K Nelson (rnelson at airflowsciences.com) SOLARIS Port: Carl Erhorn (Carl Erhorn at hyperion.com) OpenBSD Port: Devin Reade (gdr at gno.org) NetBSD Port: Neil Darlow (neil at darlow.co.uk) Win32 Port: Kern Sibbald (kern at sibbald dot com) Paul Z. Stagner (paul.stagner at charterco.com) testing WEB Interfaces: Kern Sibbald (kern at sibbald dot com) Joseph Acosta (joeja at mindspring.
Project Discussions: APCUPSD Mailing List 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.
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.
# 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_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
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.
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.
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
| | |__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.
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.
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.
S: C:* I: E: E: E: Product=Peracom USB to Serial Converter #Ifs= 1 Cfg#= 1 Atr=a0 MxPwr=100mA If#= 0 Alt= 0 #EPs= 3 Cls=00(>ifc ) Sub=00 Prot=00 Driver=serial Ad=81(I) Atr=02(Bulk) MxPS= 64 Ivl= 16ms Ad=01(O) Atr=02(Bulk) MxPS= 16 Ivl= 16ms Ad=82(I) Atr=03(Int.
### END ### Interpretation of /proc/bus/usb info on 2.6 kernels: /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.
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.
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.
| |__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.
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.
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.
C:* I: E: E: E: #Ifs= 1 Cfg#= 1 Atr=a0 MxPwr=100mA If#= 0 Alt= 0 #EPs= 3 Cls=00(>ifc ) Sub=00 Prot=00 Driver=serial Ad=81(I) Atr=02(Bulk) MxPS= 64 Ivl= 16ms Ad=01(O) Atr=02(Bulk) MxPS= 16 Ivl= 16ms Ad=82(I) Atr=03(Int.
### END ### 222
Index /about , 129 /events , 129 /help , 129 /install , 129 /kill , 129 /remove , 129 /run , 129 /service , 129 /servicehelper , 129 /status , 129 —disable-install-distdir , 33 —enable-apcsmart , 31 —enable-cgi , 31 —enable-dumb , 31 —enable-master-slave , 31 —enable-net , 31 —enable-nis , 32 —enable-powerflute , 31 —enable-pthreads , 32 —enable-snmp , 31 —enable-test , 32 —enable-usb , 31 —prefix , 30 —sbindir , 31 —with-cgi-bin , 31 —with-css-dir , 31 —with-libwrap , 32 —with-lock-dir , 32 —with-log-dir ,
Apctest , 63 Apcupsd Building and Installing , 26, 109 Testing , 53 Apcupsd Bugs , 96 Apcupsd Known USB Issues , 15 Apcupsd Network Monitoring (CGI) Programs , 71 Apcupsd Notification and Events , 70 Apcupsd Status Logging , 170 Apcupsd Support and Knowledge Base: , 198 Apcupsd System Logging , 113 Apcupsd User’s Manual , 6 Apcupsd — RPM Packaging FAQ , 195 Areas Problem , 124 Arranging for Reboot on PowerUp , 45 Quick Start for , 9 Bits Status , 188 Bugs Apcupsd , 96 Building and Installing apcupsd , 26,
Once you have established serial , 155 Troubleshooting Serial Line , 155 Communications Test , 58 Compilers and Options , 34 Config Kernel , 200 Configuration Simple Master , 49 Simple Slave , 50 Simple USB , 47 Variation on the Master/Slave , 51 Configuration , 106 Configuration Directive Reference , 159 Configuration Directives , 101 Configuration Directives for Sharing a UPS , 165 Configuration Directives Used by the Network Information Server , 160 Configuration Directives used during Power Failures , 1
Disclaimer: NO WARRANTY , 199 Discontents Shutown Sequence and its , 176 Distribution Maintainers: , 198 DLOWBATT , 174 doreboot , 98 doshutdown , 98 Driver Sample NIS Slave Configuration Using the Net , 51 DSHUTD , 174 Dumb Simple Configuration for a Simple Signaling or , 49 dumb , 12 DWAKE , 174 Example Status Report , 171 Examples Configuration , 47 EXTBATTS , 175 FACILITY , 165 Failed Connect to slave SSS , 104 failing , 98 Failures Configuration Directives used during Power , 161 FAQ Apc
Determining Which VoltageSignaling Cable You , 155 Hid-ups and USB Specific Information , 71 HITRANS , 174 HITRANSFER
Controlling Multiple UPSes on one , 106 mainsback , 98 Maintaining Your UPS , 82 Making sure apcupsd Is Running , 46 MANDATE , 175 Manual Apcupsd User’s , 6 How To Use This , 9 MASTER for slave machines.
percent , 162 Pin Assignment for the Serial Port (RS-232C), 25-pin and 9pin, Female End , 148 Planning Your Installation , 9 Port Connecting a APC USB UPS to either a PC USB or Serial , 131 Connecting a Serial-Line UPS to a USB , 130 Post Installation , 124 Power Down During Shutdown , 128 powered , 97 powerout , 99 Problem Areas , 124 Problems Known , 109 Master/Slave , 101 Shutdown , 180 Process-Status Test , 53 Programming the UPS EEPROM , 194 Programs apcupsd Network Monitoring CGI , 71 Setting up and T
SENSITIVITY , 168 Sequence Shutdown , 63, 176 Serial Communications: , 197 SERIALNO , 175 Server Alternate Ways To Run The Network Information , 110 Configuration Directives Used by the Network Information , 160 Setting up and Testing the CGI Programs , 71 Shutdown Master/Slave , 180 Power Down During , 128 Shutdown Problems , 180 Shutdown Sequence , 63, 176 Shutown Sequence and its Discontents , 176 Signalling Voltage , 137 Signals Back-UPS Office 500 , 138 Simple Configuration for
Supported Operating Systems, UPSes and Cables , 11 Supports Other APC Cables that apcupsd , 136 System Shutdown Test , 61 Systems Recommended Options for most , 33 Maintaining Your , 82 Monitoring and Tuning your , 66 ups-name , 97 UPSCABLE > , 159 UPSCLASS , 165 UPSes Installation: Serial-Line , 130 Known Problems with USB , 65 Overview of Serial-Interface , 130 Status Logging On Serial-Line , 157 Support for SNMP , 108 Testing Serial-Line , 149 Voltage-Si
EEPROM , 192 Variation on the Master/Slave Configuration , 51 Verifying a Source Installation , 28 Version Command Line Options Specific to the Windows , 129 Voltage Signalling , 137 Voltage Signalling Features Supported by Apcupsd for Various Cables , 137 Voltage-Signalling Cable for dumb UPSes , 134 WAKEUP , 169 WARRANTY Disclaimer: NO , 199 WEB Interfaces: , 198 What Various People Have to Say about Batteries , 83 Where Carl Suggests You Get Batteries , 89 Win32 Implementation Restrict
