
			      WebSitter(tm)


Contents:
---------

1.0 Legal Stuff
2.0 Description
3.0 How It Works
4.0 Requriements
5.0 Archive Contents
6.0 Installation
7.0 Setup
7.1   Setting Up a Job list
7.2   Starting WebSitter
8.0 Netiquette
9.0 Advanced topics
9.1   Running without cron
9.2   Multiple jobs
9.3   Notification agents
10.0 Contact Information

1.0 Legal Stuff
---------------

    Copyright (C) 1999,2000  Data Exchange Associates, Inc.

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

    Contact information:

    Data Exchange Associates, Inc.
    230 Burnt Meadow Road
    Groton, MA  01450

    http://www.dexa.com
    support@dexa.com

WebSitter is normally free of charge, and is distributed under the GNU
general public license. This means that individuals and organizations,
both commercial and non-commercial, may use WebSitter without
charge. If you modify and redistribute it, there are certain
obligations you must fulfill. See the file COPYING which came with
your WebSitter distribution for the full license.

WebSitter is not guaranteed to be supported other than by making full
source code available. If it breaks you get to keep both
pieces. However, Data Exchange Associates, Inc. (DEX) sometimes
answers questions. The more concise and better-researched your
question, the more likely it is to get an answer. No tutorials will be
provided. You have to learn this stuff on your own.  If you desire
expert help installing or configuring WebSitter, or enhancments DEX
can provide support at our prevailing hourly consulting rate (please
call).

2.0 Description
---------------

WebSitter is a utility for web designers and webmasters who must keep
tabs on many websites at once.  WebSitter automates the process of
checking that your websites are up and accessible.  Additionally
WebSitter can check and report on the status of domains by way of the
internet WHOIS protocol.  The WHOIS feature is useful for tracking
registration and changes to domains under your control.

WebSitter is intended to be run with UNIX/Linux cron facility, but you
can invoke it directly form the command prompt as well.  When used in
conjuction with cron WebSitter can periodically monitor the status of
your websites.

This version of WebSitter comes packaged with an e-mail notification
agent.  Other types of agents are possible consult the section
"Notification agents" for more information on creating and using other
types of notification agents.

3.0 How It Works
----------------

WebSitter(tm) takes a list of websites and documents you supply and
attempts to open them one at a time.  If the site and document are
accessible and available an OK report is produced.  Otherwise
WebSitter produces a FAIL report.  WebSitter uses the UNIX/Linux cron
facility to periodically run.  If you do not know what cron is and how
to use consult your ISP.

4.0 Requirements
----------------
WebSitter requires the following inorder to operate:

* UNIX/Linux Operating System
* Access to the cron facility
* Perl 5.004 or higher


5.0 Archive Contents
--------------------

The WebSitter archive should contain the following files:

WebSitter.pl - The main WebSitter script file.
WebSitter.pm - Configuration module used by WebSitter.pl.
WebSitter.sh - Kick-off shell script for use with cron.
MailNotifier.pl - WebSitter email notification agent script
MailNotifier.pm - MailNotifier.pl Configuration module.
README - This file.
COPYING - GNU general public license.
jobfile - a sample job file containing a list of websites to monitor.
crontab - a sample crontab.


6.0 Installation
----------------

Begin the installation process by placing a copy of the archive in a
temporary directory and follow the steps below.  Note you may also
unpack the archive on you own PC and "ftp" the files to your host system.

1. Unpack the WebSitter archive.  If the archive is a "tar" file use
the command:

$ tar -xvf WebSitter-1.0.tar

If the archive is a "zip" file:

$unzip WebSitter-1.0.ZIP

2. Verify that you have all the files listed in the "Archive Contents"
section of this document.

3. Set the "execute" permission on the WebSitter.pl and WebSitter.sh
files.

$ chmod +x  WebSitter.pl WebSitter.sh MailNotifier.pl

4. Copy the WebSitter files to the directory where you will access
them.  This may be your own local "bin" directory.  Example:

$ cp WebSitter.* MailNotifier.* jobfile crontab ~/bin

This copies the necessary files to your own "bin" directory if it
exists. 

Once you have installed WebSitter proceed to the "Setup" section of
this document.


7.0 Setup
---------

This section briefly explains how to configure WebSitter.  All
configuration is accomplished with a programmers editor.

1. Be sure that the first line of the WebSitter.pl and WebSitter.sh
files point to the proper shell interpreters.  WebSitter.pl should
point to your perl interpreter, usually "/usr/bin/perl".  If you do
not know the location of your perl use the "which" command.  Example:

$ which perl
/usr/bin/perl

The "which" command show perl is located in /usr/bin/perl, no change
to WebSitter.pl is required.  You may do the same for the "sh" shell
used in WebSitter.sh.

2. WebSitter comes with a single notification agent script
"MailNotifier.pl".  As the name implies e-mail is used as the
notification method.  In order to configure "MailNotifier" correctly
you must determine the correct location of your systems Mail Transport
Agent (MTA).  The MTA is used by WebSitter to deliver your status
reports.  This item is to be found in the file "MailNotifier.pm".  The
default is "sendmail" which is most widely used mail transport agent.
Here again you may use the "which" command to determine the location
of "sendmail".  Example:

$ which sendmail
/usr/sbin/sendmail

Using a programmers editor change the $mailer variable in MailNotifier.pm:

$mailer = '/usr/sbin/sendmail';

You may also change the options (switches) passed to the mailer by
changing the $mailerOpts variable.  Consult the manpage for you mailer
agent for the proper options.

2a. Next you must tell the MailNotifier where you want the reports
delivered.  Change the $To variable from "me@mydomain.com" to the
email address to recieve the WebSitter reports.  For example:

$To = 'thomper@gollwog.net';

2b. Finally you must tell MailNotifier the "From" email address.  This
is the address that your reports will appear to come from.  Change the
$From variable from "me@mydomain.com" to your email address.  This
operation is similar to the above $To change.

3. Modify the WebSitter.sh script.  This script is used by the crontab
to kick off the WebSitter.pl process.  The "cd" command must point the
the directory where you intend to house your copy of Websitter.  If
for example your WebSitter is installed in /home/MyHome/myBin the you
would change the "cd" command as shown below:

cd /home/MyHome/myBin

4. Modify the crontab file to point the the kick-off script
WebSitter.sh.  Change "$HOME/bin/WebSitter.sh" to reflect the actual
location where you install "WebSitter.sh".

5.  By default WebSitter directs all WHOIS queries to the whois server
at "whois.internic.net".  The variable:

$whoisServer = 'whois.internic.net';

in the file WebSitter.pm controls this.  You may change it as required.

Once you have completed this section proceed to the section "Setting
up a Job List".


7.1 Setting Up a Job list
-------------------------

Once WebSitter has been setup you may create a "job file".  A job file
is a list of websites, documents and domains you wish to have
WebSitter verify.  A job file is created with a programmers editor.  A
sample job file "jobfile" is included with the distribution.

The form of a job file is simple.  Lines beginning with a "#"
character are comments and are ignored.

A job entry consists of a single line specifing the type of query ( website,
or whois), followed by the website, or domain and finally the
document.

	[[http|whois]://]host.domain.name[document]

Here are some sample job entries:

http://www.somesite.com/index.html

This entry will cause WebSitter to check that the docment /index.html
on www.somesite.com is accessible.

If the http:// is left off WebSitter interprets the job entry as an
http:// entry.

www.somesite.com/index.html

This entry will also cause WebSitter to check that the docment
/index.html on www.somesite.com is accessible.


If you leave off the document name  WebSitter will check the default
document which is usuall "index.html"

www.somesite.com

This entry is equivalent to the previous two.


whois://somesite.com

This entry will cause WebSitter to check the default whois server
for the status of "somesite.com".  A registrant record is returned.

You are free to modify the "job file" at anytime.


7.2 Starting WebSitter
----------------------

You are now ready to start WebSitter.  This is accomplished by
submitting a crontab entry to the cron daemon.  Example to submit the
sample crontab entry the following command:

$ crontab crontab

This will cause "cron" to create a crontab entry for you and your job
will be run on the schedule from the file "crontab" supplied.
Additional information regarding the format of a crontab entry can be
found on the manpage crontab(5).

To verify that cron has indeed setup your crontab entry the command:

$ crontab -l

# DO NOT EDIT THIS FILE - edit the master and reinstall.
# (crontab installed on Tue Feb 23 15:54:22 1999)
# (Cron version -- $Id: crontab.c,v 2.13 1994/01/17 03:20:37 vixie Exp $)
# Crontab entry to run WebSitter on a regular basis
# This tab will run WebSitter at 7:00AM every day of every month
#min hour day-of-month month day-of-week	script
0     7       *          *       *		$HOME/bin/WebSitter.sh


8.0 Netiquette
--------------

WebSitter makes every attempt to be as parsimonious as possible of
network and webserver resources.  It is, however, possible to abuse
WebSitter and create unnecessary network traffic.  When using
WebSitter you should be a good Net Citizen (Netizen) by following
these guidelines:

1. Don't probe sites too often.  This chews up bandwidth and may
prevent clients from accessing the site if the webserver becomes too
busy.  The cron facility can wake WebSitter up once a minute, but that
would be excessive.

2. Don't test every page on a website.  One document is sufficient to
determine if a site is up.  Restrict your queries to only those
pages that it is critical to know the status of.


9.0 Advanced topics
----------------

9.1 Running without cron
-------------------------

WebSitter may be run directly form the command line without cron.
This is handy for when you are trying out a new job file, or testing,
or don't have access to cron.  Simply loggin and go to the directory
where you installed WebSitter and invoke it.  Example:

$ cd bin
$ ./WebSitter.pl myJobFile

This will cause WebSitter to run immediately.

You could also create a webpage with a form that will invoke WebSitter
and kick-off a report that way.  This is left as a exercise for the
student.

9.2 Multiple jobs
-----------------

You can create multiple "job files" and invoke WebSitter on each job
file.  This is handy if you must monitor sites that are logically
grouped together.  You can do this manually, or by adding additional
entries to your crontab file one for each "job file".  You simply need
to create a kick-off shell script, similar to WebSitter.sh, for each
"job file" you wish to process.


9.3 Notification agents
-----------------------

WebSitter comes with a notification agent that uses e-mail to provide
you with status reports on your websites.  Other agents may be created,
e.g. an HTML generator.  In order to create a notification agent
acceptable for use with WebSitter you must follow these guidelines:

1. Your agent must read input from standard input (STDIN).  WebSitter
opens a pipe to your notification agent.
2. The first line delivered by WebSitter contains the site
information, i.e site name and webpage name.
3. WebSitter opens the the notifier once for each website reported.

A notification agent may be any executeable that adheres to the above
guidelines.

Once you have created a new agent you must register it with
WebSitter.  This is done by editing the file "WebSitter.pm".  Set the
variable $notifier" to point to your new agent.  If your agent
requires commandline options place them in the variable
$notifierArgs. 

10.0 Contact Information
------------------------

If you have questions concerning WebSitter you may contact Data
Exchange Associates, Inc. via:

    Data Exchange Associates, Inc.
    230 Burnt Meadow Road
    Groton, MA  01450-1539
    Tel.:  978-448-3188
    WWW: http://www.dexa.com
    email: support@dexa.com





	
