<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<HTML>
<HEAD>
<TITLE>cgiprogs</TITLE>
<meta name="Author" content="Kern Sibbald">
<link rel=stylesheet href="apcupsd-styles.css" type="text/css">
</HEAD>
<BODY>
<H1>Apcupsd Network Monitoring (CGI) Programs</H1>
<h2>Configuration</h2>
With this release, there are five <a href="cgiprogs.html">CGI programs</a> (<b>multimon.cgi</b>,
<b>multimoncss.cgi</b>,
<b>upsstats.cgi</b>, <b>upsfstats.cgi</b>, and <b>upsimage.cgi</b>). To
have them properly installed, you must run the <b>./configure</b> command with
<b>--enable-cgi</b> and you should specify an installation directory with
<b>--with-cgi-bin=</b> or load them manually. To install the Cascading Style
Sheet, which is used by multimoncss.cgi, you must use the
<b>--with-css-dir=</b> option. The default directory for installation
of the CGI programs is <b>/etc/apcupsd</b>, which is not really where you want them
if you are going to use them. Normally, they should go in the <b>cgi-bin</b> of your
Web server.
<P>Once built and loaded, they will give you the status of your UPS or UPSes over the network.
<p>Normally only <b>multimon.cgi</b> or <b>multimoncss.cgi</b>is directly invoked by the user. However, it
is possible to directly invoke <b>upsstats.cgi</b> and <b>upsfstats.cgi</b>. <b>upsimage.cgi</b>
should never be directly invoked as it is used by <b>upsstats.cgi</b> to produce the bar charts.
<h2>Setting up and Testing the CGI Programs</h2>
<p>Before using <b>multimon</b> and the other CGI programs,
first ensure that <b>apcupsd</b> is configured to run the
Network Information Server. This is done by setting <b>NETSERVER on</b>
in <b>/etc/apcupsd/apcupsd.conf</b>. See the
<a href="configure.html#ConfigInfoServer">Network Information Server</a>
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.
<p>Next you must edit the <b>hosts</b> file <b>/etc/apcupsd/hosts.conf</b> 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:
<pre>
MONITOR matou "Server"
MONITOR polymatou "Backup server"
MONITOR deuter "Disk server"
</pre>
matou, polymatou, and deuter are the
network names of the three machines currently running apcupsd.
<p></p>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 <b>:<port></b>, where the port is the NIS
port address you wish to use. This is useful if you are running multiple
copies of <b>apcupsd</b> 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:
<pre>
MONITOR matou "Server"
MONITOR polymatou "Backup server"
MONITOR deuter "Disk server"
MONITOR polymatou:7001 "APC USB UPS"
</pre>
where the USB copy of <b>apcupsd</b> 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.
<p>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:
<p class="tty">./multimon.cgi</p>
If everything is setup correctly, it will print a bunch of html
with the values of the machines that you have put in the <b>hosts.conf</b>
file. It should look something like the following (note, only a small
portion of the output is reproduced here):
<pre>
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>
...
</pre>
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.
<p>To invoke <b>multimon</b> in your Web browser, enter:
<p class="tty">http://<your-site>/cgi-bin/multimon.cgi</p>
You should get something similar to the screenshot shown below.
</P>
<p>If you wish additional control over the colors, type faces, and sizes
of the multimon output, you might wish to use <b>multimoncss.cgi</b> in
place of multimon. In this case, you simply edit the multimon.css file
to specify the styles you prefer. There are several sample Style Sheet
files in the <b>cgi</b> subdirectory of the source tree.</p>
<P>To see a working example of the these programs, visit
<a href="http://www.sibbald.com/cgi-bin/multimon.cgi">http://www.sibbald.com/cgi-bin/multimon.cgi</a>
</P> or
<a href="http://www.sibbald.com/cgi-bin/multimoncss.cgi">http://www.sibbald.com/cgi-bin/multimoncss.cgi</a>
<H2>multimon.cgi</H2>
<P>This program monitors multiple UPSes at the same time. A typical
output of <b>multimon.cgi</b> as displayed in your Web browser might look
like the following:
</P>
<P><IMG SRC="multimon.gif" NAME="Graphic1" ALT="multimon.cgi" ALIGN=BOTTOM WIDTH=862 HEIGHT=210 BORDER=0>
</P>
<P>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)
</P>
<H2>upsstats.cgi</H2>
<P>By clicking on the <b>system</b> name in the
<b>multimon.cgi</b> display, you will invoke <b>upsstats.cgi</b> for the specified
system, which will produce a bar graph display of three of the
monitored values. For example,
</P>
<P><IMG SRC="status.gif" NAME="Graphic2" ALT="upsstatus.cgi" ALIGN=BOTTOM WIDTH=846 HEIGHT=636 BORDER=0>
</P>
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.
<p>As with <b>multimon</b>, if you have your local host configured in the
<b>/etc/apcupsd/hosts.conf</b> file, you can execute it from a Unix
shell from the source cgi directory as follows:
<p class="tty">./upsstats.cgi</p>
As with <b>multimon</b>, quite a few lines of html should then
be displayed.
<H2>upsfstatus.cgi</H2>
<P>If you would like to see all of the STATUS variables available
over the network, click on the <b>Data</b> field of the desired
system, and your browser will display something like the following:
</P>
<pre>
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
</PRE>
You should get pretty much the same output mixed in with html if
you execute <b>upsfstats.cgi</b> directly from a Unix shell in the
cgi subdirectory as explained above for <b>upsstats.cgi</b> and
<b>multimon.cgi</b>.
<H2>Working Example</H2>
<P>To see a working example of the above programs, visit
<a href="http://www.sibbald.com/cgi-bin/multimon.cgi">http://www.sibbald.com/cgi-bin/multimon.cgi</a>.
</P>
<h2>Client Test Program</h2>
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 <b>client.c</b> and can be
found in the <b>examples</b> subdirectory of the source distribution.
To build the program, when in the examples directory, use something like the following:
<p class="tty">cc client.c ../lib/libapc.a -o client</p>
Then execute it:
<p class="tty">./client <host>[:<port>] [<command>]</p>
Where <b>host</b> 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 <b>status</b> or <b>events</b> data into another program
such as Perl.
<p>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: <b>events</b> and
<b>status</b>. Hence the following commands:
<p class="tty">./client<br>
status<br>
events<br>
xyz<br>
^D
</p>
Should produce the status listing (the same as produced by <b>apcaccess status</b>),
followed by the list of the last 10 events (in response to the <b>events</b> command),
and finally <b>Invalid command</b> in response to the <b>xyz</b> input, which
is not a valid command. The control-D
terminates the <b>client</b> program.
<h2>A Tip from Carl Erhorn for Sun Systems</h2>
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:
<p class="tty">http://hostname:8888/cgi/multimon.cgi</p>
<h2>Credits</h2>
Many thanks go to Russell Kroll <rkroll@exploits.org> who
wrote the CGI programs to work with his UPS Monitoring system
named <a href="http://www.exploits.org/nut/library/apcsmart.html">Network UPS Tools (NUT)</a>.
Thanks also to Jonathan Benson <jbenson@technologist.com> for
initially adapting the upsstatus.cgi program to work with <B>apcupsd</B>.
<p>We have enhanced the bar graph program and hope that our changes can
be useful to the original author in his project.
<hr>
<a href="bugs.html" target="_self"><img src="back.gif" border=0 alt="Back"></a>
<a href="data.html" target="_self"><img src="next.gif" border=0 alt="Next"></a>
<a href="index.html"><img src="home.gif" border=0 alt="Home"></a>
</BODY>
</HTML>
