IEPM

PingER Performance Reporting Tool for Monitoring Hosts - Implementation Notes

SLAC Home Page

Introduction

This document is for people installing the PingER reporting tool at collection sites. A pre-requisite is to
install the PingER measurement and data-collection tools. The current page may also be useful to implementers or people needing to enhance or debug the tool. Further information on the tool may be found by reading the manual pages. For more information read the code which is reasonably well commented.

This tool is a Perl 5 CGI script to provide tabular information on the most recent monitoring results for remote sites being pinged. It reads the raw monitoring data, selects the most recent measurements for each remote host, and builds a Web HTML page in tabular form that includes hot links to allow sorting of the table; to access the raw data for each host; and to access other information for each site (such as a plot of the ping performance for the last 180 days). In addition instructions are provided on how to use the table, further sources of information and manual pages for the script. The script can generate a tab-separated-value (tsv) file for use wih Excel and other spreadsheets.

The package is designed to be secure and exportable to other sites and so has many configuration options (e.g. where to find various files, the text providing instructions and further information) that may change from site to site. The idea is that collection sites can install this package and provide some analysis of the data they have collected without relying on the analysis sites. It requires Perl 5 and the cgi-lib library written by Steve Brenner.

To view an example of the report generated, point your browser to:

http://www-iepm.slac.stanford.edu/cgi-bin/connectivity.pl

Configuration

The script is designed so that a small number of changes will customize the script at each site. The intent is that once a site has installed the script and done the customization, future updates to the script should require minimal work to re-customize for the site. Customization is accomplished by editing a configuration file (connectivity.cf) which is commented to help in understanding the purposes of the configuration variables set in there). This file contains the locations (file paths and names, and URLs) of various files and Web pages used by the script (connectivity.pl), Where possible, the script provides defaults for configuration settings (e.g. the default header file has the same path and name as the script but with the trailing ".pl" replaced by ".head").

Two changes may be required within the script itself (connectivity.pl). These are:

Files Needed

The tool uses the following files, directories, and URLs (the names in capitals are the identifiers used in the configuration file, $dir in the Default column means the file is found in the same directory as the script (connectivity.pl), $path in the Default column means the URL is found in the same URL path as connectivity.pl)

File Name Required Default Purpose
connectivity.pl Mandatory None The main driver CGI script.
connectivity.cf Mandatory $dir The configuration file for connectivity.pl.
connectivity.foot Optional $dir An html file containing information to be displayed after the table. If not provided the footer will be located in the same path as connectivity.pl. If it is not there, then no footer will be displayed. The full path and name is in FOOTFILE.
connectivity.head Optional $dir An html file containing header information to be displayed before the table. If not provided, the header will be located in the same path as connectivity.pl. If it is not there, then no header will be displayed. The full path and name is in headFILE.
cgi-lib Mandatory $dir Steve Brenner's cgi-lib. The full path and name is in CGILIB.
mon-lib.pl Mandatory $dir A set of utility subroutines. The full path and name is in MONLIB.
getsite.cf Optional   Provides a set of remote host name patterns and describes the mapping of host names to file names containing host data. If not provided, then file names are automatically derived from the remote host names. The full path and name is in GETSITECF.
       
Directory Name     Purpose
DATADIR Mandatory None The directory where the script will find the ping data measurements.
TRENDSDIR Optional   The directory for trend type information (see also TRENDSURL).
       
URL Name     Purpose
SCRIPTURL Optional $path The URL of the connectivity script. If not provided, then the URL is assumed to be in the same URL path as connectivity.pl.
TRENDSURL Optional None The URL path to trend type information for the remote sites being monitored. The remote site name of each remote site being monitored is added to this URL to provide a pointer, for each site name, to more long term trend information. If not provided no pointers will be provided in the table to such trend information for each sitename (see also GETSITECF).
       
Column URLs     Purpose
URLCOLUMNn Optional N/A Column URLs in the configuration file connectivity.cf (see the file for more details),designate the columns that will link to plots, rawdata, dynamic probing (see below) of hosts, etc.

Installation

Contact your Webmaster to make sure your Web server has access to Perl 5 and that Steve Brenner's cgi-lib is installed and available and where they are located.

Copy and save mon-lib.pl so it is accessible and executable (in Unix mon-lib.pl can be made executing using the commandchmod a+x mon-lib.pl)by the Web server. The default is to save it in the same directory that connectivity.pl will be saved in (e.g. where the URL path /cgi-bin/ points to).

Copy getsite.cf to an appropriate location, the default is to put it in the same directory as mon-lib.pl.

Copy and edit the header (connectivity.head) and footer (connectivity.foot) files and save them in an appropriate place and note their locations in the configuration file.

Copy and edit the configuration file connectivity.cf) to customize for your site (see the comments in connectivity.cf plus the Files Needed section above for more information on customizing the configuration). Then store the edited configuration file in an appropriate location, the default is to place it in the same directory where you will save the connectivity.pl script itself (if you do not save it there then you will need to edit the connectivity.pl file to indicate where it can find the configuration file).

Copy and edit the connectivity.pl file to indicate (in the first line) where the Perl 5 interpreter is kept on your Web server. If you did not place the configuration file in the default location then you will also need to edit connectivity.pl to indicate where the configuration file has been stored. Next you will need to install the connectivity.pl script in the CGI directory of your Web server, and make it executable (e.g. in Unix by using the command chmod a+x connectivity.pl).

After installation please register so we can inform you of new releases, and also to add a pointer to your site in our WAN Monitoring page.

Hosts & Sites

In order to allow changes in the host being monitored at a given site, we use an algorithm to deduce the site name from a given host name. This algorithm is embedded in the mon-lib.pl library function GetSite. It is the same algorithm used to deduce the file names for the long term (180 day plots, and monthly tables) reports produced by SAS (a statistics package), and so can be used to point to such reports when they are available.

Dynamic Probing

To enable a user to check the current status of a host (e.g. via ping, traceroute etc.), for each host a link may be inserted into the table to point to a CGI script URL that probes that host. To facilitate this we are also providing some simple probing CGI scripts. These are available as follows (in the Source Code column <slac> is to be replaced by http://www.slac.stanford.edu/comp/net/mon/tool/).:

CGI Script Purpose Typical URL Source Code
Traceroute /cgi-bin/traceroute.pl?target=host <slac>traceroute.pl
Ping /cgi-bin/traceroute.pl?target=host&function=ping <slac>traceroute.pl

If you wish to use these scripts, they will need to be copied, installed in cgi-bin on your Web server, and made executable.

Debugging

As delivered the script has the "Taint" and "warning" flags set. To enable using the Perl debug facility, you my find it easier to temporarily remove the Taint flag (i.e. change "-Tw" to "-w" in the first line of the script).

A $debug variable is provided. As delivered this is set to -1. Possible values of $debug are:

$debug Value Purpose
-1 Ignore any bad data and provide no warnings
0 Provide warnings concerning bad input data
1 Provide diagnostic debugging information
Back to Top

Revised June 29, 2006
URL: http://www-iepm.slac.stanford.edu/pinger/tools/install.html
Comments to iepm-l@slac.stanford.edu