Apcupsd Network Monitoring (CGI) Programs
ConfigurationWith 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.cgiIf 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.cgiYou 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.cgior http://www.sibbald.com/cgi-bin/multimoncss.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:
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.cgiAs 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 1999You 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.sibbald.com/cgi-bin/multimon.cgi.
Client Test ProgramWhen 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 clientThen 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:
A Tip from Carl Erhorn for Sun SystemsIt 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:
CreditsMany thanks go to Russell Kroll <firstname.lastname@example.org> who wrote the CGI programs to work with his UPS Monitoring system named Network UPS Tools (NUT). Thanks also to Jonathan Benson <email@example.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.