- Installation and Running
HTTPPoll is a website monitoring and alert program. It polls
a list of URLs at periodic intervals, and notifies you when any of
them returns an error code.
HTTPPoll can run three types of
Email. This can be especially useful if
you have a beeper-enabled email address.
Dialog box. This is handy if you are at
your computer. The pop up box will notify you of the
problem as soon as it is detected.
Shell script. If you want to perform an
action automatically when a website goes down, you can
write your own script and have
HTTPPoll is a command-line driven program, written in the
Java language. It is released under the
Public License and uses a variety of Open Source libraries,
including: Jakarta commons
Java 1.4 runtime*.
HTTPPoll may work
with lower Java versions, but I haven't tested for that.
UNIX Operating System, due to the
HTTPPoll.sh script being UNIX based. Once a
version of the script gets written,
should work fine on Windows. Currently I have only tested
HTTPPoll on Linux machines.
UPDATE [2003-02-01]: I added Kevin
.bat files for running HTTPPoll on
Windows (I have not personally been able to test them,
however). This is available in the 1.01 release.
NOTE: I did run into a problem using Sun's JDK
1.4. For some reason, the library files were
not getting added to
HTTPPoll's classpath. The
startup script's syntax is valid, as far as I can tell, but the
external .jar files were not getting picked up. I am now using
IBM's JDK 1.4 without problem.
Installation and Running
HTTPPoll package from its SourceForge
Unzip it to wherever you want to install the application on your
Enter the installation directory - Let's call it
Edit the configuration file,
Run the HTTPPoll script from
HTTPPoll comes ready to run, with a binary .jar in
<INSTALL>/dist directory, as well as all
the necessary support libraries under
<INSTALL>/lib. However, you may choose to build
from source, especially if you want to work on the source code,
or if you want to tweak the log4j configuration.
To build and package HTTPPoll, you need
ant installed on your
machine, with the
ant script in your shell's PATH.
All you should need to do is:
shell$ cd <INSTALL>
The build process will result in a new
stored in the
The configuration file for
HTTPPoll is located at
should find this automatically when it runs (Technically,
the program first looks for
$HOME directory. If it isn't found there,
HTTPPoll looks for
relative to the startup script's location). Alternately, you can
specify a configuration file by running:
./HTTPPoll.sh -f <path-to-config-file>
HTTPPoll validates the configuration's XML
httppoll.dtd file must reside in the
same directory as the configuration file.
The downloaded package includes an example
httppoll.xml configuration file, as well as its
DTD (Document Type Definition).
This manual will explain the configuration in
this example file:
<!-- Seconds to wait between polling -->
poll-interval - The number of
seconds to wait between each poll. In the example, we will
poll our targets every 3 minutes (180 seconds).
<!-- SMTP host for email alerts -->
smtp-host - The SMTP host for
outgoing email. This is used if you enable email alerts. If you
aren't using this feature, leave the element blank (but you
still must include it).
<!-- Default alert action settings -->
<subject>HTTPPoll alert - $URL</subject>
<message>$URL returned error code: $ERROR_CODE / $ERROR_MESSAGE</message>
<title>HTTPPoll alert - $URL</title>
<message>$URL returned error code: $ERROR_CODE / $ERROR_MESSAGE</message>
default-alert-action - Here we
define the default behavior for each alert category:
If you want to override the
default-alert-action for a target,
you can specify that behavior in the
alert-action section, later in the file.
shell - This is where you
configure the default script/program to be run by
HTTPPoll when an alert condition arises.
email - Default configuration for
the email alert. This will be an email sent out
through the server specified by
repeatable - Should
this action repeat if an error is returned from two
consecutive polls? To prevent
HTTPPoll from sending us a
bunch of duplicate emails, we've set the default value to false.
to - the email address
to send this message to.
from - the email
address of the sender.
subject - the subject
for this email message. Notice the variable
$URL - this is a built-in feature of
url for the monitored
website will be substituted here automatically in
the actual email.
message - the message
content of this email message. Notice the two
new built-in variables
$ERROR_MESSAGE. They will be
substituted with the HTTP status code (e.g. 404) and
the HTTP message (e.g. "Not Found")
dialog-box - Default configuration for
the dialog box alert. This action pops up an alert
window when an error is returned from a polled URL.
target - The configuration
file can contain any number of
target represents a URL that you want to
poll, including specific
<!-- Target #1 -->
Our first target is a simple one. We will poll
http://slashdot.org/ and use
the default configuration for all our alerts.
url - The base URL for
the target, in this case "slashdot.org".
file - the file path to
append to the
url. Here we
want the slashdot's root page, "/".
<!-- Target #2 -->
<subject>HTTPPoll alert - FOO down</subject>
Our second target shows a little more complexity. Here we
want to access the URL path "test1.example.com/foo/index.html".
We decide we don't want to be bothered by any error
codes for HTTP redirects (represented by HTTP codes
in the 300 range), so we set the
alert-threshhold to 400. Now we only
get an alert for this target when the code returned
is >= 400. The default threshhold value is
Instead of accepting all the
default-alert-action values, we want to
customize some actions for this target.
shell - By default, the
shell action is disabled, as specified by
default-alert-action. Since we do want to run
a shell script for this target, we add this element to
enabled to "true". We must
also specify a
command to run, since the
shell entry in
default-alert-action doesn't specify one.
email - We want to use the
email configuration, for the most part, while
changing a couple things. For one, we add a
cc element to carbon copy a
firstname.lastname@example.org. Also, we decide to
use a customized subject to
tell us that FOO is down.
dialog-box - By setting the
repeatable element to "true", we
will get a pop-up window every time a poll
returns an error for this
target, even on
consecutive polls. Otherwise, the dialog-box behavior will
be the same as that specified in
<!-- Target #3 -->
<subject>Problem with $URL</subject>
<message>status: $ERROR_CODE. message: $ERROR_MESSAGE</message>
Our third example showcases a couple more features:
The rest should be familiar at this point. Note that:
port - This is set to 8080, which
differs from the default HTTP port of 80. The
port element is optional, and
HTTPPoll will use port 80 if it is left out.
scheduled-downtime - This denotes a
time range during each day when
not poll the target. During scheduled maintenance
times, when you know the server will be down, you don't want
to be bothered with alerts. The
hour element uses
military time, so for example, 23 means 11 PM. In the above
HTTPoll will ignore the target during
11:00 PM - 11:30 PM. This element is optional.
NOTE: I am aware that this feature is
currently limited for a couple reasons:
- The scheduled downtime applies to every day. Often in
reality, there is a specific day of the week,
such as Sunday, when maintenance can be scheduled, and you
would only want
HTTPPoll to ignore a
window of time on that day. Time allowing, I will work on
adding this functionality.
- I haven't yet tested the behavior when
end times fall on
different days, such as 11:00 PM - 12:30 AM. This sort of time
range probably will not work for now.
dialog-box is set to
"false", which overrides the default value (No dialog box will pop up,
enabled is set to "true" in
There is no entry for
shell, which means this
target will use the
for all its logging, including both console output and the
httppoll.log file that gets produced when the
HTTPPoll reads a copy of the configuration file
<INSTALL>/files/log4j.properties to determine
its logging behavior. If you make changes to that file, make sure you
use ant to package the application
afterwards, or else your changes won't get read.
For information on configuring
log4j with the
log4j.properties file, take a look at the short
Copyright (C) 2003 Drake Emko
Last updated 2003-09-12