After you have verified that your UPS is working correctly, you will probably want to query the state of its health occasionally. The tools apcupsd gives you to do this include one command-line utility (apcaccess) and a GUI you can use through a Web browser. You can also use apctest to tune some parameters of the UPS itself.
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.
apcaccess will use the Network Information Server to obtain the necessary information for the status and eeprom commands. You can specify a second optional argument to apcaccess in the form of host:port where the :port is optional. The default is localhost:3551. Please note that in versions prior to 3.10.6, the default NIS port was 7000, so if you are mixing versions, you will need to take a lot of care to ensure that all components are using the same port.
To enable the apcupsd Network Information Server, which is normally the default, you set:
NETSERVER on NISPORT 3551
in your apcupsd.conf file.
As mentioned above, the full form of the command is:
apcaccess status localhost:3551
where only apcaccess status should normally be needed. localhost may be replaced by any machine name, fully qualified domain name, or IP address, which means that apcaccess can access any UPS on the network running the Network Information Server.
The 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.
Please note that if you invoke apcaccess within the first 30 seconds of launching apcupsd, you will likely get an error message such as:
APCACCESS FATAL ERROR in apcipc.c at line 325 attach_shmarea: shared memory version mismatch
This is because apcupsd is still in the process of initializing the shared memory segment used to communicate between the two processes. There is also a small window of time after which the memory segment is properly initialized but before the UPS has been completely polled. If you invoke apcaccess during this period, you will get the STATUS output, but with many of the values zero. The solution is to wait at least 30 seconds after starting apcupsd before launching apcaccess.
To invoke apcaccess, enter:
apcaccess status
For a SmartUPS 1000 apcaccess will emit the following output:
DATE : Fri Dec 03 12:34:26 CET 1999 HOSTNAME : matou RELEASE : 3.7.0-beta-1 CABLE : Custom Cable Smart MODEL : SMART-UPS 1000 UPSMODE : Stand Alone UPSNAME : UPS_IDEN LINEV : 232.7 Volts MAXLINEV : 236.6 Volts MINLINEV : 231.4 Volts LINEFREQ : 50.0 Hz OUTPUTV : 232.7 Volts LOADPCT : 11.4 Percent Load Capacity BATTV : 27.7 Volts BCHARGE : 100.0 Percent MBATTCHG : 5 Percent TIMELEFT : 112.0 Minutes MINTIMEL : 3 Minutes SENSE : Low DWAKE : 060 Seconds DSHUTD : 180 Seconds LOTRANS : 204.0 Volts HITRANS : 253.0 Volts RETPCT : 050.0 Percent STATFLAG : 0x08 Status Flag STATUS : ONLINE ITEMP : 29.2 C Internal ALARMDEL : Low Battery LASTXFER : U command or Self Test SELFTEST : NO STESTI : 336 DLOWBATT : 02 Minutes DIPSW : 0x00 Dip Switch REG1 : 0x00 Register 1 REG2 : 0x00 Register 2 REG3 : 0x00 Register 3 MANDATE : 01/05/99 SERIALNO : GS9902009459 BATTDATE : 01/05/99 NOMOUTV : 230.0 NOMBATTV : 24.0 HUMIDITY : N/A AMBTEMP : N/A EXTBATTS : 0 BADBATTS : N/A FIRMWARE : 60.11.I APCMODEL : IWI END APC : Fri Dec 03 12:34:33 CET 1999
For the various smaller, cheaper APC USB UPSes, such as the CS, ES, ..., you will get much of the information that is presented above, but not all of it. For example, you will not get MAXLINEV, MINLINEV, LINEFREQ, ... and in particular, the LOADPCT will be zero when you are running on mains. LOADPCT will display when the UPS is on batteries. You must remember that the non-SmartUPSes are much simpler (and less expensive) and therefore produce less information.
The eprom command line option for apcaccess allows you to examine the current values of your UPS' EPROM as well as to know the permitted values that can be set in the EPROM. For information about changing these values, see the section on tuning EEPROM parameters (see Configuring Your EEPROM).
A typical output from apcaccess eprom is:
Valid EPROM values for the SMART-UPS 1000 Config Current Permitted Description Directive Value Values =================================================================== Upper transfer voltage HITRANSFER 253 253 264 271 280 Lower transfer voltage LOTRANSFER 208 196 188 208 204 Return threshold RETURNCHARGE 15 00 15 50 90 Output voltage on batts OUTPUTVOLTS 230 230 240 220 225 Sensitivity SENSITIVITY H H M L L Low battery warning LOWBATT 2 02 05 07 10 Shutdown grace delay SLEEP 180 020 180 300 600 Alarm delay BEEPSTATE T 0 T L N Wakeup delay WAKEUP 60 000 060 180 300 Self test interval SELFTEST 336 336 168 ON OFF
When a major event is generated within apcupsd, control is passed to the script apccontrol normally found in /etc/apcupsd/apccontrol. The event name, and a number of other important parameters are passed to the script.
The major function of the apccontrol script is to performa a shutdown of the system (as well as the killpower operation). In addition, another major task for this script is to notify you by email when certain events such as powerfail occur.
Since apccontrol is a script, you can customize it to your own needs using any text editor. To do so, you must have a minimal knowledge of Unix shell programming. In addition, another feature is that you can write your own scripts that will be automatically called by apccontrol before any of its own code is executed. Details of the events and how to program them are contained in the Advanced topics section entitled Customizing Event Handling (see Customizing Event Handling).
The UPS has an internal set of timers and remaining capacity counters, which it uses to determine when to shutdown. These are in addition to the apcupsd counters BATTERYLEVEL and MINUTES. As a consequence, apcupsd will shutdown on the first limit that triggers (either an apcupsd limit, or a UPS limit). The UPS internal counter equivalent to BATTERYLEVEL can be found in the hid-ups report as RemainingCapacityLimit, which is typically factory set to 10 percent. In addition, the Low Battery signal is normally given by the UPS when less than 2 minutes of run time remain.
With this release, there are four CGI programs (multimon.cgi,
upsstats.cgi, upsfstats.cgi, and upsimage.cgi). To have them properly
installed, you must run the ./configure command with --
enable-cgi
and you should specify an installation directory with --
with-cgi-bin= or
load them manually. The default directory for installation of the CGI programs is
/etc/apcupsd, which is not really where you want them if you are going to use them.
Normally, they should go in the cgi-bin of your Web server.
Once built and loaded, they will give you the status of your UPS or UPSes over the network.
Normally only multimon.cgi is directly invoked by the user. However, it is possible to directly invoke upsstats.cgi and upsfstats.cgi. upsimage.cgi should never be directly invoked as it is used by upsstats.cgi to produce the bar charts.
Before using multimon and the other CGI programs, first ensure that apcupsd is configured to run the Network Information Server. This is done by setting NETSERVER on in /etc/apcupsd/apcupsd.conf. This switch is on by default. If you are unsure of its state, see the section at the end of this chapter concerning the Client test program.
Next you must edit the hosts file /etc/apcupsd/hosts.conf and at the end, add the name of the hosts you want to monitor and a label string for them. Kern Sibbald uses multimon.conf unmodified from what is on the source distribution. However, he has modified the hosts.conf file to contain the following three lines:
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. Please note that the network names may either be IP addresses or fully qualified domain names. The network name (or IP address) may optionally be followed by :<port>, where the port is the NIS port address you wish to use. This is useful if you are running multiple copies of apcupsd on the same system or if you are running in a mixed vendor environment where the NIS port assignments differ. An example could be the following:
MONITOR matou "Server" MONITOR polymatou "Backup server" MONITOR deuter "Disk server" MONITOR polymatou:7001 "APC USB UPS"
where the USB copy of apcupsd has been configured to use port 7001 (with --
with-nis-port=7001 on the ./configure or by modifying apcupsd.conf).
Note, the default NIS port is 3551 on most platforms.
To test multimon.cgi, you can execute it as non-root directly from the source cgi build directory. To do so, enter at a shell prompt:
./multimon.cgi
If everything is set up correctly, it will print a bunch of HTML with the values of the machines that you have put in the hosts.conf file. It should look something like the following (note, only a small portion of the output is reproduced here):
Content-type: text/html <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd"> <HTML> <HEAD><TITLE>Multimon: UPS Status Page</TITLE></HEAD> <BODY BGCOLOR="#FFFFFF"> <TABLE BGCOLOR="#50A0A0" ALIGN=CENTER> <TR><TD> <TABLE CELLPADDING=5> <TR> <TH COLSPAN=10 BGCOLOR="#60B0B0"> <FONT SIZE="+2">APCUPSD UPS Network Monitor</FONT> <BR>Sun Jan 16 12:07:27 CET 2000</TH> </TR> <TR BGCOLOR="#60B0B0"> <TH COLSPAN=1>System</TH> <TH COLSPAN=1>Model</TH> <TH COLSPAN=1>Status</TH> ...
If you do not get similar output, check the permissions of the /etc/apcupsd directory and of those of /etc/apcupsd/hosts.conf to ensure that your web server can access it. At many sites such as mine, the Apache server is not running as root, so you must be careful to ensure that that /etc/apcupsd/hosts.conf and /etc/apcupsd/multimon.conf are world readable.
To invoke multimon in your Web browser, enter:
http://<your-site>/cgi-bin/multimon.cgi
You should get something similar to the screen shot shown below.
If you wish additional control over the colors, type faces, and sizes of the multimon output, you may simply edit the apcupsd.css file to specify the styles you prefer.
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)
By clicking on the system name in the multimon.cgi display, you will invoke upsstats.cgi for the specified system, which will produce a bar graph display of three of the monitored values. For example,
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.
If you would like to see all of the STATUS variables available over the network, click on the Data field of the desired system, and your browser will display something like the following:
APC : 001,048,1109 DATE : Thu Dec 02 17:27:21 CET 1999 HOSTNAME : matou.sibbald.com RELEASE : 3.7.0-beta-1 CABLE : Custom Cable Smart MODEL : SMART-UPS 1000 UPSMODE : Stand Alone UPSNAME : UPS_IDEN LINEV : 223.6 Volts MAXLINEV : 224.9 Volts MINLINEV : 222.3 Volts LINEFREQ : 50.0 Hz OUTPUTV : 223.6 Volts LOADPCT : 6.2 Percent Load Capacity BATTV : 27.9 Volts BCHARGE : 100.0 Percent MBATTCHG : 5 Percent TIMELEFT : 167.0 Minutes MINTIMEL : 3 Minutes SENSE : High DWAKE : 060 Seconds DSHUTD : 020 Seconds LOTRANS : 196.0 Volts HITRANS : 253.0 Volts RETPCT : 050.0 Percent STATFLAG : 0x08 Status Flag STATUS : ONLINE ITEMP : 35.1 C Internal ALARMDEL : Low Battery LASTXFER : U command or Self Test SELFTEST : NO STESTI : 336 DLOWBATT : 02 Minutes DIPSW : 0x00 Dip Switch REG1 : 0x00 Register 1 REG2 : 0x00 Register 2 REG3 : 0x00 Register 3 MANDATE : 01/11/99 SERIALNO : GS9903001147 BATTDATE : 01/11/99 NOMOUTV : 230.0 NOMBATTV : 24.0 HUMIDITY : N/A AMBTEMP : N/A EXTBATTS : 0 BADBATTS : N/A FIRMWARE : 60.11.I APCMODEL : IWI END APC : Thu Dec 02 17:27:25 CET 1999
You should get pretty much the same output mixed in with html if you execute upsfstats.cgi directly from a Unix shell in the cgi subdirectory as explained above for upsstats.cgi and multimon.cgi.
To see a working example of the above programs, visit http://www.apcupsd.com/cgi-bin/multimon.cgi.
When your Network Information Server is up and running, you can test it using a simple program before attempting to access the server via your Web server. The test program is called client.c and can be found in the examples subdirectory of the source distribution. To build the program, when in the examples directory, use something like the following:
cc client.c ../lib/libapc.a -o client
Then execute it:
./client <host>[:<port>] [<command>]
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.
If no error messages are printed, it has most likely established contact with your server. Anything that you type as standard input will be passed to the server, and anything the server sends back will be printed to standard output. There are currently two commands recognized by the server: events and status. Hence the following commands:
./client status events xyz ^D
should produce the status listing (the same as produced by apcaccess status), followed by the list of the last 10 events (in response to the events command), and finally Invalid command in response to the xyz input, which is not a valid command. The control-D terminates the client program.
The purpose of this program is to show you how to write your own program that can determine the status of apcupsd and act any way you want (e.g. send you email messages on certain events like line voltage boost, ...).
It is possible to run the CGI code to monitor your UPS using the answerbook HTTP server that runs on Solaris. As long as your server has the Answerbook2 web server installed and running, you can insert the cgi scripts into the cgi directory of the web server, and access the cgi using something like:
http://hostname:8888/cgi/multimon.cgi
Many thanks go to Russell Kroll <rkroll at exploits.org> who wrote the CGI programs to work with his UPS Monitoring system named Network UPS Tools (NUT). Thanks also to Jonathan Benson <jbenson at technologist.com> 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.
If you are running apcupsd as an NIS server, you will need to ensure that the clients can reach it by opening up NISPORT (default: TCP 3551) on any firewall running on the server. You may wish to configure your firewall(s) to only allow connections from your local network or specifically from the masters, slaves, and servers as needed.
If your operating system does not support a host based firewall (a
firewall running on the local machine) then you may try to get some of
the funtionality of such a firewall with TCP Wrappers.
As of apcupsd version 3.8.2, TCP Wrappers are implemented if you turn them on
when configuring (./configure --
with-libwrap). With this code enabled,
you may control who may access your apcupsd via TCP connections (the Network
Information Server). This control is done by modifying the file: /etc/hosts.allow.
This code is implemented but untested. If you use it, please send us some feedback.
If you have a SmartUPS, there are depending on the UPS at least 12 different values stored in the EEPROM that determine how the UPS reacts to various conditions such as high line voltage, low line voltage, power down grace periods, etc.
In general, for the moment, we do not recommend that you change your EEPROM values unless absolutely necessary. There have been several reported cases of problems setting the Low Transfer Voltage. Consequently, if at all possible, do not attempt to change this value.
If despite these warnings, you must change your EEPROM, we recommend connecting your UPS to a Windows or NT machine running PowerChute and making the changes.
Unlike version 3.8.6, apcupsd version 3.10.x no longer has code to program the EEPROM. Instead we have implemented interactive EEPROM modification code in the apctest program. EEPROM programming must be done with apcupsd stopped so that apctest can access the UPS. In addition, EEPROM programming is currently implemented only for UPSes using the Smart protocol running in serial mode. Perhaps at a later time when the appropriate kernel modifications are standard, we will extend EEPROM programming to USB models.
Before changing your EEPROM, you should make a printed copy of the current state of your UPS before any EEPROM changes so that you can check the changes that you have made. Do so by printing a copy of the output from apcaccess status and also print a copy of the output from apcaccess eprom.
Once this is done, choose which values of the EEPROM you want to change. Typical output from apcaccess should look like the following:
apcaccess eeprom Valid EPROM values for the SMART-UPS 1000 Config Current Permitted Description Directive Value Values ================================================================ Upper transfer voltage HITRANSFER 253 253 264 271 280 Lower transfer voltage LOTRANSFER 196 196 188 208 204 Return threshold RETURNCHARGE 0 00 15 50 90 Output voltage on batts OUTPUTVOLTS 230 230 240 220 225 Sensitivity SENSITIVITY H H M L L Low battery warning LOWBATT 2 02 05 07 10 Shutdown grace delay SLEEP 20 020 180 300 600 Alarm delay BEEPSTATE 0 0 T L N Wakeup delay WAKEUP 0 000 060 180 300 Self test interval SELFTEST 336 336 168 ON OFF
where the Current Value will depend on how your UPS is configured, and the Permitted Values will depend on what UPS model you have.
To make the EEPROM changes with apctest you must first stop the apcupsd daemon
apctest is not installed during the installation process, so to use it you will need to do the following after having built apcupsd:
cd <apcupsd-source>/src su <root-password> ./apctest
At that point, you should get output similar to the following:
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:
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. 1) Print EEPROM values 2) Change Battery date 3) Change UPS name 4) Change sensitivity 5) Change alarm delay 6) Change low battery warning delay 7) Change wakeup delay 8) Change shutdown delay 9) Change low transfer voltage 10) Change high transfer voltage 11) Change battery return threshold percent 12) Change output voltage when on batteries 13) Change the self test interval 14) Set EEPROM with conf file values 15) Quit Select function number:
If you wish to use the old pre-3.10.x method of EEPROM programming with values specified in the apcupsd.conf file, select option 14). However, we recommend that you start with item 1) to see what EEPROM values apctest finds. This command can take a few minutes to run, so be patient. The values printed should be the same as what you got using apcaccess, but in addition, the EEPROM battery date and UPS Name should be displayed. For example:
Select function number: 1 Doing prep_device() ... Valid EEPROM values for the SMART-UPS 1000 Config Current Permitted Description Directive Value Values =================================================================== Upper transfer voltage HITRANSFER 253 253 264 271 280 Lower transfer voltage LOTRANSFER 196 196 188 208 204 Return threshold RETURNCHARGE 0 00 15 50 90 Output voltage on batts OUTPUTVOLTS 230 230 240 220 225 Sensitivity SENSITIVITY H H M L L Low battery warning LOWBATT 2 02 05 07 10 Shutdown grace delay SLEEP 20 020 180 300 600 Alarm delay BEEPSTATE 0 0 T L N Wakeup delay WAKEUP 0 000 060 180 300 Self test interval SELFTEST 336 336 168 ON OFF =================================================================== Battery date: 07/31/99 UPS Name : UPS_IDEN
At this point, you can select any item from 2) to 13) to modify the appropriate value. You will shown the existing value and prompted for the new values.
We recommend that you change the EEPROM as little as is absolutely necessary since it is a somewhat delicate process that has occasionally produced problems (i.e. improper EEPROM values are displayed after the update). Fortunately this seems to be quite rare and was much more likely to occur with the old ``batch'' like process especially if incorrect values were supplied.