Testing Apcupsd

Simple Signaling UPSes (sometimes called Dumb UPSes)

The following testing procedures apply for the most part to Smart UPSes. If you have a simple signaling UPS such as a BackUPS or other non-Smart UPS, your testing procedures will be somewhat different (Smart UPSes include SmartUPS and MatrixUPS models). For example, for simple signaling (Dumb) UPSes, apcupsd is not currently able to detect whether or not the serial cable is connected. In addition, some simple signaling UPSes with certain cable combinations are not able to detect the low battery condition. For more details please see the Cable Chapter of this manual, an more specifically, the Cable Modes section. Many of the other testing features should work similar to described below. However, since it is easy to configure the cable incorrectly and thus have premature shutdowns of the UPS power, we strongly recommend, especially for simple 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 shutoff, your computer will continue to run. We also recommend using the safe-apccontrol as described below, until you are sure that the signaling is correct.

Please note that if launch the execution of apcupsd while your simple signaling UPS is on battery power, it is very likely that your UPS will immediately shut off the power. This is due to the initialization of the serial port line signals.

Determining Which Simple Signaling Cable You Have

The most frequently encountered problem with Simple Signaling UPSes (e.g. BackUPS 650) is that you have incorrectly specified which cable is being used. For a simple signaling (dumb) UPS, it is important to know what cable you have. All cables furnished by APC have the cable number stamped on the side of the computer connector end of the cable. Using this number with apcupsd will normally work fine.

If you do not know what cable you have, you can use the apctest program to determine the type of cable that you have. Please see the apctest Chapter of this manual for the details of running apctest.

For simple signaling UPSes, you should NOT use simple in the cable specification (i.e. UPSCABLE simple) unless you have made the cable yourself according to the wiring diagram given in the cables chapter of this manual.

Smart UPSes

Most of rest of this chapter concerns testing Smart UPSes. As noted above many of these tests will apply with certain restrictions to Simple Signaling (dumb) UPSes.

USB port

Please see the USB Chapter of this manual for details of testing connections to a USB port. Once you have the UPS and the computer connected, most of the testing procedures described here apply equally well to USB UPSes.

Checking the Installation

Before continuing, please first read the section Checking the Installation in the Installation Section of this manual.

Establishing Serial Port Connection

Once you have compiled, installed, and invoked apcupsd, you should wait to allow apcupsd to configure itself and establish contact with the UPS.

If you see the following message about 30 seconds after starting apcupsd:

apcupsd FATAL ERROR in apcserial.c at line 156
PANIC! Cannot communicate with UPS via serial port.

it means that apcupsd tried for about 30 seconds to establish contact with the UPS via the serial port, but was unable to do so. Before continuing, you must correct this problem. Some of the possible sources of the problem are: The first thing to do is to look at your log file, usually /var/log/messages because apcupsd writes more detailed information to the log file whenever there is an error.

If you have a UPS that uses SubSmart or Smart protcol (see the Configuration section for a list of the UPSes using these protocols), you can manually test the serial communications with the UPS by starting a serial port communications program (such as minicom, tip, or cu) with the settings 2400 8N1 (2400 baud, 8 bits, no parity, 1 stop bit). Be extremely careful what you send to your UPS as certain characters may cause it to power down or may even cause damage to the UPS. Try sending an upper case Y to the UPS (without a return at the end). It should respond with SM. If this is not the case, review the possible problems listed above. If you fat finger the Y and enter y instead, no cause for alarm, you will simply get the APC copyright notice.

Once you are sure that serial port communications is working, proceed to the next test.

PS Test

After you start apcupsd, execute the following command:

ps fax

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

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

This indicates that apcupsd is up and running and has started the two (default) child processes.

apcmain
is the main program that waits until it receives a termination signal (SIGTERM) or one of the child processes dies.
apcser
is the process that manages the serial port and takes any actions (generates events) that are necessary as a result of a change of state of the UPS.
apcnis
is the Network information server process that provides EVENTS and STATUS information over the network. This information is used by the CGI programs.

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

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

Logging Test

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

tail /etc/var/messages

You should see output that looks similar to the following:

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

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

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

These messages should also appear in the temporary EVENTS file (/etc/apcupsd/apcupsd.events) if you are using the default configuration file.

apcaccess Test

This test consists of running apcaccess to see if apcupsd is properly updating its internal variables. Please note that if you are running a pthreaded version of apcupsd (installed from rpm or --enable-pthreads on the ./configure line), you must enable the apcupsd Network Information Server in your configuration file for apcaccess to work.

To run the apcaccess test, use the following command:

apcaccess status

Depending on the type of UPS you have, you will get slightly different output, but an example For a Smart-UPS is as follows:
APC      : 001,048,1088
DATE     : Fri Dec 03 16:49:24 EST 1999
HOSTNAME : daughter
RELEASE  : 3.7.2
CABLE    : APC Cable 940-0024C
MODEL    : APC Smart-UPS 600
UPSMODE  : Stand Alone
UPSNAME  : SU600   
LINEV    : 122.1 Volts
MAXLINEV : 123.3 Volts
MINLINEV : 122.1 Volts
LINEFREQ : 60.0 Hz
OUTPUTV  : 122.1 Volts
LOADPCT  :  32.7 Percent Load Capacity
BATTV    : 26.6 Volts
BCHARGE  : 095.0 Percent
MBATTCHG : 15 Percent
TIMELEFT :  19.0 Minutes
MINTIMEL : 3 Minutes
SENSE    : Medium
DWAKE    : 000 Seconds
DSHUTD   : 020 Seconds
LOTRANS  : 106.0 Volts
HITRANS  : 129.0 Volts
RETPCT   : 010.0 Percent
STATFLAG : 0x08 Status Flag
STATUS   : ONLINE 
ITEMP    : 34.6 C Internal
ALARMDEL : Low Battery
LASTXFER : Unacceptable Utility Voltage Change
SELFTEST : NO
STESTI   : 336
DLOWBATT : 05 Minutes
DIPSW    : 0x00 Dip Switch
REG1     : N/A
REG2     : N/A
REG3     : 0x00 Register 3
MANDATE  : 03/30/95
SERIALNO : 13035861
BATTDATE : 05/05/98
NOMOUTV  : 115.0
NOMBATTV :  24.0
HUMIDITY : N/A
AMBTEMP  : N/A
EXTBATTS : N/A
BADBATTS : N/A
FIRMWARE : N/A
APCMODEL : 6TD
END APC  : Fri Dec 03 16:49:25 EST 1999

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

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

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

LINEV
This is the line voltage and it should be a value that is appropriate for your equipment. In the USA, it is typically about 120 Volts while in Europe, it is about 220 Volts.
BATTV
Unless you have additional battery packs, this should be near 24 Volts plus or minus 5 Volts.
STATUS
This is the status of the UPS and it should normally be ONLINE.

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.
It means that you have probably not enabled NIS in apcupsd.

Communications Test

At this point, you should ensure that apcupsd is handling the serial port correctly. This test assumes you have a Smart UPS. If you have a simple signaling UPS, please skip to the next section (Simulated Power Fail Test).

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

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

Warning serial port communications with UPS lost.

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

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

Serial 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 there is a problem with apccontrol. If you are running a window manager such as GNOME and don't have a console window open, you may not receive the wall messages. However, you should find them in your system log file (normally /var/log/messages and in the temporary EVENTS file, /etc/apcupsd/apcupsd.events. For example, to observe these events in the temporary EVENTS file, you might do a

tail -f /etc/apcupsd/apcupsd.events

before running the test.

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

Simulated Power Fail Test

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

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

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

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

Warning power loss detected.

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

Power failure. Running on UPS batteries.

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

Power has returned...

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

At this point, we recommend that you do a simulated power down of your system. If you are adventuresome or have been through this before, skip to the next section in this manual and do the real power fail shutdown. If you continue with the simulated power down and if all goes well, apcupsd will go through all the motions without actually shutting down the system. Continue using the safe apccontrol that you installed. Edit the configuration file /etc/apcupsd/apcupsd.conf and change the value of TIMEOUT from 0 to something like 30. Doing so will cause apcupsd to attempt to shutdown the system 30 seconds after it detects a power failure. Once this change has been made, you must stop and restart apcupsd for the new configuration value to take effect.

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

Beginning Shutdown Sequence

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

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

System Shutdown Test

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

       ${APCUPSD} --killpower

when it is commented out, it looks like:

#      ${APCUPSD} --killpower

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

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

Full Power Down Test

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

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

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

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

Automatic Reboot of your Computer after a Power Shutdown

If you have succeeded in getting apcupsd to power down the UPS as described above, you will most likely want your computer to automatically reboot when the power returns. Please see the Automatic Reboot section of the Shutdown Chapter of this manual for the details.

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 Chapter of this manual.

Testing the CGI Programs

Please see the CGI Programs chapter of this manual for how to test the Network Information Server and the CGI programs.

Recalibrating the UPS Runtime

This section does not apply to simple signaling or dumb UPSes such as the BackUPS.

Smart UPSes internally compute the remaining runtime, and apcupsd uses the value supplied by the UPS. As the batteries age (after say two or three years), the runtime computation may no longer be accurate since the batteries no longer hold the same charge. As a consequence, in the event of a power failure, the UPS and thus apcupsd can report a runtime of 5 minutes remaining when in fact only one minute remains. This can lead to a shutdown before you might expect it, because regardless of the runtime remaining that is reported, the UPS will always correctly detect low batteries and report it, thus causing apcupsd to correctly shutdown your computer.

If you wish have the UPS recalibrate the remaining runtime calculations, you can do so manually as the current version of apcupsd does not support this feature. To do so,

In principle, you should be able to do this with the computer powered by the UPS, but if you wish to be completely safe, you should plug your computer into the wall prior to performing the runtime calibration. In that case, you will need to artificially load the UPS with light bulbs or other means. You should supply a load of about 30 to 35% but not more than 50%. You can determine the load by looking at the output of the apcaccess status command while apcupsd is running.

You should not run the recalibration command more than once or twice per year as discharging these kinds of batteries tends to shorten their life span.


Back Next Home