INSTALL

Network Weathermap
version 1.1.1 (20040422)
Panagiotis Christias, p.christias@noc.ntua.gr


1. Description

The network weathermap displays in a visual way the utilization of
network links. The required data are acquired from graphs created
arrows on a map representing the logical topology of the network.
The resulted image is presented in a web page using extra DHTML and
JavaScript code for web-over pop-ups, based on the OverLib JavaScript
library. The image can be automatically generated via cron.

 
2. Required software

The network weathermap is written in Perl programming language. It is
using the GD perl module for opening, manipulating and writing image
files. The GD module requires the Gd Graphics Library (libgd). The Gd
Graphics Library requires several libraries like freetype, libjpeg,
libpng and libz.

The current version of the network weathermap does not do any SNMP data
acquisition but relies on MRTG for that task since MRTG does it in a
simple and effective way. MRTG stores the values of the last SNMP query
as HTML comments within the HTML file that creates for each network link:

  <!-- maxin d 128563 --> <!-- maxout d 29795 -->
  <!-- avin d 17219 --> <!-- avout d 18115 -->
  <!-- cuin d 11369 --> <!-- cuout d 19663 -->
  <!-- avmxin d 23106 --> <!-- avmxout d 18598 -->

The network weathermap retrieves the HTML files directly from the file
system or remotely from a specified web server using GNU wget, parses
them and uses the current in and out values (cuin d and cuout d values)
to generate the map.


3. Installation and configuration

Perl, libgd and the GD perl modules, optionally wget too, should be
installed and be available in the system that will host the network
weathermap. MRTG should be installed, configured and run regularly for
the network links that will be displayed on the network weathermap.
The MRTG setup is not required to run on the same system with the
network weathermap. Nevertheless, the network weathermap should have
access the HTML files generated by MRTG. That can be direct file
system access or any network method supported by wget (HTTP, HTTPS,
FTP etc.).

The network weathermap is a single Perl script. There are 6 parameters
that are defined in the first lines of the script:

  1. the full path of the wget utility with its arguments:
     $WGET="/usr/local/bin/wget -qO -";

  2. the full path of the default configuration file, which can also be
     defined through the "-c" command line option:
     $CONFIG = "weathermap.conf";

  3. the full path of the output image file, which can also be defined
     through the "-o" command line option:
     $OUTPUT = "weathermap.png";

  4. the debug parameter, which can be accessed through the "-v"
     command line option:
     $DEBUG  = 0;

  5. the default wight and height of the output image in case no
     background image is defined in the configuration file:
     $WIDTH  = 880;
     $HEIGHT = 750;

The configuration of the network weathermap is defined in a single text
file (weathermap.conf). It includes the definition of:

  * nodes: name (NODE xxx), position on the image (POSITION x y) and
    label (LABEL zzz)

  * links: name (LINK xxx), start and end nodes (NODES xxx yyy), HTML
    file from MRTG (TARGET /xxx/yyy/zzz.hmtl or TARGET http://xxx/zzz.html
    etc). and bandwidth of the link (BANDWIDTH y) in Kbps.

  * image used as background (BACKGROUND /xxx/yyy/zzz.gif) or
    alternatively the size of the resulted image (WIDTH x and HEIGHT y).

  * position of the key in the image (KEYPOS x y )

  * color scale used for the link utilization (SCALE low hight rrr ggg bbb)

White spaces and empty lines are ignored. Shell-like comments (#...) are
supported.

See example/ directory for a sample configuration.

A HTML page can be written to host the network weathermap image. This
page can use HTML, DHTML and JavaScript features in order to create an
"interactive" version of the network weathermap using imagemaps and
web-over pop-ups displaying the MRTG graphs and linking to the MRTG pages.

Again, see example/ directory for such HTML files (weathermap.html and
weathermap-overlib.html).

The network weathermap can be executed via cron with a crontab entry
like:

*/5 * * * * /path/to/weathermap > /tmp/weathermap.out 2>&1


4. Links to used software

Perl programming language:
http://www.perl.org/

GD Graphics Library:
http://www.boutell.com/gd/

GD perl module:
http://stein.cshl.org/WWW/software/GD/
or http://www.cpan.org/

MRTG, The Multi Router Traffic Grapher:
http://people.ee.ethz.ch/~oetiker/webtools/mrtg/

GNU wget:
http://www.gnu.org/software/wget/wget.html

overLIB:
http://www.bosrup.com/web/overlib/


5. Usage examples:

6NET:
http://netmon.grnet.gr/6net.html

GRNET:
http://netmon.grnet.gr/map.shtml

GRNET Athens MAN:
http://netmon.grnet.gr/map-man.shtml

SEEREN:
http://netmon.grnet.gr/seeren.shtml