Apcupsd Network Monitoring (CGI) Programs

Configuration

With this release, there are five CGI programs (multimon.cgi, multimoncss.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. To install the Cascading Style Sheet, which is used by multimoncss.cgi, you must use the --with-css-dir= option. 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 or multimoncss.cgiis 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.

Setting up and Testing the CGI Progams

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. See the Network Information Server section of the configuration section of this manual for additional details. Also, 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. On my site, I use multimon.conf unmodified from what is on the source distribution. However, I have 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 7000 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 setup 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 screenshot shown below.

If you wish additional control over the colors, type faces, and sizes of the multimon output, you might wish to use multimoncss.cgi in place of multimon. In this case, you simply edit the multimon.css file to specify the sytles you prefer. There are several sample Style Sheet files in the cgi subdirectory of the source tree.

To see a working example of the these programs, visit http://www.sibbald.com/cgi-bin/multimon.cgi

or http://www.sibbald.com/cgi-bin/multimoncss.cgi

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:

multimon.cgi

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.cgi for the specified system, which will produce a bar graph display of three of the monitored values. For example,

upsstatus.cgi

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.cgi

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.

Working Example

To see a working example of the above programs, visit http://www.sibbald.com/cgi-bin/multimon.cgi.

Client Test Program

When your Network Information Server is up and running, you can test it using a simple program before attempting to access the server via you 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.

A Tip from Carl Erhorn for Sun Systems

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

Credits

Many thanks go to Russell Kroll <rkroll@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@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.