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.
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:
- 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.
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.
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
- 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 inside.
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:
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 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 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 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 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 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 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 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 targetspec
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 an MRTG-produced HTML "graph holder"
page.
- a URL to an MRTG-produced HTML "graph holder"
page.
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 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 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 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
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 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 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 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 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 percent
or
BWLABELS bits
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 x y
If no KEYPOS line is given, then no legend is drawn -
handy if you have many many colour ranges.
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 titletext
If HTML generation is used, then this will be used for
the <TITLE> tag contents in the HTML page.
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
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.
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.