Configuration Reference

This page is automatically compiled, and documents all the configuration directives that are available in PHP Weathermap Version 0.81.

Introduction

Node-specific Configuration Directives

NODE

NODE nodename

The initial definition of a NODE. This must come before any other configuration related to this node.

The 'nodename' is used in link definitions to specify which nodes the link joins. The nodename is must be a single word, with no spaces. XXX

There is one special node name, 'DEFAULT', which allows for the setting of defaults. All nodes that are defined after this one in the configuration file will use the parameters of this node as a starting point. For this reason, it is best to define the DEFAULT node at the top of the configuration file, if you intend to use it.

Change History

0.7
Added DEFAULT node.

POSITION

POSITION x-coord y-coord

Specifies where to place the node on the map. Coordinates are in pixel units, with the origin at the top-left of the map.

LABEL

LABEL labeltext

Specifies a label for the node. Everything to the end of the line is used.

If the node has an ICON defined as well, then you can specify the position of the label relative to the node's centre-point by using LABELOFFSET.

This is drawn using the font specified by LABELFONT in the colours specified by LABELFONTCOLOR, LABELFONTSHADOWCOLOR, LABELBGCOLOR and LABELOUTLINECOLOR.

ICON

ICON iconimagefile

Specifies an icon to use for the node.

The filename can either be a full path to the image, or a relative one.

The icon file must be in PNG format. Alpha-transparency within the icon should be honoured by Weathermap, to create irregular shapes.

The size of the icon image is used by LABELOFFSET to decided how far to move the label, if you use compass-point offsets.

LABELOFFSET

LABELOFFSET compass-point
LABELOFFSET x-offset y-offset

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.

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.

For more control, you can specify an integer offset for the x and y positions of the label (e.g. LABELOFFSET -10 -20) instead.

Change History

0.7
Originally added LABELOFFSET

LABELFONT

LABELFONT fontnumber

Specify the font used for drawing the LABEL.

Fonts are specified by number. The GD library that Weathermap uses has 5 built-in fonts, 1-5. You can define new fonts based on TrueType or GD fonts by using the FONTDEFINE directive.

Change History

0.7
Global NODEFONT became per-node LABELFONT.
0.6
Originally added NODEFONT.

*COLOR

LABELFONTCOLOR red green blue
LABELFONTSHADOWCOLOR red green blue
LABELBGCOLOR red green blue
LABELOUTLINECOLOR red green blue

Specify the colours used for drawing the LABEL.

red, green and blue are numbers from 0 to 255.

LABELFONTSHADOWCOLOR, LABELBGCOLOR and LABELOUTLINECOLOR have an additional option - 'none' - which stops that element of the LABEL being drawn. LABELFONTSHADOWCOLOR defaults to 'none'.

Change History

0.8
Added LABELFONTCOLOR, LABELFONTSHADOWCOLOR, LABELBGCOLOR and LABELOUTLINECOLOR.

INFOURL

INFOURL url

Creates a hyperlink in the HTML output.

If you are using the HTML output facility, then a link is added to the <map> section of the HTML so that when you click on the node, you are taken to the url specified here.

OVERLIBGRAPH

OVERLIBGRAPH url

Creates a popup image in the HTML output.

If you are using the HTML output facility, and HTMLSTYLE is set to 'overlib', then a link is added to the <map> section of the HTML so that when you move the mouse pointer over the the node, a box will pop up containing the image that you specify. Typically used to link to historical data in your network monitoring system.

Examples

Typical use of OVERLIBGRAPH
OVERLIBGRAPH http://www.yoursite.net/mrtg/router1-cpu-daily.png

OVERLIBWIDTH

OVERLIBWIDTH imagewidth

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.

Change History

0.7
Originally added OVERLIBWIDTH and OVERLIBHEIGHT based on code by Niels Baggesen.

OVERLIBHEIGHT

OVERLIBHEIGHT imagewidth

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 OVERLIBWIDTH, for either to have any effect.

Change History

0.7
Originally added OVERLIBWIDTH and OVERLIBHEIGHT based on code by Niels Baggesen.

Link-specific Configuration Directives

LINK

LINK linkname

The first line of a LINK definition.

The linkname must be unique within the map, and must not contain spaces. The only place it currently appears is in the small title-bar of a popup graph if you specify an OVERLIBGRAPH, however.

There is one special link name, 'DEFAULT', which allows for the setting of defaults. All links that are defined after this one in the configuration file will use the parameters of this link as a starting point. For this reason, it is best to define the DEFAULT link at the top of the configuration file, if you intend to use it.

NODES

NODES nodename{:offset} nodename{:offset}

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.

Optionally, you can add an offset after a nodename, to move the location of that end of the link. This can help with crowded areas of the map, and also in making parallel links. Valid offsets are named after compass-points: N,S,E,W,NE,NE,SE,SW.

The order of the nodes is significant. When reading data sources, the flow from the first node to the second is considered 'out' and from second-to-first is 'in'.

Examples

Two parallel links, using offsets
LINK firstlink
  NODES node1:E node2:E

LINK secondlink
    NODES node1:W node2:W

Change History

0.8
Added ability to specify node offset.

TARGET

TARGET targetspec

Specifies where to look for the current throughput information for this LINK. Currently this can be done in 5 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
  • a path to an MRTG-produced HTML "graph holder" page.
  • a path to a tab-delimited text file
  • 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.

The default DS names for RRD files are 'traffic_in' and 'traffic_out', which works with the majority of Cacti RRD files. For MRTG-produced RRD files, the names are 'DS0' and 'DS1'. You can also specify '-' for either DS name, which tells Weathermap to ignore this rrd file for the purposes of the input or output value. This is mainly useful in combination with the aggregation feature.

For tab-delimited data files, the format is plain-text, with three tab-seperated columns. The first one is a linkname, and the second and third are traffic-in and traffic-out, respectively. The linkname should match the name in the configuration file. This allows you to create one text file for the entire map from some outside source. Traffic in & out values can use the same "K,M,G,T" abbreviated forms as the BANDWIDTH configuration command. The file should have an extension of .txt or .tsv to be recognised as a tab-delimited file by Weathermap.

You can also specify multiple targets, which will then be added together to make the aggregate bandwidth which is then displayed. Specify the targets on one TARGET line, seperated with a space.

Examples

Using multiple data sources for one link
TARGET link1a.rrd  link1b.rrd
Taking the input from one file, and output from another
TARGET poot.rrd:-:DS1 poot2.rrd:DS0:-
A suitable tab-delimited data file
link1    3M    4M
link2    66K   1.8M
link3    34.6K 113

Change History

0.8
Added ability to specify multiple targets. Added tab-delimited data source. Added 'ignore' DS name.
0.5
Added ability to specify DS names.

WIDTH

WIDTH width

Specifies the width of this link when drawn, in pixels.

BANDWIDTH

BANDWIDTH max-bandwidth
BANDWIDTH max-in-bandwidth max-out-bandwidth

Specifies the maximum throughput of this link, in bits per second.

This is used to calculate the percentage utilisation, 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 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.

Examples

A typical ADSL line (as seen from the CPE)
BANDWIDTH 2M 256K

Change History

0.5
Added support for decimals in BANDWIDTH specifications.
0.4
Added support for K,M,G,T suffixes on bandwidth specs. Changed bandwidth from bytes to bits.

BWLABEL

BWLABEL formatname

Specifies the type of 'bandwidth' label shown on each link.

The default is 'percent', but you can also have 'none', 'unformatted' or 'bits'. 'bits' shows the actual bandwidth, formatted using K,M,T,G suffixes where appropriate. 'unformatted' takes the value from the TARGET and displays it without any formatting - this can be useful for mapping things other than bandwidth. 'none' hides the bandwidth label altogether.

Change History

0.8
Added unformatted format.
0.7
Changed from global BWLABELS to per-link BWLABEL.

BWFONT

BWFONT fontnumber

Specify the font used for drawing the BWLABEL boxes.

Fonts are specified by number. The GD library that Weathermap uses has 5 built-in fonts, 1-5. You can define new fonts based on TrueType or GD fonts by using the FONTDEFINE directive.

*COLOR

OUTLINECOLOR red green blue
BWOUTLINECOLOR red green blue
BWFONTCOLOR red green blue
BWBOXCOLOR red green blue

Specify the colours used for drawing the link.

red, green and blue are numbers from 0 to 255.

OUTLINECOLOR, BWOUTLINECOLOR and BWBOXCOLOR have an additional option - 'none' - which stops that element of the link being drawn.

Change History

0.8
Added OUTLINECOLOR, BWOUTLINECOLOR, BWFONTCOLOR and BWBOXCOLOR.

INFOURL

INFOURL url

Creates a hyperlink in the HTML output.

If you are using the HTML output facility, then a link is added to the <map> section of the HTML so that when you click on the (weathermap) link, you are taken to the url specified here.

OVERLIBGRAPH

OVERLIBGRAPH url

Creates a popup image in the HTML output.

If you are using the HTML output facility, and HTMLSTYLE is set to 'overlib', then a link is added to the <map> section of the HTML so that when you move the mouse pointer over the the (weathermap) link, a box will pop up containing the image that you specify. Typically used to link to historical data in your network monitoring system.

Examples

Typical use of OVERLIBGRAPH
OVERLIBGRAPH http://www.yoursite.net/mrtg/router1-link2-daily.png

Change History

0.0pre
Odd fact: This command, and the accompanying code to generate overlib imagemaps, were the first modification I ever made to the GRNET perl weathermap, and was what got me interested in writing my own version.

OVERLIBWIDTH

OVERLIBWIDTH imagewidth

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.

Change History

0.7
Originally added OVERLIBWIDTH and OVERLIBHEIGHT based on code by Niels Baggesen.

OVERLIBHEIGHT

OVERLIBHEIGHT imagewidth

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 OVERLIBWIDTH, for either to have any effect.

Change History

0.7
Originally added OVERLIBWIDTH and OVERLIBHEIGHT based on code by Niels Baggesen.

VIA

VIA x-coord y-coord

Specify an additional point that a link must pass through.

A link normally goes in a straight line between the two nodes listed in the NODES configuration line. If you need it to go around something else, or to seperate two parallel links so that the bandwidth labels are all visible, you can make the link curve.

If you specify multiple VIA lines, then the link will pass through each in turn, in the order they are specified.

Change History

0.8
Originally added VIA.

ARROWSTYLE

ARROWSTYLE stylename
ARROWSTYLE width length

Specifies 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.

Finally, you can get finer control by adjusting the size yourself. The width and length of the head are in units of link-width.

Classic is equivalent to '4 2' and Compact is equivalent to '1 1'.

Change History

0.8
Added custom numeric form.
0.7
First added.

Global Configuration Directives

BACKGROUND

BACKGROUND imagefile

Specify an PNG image file to be used as a background image.

Any WIDTH and HEIGHT specifications will be ignored - the map will take the size of the background.

WIDTH

WIDTH map-width

Specifies the width of the map image in pixels.

If a BACKGROUND is specified, and the imagefile is successfully loaded, then any WIDTH specified is ignored. If neither a BACKGROUND or WIDTH is specified, then the default WIDTH is 800 pixels.

HEIGHT

WIDTH map-height

Specifies the height of the map image in pixels.

If a BACKGROUND is specified, and the imagefile is successfully loaded, then any HEIGHT specified is ignored. If neither a BACKGROUND or HEIGHT is specified, then the default HEIGHT is 600 pixels.

HTMLOUTPUTFILE

HTMLOUTPUTFILE htmlfile

This specifies the name of the HTML file that will be generated.

The equivalent command-line option takes precedence over this configuration line, if both are used.

IMAGEOUTPUTFILE

IMAGEOUTPUTFILE imagefile

This specifies the name of the PNG file that will be generated.

The equivalent command-line option takes precedence over this configuration line, if both are used.

FONTDEFINE

FONTDEFINE fontnumber gdfontfile
FONTDEFINE fontnumber ttffontfile fontsize

Defines a custom font to be used for text within the map.

By default, the GD library used by Weathermap has 5 fonts, numbered 1-5. FONTDEFINE allows you to define new font numbers, and link them to fonts in two other formats.

The first format is 'GD fonts', which are a bitmapped format used by GD alone. They are not scalable, and are also platform-specific (they use a different byte-order depending on the host). You should specify the full filename including any extensions.

The second format is TrueType fonts, which are scalable, standard and generally a lot nicer! This time, you need to specify the size that the font should be rendered at. The size is in pixels. You can load the same font into multiple fontnumbers with different sizes to use in different parts of a map.

The freetype library used in PHP makes a somewhat complex set of rules for where it will search for truetype fonts. The two easiest options are:

  • Use the full absolute path to your .ttf file
  • Keep your .ttf files in the Weathermap directory, and use the first part of the filename only, with no '.ttf' on the end.
The full set of rules is available here

Regardless of the format, the newly defined font can be used anywhere that you'd normally use a font number (for example, BWFONT or KEYFONT).

Examples

Defining a new Truetype font, with the font file in the weathermap directory
FONTDEFINE 10 VeraBd 16

Change History

0.8
First added FONTDEFINE

*FONT

TITLEFONT fontnumber
KEYFONT fontnumber
TIMEFONT fontnumber

Specify the fonts used for various text.

Fonts are specified by number. The GD library that Weathermap uses has 5 built-in fonts, 1-5. You can define new fonts based on TrueType or GD fonts by using the FONTDEFINE directive.

Change History

0.8
Originally added TIMEFONT.
0.7
Originally added TIMEFONT.
0.6
Originally added KEYFONT.

*COLOR

BGCOLOR red green blue
TIMECOLOR red green blue
TITLECOLOR red green blue
KEYTEXTCOLOR red green blue
KEYOUTLINECOLOR red green blue
KEYBGCOLOR red green blue

Specify the colours used for drawing the global elements of the map.

red, green and blue are numbers from 0 to 255.

LABELFONTSHADOWCOLOR, LABELBGCOLOR and LABELOUTLINECOLOR have an additional option - 'none' - which stops that element of the LABEL being drawn. LABELFONTSHADOWCOLOR defaults to 'none'.

Change History

0.8
Added TIMECOLOR, TITLECOLOR, KEYTEXTCOLOR, KEYOUTLINECOLOR and KEYBGCOLOR.
0.7
Added BGCOLOR.

KEYPOS

KEYPOS x-pos y-pos
KEYPOS x-pos y-pos headingstring

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. You can optionally 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.

Change History

0.6
Added ability to change text.

TIMEPOS

TIMEPOS x-pos y-pos
TIMEPOS x-pos y-pos formatstring

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 -200 or so.

You can optionally 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.

Change History

0.6
Added ability to change text.
0.5
Originally added TIMEPOS

TITLE

TITLEPOS titlestring

Specifies the title text.

The TITLE is shown in file-selectors for both the editor and the Cacti plugin. If you'd like the title to be shown on the map too, then add TITLEPOS line also.

Change History

0.8
Originally added TITLEPOS.

TITLEPOS

TITLEPOS x-pos y-pos
TITLEPOS x-pos y-pos headingstring

Specifies the position of the title text.

If no TITLEPOS line is given, then no title is drawn. You can optionally specify an additional parameter, to change the title. Any text after the second coordinate is taken as a new TITLE.

Change History

0.8
Originally added TITLEPOS.

KILO

KILO number

Specifies base value for kilo, mega and giga abbreviations.

Both BANDWIDTH and BWLABEL can use K,M,G,T as abbreviations for thousands, millions and so on. You can define what the multiple used is. The default is 1000.

Change History

0.4
Originally added KILO.

HTMLSTYLE

HTMLSTYLE formatname

Specifies the HTML output style.

When HTML output is enabled, there are two variations, which you can choose between. 'static' is a basic HTML page with client-side imagemap, but no 'pop up' graphs. 'overlib' adds the use of the OverLib library to the page, so that pop up graphs can work, too. This requires Javascript, which is why 'static' is the default.

SCALE

SCALE min max red green blue
SCALE min max red green blue red2 green2 blue2

Defines one 'span' within the link colour-coding table.

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 specify two colours on the line (the second form above), then the colour chosen for the link will be calculated as a proportion between the two colours. You can avoid specifying many SCALE lines this way.

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. Any percentage not matched by SCALE rules is rendered in grey.

Examples

Setting up a (very simple) colour scale. Colours run smoothly from green to red.
SCALE 0 100   0 255 0   255 0 0
The default scale set
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

Change History

0.8
Added interpolated scale colours.
0.5
Changed to allow min and max to be fractional.