Copyright 2005 Howard Jones, howie@thingy.com. (Website)

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, and 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. It also has a interactive map editor, so you can largely avoid the text configuration files, if you prefer.

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 with PNG and TrueColour support. You will need command-line (aka shell/ssh/telnet) 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.

I've broken the rest of this manual up into sections - an Installation guide for the command-line program, a quick-start basic intro, a reference of all the configuration options, an introduction to the new editor, and a FAQ/Tips section.

Support

Also new since the last version, there are two mailing lists for php-weathermap:

php-weathermap@thingy.com

General discussion of weathermap-related issues, bug reports and development. Fairly low traffic currently.

php-weathermap-announce@thingy.com

Very low volume list for new version announcements and other similarly rare events!

Also, if you have an RSS reader, you can subscribe to the 'appcast' feed for php-weathermap which contains roughly the same content as the -announce mailing list.

Installation Guide

Unpack the zip file into a directory somewhere. If you are intending to use the browser-based editor, then this location should be within the 'web space' on the web server that runs your data-collection application (that is, Cacti, MRTG, or similar). If you intend to just use the 'traditional' hand-written text configuration files, then it can be anywhere on that same server.

You'll need to edit two lines in the weathermap file:

• If you are on a Unix-based platform (BSD, OS X, Linux etc), the path in the very top line should be the full path to your command-line php executable
• Around line 20 or so, you may need to change the path to your rrdtool executable.

from a shell or command prompt, 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.

To use the editor to create your configuration files, there is more involved in the setup, which is covered in a separate section. At the moment, the editor won't let you do everything that editing a configuration file by hand does, so it's worth knowing how to do that, too.

Basics

The weathermap is defined by a plain-text file which by default is called weathermap.conf (you can have many configurations, 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 configuration 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

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

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 data-source is given in the TARGET line, and can be one of

• MRTG-generated HTML file (which contains a special HTML comment at the bottom with the current values)
• Cacti-generated RRD file
• Some other RRD file, provided you know how it is structured internally.

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:

There are also global settings to set which fonts are used for various elements of the map, where to position the colour-legend, if at all, and what files to output. The full list is in the Reference section below.

Command-line options Reference

--output is used to specify the name of the PNG file that is created. This can also now be specified inside the configuration file, instead.

--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. Note that particularly with PHP 4.x, it's possible that this will never end, as the way that references to objects are handled has changed between PHP 4 and PHP 5.

--dumpconfig writes out a new configuration file after reading in the specified one. This is useful when migrating older configuration files, as it will remove extra stuff made redundant by the newer 'default link and node' style of configuration. Obviously, you should be careful not to overwrite your existing configuration files!

--sizedebug simply tells weathermap to draw the links with themaximum bandwidth shown, not the current. It only works if BWLABEL is set to 'bits', but it is useful for checking you have the right sized links once you have finished your map.

--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. This can also now be specified inside the configuration file, instead.

Configuration Directives Reference

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

Defaults

New in version 0.7, you can specify defaults for all NODEs and all LINKs by defining two special items in your configuration file. These are a NODE and a LINK, both with the name 'DEFAULT'. You should make these the first definitions in your configuration file. The default NODE and LINK can take most parameters that a regular NODE or LINK has, with the exception of a few that don't make sense (default POSITION for a NODE, for example).

Once these items are defined, they will be used as defaults for any other NODE or LINK in your map that don't have a more specific configuration line of their own. If you want most of your LINKs to be narrower, having a 'LINK DEFAULT' with 'WIDTH 3' is the most efficient way to do that, for example.

Nodes

NODE

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. The special nodename of 'DEFAULT' marks the beginning of the default node definition - that which all other NODEs will copy unless they have their own parameters to override it.

POSITION

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

LABEL

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 which will be draw in it's position, instead.

INFOURL

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

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.

OVERLIBWIDTH

Specify the width, in pixels of the graph image referred to by OVERLIBGRAPH line. This is an optional extra that allows the OverLib library to make a better job of positioning the 'popup' image so that it doesn't appear off the edge of the screen. Typically, you would use this once, in the default node. If you use this, you must also use OVERLIBHEIGHT, for either to have any effect.

OVERLIBHEIGHT

Specify the height, in pixels of the graph image referred to by OVERLIBGRAPH line. This is an optional extra that allows Overlib to make a better job of positioning the 'popup' image so that it doesn't appear off the edge of the screen. Typically, you would use this once, in the default node. If you use this, you must also use OVERLIBHEIGHT, for either to have any effect.

ICON

If you specify an ICON, then the referred image is drawn, followed by the LABEL, if there is one. It will be centred around the POSITION of the node. The ICON must be a PNG file

LABELOFFSET

If you specify an ICON, and also a LABEL, then you will find that the label is often hard to read. LABELOFFSET allows you to move the position of the LABEL, so that it's not directly over the centre of the node anymore. There are two ways to do this. You can specify an integer offset for the x and y positions of the label (e.g. LABELOFFSET -10 -20), or you can specify a compass-point (e.g. LABELOFFSET S). The compass-point method takes the size of the ICON, and uses that as the offset distance in the direction you specify. This way, you can change your icon for something of a different size, and not need to change all your offsets. You can use the main 8 points of the compass: N, E, S, W, NE, SE, NW, SW.

LABELFONT

Since version 0.7, you can specify the font used to write the LABEL for a node. You can specify one of the 5 built-in GD fonts, which are numbered 1 to 5 in order of size. 3 is the default size. In version 0.6, this was a global setting called NODEFONT. This is still recognised, but will be removed in a later version.

Links

LINK

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

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

Specifies where to look for the current throughput information for this LINK. Currently this can be done in 3 ways:

• a path to a cacti-produced RRD file
• a path to a non-cacti-produced RRD file and the DS names within that RRD (new in 0.5)
• a path to an MRTG-produced HTML "graph holder" page.
• a URL to an MRTG-produced HTML "graph holder" page.

Since version 0.5, you can specify which DS names to use within RRD files with the following syntax:

The default DS names are traffic_in and traffic_out, which work with the majority of Cacti RRD files.

BANDWIDTH

The second form allows you to have 'asymmetric' links, like an ADSL, where the first number is the maximum bandwidth from node1 to node2 and the second is the maximum from node2 to node1, 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

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

If you use the HTML generation features of Weathermap, and also have HTMLSTYLE overlib in your configuration 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.

OVERLIBWIDTH

Specify the width, in pixels of the graph image referred to by OVERLIBGRAPH line. This is an optional extra that allows the OverLib library to make a better job of positioning the 'popup' image so that it doesn't appear off the edge of the screen. Typically, you would use this once, in the default link. If you use this, you must also use OVERLIBHEIGHT, for either to have any effect.

OVERLIBHEIGHT

Specify the height, in pixels of the graph image referred to by OVERLIBGRAPH line. This is an optional extra that allows Overlib to make a better job of positioning the 'popup' image so that it doesn't appear off the edge of the screen. Typically, you would use this once, in the default link. If you use this, you must also use OVERLIBHEIGHT, for either to have any effect.

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.

BWLABEL

Since version 0.7, you can specify the type of 'bandwidth' label shown on each link. The default is 'percent', but you can also have 'none' or 'bits'. See also BWFONT for more formatting options for these labels. In version 0.6 and prior, this was a global setting called BWLABELS. This is still recognised, but will be removed in a later version.

BWFONT

Since version 0.7, you can specify the font used to write the bandwidth/usage for a link. You can specify one of the 5 built-in GD fonts, which are numbered 1 to 5 in order of size. 2 is the default size. In version 0.6, this was a global setting called LINKFONT. This is still recognised, but will be removed in a later version.

ARROWSTYLE

Since version 0.7, you can specify the style of arrowhead used for drawing links. The default is 'classic' which has a wide arrowhead. You can also choose 'compact' which gives narrower heads.

Global Settings

WIDTH

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

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

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.

BACKGROUNDCOLOR

Since version 0.7, if no BACKGROUND is supplied, then you can specify a background colour for your map. The default is white. Valid values for red, green and blue are integers from 0-255.

KILO

SCALE

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

Specifies the position of the key, or legend, that shows what each colour-range means. If no KEYPOS line is given, then no legend is drawn - handy if you have many many colour ranges. Since version 0.6, you can specify an additional parameter, to change the heading above the colours in the key. This can be used to change the language of the map, for example.

KEYFONT

Since version 0.7, you can specify the font used to write the text in the key. You can specify one of the 5 built-in GD fonts, which are numbered 1 to 5 in order of size. 3 is the default size.

TIMEPOS

Specifies where to draw the timestamp on the map. If no TIMEPOS line is given, then the timestamp is drawn in the top-right corner. To hide it completely, set y to be -20 or so. Since version 0.6, you can specify an additional parameter to change the text of the timestamp. This text can contain special tokens which are substituted with parts of the current time. The default timestamp text is Created: %b %d %Y %H:%M:%S. The tokens used are those accepted by the PHP strftime function. For a full list see the PHP manual page

HTMLSTYLE

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.

HTMLOUTPUTFILE

This specifies the name of the HTML file that will be generated, and enables HTML generation. The equivalent command-line option takes precedence over this configuration line.

IMAGEOUTPUTFILE

This specifies the name of the image file that will be generated. The equivalent command-line option takes precedence over this configuration line.

TITLE

A Sample Config

#
# some initial comments...
#
BACKGROUND background.png
HTMLOUTPUTFILE example.html
IMAGEOUTPUTFILE example.png
TITLE Network Overview
HTMLSTYLE overlib
KEYPOS 10 400
KEYFONT 2

LINK DEFAULT
	BANDWIDTH 100M
	BWLABEL bits
	BWFONT 1
	
NODE DEFAULT
	LABELFONT 2
	LABELOFFSET s

NODE transit
	POSITION 400 180
	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

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
	ARROWSTYLE compact
	WIDTH 4
	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

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

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

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

The Map Editor

FAQ & Useful Tips

FAQs

Here are a few things that have come up more than once from previous versions. Also, it's worth checking the online copy of this document, which will be updated over time.

I need to have a link that isn't just a straight line...how can I do this?

Right now, the way you'd do this is to create a 'filler' node at the point where you want to turn a corner, without a label, and then two links one from A to 'filler' and one from 'filler' to B, both with the same BANDWIDTH, TARGET and so on. It's not pretty but it will do what you want. I intend to address this better in a future release.

I need to have more than one link from node A to node B...how can I do this?

You can use the 'non-straight' links technique above to how one or both links take a different route, and not overlap.

Will you extend weathermap to do XYZ?

It depends. I have an internal idea of what I want weathermap to be like. I don't want it to feel (too much) like a small program with everyone's wishlist bolted on afterwards. If it seems like something that a number of people could use, and doesn't dramatically change the direction of the program (it won't get mail-reading capability [*] anytime soon), then it stands a better chance. Things that take dozens of parameters to adjust something very subtle are less likely. Ultimately, it is a GPLed program though, so you can always add your own features! I try to keep a todo list on the website for current work-in-progress.

How can I possibly repay you for making my life and work so much easier?

Actually, this one isn't very frequent. If you do find yourself asking it, there are the ubiquitous Amazon wishlists at my homepage, though. I do like to hear from users anyway - it's nice to know that people do use this thing.

I get some error about 'module not found', or similar...can you help?

The answer is probably no, or at least not directly. In most cases, this is the result of a missing dependency, either PHP with no GD, or with an older version, or without PHP support, or without TrueColour support. I do try to extend weathermap to make these error messages more explanatory wherever possible, but ultimately, you need to get PHP working first. Beware that on some systems you can have a working GD in your 'web' PHP (mod_php) and have a non-working command-line PHP. Also be sure that the PHP you get from the command-line is the same installation as you expect - 'which php' and 'whereis php' will provide some *nix users with an idea that they are running the right one, as does 'php -m' and 'php -v' (is it the version you expect?).

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. No longer updated.

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.