HTTPPoll Manual

  1. Introduction
  2. Requirements
  3. Installation and Running
  4. Building
  5. Configuration
  6. Logging

Introduction

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 alerts:

  1. Email. This can be especially useful if you have a beeper-enabled email address.

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

  3. Shell script. If you want to perform an action automatically when a website goes down, you can write your own script and have HTTPPoll run it.

HTTPPoll is a command-line driven program, written in the Java language. It is released under the GNU General Public License and uses a variety of Open Source libraries, including: Jakarta commons HTTPClient and cli, JDOM, JavaMail, and log4j.

Requirements

  • 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 .bat version of the script gets written, HTTPPoll should work fine on Windows. Currently I have only tested HTTPPoll on Linux machines.

    UPDATE [2003-02-01]: I added Kevin Scott's .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

  1. Download the HTTPPoll package from its SourceForge project site.

  2. Unzip it to wherever you want to install the application on your computer.

  3. Enter the installation directory - Let's call it <INSTALL>.

  4. Edit the configuration file, <INSTALL>/config/httppoll.xml.

  5. Run the HTTPPoll script from <INSTALL>: 

    ./HTTPPoll.sh

Building

HTTPPoll comes ready to run, with a binary .jar in the <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>
      shell$ ant
The build process will result in a new HTTPPoll.jar binary stored in the <INSTALL>/dist directory.

Configuration

The configuration file for HTTPPoll is located at <INSTALL>/config/httppoll.xml. HTTPPoll should find this automatically when it runs (Technically, the program first looks for httppoll.xml in your $HOME directory. If it isn't found there, HTTPPoll looks for config/httppoll.xml, relative to the startup script's location). Alternately, you can specify a configuration file by running: 

      ./HTTPPoll.sh -f <path-to-config-file>
Because HTTPPoll validates the configuration's XML syntax, the 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>180</poll-interval>
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>smtp.example.com</smtp-host>
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 -->
  <default-alert-action>
    <shell>
      <enabled>false</enabled>
    </shell>
    <email>
      <enabled>true</enabled>
      <repeatable>false</repeatable>
      <to>drake@example.com</to>
      <from>admin@example.com</from>
      <subject>HTTPPoll alert - $URL</subject>
      <message>$URL returned error code: $ERROR_CODE / $ERROR_MESSAGE</message>
    </email>
    <dialog-box>
      <enabled>true</enabled>
      <repeatable>false</repeatable>
      <title>HTTPPoll alert - $URL</title>
      <message>$URL returned error code: $ERROR_CODE / $ERROR_MESSAGE</message>
    </dialog-box>
  </default-alert-action>
default-alert-action - Here we define the default behavior for each alert category: shell, email, and dialog-box. If you want to override the default-alert-action for a target, you can specify that behavior in the target's 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.

    • enabled - Here we've disabled the shell action by default.

  • email - Default configuration for the email alert. This will be an email sent out through the server specified by smtp-host.

    • 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 HTTPPoll. The 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_CODE and $ERROR_MESSAGE. They will be substituted with the HTTP status code (e.g. 404) and the HTTP message (e.g. "Not Found") respectively.

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

    • title - The title on the dialog box frame.

    • message - The message to be displayed.

target - The configuration file can contain any number of target elements. Each target represents a URL that you want to poll, including specific alert-actions for that URL. 

  <!-- Target #1 -->
  <target>
    <url>slashdot.org</url>
    <file>/</file>
  </target>

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 -->
  <target>
    <url>test1.example.com</url>
    <file>/foo/</file>
    <alert-threshhold>400</alert-threshhold>
    <alert-action>
      <shell>
        <enabled>true</enabled>
        <command>touch /tmp/HTTPPoll_ALERT_FOO</command>
      </shell>
      <email>
	<cc>joe@example.com</cc>
	<subject>HTTPPoll alert - FOO down</subject>
      </email>
      <dialog-box>
	<repeatable>true</repeatable>
      </dialog-box>
    </alert-action>
  </target>
Our second target shows a little more complexity. Here we want to access the URL path "test1.example.com/foo/index.html".

  • alert-threshhold - 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 300.

  • alert-action - 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 alert-action and set 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 default email configuration, for the most part, while changing a couple things. For one, we add a cc element to carbon copy a message to joe@example.com. 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 default-alert-action. 

  <!-- Target #3 -->
  <target>
    <url>test2.example.com</url>
    <port>8080</port>
    <file>/bar.html</file>
    <alert-action>
      <email>
	<to>Alice &lt;alice@example.com&gt;</to>
	<cc>Joe &lt;joe@example.com&gt;</cc>
	<subject>Problem with $URL</subject>
        <message>status: $ERROR_CODE. message: $ERROR_MESSAGE</message>
      </email>
      <dialog-box>
        <enabled>false</enabled>
      </dialog-box>
    </alert-action>
    <scheduled-downtime>
        <start>
	    <hour>23</hour>
	    <minute>0</minute>
	</start>
	<end>
	    <hour>23</hour>
	    <minute>30</minute>
	</end>
    </scheduled-downtime>
  </target>
Our third example showcases a couple more features:

  • 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 HTTPPoll should 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 example, 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:

    1. 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.
    2. I haven't yet tested the behavior when the start and 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.

The rest should be familiar at this point. Note that:

  • enabled for dialog-box is set to "false", which overrides the default value (No dialog box will pop up, even though enabled is set to "true" in default-alert-action.

  • There is no entry for shell, which means this target will use the default-alert-action's shell configuration.

Logging

HTTPPoll uses log4j for all its logging, including both console output and the httppoll.log file that gets produced when the application runs.

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 log4j manual.

Copyright (C) 2003 Drake Emko email: drake-AT-zworg-DOT-com

Last updated 2003-09-12