Network monitoring scripts

Greg Lehey, 12 January 2008

$Id: README,v 1.2 2008/01/12 02:31:19 grog Exp $

This is an adaptation of the scripts I have written to monitor my own
network connections.  See http://www.lemis.com/grog/satstats.html for
the original.

The graphs show:

    * Link status. This is the connectivity to the other end of the
      satellite link, measured by an ICMP echo (ping) packet once a
      minute. This should remain steady at 1. A drop to 0 indicates a
      link failure.

    * Network status. This is the number of remote systems responding
      to a ICMP echo (ping) packet at the same time as the link status
      ping. I currently ping 5 systems which I frequently access:
      freefall.FreeBSD.org, shell.mysql.com, www.auug.org.au,
      ozlabs.org and ftp.NetBSD.org. Normally this value should be
      5. If it's less, the script retries every second until full
      connectivity is restored.

    * TCP transfer speed. This is a reciprocal function of the time it
      takes to transfer a very small \u201cweb page\u201d (four bytes)
      from Greg's external web server\u2014see the right hand side of
      the plot for the scale. The values shown are reciprocal seconds:
      0.5 is 2 seconds, 2 is 0.5 seconds, etc. It seems that it takes
      about 4 seconds to perform the transfer, which is due mainly to
      satellite latency and connection setup and closing down.

These scripts work on FreeBSD and Apple Mac OS X.  They will probably
work under Linux, but I haven't checked that yet.  The installation
makes some assumptions; it's probably best to run it as I have tested
it, though feedback and improvements are welcome.

INSTALLATION
============

You'll need to install gnuplot (http://www.gnuplot.info/) to perform
the plots.

The archive itself is gzipped tar.  It's intended for installation in
a subdirectory called satstat.  To install, change to your home
directory and extract:

  $ cd
  $ tar xzvf satstat.tar.gz

This creates the directories satstat, satstat/data and satstat/html if
necessary, and populates them.  The files are:

README                      This file
config

	Basic configuration.  You'll need to change some of the
        entries to match your system.  Details are in the file.

crontab

	Draft entries for crontab to run the plotting scripts at
	regular intervals.

getsatstats

	A script to create the graphs at regular intervals.  I run
	this every 10 minutes via a cron job.

getsatstats.week

	A script to create the graphs once a day.  I run this in the
	early morning via a cron job.  This second file is needed
	because after collecting a fair amount of data, it can run for
	a very long time.

linkcheck

	The main script to perform the tests.

satplot

	Raw gnuplot commands to perform the 4 hour and 24 hour graphs.
	This is processed into a real file by the getsatstats script.
	You don't need to do anything with this file unless you change
	your directory structure.

satplot.all

	Raw gnuplot commands to perform the weekly and 3 monthly
	graphs.  This is processed into a real file by the
	getsatstats.all script.  You don't need to do anything with
	this file unless you change your directory structure.

tcpcheck

	Script to test the TCP connectivity, invoked by linkcheck.
	You shouldn't need to do anything with this file.

The directories data and html are populated by linkcheck and
getsatstats* respectively.  As supplied, there are some empty files
and the file satstats.html, which contains the text and links to the
graphs.

CONFIGURATION
=============

You'll need to modify the files 'config' to suit your local
configuration.  Read the instructions in the file.  If you use cron to
run the plot scripts, you'll need to copy the data in the file
'crontab' to your crontab, and also to modify it for your
installation.  Again, the instructions are in the file.

RUNNING
=======

Run the data collection script linkcheck without any parameters:

  $ cd satstat
  $ ./linkcheck &

It runs in the background; you don't need to do anything else.

The best way to run the plots is via crontab.  Read the instructions
in the file 'crontab'.  If for some reason you don't want to do this,
run getsatstats when you want an update, and getsatstats.week after
the first day of collection.  Due to brain damage in getsatstats.week
you shouldn't run it more than once a day, or it will leave holes in
your daily graphs.

VIEWING RESULTS
===============

Look at the file html/satstats.html with a web browser.  If you're
running a web server, you can create a symbolic link to the html
directory.

$Id: README,v 1.2 2008/01/12 02:31:19 grog Exp $