This page describes in more detail the scripts which create my satellite Internet monitoring page. This is effectively an HTML markup of the README file in the distribution.

Download

The scripts are here. Before downloading them, read on to see if you can use them or not.

What it is

This is an adaptation of the scripts I have written to monitor my own network connections. 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 “web page” (four bytes) from Greg's external web server—see 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, Linux and Apple Mac OS X. The installation makes some assumptions; it's probably best to run it as I have tested it, though feedback and improvements are welcome.

Prerequisites

I've only tried this on FreeBSD, Linux (Debian) and Mac OS X. I expect the scripts will work just as well with NetBSD or OpenBSD. They won't work with Microsoft.

You'll need to install gnuplot to perform the plots. Linux installations also need wget.

Installation

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

Collecting data

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. The link shows what you should expect to see, but it's not the same as the real file in the distribution. If you're running a web server, you can create a symbolic link to the html directory.