next up previous contents index
Next: Troubleshooting Your Installation Up: Apcupsd User's Guide Previous: Configuration Examples   Contents   Index

Subsections


Testing Apcupsd

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


Process-Status Test

After you start apcupsd, execute the following command:

     ps fax

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

     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

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

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

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

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

apcmain
is the main thread that waits until it receives a termination signal (SIGTERM) or one of the child processes dies.

apcser
is the thread that manages the serial port and takes any actions (generates events) that are necessary as a result of a change of state of the UPS.

apcnis
is the Network information server thread that provides EVENTS and STATUS information over the network. This information is used by the CGI programs and the NIS client/server networking mode.


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.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 file (/etc/apcupsd/apcupsd.events) if you are using the default configuration file. If you have installed the RPM, they will probably be in /var/log/apcupsd.events.


apcaccess Test

This test consists of running apcaccess to see if apcupsd is properly updating its internal variables. Please note that you must enable the apcupsd Network Information Server in your configuration file for apcaccess to work. This is done by setting:

     NETSERVER on
     NISPORT 3551

in your apcupsd.conf file.

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:

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

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 the Network Information Server in your configuration file for apcaccess to work. This is done by setting:

     NETSERVER on
     NISPORT 3551

in your apcupsd.conf file.


Communications Test

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

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

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

Warning communications lost with UPS lost.

At the same time, it sends the same message to the system log and to the temporary EVENTS 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. 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

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

before running the test.

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


Simulated Power Fail Test

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

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

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

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

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

     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 apcupsd and change the value of TIMEOUT from 0 to something like 30. Doing so will cause apcupsd to attempt to shutdown the system 30 seconds after it detects a power failure. Once this change has been made, you must stop and restart apcupsd for the new 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 Building and Installing apcupsd of this manual, or the README files for additional details about the halt modifications necessary.

When you are ready to do the test, either simply pull the plug and wait for the batteries to become exhausted, or set the 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''.


Shutdown Sequence

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


apctest

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

Shutdown apcupsd if it is running. Make sure your /etc/apcupsd/apcupsd.conf file has UPSTYPE smart and UPSCABLE has one of the smart cables that are supported.

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

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

or on Windows systems with:

     make apctestwin32
     ./apctest

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

     2003-07-07 11:19:21 apctest 3.10.6 (07 July 2003) redhat
     Checking configuration ...
     Attached to driver: apcsmart
     sharenet.type = DISABLE
     cable.type = CUSTOM_SMART
     
     You are using a SMART cable type, so I'm entering SMART test mode
     mode.type = SMART
     Setting up serial port ...
     Creating serial port lock file ...
     Hello, this is the apcupsd Cable Test program.
     This part of apctest is for testing Smart UPSes.
     Please select the function you want to perform.
     
     1) Query the UPS for all known values
     2) Perform a Battery Runtime Calibration
     3) Abort Battery Calibration
     4) Monitor Battery Calibration progress
     5) Program EEPROM
     6) Enter TTY mode communicating with UPS
     7) Quit
     
     Select function number: 1

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

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

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

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

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

Item 4 can be used to restart the monitoring of a Battery Calibration if you should some how become disconnected during the test.

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

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

Item 7 will terminate apctest.


next up previous contents index
Next: Troubleshooting Your Installation Up: Apcupsd User's Guide Previous: Configuration Examples   Contents   Index
2009-11-06