Please note that if launch the execution of apcupsd while your simple signalling 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.
Before continuing, please first read the section Checking the Installation in the Installation Section of this manual.
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.
You can manually test if you have serial communications with the UPS by starting a serial port communications program 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 fax
or the equivalent for your system, and 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.
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 status
Depending on the type of UPS you have, you will get slightly different output, but an example 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
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.Check the following variables:
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 signalling 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.
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.
${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.
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".
The shutdown sequence is as follows:
The conditions that trigger the shutdown can be: running time on batteries have expired (TIMEOUT), the battery runtime remaining is below the configured value (BATTERYLEVEL), the estimated remaining runtime is below the configured value (MINUTES), or the UPS signals that the batteries are exhausted.
A shutdown could also be initiated if apcupsd detects that the batteries the batteries are no longer functioning correctly. This case, though very unusual, can happen at any time even if there is proper mains voltage, and /etc/apcupsd/apccontrol emergency is called.
When issuing any shutdown, apcupsd will create the file /etc/apcupsd/powerfail. This file will be used later in the shutdown sequence to recall apcupsd after syncing of the disks to initiate a power down of the UPS.
If the /etc/nologin file has not already been created, it will normally be created during the shutdown sequence to prevent additional users from logging in (see the NOLOGIN configuration directive).
Even though apcupsd has requested the system to perform a shutdown, it continues running. If it is a master with slaves, it will inform the slaves to do a shutdown. They perform their shutdown by calling /etc/apcupsd/apccontrol remotedown.
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 RedHat version is:
# See if this is a powerfail situation. # ***apcupsd*** if [ -f /etc/apcupsd/powerfail ]; then # ***apcupsd*** echo # ***apcupsd*** echo "APCUPSD will now power off the UPS" # ***apcupsd*** echo # ***apcupsd*** /etc/apcupsd/apccontrol killpower # ***apcupsd*** echo # ***apcupsd*** echo "Please ensure that the UPS has powered off before rebooting" # ***apcupsd*** echo "Otherwise, the UPS may cut the power during the reboot!!!" # ***apcupsd*** echo # ***apcupsd*** sleep 2d # ***apcupsd*** exit 0 # ***apcupsd*** fi # ***apcupsd***
Please note that the above code should be inserted as late as possible in the halt script. On many systems, such as RedHat, all the disk drives were unmounted, then remounted read-only, thus permitting access to the /etc files and the apcupsd executable. If your system does not explicitly remount the disks, you must remount them in read-only mode in the code that you add. Examples of code fragments that do this can be found in the distributions/suse subdirectory of the source.
If you are not able to insert the above code in your halt script because there is no halt script, or because your halt script calls the init program as some Unix systems do, you can either just forget about powering off the UPS, which means that your machine will not automatically reboot after a power failure, or there is yet another alternative, though not at all as satisfying as inserting code in the halt script.
Only if you cannot insert the appropriate code in the halt script, when you start apcupsd, normally from the /etc/rc.d/init.d/apcupsd script, use the --kill-on-powerfail option. This will cause apcupsd to program the UPS to shutoff the power just before it (apcupsd) does the system shutdown. Please note that this is not the most ideal solution. Read on to understand why.
A very important consideration is that you must set the EEPROM in your UPS so that it waits a sufficient time for the system to halt before it shuts off the UPS power. The current value as well as the permitted values for your UPS can be determined by executing:
apcaccess eeprom
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 02 05 07 10 Shutdown grace delay SLEEP 20 020 180 300 600 Alarm delay BEEPSTATE 0 0 T L N Wakeup delay WAKEUP 0 000 060 180 300 Self test interval SELFTEST 336 336 168 ON OFFThe line of interest for you is the Shutdown grace delay, which can be changed using the SLEEP directive in your apcupsd.conf file. The default value is 20 seconds, but generally, you can set it to 180, 300, or 600 seconds depending on your UPS. See the EEPROM programming section of this manual for further details on how to change this EPROM value.
The UPS contains two internal EPROM values that determine when it will restore power to your computer after a full power shutdown. They are the RETURNCHARGE percentage and the WAKEUP delay. Briefly, the RETURNCHARGE specifies what percentage charge the battery must have before the power is restored. Higher values are recommended in regions where the power goes up and down frequently. The WAKEUP delay is a simple time delay. Most sites will have both of these at zero, or perhaps the RETURNCHARGE set to 15. Please follow the links to the Configuration section of this manual for more information. See the EEPROM programming section of this manual for further details on how to change these EPROM values.
The final consideration for a automatic reboot after a full power down is to ensure that your computer will automatically reboot when the power is restore. This is not the normal behavior of most computers as shipped from the factory. Normally after the power is cut and restored, you must explicitly press a button for the power to actually be turned on. You can test your computer by powering it down; shutting off the power (pull the plug); then plugging the cord back in. If your computer immediately starts up, good. There is nothing more to do. If your computer does not start up, manually turn on the power (by pressing the power on button) and enter your computer's SETUP program (often by pressing DEL during the power up sequence; sometimes by pressing F10). You must then find and change the appropriate configuration parameter to permit instant power on. Normally, this is located under the BOOT menu item, and will be called something such as Restore on AC/Power Loss. The exact words will vary according to the ROM BIOS provider. Generally you will have three options: Last State, Power On, and Power Off. Although Last State should normally work, I set my computers 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.
sleep 30
just after the line that readsdoshutdown)
in the apccontrol file (approximately line 79 - depending on your system version).Also, on a slave machine, you do not want to use the modified halt script since it will recall apcupsd, which will detect that it is a slave (i.e. no connection to the UPS) and will complain that it cannot do the killpower. This situation is not harmful just annoying and possibly confusing.
One possible problem during shutdown can be caused by remnants of old versions. Please be sure to delete or rename all prior versions (/usr/local/sbin/apcupsd or /sbin/powersc).
<path>/apcupsd start
where <path> is normally /etc/rc.d or /etc/rc.d/init.d depending on your system (isn't Unix wonderful? :-)). Using this script is important so that any files remaining around after a power failure are removed. Likewise, shutting down apcupsd should be done with the same script:<path>/apcupsd stop