PINGMON 1.6 By Ian Chapman, September 2003
------------------------------------------

Requirements
------------

Perl : The recommended version is 5.8. Earlier versions >5.000 will probably work, but have
       not been tested.

Term::ReadKey : The recommended minimum version is 2.20, earlier versions may work, but have
                not been tested. Redhat Linux offers this as a pre-compiled RPM however it can
                also been downloaded from http://search.cpan.org/search?dist=TermReadKey

ANSI Terminal: Pingmon requires an ANSI terminal, either colour or monochrome. This isn't usually
               a problem as most terminals today are ANSI compliant.

Installation
------------

    Pingmon 1.6 has been tested and appears to work OK on:
        RedHat Linux 9 (X86) - xterm and virtual consoles
        Solaris 9 (SPARC) - dtterm in X

If you installed Pingmon in a package form such as RPM, then the following
installation procedures should have been done automatically by the installer.

Pingmon requires root permissions to run, so it is recommended you ensure
it has a permissions setting of 700 (chmod 700 pingmon.pl)

1. Copy the perl script "pingmon.pl" to to a location within your command
   path such as /usr/local/sbin or /usr/sbin . For example:

        cp pingmon.pl /usr/local/sbin

   Remember to set the location of the perl interpreter at the top of the 
   script, to that on your system. Usually /usr/bin/perl or 
   /usr/local/bin/perl

2. It's not required but recommended you create a symlink from pingmon.pl to
   pingmon. For example:

        ln -s /usr/local/sbin/pingmon.pl /usr/local/sbin/pingmon

3. By default, pingmon looks for its configuration files in /etc/pingmoncfg,
   so copy the directory pingmoncfg to /etc. For example:

        cp -pR pingmoncfg /etc

4. If you want sound, by default pingmon looks for its sound files in 
   /usr/share/sounds , so copy the sound files to this directory (make it, 
   if it doesn't exist). For example:

        mkdir -p /usr/share/sounds
	cp -p sounds/* /usr/share/sounds 

5. Read on to see how to configure Pingmon

Introduction
------------

Pingmon is a simple utility to monitor whether hosts are up or down on a 
network. The emphasis is on simple. If you want a network monitoring
utility with all the bells and whistles then pingmon is not for you. 

Pingmon came about because we simply wanted to be alerted when a host went
down on our UNIX network and most similar tools offered far more than we 
wanted. Pingmon simply runs in a terminal which can be constantly displayed
on a spare machine for example, and will give an optional  audible warning
should a host drop off the network. It does this by pinging each specified
host to test for basic network connectivity 

Features
--------

- Choose hosts to monitor. (Also supports specifying ranges)
- Set monitored hosts to be ignored. Useful for example if they are going 
  to be offline for a lengthy period of time. (Supports ranges)
- Specify for which hosts a log entry should be made if they go down.
  (Supports ranges)
- Choose between ICMP, TCP and UDP pings.
- Control the network traffic pingmon generates by specifying the rate at 
  which pings should be sent, as well as the delay between scans
- Colour Display and optional black and white display
- Optional audible warning if a host goes down
- Maintains a list of hosts which are currently down.
- Reload configuration files. No need to restart pingmon.

Configuration
-------------

By default, the configuration files are located in /etc/pingmoncfg

hosts.cfg
Add to this the lists of hosts you want to monitor.

ignore.cfg
Add to this any hosts which you want ignored. This is useful for example 
if a host is going to be offline for a long period of time. It makes sense 
to add the host here and not remove it from hosts.cfg because Pingmon will 
display the fact it is being ignored, hopefully acting as a reminder that 
it can be removed from the ignore list once the host is up again.

loghosts.cfg
Add to this any host for which a log entry should be made if it goes down

All three text files simply expect a hostname or an IP address per line. 
You can also specify ranges of machines if required. For example, on our 
network we have 120 linux machines and 20 Silicon Graphics machines. Their 
hostnames are linux1 ... linux 100 and sgo2-1 ... sgo2-20 . We can 
specify this as a range, with one range per line, for example:

linux!:1:100
sgo2-!:1:40

The ! character indicates where in the hostname the number should appear. 
The first number indicates the starting value whilst the second indicates 
the ending value. They should be separated by the : character. You can of 
course mix single host names and ranges in a single file.

Additional Configuration Options
--------------------------------

Additional configuration options to fine tune Pingmon can be found at the
start of the perl script, with explanations. You are advised to at least
check them.

Usage
-----

Upon running Pingmon, it will immediately start monitoring your hosts and 
displaying output. Whilst it is running, the following keys can be used.

S - Switch the sound on/off
C - Switch between colour and black & white display. Please be aware that 
    black & white mode still uses ANSI sequences, if this is an issue for 
    your terminal
R - Refresh the terminal if it becomes messed.
L - Reload the configuration files if they have been changed whilst 
    pingmon was running.
D - Display the list of hosts which are currently down.
+ - Increase Delay (slower scanning)
- - Decrease Delay (faster scanning)
Q - Quit

Pingmon will also respond to the following signals, their success will
largely depend on the operating system you are using:

SIGTERM, SIGABRT, SIGQUIT - Quits Pingmon
SIGHUP - Reloads the configuration

CONTACT
-------

For comment or suggestions, contact me at:

ian.chapman@bleach.demon.co.uk 
i.p.chapman@tees.ac.uk
