PHP Weathermap is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

PHP Weathermap is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with PHP Weathermap; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA

Example Weathermap

Introduction

PHP Weathermap is one of many implementations of the same basic idea - take data from your network devices and use it to provide a single-page overview of the current state of network, like the one to the right. It complements a tool like MRTG, Cricket or Cacti, that provide in-depth graphing, and historical information, and can use data from those systems to produce it's maps. In fact, it requires some other data-collection source, as it does no device-polling on it's own.

This particular version is written in PHP, based on extensions I made to a perl version by Panagiotis Christias. It can read statistics data from MRTG-produced HTML files, and from RRD files, such as those produced by newer MRTG setups, Cacti (my favourite) or another tool. It can also generate HTML 'holder' files for the map images, which can include DHTML overlays of historical data and links into your other monitoring/statistics system.

Based on lessons learned with the perl version, this one has a very restricted set of dependencies - you'll need a recentish PHP (>4.3.0 I think) including the CLI version and the 'gd' extension. You will need command-line access to the server which will host the maps. To read RRD files, you'll need the rrdtool command-line program. Apart from the gd module, these requirements are the same as for Cacti, which is the most-tested partner stats system.

For the benefit of users of either the GRNET or my perl weathermap, your existing config files should still work in the PHP version, at least with version 0.4.

I've broken the rest of this manual up into sections - Installation guide, a quick-start basic intro, a reference of all the config options, and a FAQ/Tips section.

Installation Guide

Unpack the zip file into a directory somewhere. It's not a regular PHP file you run from your webserver, so it doesn't need to be in your web directories in particular. You'll need to edit two lines in the weathermap.php file: That should be it! You should be able to run
./weathermap.php
or
php weathermap.php
from a shell, and get a weathermap.png file in return, although with a lot of warnings about missing TARGETs. If you don't you should get some kind of error to help you figure out why.

Basics

The weathermap is defined by a plain-text file which by default is called weathermap.conf (you can have many configs, and choose between them with command-line switches). By default, weathermap will read that file, and produce a single PNG file called weathermap.png.

The config file has three sections: Node definitions, Link definitions and Global settings. There is an example of a complete file at the bottom of this page.

Nodes

NODE nycore1
    LABEL NYC
    POSITION 30 30
A simple NODE
Nodes are the points on your network that are joined together. Depending on the detail in the map, they might be cities or individual routers. In a basic map, a node has 3 pieces of information - an internal name which must be unique to this node, it's position from the top-left corner of the map, in pixels, and optionally a label, which will appear within the box marking the position of the node. Nodes without a label don't appear on the map at all, but can still be used as an endpoint for a link.

Links

LINK backbone1
    NODES nycore1 paix1
    BANDWIDTH 3M
    TARGET ../my-mrtg-data/backbone1.html
A simple LINK
Links are the network routes between the Nodes. Typically they are actual network links, but they can be anything that you can get numbers for that make sense on map.

An absolute minimal link has 3 pieces of information too. They are the unique internal name for this link, and unique node names for the two endpoints. To show current usage on the map, you'll need to give two more pieces: the maximum bandwidth on the link, and a way to get the current throughput. The BANDWIDTH is measured in bits/sec, and can include the usual K,M,G and T suffixes for large values. The datasource is given in the TARGET line, and can be one of

One important note: the order of the nodes in the NODES line is significant. The first node is considered to be the 'local' one when thinking about the data source in the TARGET. 'out' will be 'out' relative to the first node. If you find the map shows all your data flowing in the wrong direction, try swapping the order of the nodes here.

Global Settings

These settings usually live at the top of the text file, and specify basic information about the map. The minimum settings are:
WIDTH 800
HEIGHT 600
This is specifies the size of the map in pixels. If you want something a bit fancier than a plain white background, you can make up a background image to use in PNG format. In that case, the map will be the size of the background image:
BACKGROUND western-europe.png
You can also specify whether to show percentage utilisation or absolute bandwidth figures in the small boxes on the link arrows. BWLABELS percent is the default, but BWLABELS bits gets you labels in Kilo/Mega/Gigabits per second.

Command-line options Reference

The unix man-style specification for php-weathermap.php is:
./php-weathermap.php [--config configfile] [--output pngfile] [--htmloutput htmlfile] [--debug] [--dumpafter]
As you can see, all the parameters are optional! By default the script will look for a configuration file called weathermap.conf, and produce a PNG image file called weathermap.png.

--output is used to specify the name of the PNG file that is created.

--config is used to specify the name of the configuration file that is read.

--debug enables a lot of chatty debug output that may be useful in the event of a problem. In case --debug isn't verbose enough for you, --dumpafter dumps the whole of the internal structure used by weathermap at the end of a run.

--htmloutput specifies the name for an HTML file to be generated to go with the PNG image file. This HTML can include imagemap and DHTML features to make your weathermap interactive to different degrees. This is governed by the HTMLSTYLE global setting, and INFOURL and OVERLIBGRAPH settings in NODE and LINK definitions.

Configuration Directives Reference

This is a complete reference of all the possible configuration file directives. After that is a sample config, which shows how it all fits together.

Nodes

NODE

NODE nodename
The first line of a NODE definition. The nodename must be unique within the map and is used in the NODES specification of a LINK.

POSITION

POSITION x y
Where to place the NODE against the background of the map. The origin (0,0) is the top-left of the map.

LABEL

LABEL labeltext
If there is a LABEL specified, then it is shown on the map in a box centred around the POSITION specified. If no LABEL is specified, you can still use the NODE as an endpoint for LINKs, but it won't be visible in it's own right. The exception is if you have an ICON.

INFOURL

INFOURL url
If you use the HTML generation features of Weathermap, then it will produce an HTML client-side imagemap to go with your PNG graphical map. For NODEs (or LINKs) that have an INFOURL line, it will generate a link to that URL, when you click on the NODE in question. Typically this would be a page within your network statistics software.

OVERLIBGRAPH

OVERLIBGRAPH url
If you use the HTML generation features of Weathermap, and also have HTMLSTYLE overlib in your config file, then the generated HTML will make use of the OverLib DHTML library to produce a 'popup' image when you hover over the relevant NODE or LINK. The image that pops up will be the one specified here. Typically, this will be a graph from your network statistics software.

ICON

ICON iconfilename
If you specify an ICON, then the referred image is used instead of a boxed-LABEL. Like the LABEL, it's centred on the POSITION. The ICON must be a PNG file.

Links

LINK

LINK linkname
The first line of a LINK definition. The linkname must be unique within the map. The only place it really appears is in the small title-bar of a popup graph if you specify an OVERLIBGRAPH, however.

NODES

NODES node1 node2
These are the NODEs that this link joins. There can be only two. They are the 'nodename's from the NODE line for each node.

TARGET

TARGET targetspec
Specifies where to look for the current throughput information for this LINK. Currently this can be done in 3 ways: The last of these relies on your PHP installation having the "fopen URL extension" enabled. As far I know, it is enabled by default on a new install of current PHP version.

BANDWIDTH

BANDWIDTH a
or
BANDWIDTH a b
Specifies the maximum throuput of this link, in bits per second. This is used to calculate the percentage use, which in turn is used to make the colour for the link arrow, and optionally the label on the link.

The second form allows you to have 'asymmetric' links, like an ADSL, where the first number is the maximum bandwidth from link1 to link2 and the second is the maximum from link2 to link1, as they are given in the NODES line. Bandwidths can also use K,M,G and T suffixes to specify large values. Also see the KILO global option though.

INFOURL

INFOURL url
If you use the HTML generation features of Weathermap, then it will produce an HTML client-side imagemap to go with your PNG graphical map. For LINKs (or NODEs) that have an INFOURL line, it will generate a link to that URL, when you click on the LINK in question. Typically this would be a page within your network statistics software.

OVERLIBGRAPH

OVERLIBGRAPH url
If you use the HTML generation features of Weathermap, and also have HTMLSTYLE overlib in your config file, then the generated HTML will make use of the OverLib DHTML library to produce a 'popup' image when you hover over the relevant LINK or NODE. The image that pops up will be the one specified here. Typically, this will be a graph from your network statistics software.

WIDTH

WIDTH width
Specify a width in pixels for the main 'line' part of the link. This allows less important links on the map to be thinner. The default width is 7 pixels.

Global

WIDTH

WIDTH w
Specifies the width of the map image in pixels. If neither a BACKGROUND or WIDTH is specified, then the default WIDTH is 800 pixels.

HEIGHT

HEIGHT h
Specifies the height of the map image in pixels. If neither a BACKGROUND or HEIGHT is specified, then the default HEIGHT is 600 pixels.

BACKGROUND

BACKGROUND filename
If a BACKGROUND is supplied, then the WIDTH and HEIGHT global settings are ignored, in place of the width and height of the background image. The background image must be in PNG format.

KILO

KILO base
New with 0.4, you can specify the BANDWIDTH of LINKs using the usual suffixes for Kilo-, Mega-, Giga- and Tera-bit/sec links. By default, we treat 1K as being 1000. If you want 1K to be 1024, then KILO 1024 will do that for you. If you're really twisted, you can have any other value too. Other values are then calculated as 1M = 1K*1K, 1G=1M*1K and so on.

BWLABELS

BWLABELS percent
or
BWLABELS bits

SCALE

SCALE min max red green blue
SCALE is used to specify how LINKs are colour-coded according to their percent usage. If the percentage usage falls between min and max then the colour specified by red, green and blue is used to colour the link. Colour values are between 0 and 255. Percentages are between 0 and 100, obviously. If you don't add any SCALE lines to a configuration file, then a default set is added for you, but as soon as you add one, you'll need to make enough to cover the whole 0-100 range to get nice colours. The default set is:
SCALE   1   10    140     0  255
SCALE  10   25     32    32  255
SCALE  25   40      0   192  255
SCALE  40   55      0   240    0
SCALE  55   70    240   240    0
SCALE  70   85    255   192    0
SCALE  85  100    255     0    0

KEYPOS

KEYPOS x y
If no KEYPOS line is given, then no legend is drawn - handy if you have many many colour ranges.

HTMLSTYLE

HTMLSTYLE static
or
HTMLSTYLE overlib
If HTML generation is enabled on the command-line, this specifies what type of HTML file will be generated. static produces a plain HTML file with the image, and a clickable imagemap. Any LINK or NODE in the configuration file that contains a INFOURL entry will be clickable. overlib uses Erik Bosrup's overlib DHTML library to produce fancy 'popup' graphs for all NODEs and LINKs that have an OVERLIBGRAPH entry, in addition to the clickable INFOURL links. The default is 'static'. A copy of a recent overlib.js is included with the PHP Weathermap distribution.

TITLE

TITLE titletext
If HTML generation is used, then this will be used for the <TITLE> tag contents in the HTML page.

A Sample Config

Here's a sample config, and here's what it produces. The data isn't live in the output, but it gives you an idea of what can be done. The initial background image is here. The config file is also in the docs directory of the distribution, should you want it.
BACKGROUND background.png
TITLE Network Overview

HTMLSTYLE overlib
BWLABELS bits

KEYPOS 10 400

NODE transit
	POSITION 400 200
	LABEL TRANSIT

NODE isp1
	POSITION 250 100
	LABEL ISP1
	INFOURL http://www.isp1.com/support/lookingglass.html

NODE isp2
	POSITION 550 100
	LABEL ISP2
	INFOURL http://www.isp2.net/portal/

NODE core
	POSITION 400 300
	LABEL core
	INFOURL https://core.mynet.net/admin/

NODE customer1
	LABEL xy.com
	POSITION 150 370

NODE customer2
	LABEL ww.co.uk
	POSITION 250 450

NODE infra
	LABEL INFRASTRUCTURE
	POSITION 450 450

NODE sync
	LABEL Sync
	POSITION 550 370

NODE site1
	LABEL site1
	POSITION 750 320
	

NODE site2
	LABEL site2
	POSITION 750 420

LINK sync-core
	NODES sync core
	TARGET data/sync_traffic_in_259.rrd
	OVERLIBGRAPH http://support.mynet.net/cacti/graph_image.php?local_graph_id=256&rra_id=0&graph_nolegend=true&graph_height=100&graph_width=300
	INFOURL http://support.mynet.net/cacti/graph.php?rra_id=all&local_graph_id=256
	BANDWIDTH 100M


LINK sync-site1
	NODES sync site1
	WIDTH 3
	TARGET data/sync_traffic_in_257.rrd
	OVERLIBGRAPH http://support.mynet.net/cacti/graph_image.php?local_graph_id=254&rra_id=0&graph_nolegend=true&graph_height=100&graph_width=300
	INFOURL http://support.mynet.net/cacti/graph.php?rra_id=all&local_graph_id=254
	BANDWIDTH 2M


LINK sync-site2
	NODES sync site2
	WIDTH 3
	TARGET data/sync_traffic_in_251.rrd
	OVERLIBGRAPH http://support.mynet.net/cacti/graph_image.php?local_graph_id=248&rra_id=0&graph_nolegend=true&graph_height=100&graph_width=300
	INFOURL http://support.mynet.net/cacti/graph.php?rra_id=all&local_graph_id=248
	BANDWIDTH 1M


LINK transit-isp1
	NODES transit isp1
	TARGET data/trans1_traffic_in_352.rrd
	OVERLIBGRAPH http://support.mynet.net/cacti/graph_image.php?local_graph_id=355&rra_id=0&graph_nolegend=true&graph_height=100&graph_width=300
	INFOURL http://support.mynet.net/cacti/graph.php?rra_id=all&local_graph_id=355
	BANDWIDTH 10M


LINK transit-isp2
	NODES transit isp2
	TARGET data/trans1_traffic_in_438.rrd
	OVERLIBGRAPH http://support.mynet.net/cacti/graph_image.php?local_graph_id=433&rra_id=0&graph_nolegend=true&graph_height=100&graph_width=300
	INFOURL http://support.mynet.net/cacti/graph.php?rra_id=all&local_graph_id=433
	BANDWIDTH 34M


LINK core-transit
	NODES transit core
	TARGET data/trans1_traffic_in_350.rrd
	OVERLIBGRAPH http://support.mynet.net/cacti/graph_image.php?local_graph_id=347&rra_id=0&graph_nolegend=true&graph_height=100&graph_width=300
	INFOURL http://support.mynet.net/cacti/graph.php?rra_id=all&local_graph_id=347
	BANDWIDTH 100M


LINK cust1-core
	NODES customer1 core
	TARGET data/extreme_traffic_in_299.rrd
	OVERLIBGRAPH http://support.mynet.net/cacti/graph_image.php?local_graph_id=296&rra_id=0&graph_nolegend=true&graph_height=100&graph_width=300
	INFOURL http://support.mynet.net/cacti/graph.php?rra_id=all&local_graph_id=296
	BANDWIDTH 100M


LINK cust2-core
	NODES customer2 core
	TARGET data/extreme_traffic_in_286.rrd
	OVERLIBGRAPH http://support.mynet.net/cacti/graph_image.php?local_graph_id=283&rra_id=0&graph_nolegend=true&graph_height=100&graph_width=300
	INFOURL http://support.mynet.net/cacti/graph.php?rra_id=all&local_graph_id=283
	BANDWIDTH 100M


LINK infra-core
	NODES infra core
	TARGET data/extreme_traffic_in_294.rrd
	OVERLIBGRAPH http://support.mynet.net/cacti/graph_image.php?local_graph_id=291&rra_id=0&graph_nolegend=true&graph_height=100&graph_width=300
	INFOURL http://support.mynet.net/cacti/graph.php?rra_id=all&local_graph_id=291
	BANDWIDTH 100M

A Sample Config

FAQ & Useful Tips

FAQs

None yet. Ask something a few times, and it'll become one ;-) Also, check the online copy of this document, which will be updated over time.

Other Weathermaps

Obviously, you can't please everyone, so here's a list of other weathermap or network visualisation implementations that I know of. Some are open source, some aren't. All of them have some subtle or interesting wrinkle that the others don't. Let me know if you know of any others.
GRNET perl version by Panagiotis Christias.
Support only for MRTG, or anything else that can produce similar HTML files.
My own perl weathermap
A forked/modified version of the GRNET one above, adds imagemaps, DHTML, RRD-reading and a number of smaller tweaks.
Weathermap4RRD
Another fork of the GRNET perl map. Also with (only?) RRD support, and various graphical enhancements. Also now with a PHP version!
Indiana University Abilene Weathermap
Another perl (i think) script, but with a rather different map design. Can show error rates on links, too.
PREGINET Network Weathermap
Another perl open source map. Works by reading MRTG logs, as far as I can tell.
V13 netmap (click 'netmap' in the left hand panel - I love frames)
Similar output to this program, but does all it's own SNMP data collection.