diff --git a/CHANGELOG.md b/CHANGELOG.md index aec042af..60b0144a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,6 +18,12 @@ IMPORTANT NOTE: This version only works on CACTI 1.x++! * dev: Pin the CI database image and shared test dependencies, disable persisted checkout credentials, and limit workflow permissions and runtime +--- 2.0.1 --- + +* issue#322: Refresh the bundled manual with current installation, upgrade, editor, image management and troubleshooting guides; retain the configuration and data-source references and repair documentation links +* issue#322: Update editor and map-management screenshots, including map creation, management, the viewer, hover graphs and Advanced settings; use compact previews with full-size links and refresh cached documentation assets +* feature#322: Add themed Docs access from the map heading and a Docs button after Rebuild All in map management, opening the bundled manual in a new tab + --- 2.0 --- * security: Add a version-safe CSP nonce (`plugin_weathermap_csp_nonce()`) to every inline ` -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +
Historical example network map with labelled nodes and directional traffic links
Example map object NODE:N104:0 +Example map object NODE:N105:0 +Example map object NODE:N106:0 +Example map object NODE:N107:0 +Example map object NODE:N108:0 +Example map object NODE:N109:0 +Example map object NODE:N110:0 +Example map object NODE:N111:1 +Example map object NODE:N111:0 +Example map object NODE:N112:0 +Example map object NODE:N113:0 +Example link sync-core +Example link sync-core +Example link sync-core +Example link sync-core +Example link sync-site1a +Example link sync-site1a +Example link sync-site1a +Example link sync-site1a +Example link sync-site1b +Example link sync-site1b +Example link sync-site1b +Example link sync-site1b +Example link sync-site2a +Example link sync-site2a +Example link sync-site2a +Example link sync-site2a +Example link sync-site2b +Example link sync-site2b +Example link sync-site2b +Example link sync-site2b +Example link transit-isp1 +Example link transit-isp1 +Example link transit-isp1 +Example link transit-isp1 +Example link transit-isp2 +Example link transit-isp2 +Example link transit-isp2 +Example link transit-isp2 +Example link core-transit +Example link core-transit +Example link core-transit +Example link core-transit +Example link cust1-core +Example link cust1-core +Example link cust1-core +Example link cust1-core +Example link cust2-core +Example link cust2-core +Example link cust2-core +Example link cust2-core +Example link infra-core +Example link infra-core +Example link infra-core +Example link infra-core
Network Map created with PHP Network Weathermap v0.98a \ No newline at end of file diff --git a/docs/example/graph_page.html b/docs/example/graph_page.html index 19cb75c4..a8cf587b 100644 --- a/docs/example/graph_page.html +++ b/docs/example/graph_page.html @@ -10,7 +10,7 @@

Your history here

- +Historical sample traffic graph

And this would normally be a page within your Cacti or MRTG system.

diff --git a/docs/example/label-positions-2.0.conf b/docs/example/label-positions-2.0.conf new file mode 100644 index 00000000..d24db81a --- /dev/null +++ b/docs/example/label-positions-2.0.conf @@ -0,0 +1,19 @@ +WIDTH 660 +HEIGHT 210 +KEYPOS -1 -1 +TIMEPOS -1 -1 +NODE DEFAULT + ICON 72 72 images/objects/cisco-router.png + LABELFONT 3 +NODE top + LABEL Top (N) + POSITION 110 100 + LABELOFFSET N +NODE middle + LABEL Middle (C) + POSITION 330 100 + LABELOFFSET C +NODE bottom + LABEL Bottom (S) + POSITION 550 100 + LABELOFFSET S diff --git a/docs/example/traffic-pulse-2.0.conf b/docs/example/traffic-pulse-2.0.conf new file mode 100644 index 00000000..d4b01467 --- /dev/null +++ b/docs/example/traffic-pulse-2.0.conf @@ -0,0 +1,20 @@ +# Global settings belong before the first NODE or LINK. +WIDTH 660 +HEIGHT 180 +KEYPOS -1 -1 +TIMEPOS -1 -1 +SET traffic_pulse 1 +NODE DEFAULT + LABELFONT 3 +NODE core + LABEL Core + POSITION 60 90 +NODE access + LABEL Access + POSITION 600 90 +LINK uplink + NODES core access + WIDTH 12 + BANDWIDTH 1G + TARGET static:900M:200M + BWLABEL percent diff --git a/docs/images/editor-additional-hover-2.0.png b/docs/images/editor-additional-hover-2.0.png new file mode 100644 index 00000000..ab1670a7 Binary files /dev/null and b/docs/images/editor-additional-hover-2.0.png differ diff --git a/docs/images/editor-advanced-sources-2.0.png b/docs/images/editor-advanced-sources-2.0.png new file mode 100644 index 00000000..8bd51a8f Binary files /dev/null and b/docs/images/editor-advanced-sources-2.0.png differ diff --git a/docs/images/editor-advanced-urls-2.0.png b/docs/images/editor-advanced-urls-2.0.png new file mode 100644 index 00000000..e94919df Binary files /dev/null and b/docs/images/editor-advanced-urls-2.0.png differ diff --git a/docs/images/editor-canvas-2.0.png b/docs/images/editor-canvas-2.0.png new file mode 100644 index 00000000..a7e2620e Binary files /dev/null and b/docs/images/editor-canvas-2.0.png differ diff --git a/docs/images/editor-link-label-positions-2.0.png b/docs/images/editor-link-label-positions-2.0.png new file mode 100644 index 00000000..9a363a51 Binary files /dev/null and b/docs/images/editor-link-label-positions-2.0.png differ diff --git a/docs/images/editor-link-properties-2.0.png b/docs/images/editor-link-properties-2.0.png new file mode 100644 index 00000000..3faece33 Binary files /dev/null and b/docs/images/editor-link-properties-2.0.png differ diff --git a/docs/images/editor-manage-colors-2.0.png b/docs/images/editor-manage-colors-2.0.png new file mode 100644 index 00000000..c36e4046 Binary files /dev/null and b/docs/images/editor-manage-colors-2.0.png differ diff --git a/docs/images/editor-map-properties-2.0.png b/docs/images/editor-map-properties-2.0.png new file mode 100644 index 00000000..c29bedeb Binary files /dev/null and b/docs/images/editor-map-properties-2.0.png differ diff --git a/docs/images/editor-map-style-2.0.png b/docs/images/editor-map-style-2.0.png new file mode 100644 index 00000000..72adfaf5 Binary files /dev/null and b/docs/images/editor-map-style-2.0.png differ diff --git a/docs/images/editor-node-properties-2.0.png b/docs/images/editor-node-properties-2.0.png new file mode 100644 index 00000000..be4c2a57 Binary files /dev/null and b/docs/images/editor-node-properties-2.0.png differ diff --git a/docs/images/editor-note-properties-2.0.png b/docs/images/editor-note-properties-2.0.png new file mode 100644 index 00000000..145cd2a4 Binary files /dev/null and b/docs/images/editor-note-properties-2.0.png differ diff --git a/docs/images/editor-overview-2.0.png b/docs/images/editor-overview-2.0.png new file mode 100644 index 00000000..9e7cb91b Binary files /dev/null and b/docs/images/editor-overview-2.0.png differ diff --git a/docs/images/management-add-control-2.0.png b/docs/images/management-add-control-2.0.png new file mode 100644 index 00000000..6f91101a Binary files /dev/null and b/docs/images/management-add-control-2.0.png differ diff --git a/docs/images/management-create-2.0.png b/docs/images/management-create-2.0.png new file mode 100644 index 00000000..18548ed8 Binary files /dev/null and b/docs/images/management-create-2.0.png differ diff --git a/docs/images/management-overview-2.0.png b/docs/images/management-overview-2.0.png new file mode 100644 index 00000000..f04efc32 Binary files /dev/null and b/docs/images/management-overview-2.0.png differ diff --git a/docs/images/management-register-2.0.png b/docs/images/management-register-2.0.png new file mode 100644 index 00000000..1a60e84e Binary files /dev/null and b/docs/images/management-register-2.0.png differ diff --git a/docs/images/reference-combined-sources-2.0.png b/docs/images/reference-combined-sources-2.0.png new file mode 100644 index 00000000..2a81df97 Binary files /dev/null and b/docs/images/reference-combined-sources-2.0.png differ diff --git a/docs/images/reference-curved-comments-2.0.png b/docs/images/reference-curved-comments-2.0.png new file mode 100644 index 00000000..63d4b879 Binary files /dev/null and b/docs/images/reference-curved-comments-2.0.png differ diff --git a/docs/images/reference-label-positions-2.0.png b/docs/images/reference-label-positions-2.0.png new file mode 100644 index 00000000..a8fe9752 Binary files /dev/null and b/docs/images/reference-label-positions-2.0.png differ diff --git a/docs/images/reference-traffic-pulse-2.0.png b/docs/images/reference-traffic-pulse-2.0.png new file mode 100644 index 00000000..8e272bc2 Binary files /dev/null and b/docs/images/reference-traffic-pulse-2.0.png differ diff --git a/docs/images/reference-traffic-pulse-2.0.svg b/docs/images/reference-traffic-pulse-2.0.svg new file mode 100644 index 00000000..c66ed247 --- /dev/null +++ b/docs/images/reference-traffic-pulse-2.0.svg @@ -0,0 +1,2 @@ + +High-load pulse exampleIllustrated map with 90 percent inbound utilisation and 20 percent outbound. Only the 90 percent arrow pulses. Values are fixed demonstration data. diff --git a/docs/images/viewer-overview-2.0.png b/docs/images/viewer-overview-2.0.png new file mode 100644 index 00000000..591b3cd5 Binary files /dev/null and b/docs/images/viewer-overview-2.0.png differ diff --git a/docs/index.html b/docs/index.html index e78502d3..dc32fa28 100644 --- a/docs/index.html +++ b/docs/index.html @@ -1,102 +1,74 @@ - - - - - PHP Weathermap v0.98a - Start Here - - - - - - - -
- - - -

New - Users should start here.

- -

Documentation Guide

-

New in 0.97b, there is a Security Notes section that you should read.

- -

There are several sections, including - Introduction, - Installation, - The Basics, - FAQ, - Reference, and - Advanced Topics. There are seperate - pages for the - Cacti Plugin, and for the - optional web-based editor. There is also a - reference page for - all the error codes that Weathermap can - produce, with an explanation, and another - reference for the built-in datasource - plugins.

- -

For existing users, there's an overview to the - changes from the previous version, and a - guide to upgrading.

- -

There are also a growing number of articles at - network-weathermap.com - about specific tricks and techniques for making your own maps, including - animation, non-network maps and more!

- -

What I'm trying to say is - RTFM, - but in a more polite way! - :-) I put a fair amount of my own time and effort into writing the - program, and then a whole bunch - more into writing the manual and other documentation - more than a thousand hours by now. I also spend my - spare time supporting Weathermap users [I'm one of the all-time most active users on the Cacti forums], but a lot of questions asked are - answered in the manual, or worse still, in the FAQ section. - Please take a look.

- -

Visual Guides

- -

If you are more visually-minded, like me, then the following might also help:

- -
-
-

- -

- -

Diagram explaining a lot of the basic map - formatting commands. Look in the - Configuration Reference - for more information on the commands mentioned. - -
Larger version | - PDF version

-
- -
-

- -

- -

Sample output from php-weathermap, using data - collected by Cacti and MRTG. - -
Larger version

-

This is from the Example Map section of the manual.

-
-
- -
- -
- + + + + + Network Weathermap 2.0 documentation — Network Weathermap 2.0 + + + + +
+ Network Weathermap 2.0 +

Cacti plugin manual

+
+
+ +
+

Network Weathermap 2.0 documentation

+

Create network maps that show utilisation, device measurements and links to + Cacti graphs. This manual covers the Cacti-maintained 2.0 plugin, its editor and its + configuration format.

+
+
+

Build your first map

+

Start with installation, add two nodes, assign an interface and choose the link + capacity.

Quick start and map basics +
+
+

Edit an existing map

+

Understand interface assignment, extra hover graphs, comments, notes and + Undo/Redo.

Editor guide +
+
+

Customise the appearance

+

Upload icons and backgrounds, position labels, choose colours and work with curved + comments.

Appearance and image libraries +
+
+

Maintain an installation

+

Upgrade safely, set permissions and investigate data or rendering + problems.

Upgrade checklist · Troubleshooting +
+
+

Reference and examples

+

The configuration reference, data-source guide and advanced + topics explain custom map files. The version guide + distinguishes 2.0 features from historical behaviour.

+

The original configuration diagram (PDF) + and sample map remain useful for learning the format. They + are historical examples, not screenshots of the 2.0 editor.

+ +
+
diff --git a/docs/index.php b/docs/index.php index d503d49e..6b9b2e9e 100644 --- a/docs/index.php +++ b/docs/index.php @@ -1,2 +1,4 @@ a { display:block; width:fit-content; max-width:100%; } +.manual-screenshot img { width:auto; max-height:520px; } + +/* Keep complete example lines readable; narrow screens scroll the table. */ +.config-summary { min-width:42rem; } +.config-summary th:first-child,.config-summary td:first-child { width:42%; min-width:19rem; } +.config-summary td:first-child a { overflow-wrap:normal; } +.config-summary code { white-space:nowrap; overflow-wrap:normal; } +@media print { .config-summary { min-width:0; } .config-summary th:first-child,.config-summary td:first-child { min-width:0; } .config-summary code { white-space:normal; } } diff --git a/docs/pages/advanced.html b/docs/pages/advanced.html index 19482273..305b74c1 100644 --- a/docs/pages/advanced.html +++ b/docs/pages/advanced.html @@ -1,454 +1,403 @@ - - - - - - PHP Weathermap v0.98a - Advanced Topics - - - - - - - -
- - - -

Advanced Topics

- -

This page contains information for the more advanced corners of - Weathermap usage. I assume that you are more familiar with the basics of map - design here - there is less explanation of the simple stuff.

- - - -

Special String Processing Tokens

- -

Most places where you can specify a string in Weathermap config files, - you can now include data from within the Weathermap data model. Useful - examples of this would be:

- -
    -
  • You can have the value of a data source printed in the map.
    • - -
  • You can have ICON filenames which change with the value of a - datasource.
    • - -
  • You can make more effective use of the DEFAULTs, by including - parameterised LABELs, ICONs and OVERLIBCAPTIONs.
    • -
- -

Finally, plugins can add internal 'notes' to objects in the map, which - you can then use in the same way as the normal Weathermap data. For example, - you could have a plugin that looks at the load-average on a server, - categorises it as light, medium or heavy and saves that to a note, which can - then be used to select an appropriate icon. -

- -

The format for the tokens is simple:

- -
{node:nodename:variablename} -
- -
{link:linkname:variablename} -
- -
{map:variablename} -
- - Where nodename and linkname are the names of nodes or links defined in the - map. There is a special link/node name, 'this', which always signifies the - node or link that the string belongs to. For example: - -
- 
 
- NODE test 
- LABEL {node:this:name} 
-
-
- - will set the label for the node to be 'test', since that is the node's name. - Using 'this' in the DEFAULT node can save you some typing: - -
- 
 
- NODE DEFAULT 
- LABEL {node:this:name} 
- OVERLIBCAPTION History for {node:this:name} 
-
- NODE test1 
- POSITION 100 100 
-
- NODE test2 
- POSITION 150 100 
-
-
- -

Each node will take it's name as the label, and a useful caption for it's - Overlib pop-up graph. -

- -

For nodes specifically, there is one other special 'nodename' - - 'parent'. If a node is positioned relative to another one, then this - refers to that other node. The idea is to allow a node to be used as an - additional data label for another one.

- -

- Here is the list of valid variablenames and their meaning.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Variable NameMeaning
bandwidth_inThe raw 'bandwidth' figure for the input side of the item. - This isn't always an actual bandwidth figure, especially for - NODEs. For bandwidth, you probably want to use the formatting - modifiers listed below.
bandwidth_outThe raw 'bandwidth' figure for the output side of the item. - As above, but for output.
max_bandwidth_inThe maximum input bandwidth, as defined by MAXVALUE or - BANDWIDTH.
max_bandwidth_outThe maximum output bandwidth, as defined by MAXVALUE or - BANDWIDTH.
inpercentThe percentage usage for the input side of the item, - calculated using the previous two figures.
outpercentThe percentage usage for the output side of the item, - calculated using the previous two figures.
nameThe name of the NODE or LINK.
inscaletagIf the SCALE has - scale tag, - then this is the scale tag for the SCALE line that the inpercent - value matched.
outscaletagIf the SCALE has - scale tag, - then this is the scale tag for the SCALE line that the - outpercent value matched.
inscalecolorThe colour in HTML style ('#rrggbb') for the SCALE line that - the inpercent value matched. Intended for use with NOTES.
outscalecolorThe colour in HTML style ('#rrggbb') for the SCALE line that - the outpercent value matched. Intended for use with NOTES.
- -

In addition to the variables defined by Weathermap itself, there are two - additional sources for variables that greatly extend the usefulness of these - string tokens: You, and Data Source Plugins.

- -

- Firstly, you can define addition variables for any NODE, LINK or for the map - in general, using the SET command. This serves two purposes. One is to allow - you to give parameters to some datasource plugins (like a database password - for some external database), but the other is just so you can use those - values elsewhere in the map. Say you have a data-collection system where - each router has an ID, but the URL is otherwise the same from one NODE to - the next. You can define a new variable with the router ID, and then use a - string token to insert that ID into the INFOURL or TARGET strings. This - makes it easier to edit the configuration, and easier to make global changes - if you move the server than runs the other system, for example. -

- -
- 
 
- NODE router_a 
- LABEL Router A 
- POSITION 100 200 
- SET router_id 33 
- INFOURL http://my.monitoring.system/view.php?id={node:this:router_id} 
- TARGET somemonitoringplugin:{node:this:router_id} 
-
-
- -

Since information from these variables can also appear in the NOTES popup - for a NODE or LINK, then you can also use this as a more structured way to - have that information in your config file, and still presented in the map.

- -

The second additional source is Data Source Plugins. Some plugins may - define additional variables, above and beyond the normal 'in bandwidth' and - 'out bandwidth' that they normally would. For example, the Cacti Host data - source plugin returns a "bandwidth" that is actually a number representing - the state of the device, according to Cacti - - up, down, disabled, recovering. Since you might want to show this as text - somewhere, or use it to change the icon for a device, it - also defines an additional variable called 'state' that contains a - string - 'up','down','recovering', or 'disabled'.

- -

- Here is one more example, showing the use of relative node positions, node - targets and tokens working together:

- -
- 
 
-
- NODE fw_a 
- POSITION 100 100 
- LABEL Firewall A 
- TARGET fw_a_cpu.rrd:cpu:- fw_a_sessions.rrd:-:sess 
-
- NODE fw_a_sessions 
- POSITION fw_a -30 0 
- LABEL {node:fw_a:outvalue} Sessions 
-
-
- -

The first node uses two targets to populate the 'in' and 'out' slots from - different RRD files. It uses the 'in' slot to change it's own color. The - second node is positioned relative to the first, and uses tokens to show the - number of sessions used (the 'out' slot) on the other node as it's label. In - combination with the 'notes' available to plugins, you can display nearly - anything in your weathermap. -

- -

Formatting in Special Tokens

- -

To allow you to control better how the values of special tokens are used, - you can add a final part inside the token that specifies the format.

- -

This borrows the '%' format from the printf() function in C, PHP, perl - and many other languages, but adds a couple of Weathermap-specific extras:

- - - - - - - - - - - - - - - - - - - - - - -
{link:this:bandwidth_in:%d}force to integer
{link:this:bandwidth_in:%04d}force to integer, and pad - to 4 digits with zeroes
{link:this:bandwidth_in:%0.2f}floating-point with 2 - decimal places
{link:this:bandwidth_in:%k}Add a prefix for mega, kilo, - giga, milli etc, and show the rest as a floating-point number - - e.g. 2.3M (Weathermap special)
{link:this:bandwidth_in:%0.2k}as above, but limit the - floating-point part to 2 decimal places (Weathermap special)
{link:this:bandwidth_in:%t}Format a duration in seconds in human-readable form (Weathermap special)
{link:this:bandwidth_in:%T}Format a duration in hundredths-of-seconds (aka SNMP TimeTicks) in human-readable form (Weathermap special)
{link:this:bandwidth_in:%2T} {link:this:bandwidth_in:%2t}Format a duration in human-readable form show only the 2 most significant parts. e.g. 1y34d13m3s becomes 1y34d (Weathermap special)
- -

SETting Hint Variables to tweak maps

- -

- In addition to any variables that you define using SET, and the ones that - Weathermap uses internally (like those listed above), there is a - third place that SET is used - - to make small adjustments to the way a map is calculated.

- -

Whenever there is a request for a 'tweak' - - a setting that doesn't really deserve creating yet another map config - keyword - - then that tweak is done by having a special SET variable to control it.

- -

These are documented in the relevant config keyword section in the - Config Reference, - but here's an example:

- -

When you are using KEYPOS and KEYSTYLE to draw the legend/key for a - particular SCALE, you can choose to hide the percentage signs, by using

- -
- 
SET key_hidepercent_DEFAULT 1
-
- - (for the DEFAULT scale in this example), in the top section of the map - config file. - -

Another example of these 'hidden' tweaks is used in the - RRDtool datasource plugin to select what - data is extracted.

- -

Writing Plugins

- -

Version 0.9 of Weathermap introduces a plugin system for extending it's - capabilities. This makes it possible for third parties to add new possible - data sources and other functions to Weathermap without needing to alter the - main code of the program.

- -

Currently, there are two basic types of plugin - - datasources and pre/post-processing. Datasource plugins allow you to add - new TARGET data sources. Pre-processing plugins are called once per map, - before datasources are read, but after the map configuration is loaded. - Post-processing plugins are called once per map, after all the data sources - have been read. The processing plugins are intended to allow you to add - additional information into the Map Notes data structure so that it can be - accessed by the - special string tokens in NODE labels, for - example.

- -

Datasource Plugins

- -

- Datasource plugins are the main plugin type in Weathermap. They allow the - user to pull in data from almost any source, and incorporate it into the - final Weathermap image. The best way to get started with writing a new DS - plugin is probably to take an existing one apart.

- -

- Each plugin is defined as a PHP class in the lib/datasources directory. The - filename of the plugin must match the classname used inside the file. It's - important to know that Weathermap doesn't instantiate the class - - all the methods are just static methods in a convenient container.

- -

Each plugin has three methods: Init, Recognise and ReadData.

- -

At startup, Weathermap calls the Init method of each plugin to see if it - can run at all. The Init method should check for the availability of - appropriate config, or PHP functions or files. It should then return TRUE or - FALSE, to indicate if it can run or not. For example, the SNMP DS plugin - returns FALSE if it can't find the snmp_get PHP function, which is normally - due to the SNMP module not being configured with PHP. -

- -

For each map, after the configuration file has been read, the ReadData - function inside Weathermap process TARGET lines to get data, before starting - to draw the map. To do this, it loops though all the objects in the map, - taking each TARGET of each object in turn (objects can have multiple - aggregated targets), and for each of the TARGETs, it calls all of the DS - plugins' Recognise method. The Recognise method should return TRUE or FALSE, - depending on if it thinks that the supplied TARGET string is intended for - it. This is normally decided by using preg_match to match a regular - expression. It - should not try and read any data source, or database, or file to - validate the actual TARGET. It should - only decide if the TARGET is the right 'shape' or not.

- -

Recognise is called even for plugins that have previously returned FALSE - for Init. This is so that Weathermap can tell the user that their TARGET - would have worked, if only the plugin was working OK, rather than - mysteriously ignoring them.

- -

Finally, once it has established which of the plugins should deal with - the TARGET string, it calls the ReadData method of that plugin, which should - return a list() of three items - input value, output value and valid_time.

- -

The valid_time is a Unix time_t (as returned by time()), to indicate when - the data was measured. This is mainly intended for things like RRDs where - there may be a delay between the RRD being written and us reading the value, - or for cached results. The input and output values are numeric, and are used - as part of the final bandwidth values for the map object. If there is no - valid result (e.g. the device id passed in the TARGET string doesn't exist) - then the plugin should return -1,-1 for those two values.

- -

The ReadData function can also set addtional variables for the map - object, which can then be used in strings in the map config file. It can do - this by calling the $map->add_note() function.

- -

It can also - receive addtional parameters that the user has defined with SET - commands in the map config file. This is mainly intended for things like - hostnames for the remote system that data is being read from, so that they - don't have to be hardcoded, or appear in every TARGET string.

- -

Pre- & Post-Processing Plugins

- -

Post-processing plugins can be used to calculate additional global - statistics for a map, which can then be used in elements on the map. For - example, you could calculate an average latency across all links in the - network, or a total network uptime based on the uptimes of all nodes. - Currently, there aren't any of these plugins, but the hooks are available.

-
- - - + + + + + + Advanced configuration and extensions — Network Weathermap 2.0 + + + + +
+ Network Weathermap 2.0 +

Cacti plugin manual

+
+
+ +
+

Advanced configuration and extensions

+ +

On this page

+

These examples assume you can already create a map and edit its configuration. Start with the map basics if the format is unfamiliar.

+ +

Special String Processing Tokens

+

Most places where you can specify a string in Weathermap config files, you can now include + data from within the Weathermap data model. Useful examples of this would be:

+
    +
  • You can have the value of a data source printed in the map.
    • +
  • You can have ICON filenames which change + with the value of a datasource. +
    • +
  • You can make more effective use of the DEFAULTs, by including parameterised LABELs, ICONs and OVERLIBCAPTIONs. +
    • +
+

Finally, plugins can add internal 'notes' to objects in the map, which you can then use in + the same way as the normal Weathermap data. For example, you could have a plugin that looks + at the load-average on a server, categorises it as light, medium or heavy and saves that to a + note, which can then be used to select an appropriate icon.

+

The format for the tokens is simple:

+
+ {node:nodename:variablename} +
+
+ {link:linkname:variablename} +
+
+ {map:variablename} +
Where nodename and linkname are the names of nodes or links defined in the map. There + is a special link/node name, 'this', which always signifies the node or link that the string + belongs to. For example: +
+ 
+ NODE test
+ LABEL {node:this:name}
+
+
will set the label for the node to be 'test', since that is the node's name. Using + 'this' in the DEFAULT node can save you some typing: +
+ 
+ NODE DEFAULT
+ LABEL {node:this:name}
+ OVERLIBCAPTION History for {node:this:name}
+
+ NODE test1
+ POSITION 100 100
+
+ NODE test2
+ POSITION 150 100
+
+
+

Each node will take its name as the label, and a useful caption for it's Overlib pop-up + graph.

+

For nodes specifically, there is one other special 'nodename' - 'parent'. If a node is + positioned relative to another one, then this refers to that other node. The idea is to allow + a node to be used as an additional data label for another one.

+

Here is the list of valid variablenames and their meaning.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Variable NameMeaning
bandwidth_in + The raw 'bandwidth' figure for the input side of the item. This isn't always an + actual bandwidth figure, especially for NODEs. For bandwidth, you probably want to use + the formatting modifiers listed below. +
bandwidth_outThe raw 'bandwidth' figure for the output side of the item. As above, but for + output.
max_bandwidth_in + The maximum input bandwidth, as defined by MAXVALUE or BANDWIDTH. +
max_bandwidth_out + The maximum output bandwidth, as defined by MAXVALUE or BANDWIDTH. +
inpercentThe percentage usage for the input side of the item, calculated using the previous + two figures.
outpercentThe percentage usage for the output side of the item, calculated using the previous + two figures.
name + The name of the NODE or LINK. +
inscaletag + If the SCALE has scale tag, then this is the scale tag for + the SCALE line that the inpercent + value matched. +
outscaletag + If the SCALE has scale tag, then this is the scale tag for + the SCALE line that the outpercent + value matched. +
inscalecolor + The colour in HTML style ('#rrggbb') for the SCALE line that the inpercent value matched. + Intended for use with NOTES. +
outscalecolor + The colour in HTML style ('#rrggbb') for the SCALE line that the outpercent value + matched. Intended for use with NOTES. +
+

In addition to the variables defined by Weathermap itself, there are two additional + sources for variables that greatly extend the usefulness of these string tokens: You, and + Data Source Plugins.

+

Firstly, you can define addition variables for any NODE, LINK or for the map in general, using the SET command. This serves two purposes. One is to allow + you to give parameters to some datasource plugins (like a database password for some external + database), but the other is just so you can use those values elsewhere in the map. Say you + have a data-collection system where each router has an ID, but the URL is otherwise the same + from one NODE to the next. You can define a new + variable with the router ID, and then use a string token to insert that ID into the INFOURL or TARGET strings. This makes it easier to edit the + configuration, and easier to make global changes if you move the server than runs the other + system, for example.

+
+ 
+ NODE router_a
+ LABEL Router A
+ POSITION 100 200
+ SET router_id 33
+ INFOURL http://my.monitoring.system/view.php?id={node:this:router_id}
+ TARGET somemonitoringplugin:{node:this:router_id}
+
+
+

Since information from these variables can also appear in the NOTES popup for a NODE or LINK, then you can also use this as a more structured + way to have that information in your config file, and still presented in the map.

+

The second additional source is Data Source Plugins. Some plugins may define additional + variables, above and beyond the normal 'in bandwidth' and 'out bandwidth' that they normally + would. For example, the Cacti Host data source plugin returns a "bandwidth" that is actually + a number representing the state of the device, according to Cacti - up, down, disabled, + recovering. Since you might want to show this as text somewhere, or use it to change the icon + for a device, it also defines an additional variable called 'state' that contains a + string - 'up','down','recovering', or 'disabled'.

+

Here is one more example, showing the use of relative node positions, node targets and + tokens working together:

+
+ 
+
+ NODE fw_a
+ POSITION 100 100
+ LABEL Firewall A
+ TARGET fw_a_cpu.rrd:cpu:- fw_a_sessions.rrd:-:sess
+
+ NODE fw_a_sessions
+ POSITION fw_a -30 0
+ LABEL {node:fw_a:bandwidth_out} Sessions
+
+
+

The first node uses two targets to populate the 'in' and 'out' slots from different RRD + files. It uses the 'in' slot to change its own colour. The second node is positioned relative + to the first, and uses tokens to show the number of sessions used (the 'out' slot) on the + other node as it's label. In combination with the 'notes' available to plugins, you can + display nearly anything in your weathermap.

+

Formatting in Special Tokens

+

To allow you to control better how the values of special tokens are used, you can add a + final part inside the token that specifies the format.

+

This borrows the '%' format from the printf() function in C, PHP, perl and many other + languages, but adds a couple of Weathermap-specific extras:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
{link:this:bandwidth_in:%d}force to integer
{link:this:bandwidth_in:%04d}force to integer, and pad to 4 digits with zeroes
{link:this:bandwidth_in:%0.2f}floating-point with 2 decimal places
{link:this:bandwidth_in:%k}Add a prefix for mega, kilo, giga, milli etc, and show the rest as a floating-point + number - e.g. 2.3M (Weathermap special)
{link:this:bandwidth_in:%0.2k}as above, but limit the floating-point part to 2 decimal places (Weathermap + special)
{link:this:bandwidth_in:%t}Format a duration in seconds in human-readable form (Weathermap special)
{link:this:bandwidth_in:%T}Format a duration in hundredths-of-seconds (aka SNMP TimeTicks) in human-readable + form (Weathermap special)
{link:this:bandwidth_in:%2T} {link:this:bandwidth_in:%2t}Format a duration in human-readable form show only the 2 most significant parts. e.g. + 1y34d13m3s becomes 1y34d (Weathermap special)
+

SETting Hint Variables to + tweak maps

+

In addition to any variables that you define using SET, and the ones that Weathermap uses internally + (like those listed above), there is a third place that SET is used - to make small adjustments to the way a + map is calculated.

+

Whenever there is a request for a 'tweak' - a setting that doesn't really deserve creating + yet another map config keyword - then that tweak is done by having a special SET variable to control it.

+

These are documented in the relevant config keyword section in the Config Reference, but here's an example:

+

When you are using KEYPOS and KEYSTYLE to draw the legend/key for a particular + SCALE, you can choose to hide the percentage + signs, by using

+
+ 
SET key_hidepercent_DEFAULT 1
+
(for the DEFAULT scale in this example), in the top section of the map config file. +

Another example of these 'hidden' tweaks is used in the RRDtool + datasource plugin to select what data is extracted.

+

Writing Plugins

+

Version 0.9 of Weathermap introduces a plugin system for extending its capabilities. This + makes it possible for third parties to add new possible data sources and other functions to + Weathermap without needing to alter the main code of the program.

+

Currently, there are two basic types of plugin - datasources and pre/post-processing. + Datasource plugins allow you to add new TARGET data sources. Pre-processing plugins are + called once per map, before datasources are read, but after the map configuration is loaded. + Post-processing plugins are called once per map, after all the data sources have been read. + The processing plugins are intended to allow you to add additional information into the Map + Notes data structure so that it can be accessed by the special string + tokens in NODE labels, for example.

+

Datasource Plugins

+

Datasource plugins are the main plugin type in Weathermap. They allow the user to pull in + data from almost any source, and incorporate it into the final Weathermap image. The best way + to get started with writing a new DS plugin is probably to take an existing one apart.

+

Each plugin is defined as a PHP class in the lib/datasources directory. The filename of + the plugin must match the classname used inside the file. Weathermap instantiates data-source + classes extending WeatherMapDataSource. Implement instance methods matching the bundled base + class and existing sources.

+

The main methods are Init, Recognise and ReadData. Register is an optional hook for + batching or initialising per-target state; match its signature to WeatherMapDataSource in + lib/WeatherMap.class.php.

+

At startup, Weathermap calls the Init method of each plugin to see if it can run at all. + The Init method should check for the availability of appropriate config, or PHP functions or + files. It should then return TRUE or FALSE, to indicate if it can run or not. For example, + the SNMP DS plugin returns FALSE if it can't find the snmp_get PHP function, which is + normally due to the SNMP module not being configured with PHP.

+

For each map, after the configuration file has been read, the ReadData function inside + Weathermap process TARGET lines to get data, + before starting to draw the map. To do this, it loops though all the objects in the map, + taking each TARGET of each object in turn + (objects can have multiple aggregated targets), and for each of the TARGETs, it calls all of the DS plugins' Recognise + method. The Recognise method should return TRUE or FALSE, depending on if it thinks that the + supplied TARGET string is intended for it. + This is normally decided by using preg_match to match a regular expression. It should + not try and read any data source, or database, or file to validate the actual TARGET. It should only decide if the + TARGET is the right 'shape' or not.

+

Recognise is called even for plugins that have previously returned FALSE for Init. This is + so that Weathermap can tell the user that their TARGET would have worked, if only the plugin + was working OK, rather than mysteriously ignoring them.

+

Finally, once it has established which of the plugins should deal with the TARGET string, it calls the ReadData method of that + plugin, which should return a list() of three items - input value, output value and + valid_time.

+

The valid_time is a Unix time_t (as returned by time()), to indicate when the data was + measured. This is mainly intended for things like RRDs where there may be a delay between the + RRD being written and us reading the value, or for cached results. The input and output + values are numeric, and are used as part of the final bandwidth values for the map object. If + there is no valid result (e.g. the device id passed in the TARGET string doesn't exist) then the plugin should + return -1,-1 for those two values.

+

The ReadData function can also set addtional variables for the map object, which can then + be used in strings in the map config file. It can do this by calling the $map->add_note() + function.

+

It can also receive addtional parameters that the user has defined with SET commands in the map config file. This is mainly + intended for things like hostnames for the remote system that data is being read from, so + that they don't have to be hardcoded, or appear in every TARGET string.

+

Pre- & Post-Processing Plugins

+

Post-processing plugins can be used to calculate additional global statistics for a map, + which can then be used in elements on the map. For example, you could calculate an average + latency across all links in the network, or a total network uptime based on the uptimes of + all nodes. Currently, there aren't any of these plugins, but the hooks are available.

+ +
+
+ + diff --git a/docs/pages/appearance.html b/docs/pages/appearance.html new file mode 100644 index 00000000..f0a8f941 --- /dev/null +++ b/docs/pages/appearance.html @@ -0,0 +1,212 @@ + + + + + + Appearance and image libraries — Network Weathermap 2.0 + + + + +
+ Network Weathermap 2.0 +

Cacti plugin manual

+
+
+ +
+

Appearance and image libraries

+

Appearance settings belong to the current map unless described as a shared + library or Cacti-wide preference. Changing one map's colours does not recolour every map. + Select a screenshot to open it at full size.

+
+

Map Properties and backgrounds

+

Set the title, canvas width/height and background in Map Properties. A new blank map + starts at 1400 × 750 pixels; change these dimensions to suit your layout. Node positions, + notes and via points use coordinates within this canvas.

+

Map Properties also holds the default IN/OUT link bandwidth for this map. New + links inherit that capacity. Default link width is in Map Style. The initial capacity is 1000M in both directions; 1G means + the same thing with the default KILO 1000.

+

Check existing links after changing the default capacity. The current + editor replaces both directions on a link when either direction matches its previous map + default. For example, changing 1000M/1000M defaults to 2000M/2000M can also change a + 1000M/200M link to 2000M/2000M. Record asymmetric capacities first, then reopen those links + and restore the intended values after saving the defaults.

+
+ + + + + + + + + + + + + + + + + + + + + +
Background sizingEffect
Use image sizeUses the background image dimensions, retaining legacy image-sized map + behaviour.
Fit to mapScales the image proportionally to fit inside the configured canvas. Unused + space keeps the map background colour.
Stretch to mapFills the configured canvas in both directions; can distort the image.
+
+

Upload a background through Manage Images, then select it in Map Properties to apply it + to the map. Review object placement after changing canvas size or background mode.

+
+
+ Map Properties with background and canvas controls and Default Link Capacity +
Map Properties keeps capacity separate from appearance. Default link width, comment style and traffic-label positions are in Map Style.
+
+
+

Map Style, fonts and comments

+

Link Appearance Defaults includes link width, Comment Style and Traffic Label Positions. + Edge places comments beside the link; Centre places them over the arrow. Traffic label + positions move the IN/OUT utilisation boxes along the route: 0% is the first node and + 100% is the second. These positions are separate from comment positions.

+

To change one link, open Link Properties. Comment Style is beside the comment controls; + Traffic Label Positions is under Advanced settings. Choose Use map default to restore + inheritance. Links using a named configuration template inherit that template's settings.

+

Map Style controls the current map's defaults for nodes, links, labels and legends. Link + Appearance Defaults includes Follow link curve, enabled by default. This affects + comment text, not the numeric traffic labels. It requires a TrueType font; choose a bundled + font and size in Map Style. Very tight bends, unsafe geometry or text that will not fit use + straight text. Turning the option off deliberately uses straight comments.

+

Via Style still determines the link route. A curved route without a bend near the + comment may produce almost straight text. Shorten long comments, move their percentage + position or adjust the via points if a fallback is unsuitable. Fonts must be readable by + both editor and poller accounts; bundled fonts avoid machine-specific paths.

+

Defaults affect objects inheriting those values. Explicit per-object overrides and + included templates may retain their own settings. Do not assume changing a default forcibly + overwrites every custom object.

+
+
+ Map Style showing Link Appearance Defaults, default width, traffic-label positions and comment style +
Map-wide link appearance defaults. Traffic labels start at IN 75% and OUT 25%; individual links can override these positions and the comment style.
+
+
+

Manage Colors and high-load pulsing

+

Manage Colors edits the map background, link outline, link-comment colours and traffic + scales, with presets and custom ranges. It applies to this map. An included shared scale + may be locked in the form; edit its source configuration deliberately if you want to affect + every map that includes it.

+

To change the traffic colours, open Manage Colors and choose a + Colour preset under Traffic Load Colours. For example, Green / Amber / Red + gives a familiar progression as utilisation rises. Review the preview, then Save. The + preset replaces the DEFAULT traffic scale for this map; other named scales are kept.

+

For your own ranges, open Advanced settings. Each row has a scale name, From/To limits, + a colour, an optional Gradient End colour and an optional legend label. Traffic scales + normally use percentages. A colour change is a visual cue, not a Cacti threshold alarm. + Check the link capacity so those percentages mean what you expect.

+

Optional high-load pulsing is a viewer effect for each link direction at 80% + utilisation or above. The saved map's values drive it; it does not sample the + network live or change RRD data. Browser reduced-motion settings and background-tab + behaviour can suppress animation. Static image exports do not animate.

+
+
+ + +
+ Manage Colors applies to the current map. Pulsing uses the measured utilisation in each + direction. +
+
+
+

Enable or disable link pulsing

+
    +
  1. Open the map in the editor and choose Manage Colors.
    2. +
  2. Under Link Appearance, set Pulse links at 80%+ and + save.
    3. +
  3. Return to the normal map viewer after the next managed render. The editor canvas is a + design preview; it does not show this animated viewer effect.
    4. +
+

In raw configuration, put the setting in the global section, before the first + NODE or LINK:

+ 
# Enable the high-load viewer effect (the default).
+SET traffic_pulse 1
+

Use SET traffic_pulse 0 to disable it for this map. If a management Map + Setting defines the same hint, that override takes precedence: see settings inheritance.

+

The 80% threshold is evaluated separately for each direction. Colour presets change the + traffic colours; they do not change this threshold. Set BANDWIDTH correctly: 900M on a 1G + direction is 90%, while 900M on a 10G direction is only 9%.

+
+ + +
+ Illustrated viewer effect using fixed example data, the renderer's arrow shapes and the + viewer's glow timing. Only the 90% direction pulses. Reduced-motion preferences show a + steady halo. Runnable example + configuration. +
+
+

A screenshot or exported PNG cannot capture the pulsing motion. No animation usually + means pulsing is disabled, the last rendered utilisation is below 80%, or + reduced-motion/background-tab handling has paused it. Check the viewer's output timestamp + as well as the link capacity.

+
+
+

Upload and manage images

+

Open Manage Images and choose the node icon or + background library. Upload PNG, JPEG or GIF files up to 5 MB and four + million pixels. Server upload limits can be lower. SVG is not accepted by the upload form. + Transparent PNG works well for node icons. Choose a file, then press Upload Node + Icon or Upload Background. Uploads save immediately; there is no + later Save step in this dialog. GIF uploads keep only the first frame.

+

The libraries are stored in images/objects/ and + images/backgrounds/. Uploads receive safe unique filenames and are + decoded/re-encoded before storage. The PHP web account needs write access to the relevant + library. The poller also needs read access. Avoid granting write access to the entire + plugin.

+

Select an uploaded icon in Node Properties, or select a background in Map Properties. + The icon picker is searchable.

+

The manager lists configuration references and prevents deletion of referenced images, + including checked INCLUDE references. Remove assignments and save before deleting an unused + image. A failed reference check blocks deletion; do not bypass it by deleting files + directly. Upload/delete operations affect shared files and are outside map Undo/Redo.

+
+
+

Labels, notes and previews

+

Node display-name positioning places the label above, centred over or below its icon. + Map notes are independent text objects. Gallery thumbnails are generated at higher + resolution than their display size, while cards remain compact. Hover graph sharpening is + separate from map-image rendering and does not require enlarging every Cacti graph + template.

+

See node controls, notes + and hover graphs for their workflows.

+
+ +
+
+ + diff --git a/docs/pages/cacti-plugin.html b/docs/pages/cacti-plugin.html index 04c0d9eb..73c6be24 100644 --- a/docs/pages/cacti-plugin.html +++ b/docs/pages/cacti-plugin.html @@ -1,273 +1,242 @@ - - - - - PHP Weathermap v0.98a - Cacti Plugin - - - - - - - -
- - -

Cacti Plugin

- -

- Since - v0.8 there is support for tighter - Cacti integration, using the Cacti - Plugin Architecture that Jimmy Conner (aka cigamit) has developed for Cacti - 0.8.x.

- -

NOTE: To start using the plugin, you should follow the - installation notes through first.

- -

With that done, you should now have a Weathermap tab showing in your - Cacti web interface, and a Weathermaps entry under Management in the Console - menu. If you already have your map configuration files, you should now copy - those into the 'configs' directory, inside the weathermap directory, so that - the plugin can find them. If you don't, there's a complete example map in - the weathermap/docs/example directory, that you can use to get started. Copy - the example.conf from there into your configs/ directory instead.

- -

- Once - your maps are in the configs directory, choose the 'Weathermaps' link from - the left side menu of the Console page in Cacti. A new screen appears, - showing the configuration files that Weathermap is currently handling. - Choose 'Add' and pick one of your configuration files from the list.

- -

It should appear in the 'Weathermaps' list now, and you can see whether - it will be updated on the next poller run ('active'), and who will be able - to see it.

- -

At this stage, you should probably wait five minutes (a poller cycle), - reload the Weathermap tab, and make sure your map was created. If it doesn't - show up, turn on the regular Cacti DEBUG logging, and wait for the next - poller cycle to finish. You should get some useful error message from - Weathermap in the Cacti logs to help you figure out what went wrong.

- -

Don't forget to turn DEBUG off again, once you are done, as it can - quickly take a lot of disk space!

Most serious errors will also show - up in the log, even with DEBUG turned off.

- -

If your map was created OK, then welcome to Weathermap!

- -

The rest of this page is a reference to all the available options in the - plugin.

- -

Managing Maps - Access Control

- -

Access-control with the - - - Weathermap plugin is in two layers. First, you can control who will see the - Weathermap tab (and the 'Weathermaps' management link) in the usual Cacti - way: in User Management, give your users the 'View Weathermaps' right. - Second, you can control - which weathermaps that they will see, from the Manage Maps page. - Click on the link for your new map in the column marked 'Accessible By', and - you will get a page where you can add and remove users from the list who can - see this particular map. There is one extra user 'Anyone', that matches - any authenticated user. This is to save you adding new users to a - list when you want to have a 'global' map available to all users.

- -

The final feature of the Management page is that you can change the order - in which the maps are shown, by clicking the Sort Order arrows to move them - up or down.

- -

Viewing Maps

- -

- Since - this is what it's really all about - presenting your users with nice maps!

- -

Your users can access the maps that they have been allowed access to (see - above) by clicking on the Weathermap tab. You will need to give them the - right to View Weathermaps in the User Management page first. The user can - choose to cycle between the maps that they can see (if there is more than - one). Also note: if you use OVERLIB popup graphs in your maps, your users - must have access to view those graphs in Cacti, or they will see a broken - image icon instead!

- -

Managing Maps - Display Options

- -

- All - of the Weathermap plugin's settings are in the Misc tab of Cacti's - Settings page (Console..Settings on the left side menu).

- -

Page style gives you two choices of layout - - a big stack of fullsize maps on one page, or a grid of thumbnails, each of - which leads to a full size map view. From either view, you can also choose - the Cycle mode. Cycle mode gives you an automatically refreshing page - cycling through all the maps available to you.

- -

If you only have one map (or a user is only allowed to see one), then the - user will get a full-size map regardless of the setting. Also in the - settings page, you can choose the maximum size of the thumbnails. The Page - style setting takes effect immediately, but the thumbnail size is used next - time the maps are generated by the poller.

- -

The last display-related Weathermap setting in the Settings page is the - Refresh Time for Cycle mode. You can choose how long each map stays - on-screen for. The default is 'Automatic', which takes the 5 minutes that - the data is valid for (a poller cycle), and divides it evenly between the - available maps - - if you had 5 maps, they would each get 1 minute onscreen before the page - reloaded with new updated maps. - This is nothing to do with changing how the Cacti poller works!

- -

Managing Maps - Other Options

- -

Output Format allows you to change the image file format used by - the plugin. Since v0.9, Weathermap can create PNG, GIF and JPEG files, as - long as the GD library on your system was compiled with the correct - libraries. JPEG images can be quite a bit smaller than PNG, without much - degradation in quality. PNG is the default.

- -

Map Rendering Interval is intended for advanced users only. If - you use the - 1-minute polling patch for Cacti, you might not want to have - Weathermap redraw your maps every minute. This option allows you to change - this, so that Weathermap only redraws every n polling cycles.

- -

During that one cycle when it does redraw, your polling cycle will still - be longer than usual, so you can also turn off the poller part of - Weathermap, so that it doesn't redraw at all. This allows you to use the - user-access parts of the plugin, but manage the redrawing of maps yourself. - To redraw all the maps outside of the standard Cacti poller process, there - is a special PHP script - weathermap-cacti-rebuild.php that does the same job as the Cacti - poller. To use this, you need to edit it, and change the path in the top of - the file to point to your Cacti root directory. Then set up a second - /etc/crontab entry, to redraw your Weathermaps without slowing down your - Cacti polling:

- -
- 
-                                */5 * * * *   cactiuser  /usr/bin/php   /your/cacti/path/plugins/weathermap/weathermap-cacti-rebuild.php
-
-
- -

You will need to change the paths to php and cacti, and the user that - cacti runs as. If you use 'crontab -e', instead of editing /etc/crontab - directly, then you should remove the 'cactiuser'. - In normal use, you don't need to add a cron job - - the Cacti poller does this work for you. -

- -

Boost support

-

With TheWitness' Boost plugin installed in Cacti, the rrd files - are no longer updated every poller cycle. This is a problem if you are - using regular rrdtool TARGETs. There is support in the Weathermap plugin - to directly access data from the poller instead of rrd files. You can - find out more in the Targets Reference. -

- -

DSStats support

- -

Another alternative, which requires changing your TARGET lines, is - the DSStats plugin, also by TheWitness. This also collects data - into the Cacti database, and has it's own benefits if you want - to produce periodic summary maps. You can - find out more in the Targets Reference.

- -

Accessing extra Cacti data

-

Both of the above datasource plugins allow you to access some - additional information from the Cacti database about the data being polled (see the Targets Reference for more). -

-

Additionally, there are some other datasource plugins that can - access more information from Cacti: - cactithold works with cigamit's THold plugin, and - cactihost accesses Cacti's host status information. -

- -

Final Notes and Troubleshooting

- -

Weathermap has quite a lot of logging. If you have a - problem, then - check your cacti.log for lines starting WEATHERMAP. Most normal - errors will appear in here with Cacti's logging level set to LOW. If you set - Cacti's logging level to DEBUG, then Weathermap will produce a - lot of log information as it runs. Also see the - FAQ section of this manual, and the - network-weathermap.com - website for more.

- - -

Recalculate Now

- -

On the Weathermap management page, there used to be a 'Recalculate NOW' button. - It worked by running the normal map update process immediately, but did so - as the user that runs the webserver. This causes some permissions problems - that you need to understand in order to use it. People would just click it - and complain it didn't work, or killed their maps. I added a warning explaining - the problem. People still complained. I removed the button.

-

- The code is all there still, so if you really promise not to ask me why your maps - all stopped working after you press the button, you can re-enable it. Simply open - weathermap-cacti-plugin-mgmt.php in and editor and change the line that says - 

-                    $i_understand_file_permissions_and_how_to_fix_them = false;
-
- to - 
-                    $i_understand_file_permissions_and_how_to_fix_them = true;
-
- Now you have the button, the following explains the issues in detail. -

- -

- This will try to recalculate all your maps on demand. This is more - complicated than it sounds, due to file permissions! Normally, the Cacti - poller would create the images and HTML files in the output directory, which - means they are owned by the 'cactiuser', whatever that user is called on - your system. When you click 'Recalculate NOW', the redraw process is run - from within your webserver, and runs as whatever user runs your webserver - (nobody, www, apache...). To allow for both these situations, the output - directory and it's contents must have appropriate permissions to allow both - users to write to the files. The lazy insecure way to do this is just 'chmod - 777 output/*', but that allows - everyone to write to the files! A better way is to create a new - group, make 'cacti' and 'www' members of that group (as well as their other - groups), then 'chgrp -R newgroup output' and 'chmod 770 output/*' so that - they can both write, but nothing else can. - This is why the button is labelled 'experimental'.

- -
- + + + + + Viewing and managing maps — Network Weathermap 2.0 + + + + +
+ Network Weathermap 2.0 +

Cacti plugin manual

+
+
+ +
+

Viewing and managing maps

+

Cacti-wide preferences control the viewer and generation defaults. Map + Properties, Map Style and Manage Colors customise individual maps.

+

The Docs button after Rebuild All on the management + page opens this manual in a new tab, keeping the management page and its filters in place. + Select a screenshot to open it at full size.

+
+ Map management filtered to a generic Example site registration +
A filtered management list with one example map. Its title opens the editor. Enabled controls poller inclusion; Group, Settings and Accessible By describe its organisation and access. Select the row checkbox to use the actions menu. The search filter hides other rows; it does not delete them.
+
+
+

Create and register a map

+

Saving a configuration in configs/ does not add it to the managed map list. + Register it here so the poller can generate it and users can view it. Management also + controls whether a map is enabled, its group, order, settings and access permissions.

+
+ Right end of the green Weather Maps heading with the white plus, expand and collapse controls +
Start here: this is the right end of the green Weather Maps heading. The white + opens the configuration picker. The + beside a file, shown below, performs a different action: registration.
+
+
    +
  1. In Manage Weathermaps, click the + at the far right + of the green Weather Maps heading. This opens the configuration picker; + it does not create or register a map yet.
    2. +
  2. Under Create Options, enter a New Map filename such + as examplesite.conf, including .conf, and an optional + Map Title, such as Example site. The filename identifies the + configuration on disk; the title is the name displayed on the map.
    3. +
  3. Choose Empty File as the Source Map for a blank map, or choose an + existing source to start from a copy. Press Create.
    4. +
  4. Find the new file in the configuration list below Create Options. If necessary, + search for its filename. Click the + beside that row to register it. + Creating the file and registering the map are separate steps.
    5. +
  5. Back on the management page, review the map's enabled status, group and permissions. + Click its title to open the editor. Add nodes and links, then use + Return to Manage when finished. An enabled, registered map is included + in normal poller runs; the file alone is not. The map title can be changed later in + Map Properties.
    6. +
+
+ Create Options with examplesite.conf, Example site, Empty File and the Create button +
Create the configuration: enter examplesite.conf, give it a map title and choose Empty File for a blank map. Source Map can also copy an existing map configuration; review any copied settings before using it.
+
+
+ Configuration list row for Example site and examplesite.conf, with a green plus, preview and delete controls +
Register the file: click the green + at the left of the examplesite.conf row. The binoculars show the configuration text; the red minus deletes an unused configuration file. After registration, click the map title on the management page to edit it.
+
+

Remove an unused configuration

+

To remove an unused file, find it in the same configuration list and choose its delete + action, labelled Delete configuration file with the filename. Check the + name in the confirmation before continuing. Registered files have no unused-file delete + action; removing a registration does not itself erase the configuration.

+

Back up before deleting: editor Undo does not restore deleted configuration files. Avoid + removing files directly while they still have active registrations.

+
+
+

Duplicate a map

+
    +
  1. In Manage Weathermaps, select the map checkbox and choose Duplicate + from the actions menu.
    2. +
  2. Review the confirmation and the new title/filename formats. + <map_title> and <map_config> stand for the existing + title and configuration name.
    3. +
  3. Continue, then review the new map before editing it. Duplication copies the + configuration and registers the copy, retaining the source map's group, access grants, + per-map settings and schedule. Generated output and warning/runtime counters start + fresh.
    4. +
+

A duplicate therefore inherits who can view the original. Review its permissions if the + copy is intended for a different audience. Creating a configuration from an existing file + in the editor is a separate workflow: register it with management before expecting normal + poller generation and viewer access.

+
+
+

Organise map groups

+

Use the group administration page to add or rename groups and adjust their order. On the + map list, use the map's group control to move it into another group. Map groups organise + the viewer and can supply shared map settings; they are different from Cacti user groups + used for access control.

+

Deleting a map group moves its maps into another existing group; it does not delete + those maps. The final remaining group cannot be deleted. Review inherited settings after + moving a map because its group overrides may change.

+
+
+

Users, groups and graph permissions

+

Cacti view/manage realms determine whether users can view Weathermap or administer it. + Map-level user/group permissions determine which maps are accessible. An + authenticated-user/Anyone grant is broad; use it deliberately. A map linking a graph does + not grant permission to that graph. Missing preview images can therefore be an access + problem even when the map is visible.

+

To grant or remove map access, open the map's Permissions page. Filter by users or Cacti + user groups. The Has Permissions filter shows existing grants when + checked; clear it to find entries without a grant. Select the relevant rows, choose Add or + Remove, and apply the action. Verify the result with an account intended to view the map. A + map-group name alone does not grant access.

+

The viewer offers authorised management shortcuts and a Docs link. Documentation is + static help and is not an editor-access grant.

+
+
+

Viewing and cycling

+

Choose a map or group, use the thumbnail overview or full-image layout, and open + individual maps for details. Responsive preview cards display generated thumbnails; + changing their maximum generated resolution takes effect after rendering. If only one map + is available, a full map can be shown directly.

+
+ Weathermap viewer showing Example site, map selector, management shortcuts, Docs and a generic three-node network +
The normal map viewer, using fixed demonstration readings. The selector changes maps; the green heading provides management shortcuts for authorised users and Docs at the far right. Arrow colours and numeric labels show utilisation; Uplink and Server connection are descriptive comments. This example uses static readings and has no live graph assignments.
+
+

Cycle mode rotates permitted maps. Its controls include previous/next, pause/resume and + fullscreen/exit. The countdown reflects viewer cycling, not remaining device-poll time. + Browser fullscreen and the viewer's fullscreen layout are related UI states, not + configuration changes.

+

Hover on links to see previews, then move into the popup to click a graph. Each + recognised Cacti preview opens its own full graph; clicking the map link still follows its + configured click destination.

+

With a keyboard, Tab to a map hotspot and press Arrow Down to move into its preview. Tab + between the available graph links. Escape from inside the popup closes it and returns focus + to the map hotspot.

+
+
+

Cacti settings: Weathermap

+

Global Cacti preferences below control the viewer and rendering service. The management + page also offers Global, Group and per-map Map Settings: these are named + hint variables corresponding to SET entries.

+

For the same hint name, precedence is per-map management setting → group setting + → global management setting → configuration-file SET. For example, a per-map + traffic_pulse override wins over its group's value. Removing an override lets + the next level apply. This is separate from normal configuration directives such as + BANDWIDTH and from Map Properties or Map Style in the editor. When a file's SET value + appears ineffective, check management overrides first.

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
SettingPurpose
Info URL StyleClick-through style when assigning graphs: Time Graph View (the current + default) or Standard Graph View. Existing custom click URLs are not changed by + selecting a different global default.
Page style / Show All Tab / Show Map SelectorViewer layout, group navigation and individual map selection.
Thumbnail Maximum SizeBounds generated thumbnails; takes effect on the next render.
Hover Graph Default Width/Height and StyleDimensions and legend style for assigned hover previews. Existing custom URLs + may retain their own parameters.
Refresh TimeCycle-view timing. Automatic fits the available maps into five minutes; it does + not change Cacti polling.
Output FormatPNG, JPEG or GIF, subject to GD support. PNG preserves crisp labels and + transparency.
Map Rendering IntervalEvery poller cycle, selected intervals or manual updates. Changing this affects + freshness.
Map Processing TimeoutTime allowance for periodic generation.
Debug Mode / Quiet LoggingGeneration diagnostics and routine log verbosity.
Show Weathermap Help LinksOptional footer help links. The map-heading Docs shortcut is directly + available.
+
+
+
+

Rendering, Boost and manual updates

+

Normally the Cacti poller generates active maps; no extra cron job is needed. The + editor's design preview and poller output are separate. With Boost or delayed RRD writes, + Weathermap can use its poller-output support; see data sources. Do not change global Cacti graph templates + merely to sharpen Weathermap previews.

+

Administrators using manual rendering can run the bundled rebuild entry point from the + plugin directory, under the usual poller account:

+ 
cd /path/to/cacti/plugins/weathermap
+php weathermap-cacti-rebuild.php
+

Use actual paths and the same PHP/environment as Cacti. It loads Cacti via the relative + installation path; do not edit a hard-coded Cacti root into the script. Avoid overlapping + schedules. Check output ownership if web and poller operations use different accounts.

+
+ +
+
diff --git a/docs/pages/changes.html b/docs/pages/changes.html index e65e9b9a..9b0d1c2b 100644 --- a/docs/pages/changes.html +++ b/docs/pages/changes.html @@ -1,1272 +1,963 @@ - - - - - - PHP Weathermap v0.98a - Changes for this version - - - - - - - -
- - - -

Changes For This Version (0.97c to 0.98)

- -

This is a roll-up of all the small bugfixes for the last couple of years, especially those that stop Weathermap - working with newer MySQL or PHP versions. There is a more substantial 1.0 release in the works, but I will - backport - any simple improvements or fixes to 0.98(abcd) releases. There are also small usability changes aimed at - reducing - repeat "error reports" in the forums.

- -

Another part of this change is that the Weathermap code is now hosted on github. There is - also an issue tracker. There - are two branches of code there, one (0.97-maintenance) is for - this 0.98 series of smaller changes, and the other (master) branch - is for the ongoing rewrite work. For now, if you want to track useful work, that will be on the 0.97-maintenance - branch.

- -

IMPORTANT NOTE - you may need to reset permissions on your users after upgrading, as I've - finally switched to the "new-style" plugin API that's been around for 5+ years. This handles - permissions differently, unfortunately. The new permissions have been in a few releases of Weathermap already - so you should check if this affects you after installation.

- -

Fixes

-
    -
  • MySQL error in table-creation. MySQL 5.6 is fussier. -
  • Editor 'delete link' broken -
  • KILO was ignored when processing %k in special tokens -
  • Various fixes for PHP deprecated or strict-mode warnings -
  • Line-ending trimming in 'external script' data source -
  • rounding error 'kinks' in angled VIA links -
  • Config file path validation issue in editor (CVE-2013-3739) -
  • Cloning a templated node in editor retains the template in the clone -
  • cacti_use_ifspeed incorrect when interfaces > 20M and ifhighspeed available -
  • More PHP 5.3/5.4/strict related errors (split -> explode) -

Changes

-
    -
  • Finally switch to "new-style" plugin API. -
  • Editor data picker improved sort (thanks shd) -
  • (Cacti plugin only) images are written to a temporary file first, to avoid displaying half-written images -
  • Editor no longer uses editor-config.php -

New Features

-
    -
  • Weathermap will use anti-aliasing if your GD supports it (php-bundled GD doesn't) (thanks shd) -
  • Special token formatting can handle timeticks and time_t formatting (%T and %t respectively) -
  • new DATAOUTPUTFILE allows collected data to be written to a file for later use (automatically enabled in - Cacti) -
  • new wmdata: datasource plugin can read data from files produced by DATAOUTPUTFILE -
  • IMAGEOUTPUTFILE and HTMLOUTPUTFILE are honoured in Cacti poller as a location for a second copy of those - files. -
  • Editor 'tidy link' function replaces Vert & Horiz, and does much nicer job -
  • 'retidy' option in editor to recalculate all links previously positioned with 'tidy'. -
  • KEYBGCOLOR and KEYOUTLINECOLOR both accept 'none' -
  • command-line weathermap has new --no-warn option to disable warnings -
  • AICONFILLCOLOR accepts 'none' for drawing giant transparent shapes. -
  • Extra warning for Boost users about poller_output -
  • if there are actually 0 maps in the database, the 'Weathermaps' tab gives some basic instructions. -
  • Cacti data picker in editor tracks most recently used hosts (thanks Zdolny) -
  • New permission in Cacti: edit maps. Maps can be edited by authorized users without needing to enable the - editor in the source code. - -
- -

Changes For This Version (0.97b to 0.97c)

- -

0.97c had no additional changes - it's just 0.97b with some silly errors fixed, and all - the CSS files included with the correct paths. There were also reports of problems with the - actual zip file.

- -

Changes For This Version (0.97a to 0.97b)

-

0.97b is a special release starting from 0.97a and backporting all the quick bugfixes from the 0.98 code. - There are larger structural changes in 0.98 and new features, but these bugfixes were useful enough to - warrant a new 0.97 release (especially the mysql schema change). A real 0.98 release will follow in - due course.

-

Also late addition to 0.97b - a couple of security analysts have pointed out flaws in the editor. - First, the ability to remotely create .php files and then cross-site-scripting vulnerabilities. Both - are really facets of the same thing - lack of input validation. 0.97b improves this a great deal.

-

Thanks to Gerry Eisenhaur and Daniel Ricardo dos Santos respectively for their security bug reports.

-

Fixes

-
    -
  • absolute SCALE definitions didn't support K (thanks wwwdrich)
    • -
  • memory leak in poller code. Memory usage is MUCH lower now.
    • -
  • updated mysql schema commands to use modern ENGINE instead of TYPE
    • -
  • static datasource plugin honours KILO
    • -
  • check-gdbug.php shouldn't complain about empty ob_flush buffers anymore
    • -
  • SNMP DS should deal better with non-numeric (and blank) return values
    • -
  • NINK colours were exchanged (thanks Deathwing00!)
    • -
  • WriteConfig (i.e. editor) won't 'lose' absolute keyword from
    • -
  • fixed some function-name clashes with other plugins
    • -
  • PHP 5.3/5.4/strict related errors ("Creating default object from empty value")
    • -
-

Changes

-
    -
  • no longer shows .-prefixed files in map config picker
    • -
  • editor ignores attempts to rename nodes to have space in names
    • -
  • Manual updates for changes in Cacti, and improvements in styling.
    • - -
  • The Cacti UI will warn you about fundamental file permissions problems
    • -
  • Moved all PHP that doesn't need to be web-accessible into lib. See Security - notes. -
    • -
  • Editor won't deal with config files that don't have a .conf extension
    • -
  • General improvements in input validation and output escaping in editor
    • -
  • 'External Script' datasource plugin is disabled by default in new installs (NOT upgrades though!)
    • -
-

New Features

-
    -
  • Caching for cacti data fetched by dsstats and rrdtool/poller_output DS plugins
    • -
- -

Changes For This Version (0.97 to 0.97a)

- -

Lots of bugs appeared the day after 0.97 was released! There are a few - small features added, but mainly this is bugfixes.

- -

Fixes

- -
    -
  • Incorrect action URL in 'map selector' combo box for Cacti users.
    • - -
  • cacti_graph_id set to 0 instead of ID, by rrd/poller_output and - dsstats plugins (thanks sh0x) -
    • - -
  • 'classic' legend drew 'hidden' colour values for things like key - background colour. (thanks jmayniac) -
    • - -
  • PHP 5.3 deprecated code in HTML_Imagemap.class.php
    • - -
  • 'Show Only First' option ignored in Cacti (thanks inko_nick)
    • - -
  • Editor deals with overlapping nodes on different ZORDERS - properly. -
    • - -
  • "property of non-object in editor.php line 466" while editing map - properties (thanks to iNeo) -
    • - -
  • no-data option on command-line didn't work
    • - -
  • Clone Node was broken in 0.97
    • - -
  • Maps with per-user permissions show up multiple times in map - selector -
    • - -
  • Removed incorrect warning about imagefilter and USEICONSCALE.
    • - -
  • string escaping bug with editor and direct config changes (thanks - uhtred) -
    • - -
  • --imageuri was ignored on command-line (thanks Marcus Stögbauer)
    • - -
  • links with targets containing spaces are broken by the editor - (thanks Andreas Braun) -
    • - -
  • deprecated jQuery function call in cacti-pick.php (thanks again - Andreas Braun) -
    • -
- -

Changes

- -
    -
  • Group sorting is a bit more logical and the presentation nicer.
    • - -
  • cacti-integrate.php uses getopt to take more command-line params
    • - -
  • Updated jQuery to latest
    • - -
  • Number formatting will pick 1G over 1000M (and similar) (thanks - cerbum) -
    • - -
  • The editor is disabled by default - - see top of editor.php (and install guide) -
    • -
- -

New Features

- -
    -
  • LINK WIDTH accepts decimals
    • - -
  • cacti-integrate.php can generate DSStats TARGETs too
    • - -
  • Simple VIA editing in editor (thanks to Zdolny)
    • - -
  • SCALE can accept G,M,K,T,m,u,n suffixes (for absolute scales)
    • -
- -

Changes For This Version (0.96a to 0.97)

- -

Fixes

- -
    -
  • RRD Aggregation regexp was failing (thanks to shd)
    • - -
  • Scale numerals honour locale (thanks again, shd)
    • - -
  • THold plugin check failed with Thold 0.4.1 (PA 2.x, actually)
    • - -
  • Uninitialized variable in ReadData when plugin is disabled
    • - -
  • Zero-length link check didn't include offsets (thanks Ryan - Botoluzzi) -
    • - -
  • Cacti-pick should get right rra path for packagers that move the rra - directory (e.g. Ubuntu, Debian *again*) -
    • - -
  • DS plugins that return one value and a null should work properly
    • - -
  • "Strange" characters (e.g. /) in NODE and LINK names broke the - imagemap. -
    • - -
  • Map Style settings in editor were broken after internal defaults - changes -
    • - -
  • Imagemap no longer contains areas with no href defined
    • - -
  • SPLITPOS was ignored with VIASTYLE angled (thanks to uhtred)
    • - -
  • 'AICONOUTLINECOLOR none' is actually valid now (thanks to mgb & - Leathon) -
    • - -
  • readdir() loop never stops, on some systems (thanks to - jerebernard) -
    • - -
  • bad regexp in the MRTG DS plugin (thanks to Matt McMahon)
    • - -
  • 0.96 had a new 'time' DS plugin - now documented!
    • - -
  • NCFPC only complains about missing scale lines on NODEs for the - variable that is in use. -
    • -
- -

New Features

- -
    -
  • USEICONSCALE no longer has special dependencies - - and the colours are nicer too. -
    • - -
  • Option of a dropdown selector to navigate between maps (in full-size - view) -
    • - -
  • Maps can be organised into groups in Cacti plugin. These appear - as tabs in the UI for viewing maps. -
    • - -
  • Extra variables can be defined per-group, so all maps in a group can - have similar settings (e.g. a "24hr average" tab). -
    • - -
  • INCLUDE keyword to include a file of common definitions (based on - work by BorisL) - (NOTE: this can confuse the editor sometimes - - see the manual page for INCLUDE) -
    • - -
  • Warning for maps that contain OVERLIBGRAPH but not 'HTMLSTYLE - overlib' -
    • - -
  • Warning for use of TEMPLATE not as the first line of an object - (overwrites settings otherwise) -
    • - -
  • SCALE will accept values below 0, and also above 100
    • - -
  • USESCALE has two new options: absolute and percent, which allows you - to have a SCALE of absolute values -
    • - -
  • New datasource plugin to support statistics from TheWitness's - DSStats Cacti Plugin. This gets you daily,weekly,monthly and annual - stats with no complicated rrdtool stuff. -
    • - -
  • New converter to take a rrdtool-based map config and make it into a - DSStats-based one -
    • - -
  • static datasource can be used for negative values
    • - -
  • SNMP datasource has configurable timeout and retry values.
    • - -
  • SNMP datasource has option to give up on a failing host
    • - -
  • LABELOFFSET supports percentage compass offsets and radial offsets, - like NODES does. -
    • - -
  • Percentage compass offsets (NODES and LABELOFFSET) support > 100% - offsets -
    • -
- -

Changes For This Version (0.96 to 0.96a)

- -

Just the usual post-release bug reports...

- -

Fixes

- -
    -
  • New z-ordering code did not work correctly on PHP4. This broke (at - least) the editor. (thanks toe_cutter) -
    • - -
  • \n is no longer treated as a newline in TARGETs (thanks - NetAdmin) -
    • - -
  • KILO was broken completely between 0.95b and 0.96 (thanks Jethro - Binks) -
    • - -
  • Link comments in certain positions could cause div-by-zero errors. - (thanks again Jethro) -
    • - -
  • USEICONSCALE didn't colorise (broken between 0.95b and 0.96 again) - (thanks colejv) -
    • - -
  • Managed to make LABELOFFSET case-sensitive.
    • -
- -

Changes For This Version (0.95b to 0.96)

- -

Fixes

- -
    -
  • Cacti poller_output support works more reliably/at all on Windows
    • - -
  • Renaming a node in the editor correctly handles other - relatively-positioned nodes and vias -
    • - -
  • Minor issue with CRLF in map title for Cacti Plugin
    • - -
  • CLI tool set --define options incorrectly.
    • - -
  • Oneway links don't draw the INCOMMENT anymore
    • - -
  • negative TIMEPOS didn't hide the timestamp
    • - -
  • DEFAULT SCALE covers 0-100 properly (Thanks Dan Fusselman)
    • - -
  • Scaled ICON in DEFAULT didn't get overwritten properly in nodes - (Thanks Fabrizio Carusi) -
    • - -
  • No more floating-point imagemap coords (Thanks Trond Aspelund)
    • - -
  • RRDtool regional output (. vs ,) workaround
    • - -
  • Cacti poller_output handles NaN more gracefully now
    • - -
  • SNMP datasource should work with Windows SNMP again
    • - -
  • MRTG datasource tried to stat() URLs
    • - -
  • Error reporting for CLI --define was bad. --help text was out of - date. -
    • - -
  • Editor will honour LABEL from NODE DEFAULT, if it is set.
    • -
- -

Changes

- -
    -
  • Cacti plugin uses "processed" map title now (allows {} tokens in the - title) -
    • - -
  • A NODE with no POSITION is not drawn, instead of drawn at 0,0. - Useful for templates. -
    • - -
  • A LINK with no NODES is no longer an error. Also for templates.
    • - -
  • The link_bulge secret mode bulges each side of a link independently - now -
    • - -
  • whitespace is stripped from the beginning and end of each line - before parsing -
    • -
- -

New Features

- -
    -
  • TEMPLATE allows a node or link to copy it's settings from another, - instead of from DEFAULT. -
    • - -
  • RRD datasource can take SET rrd_default_path to make configs a - little easier to read. -
    • - -
  • RRD datasource can take SET rrd_default_in_ds and rrd_default_out_ds - for non-Cacti users. -
    • - -
  • RRD datasource can get Cacti query information (in poller_output - mode ONLY) - like ifAlias, ifSpeed etc -
    • - -
  • RRD datasource can take the ifSpeed/ifHighSpeed from the above, and - use it in the map. -
    • - -
  • RRD datasource fills in Cacti cacti_path_rra and cacti_url with - Cacti base path and URL -
    • - -
  • RRD datasource can take global SET rrd_options to add extra options - to rrdtool command lines -
    • - -
  • SNMP datasource also stores the raw data from the SNMP agent in - snmp_raw_in/snmp_raw_out -
    • - -
  • SNMP datasource allows '-' as an OID, similar to '-' targets in - RRDs. -
    • - -
  • Control the drawing order with ZORDER.
    • - -
  • New artificial icons: nink, inpie and outpie. See ICON in manual.
    • - -
  • Warning for probably-incorrect BWLABELPOS where in<out
    • - -
  • New global SET variables to disable some common warnings you may not - care about :-) -
    • - -
  • Cacti management screen shows number of warnings for each map last - time it ran -
    • - -
  • Cacti management screen also has a link to the log entries for the - map in question -
    • - -
  • The TARGET aggregation thing can also take scale factors now: - -5.5*myrrdfile.rrd -
    • - -
  • Cacti plugin caches thumbnail sizes, improving thumbnail view - rendering -
    • - -
  • Cacti plugin allows adding the same map twice (more useful than it - sounds) -
    • - -
  • Cacti plugin allows setting of map-global variables in the - management UI -
    • - -
  • Cacti plugin allows settings of global map-global (across all maps) - variables too -
    • - -
  • Cacti plugin adds links in 'user' pages to management screen (if you - are an admin) -
    • - -
  • HTMLSTYLESHEET keyword allows you to specify a URL for a CSS - stylesheet (CLI tool only) -
    • - -
  • A few extra CSS id and class attributes, to make styling the page - easier. -
    • - -
  • New token: in/outscalecolor contains HTML colour code of node/link - colours for use in NOTES -
    • - -
  • New NODES offset type - angle+radius
    • - -
  • New NODES offset type - compass-point+percentage
    • - -
  • "KEYSTYLE inverted" - to get a thermometer-style vertical legend.
    • - -
  • "COMMENTSTYLE center" to make comments run along the centre of a - link arrow. (and 'edge' for the usual) -
    • - -
  • COMMENTFONTCOLOR accepts 'contrast' as an option, for when it's over - a link -
    • - -
  • VIASTYLE angled (or curved) - you can turn sharp corners now
    • - -
  • Comment (and pos) editing in editor (based on code by Zdolny)
    • - -
  • Editor Settings dialog works, and allows you to set grid-snap and - some overlays -
    • - -
  • SCALE allows 'none' as a colour (for non-gradients). Only affects - LINKs so far. -
    • - -
  • fping plugin allows for changing the number of pings.
    • - -
  • TARGET strings can be enclosed in quotes, to allow spaces in them - (mainly for external ! scripts) -
    • - -
  • "KEYSTYLE tags" - - like classic, but uses the scale tags instead of percentages. -
    • - -
  • scripts in random-bits to help with automatic/assisted mapping.
    • - -
  • lots more pretty pictures in the manual, so you can see what I - mean. -
    • - -
  • IMAGEURI keyword to match --image-uri command-line option (ignored - in Cacti plugin) -
    • - -
  • MINTIMEPOS and MAXTIMEPOS to track data source times
    • -
- -

Changes For This Version (0.941 to 0.95)

- -

This release has a lot of changes - - most of them are small 'polishing' tweaks, but there are a few interesting - bigger ones too. Happily, although there are a quite a few more features, - this release actually has - less lines of code than 0.941, due to some internal cleaning up.

- -

Known Issues

- - - -

Fixes

- -
    -
  • KEYOUTLINECOLOR is actually used now (thanks to llow once more)
    • - -
  • Editor doesn't throw away WIDTH and HEIGHT with no BG image
    • - -
  • Cacti Data-source and Graph picker doesn't restrict scrolling or - resizing anymore -
    • - -
  • weathermap-cacti-rebuild.php to work on both Cacti 0.8.6 and - 0.8.7 -
    • - -
  • weathermap-cacti-rebuild.php to flat-out fail if Cacti environment - is wrong. -
    • - -
  • SNMP DS plugin had a typo that stopped it working at all (and no-one - noticed for almost a year :-) ). (thanks to Fratissier Christophe for - pointing it out) -
    • - -
  • Added some better controls into SNMP DS plugin. You can correctly - pull interface oper/admin status, for example, now. -
    • -
- -

Changes

- -
    -
  • DS plugins are able to return negative results now - (breaks user-developed DS plugins)
    • - -
  • the scale: prefix for the RRD DS plugin can take negative scale - factors -
    • - -
  • (internal) plugins are each created as a single object now. Result: - the plugin can cache results internally. -
    • - -
  • (internal) broke out some of the larger classes (node, link) into - separate files. -
    • -
- -

New Features

- -
    -
  • You can add a 'tag' to a SCALE line, to be used in ICON or LABELs - later. -
    • - -
  • USEICONSCALE - colorize icon images (based on patches from llow)
    • - -
  • screenshot mode. "SET screenshot_mode 1" at the top of the map will - anonymise all labels, comments and bwlabels. -
    • - -
  • LABELFONTCOLOR can use a special value of 'contrast' to always - contrast with the label colour. -
    • - -
  • Artificial Icons. Special icon 'filenames' - - 'box' 'round' 'rbox' create a shaped icon without any file. See ICON - and AICONFILLCOLOR for more. -
    • - -
  • Map titles show up in browser title now.
    • - -
  • a basic 'live view' function which generates a map on demand. - Sometimes. It's not very useful. -
    • - -
  • LABELANGLE allows you to rotate node labels to 90,180,270 degrees. - Needs truetype font. -
    • - -
  • improved data-source picker in editor: host filter
    • - -
  • improved data-source picker in editor: option to aggregate data - sources -
    • - -
  • Moved data-source picker changes across into the graph-picker for - NODEs too. -
    • - -
  • SPLITPOS keyword to control position of midpoint in links
    • - -
  • VIA can be positioned relative to NODEs (like NODEs can) (thanks - again to llow) -
    • - -
  • Weathermap has a hook in the map viewing page to allow other plugins - to add code there -
    • - -
  • .htaccess files bundled with Weathermap to restrict direct access to - configs and output -
    • - -
  • filenames for output are much less guessable now - (may break external references to maps)
    • - -
  • You can use 'DUPLEX half' on a link to make the bandwidth percentage - calculate work for half-duplex links -
    • - -
  • ININFOURL / OUTINFOURL, INOVERLIBGRAPH / OUTOVERLIBGRAPH, INNOTES - / OUTNOTES, INOVERLIBCAPTION - / OUTOVERLIBCAPTION allow you to have different urls for the in and out - side of links (based on idea from llow) -
    • - -
  • OVERLIBGRAPH (and IN/OUT versions) can take multiple URLs separated - by spaces (again from idea by llow) -
    • - -
  • debug/warning log output contains the map name, and the debug output - is marked DEBUG -
    • - -
  • debug log output contains the calling function, file/line number, - too. Making debugging-by-mail easier. -
    • - -
  • fping: TARGET to do live pings of devices. See targets.html
    • - -
  • a very basic sample 'skeleton' DS plugin
    • - -
  • an additional check-gdbug.php to spot bad GD installs
    • - -
  • MRTG DS plugin can do a few new tricks. See TARGET and - targets.html -
    • -
- -

Changes For This Version (0.94 to 0.941)

- -

Fixes

- -
    -
  • Added extra code to help discourage browser caching.
    • - -
  • Issue with '-' DS names again.
    • - -
  • Removed some extra chatty debugging code from poller_output
    • -
- -

Changes For This Version (0.93 to 0.94)

- -

0.94 was released early, to fix the one small issue caused by files - moving around in the recent Cacti 0.8.7 release. However, there are some - nice new features even so - - INBWFORMAT has been requested for quite a while, and so has poller_output - support.

- -

Changes

- -
    -
  • Finally a better tab image, and a red 'active' one too, for the - Cacti plugin. -
    • -
- -

New Features

- -
    -
  • INBWFORMAT and OUTBWFORMAT allow you to format the text for BWLABEL, - same as for COMMENTs -
    • - -
  • New cactithold/cactimonitor data source plugin reads data from - Cacti's Threshold plugin. (Original development for this plugin was paid - for by Stellar Consulting - Thanks!) -
    • - -
  • New LINKSTYLE command allows you to have one-way (one arrow) - links. -
    • - -
  • RRD DS can use Cacti's poller_output to get data without running - RRDtool at all. (this also means it can work with the Boost plugin for - large installations) See - targets.html for more info on this one. -
    • - -
  • Editor - - Align horizontal and Align-vertical for links. Calculates link offsets - to make link vertical/horizontal. -
    • -
- -

Fixes

- -
    -
  • "Full Screen Maps" mode in Cacti Plugin was broken by me adding the - "View Only First" mode. -
    • - -
  • Imagemaps for horiz/vert format legend were wrong in editor (thanks - to Alex Moura for pointing this out) -
    • - -
  • Changes for compatibility with Cacti 0.8.7's moved config file.
    • -
- -

Changes For This Version (0.92 to 0.93)

- -

Changes

- -
    -
  • The auth realm names for Cacti have been changed to match ReportIt - and Aggregate - - easier to tell who does what (Plugin -> Weathermap: View Maps) -
    • - -
  • Editor warns about older editor-config.php format now
    • - -
  • Formatted numbers (Mega, Kilo etc) now can include milli, micro and - nano (m,u,n). -
    • -
- -

New Features

- -
    -
  • weathermap-cacti-plugin.php?action=viewmap&id=mapfilename works - as well as a map number - useful for crosslinks -
    • - -
  • Warning for duplicate node or link names
    • - -
  • unique code for each warning message, and a page to explain it on - the website. Ugh. -
    • - -
  • warning in editor file-selector so you can tell if the file is - read-only -
    • - -
  • click config filename to edit in editor from Cacti (thanks to - streaker69) -
    • - -
  • cactihost: DS plugin fetches a bunch of other stats from Cacti's DB - now, too (like availability and response times) -
    • - -
  • Picking Cacti sources from editor has a javascript "live filter" - feature now (needs a little work) -
    • - -
  • node coordinates are directly editable in the editor now
    • - -
  • File picker allows you to use an existing map as a template
    • - -
  • Editor now allows you to clone a node with all it's styling - intact. -
    • - -
  • When picking coordinates (new node, move node, move timestamp etc), - you can see the coordinates -
    • - -
  • Editor toolbar fixed to window, to make it easier to scroll around - large maps -
    • - -
  • RRD Datasource has improved warnings for non-existent DS names
    • - -
  • Editor allows you to edit raw text of nodes and links
    • - -
  • Editor link in management page (warnesj)
    • - -
  • Docs link in management page too (streaker69)
    • - -
  • Editor has a better warning for unwriteable files and directory - now. -
    • - -
  • When you come TO the editor from Cacti, the Change File goes BACK to - Cacti -
    • - -
  • "Show Only First" mode in Cacti UI - - useful for heirarchies of maps with a parent. -
    • - -
  • scale: prefix for RRD datasource - - multiply/divide by any value as you read an rrd datasource -
    • -
- -

Fixes

- -
    -
  • RRD doesn't consider DSes other than the ones you named when finding - a valid line. -
    • - -
  • editor-generated node names are a bit shorter (and easier to read) - now. -
    • - -
  • keyboard focus switches nicely to the popup dialogs now.
    • - -
  • Non-unique IDs in imagemaps, in overlib mode.
    • - -
  • COMMENTPOS 0 doesn't kill everything anymore
    • - -
  • OVERLIB would behave incorrectly with PHP4 and relatively positioned - nodes (Bernd Ziller) -
    • - -
  • Better-validating HTML produced
    • - -
  • angled bwlabels have the correct imagemap
    • - -
  • divide-by-zero error for some (?) PHP versions in poller
    • - -
  • the key_hidezero secret setting hides the zero in a gradient in a - classic scale too. -
    • -
- -

Changes For This Version (0.91 to 0.92)

- -

New Features

- -
    -
  • BWSTYLE allows you to align the BWLABEL boxes with their links. - Looks nice! -
    • - -
  • COMMENTPOS allows you to move comments, much like BWLABELPOS for - BWLABELs -
    • - -
  • The editor works the way you'd expect for defaults now.
    • - -
  • The editor does a bunch of clever maths when moving a node that is - part of a curved link to make a sensible result (I like this one). -
    • - -
  • The editor will let you pick an INFOURL and OVERLIBGRAPH for a NODE - from your Cacti graphs (but not a TARGET yet). -
    • - -
  • The editor doesn't require an - editor-config.php anymore, but if you do have one, - make sure it's based on the editor-config.php-dist in this - version. This file has changed. -
    • - -
  • Secret SET codes: key_hidepercent_scalename and - key_hidezero_scalename - -
    - - You can set these at the top of the config file, for each scale (change - scalename to the scale name). - SET key_hidezero_DEFAULT 1 hides the 0->0 line if there is - one, in a 'classic' style legend for that scale. - SET key_hidepercent_scalename 1 hides the percentage signs in - the 'classic' style legend for that scale. -
    • -
- -

Fixes

- -
    -
  • SET in a DEFAULT node or link wasn't inherited properly.
    • - -
  • weathermap.conf is a simple map again. I accidentally packaged my - test map for 0.9 and 0.91 -
    • - -
  • Any unreadable files in the configs/ directory would kill the - editor -
    • - -
  • One PHP short_tag remained, which upsets some PHP installs (seems to - be mainly Windows) -
    • -
- -

Changes For This Version (0.9 to 0.91)

- -

After all the big changes (below for 0.9), there are a whole bunch of - bugs that no-one spotted in the testing, so this release is mostly a - clean-up of those. There are a couple of small changes for new features, and - a bit more diagnostic stuff for installation problems.

- -

New Features

- -
    -
  • 'Quiet Mode' Logging - - in the Cacti plugin, there is a new setting to make Weathermap log - only errors in the standard 'LOW' logging setting. -
    • - -
  • Subtractive Aggregation - - if one of the clauses in a TARGET line begins with a '-', then that - value is subtracted from the result instead of added. This can be useful - to calculate a value that couldn't be measured directly. For example, - Netscreen firewalls don't give per-policy bandwidth stats, so to find - out how much traffic is going to the internet, and how much to a VPN, - you can start with the total interface traffic, and take out the VPN - traffic (which you can measure), to leave the Internet traffic. -
    • - -
  • There is a new - check.php script, that verifies some basic requirements of your - PHP installation. It's mainly useful during installation, so it's - described in the installation instructions. -
    • - -
  • A couple of additional variables are available in the 'special - string tokens' - - 'inscalekey' and 'outscalekey' store the internal names of the SCALE - line that was triggered for the 'in' and 'out' values of a map object. - You can use this to do some things like changing icons based on a value, - without needing to write a plugin yourself. It's pretty obscure, but - could be handy. -
    • -
- -

Fixes

- -
    -
  • RRD bug with '-' DS names. This was fixed in 0.9pre3, but somehow - slipped through. -
    • - -
  • ReadConfig doesn't complain about KEYPOS DEFAULT -1 -1 (as written - by WriteConfig) anymore -
    • - -
  • The MRTG plugin made some assumptions that broke handling of MRTG - html files on remote systems. It doesn't now. -
    • - -
  • NOTES was not fully tested, and broke cactihost: targets, at - least. -
    • - -
  • KILO was broken - fixed now.
    • - -
  • BWLABELPOS was handled badly by the editor - - it would swap them over -
    • -
- -

Changes For This Version (0.82 to 0.9)

- -

I've divided the changes up into chunks. Most of the serious work was - done in the - Structural Changes section, but there are plenty - of things for everyone. These are brief descriptions - - see the Config Reference for the full detail. I've mentioned the - appropriate configuration keywords if there are any.

- -

Graphical Changes

- -

These tend to be smaller things, but together they make a lot of useful - additions.

- -

Link comments

- -

You can add a comment string which runs down the side of link arrows. - This is intended for use for circuit references, or interface names. There - are 4 new directives to make this happen: INCOMMENT, OUTCOMMENT, COMMENTFONT - and COMMENTFONTCOLOR. You - must use a TrueType COMMENTFONT to use this feature, as none of the - other font types allow for rotation of text.

- -

Bandwidth Label Positioning

- -

You can now move the bandwidth labels (those little boxes) up and down - the link arrow. You set a percentage position with BWLABELPOS.

- -

Pixel-Offsets

- -

You can make links end at arbitrary positions relative to a node now. - Previously you could use compass-points, now you can also use pixels for the - offsets in a NODES line

- -

JPEG & GIF Support

- -

If your GD library supports it, then Weathermap now understands JPEG and - GIF files for BACKGROUND, ICON and IMAGEOUTPUTFILE.

- -

NOTES & OVERLIBCAPTION

- -

You can specify a caption string for the 'popup' overlib window now, - per-node/link. You can - also have HTML-formatted text in that window, with or without the - graph. See NOTES and OVERLIBCAPTION.

- -

Use it with String Tokens to make captions for your nodes, with - additional information.

- -

New Legend Styles

- -

The new KEYSTYLE directive allows you to choose between 'classic' and two - new styles of Legend. The new styles are neater for showing gradient scales, - or when you have a lot of different bands.

- -

Relative Positioning

- -

You can position a node relative to another node. This is handy for - maintaining big rows of nodes, where only one needs to be fixed in position - now.

- - -

Structural Changes

- -

The internal structure of Weathermap has changed quite a lot in this - version. It started as a few small changes, but each one showed that another - was required.

- -

Datasource Plugins

- -

All the data-reading parts of Weathermap are now in plugins. This is to - allow users to add their own external data sources more easily, without - having to change the Weathermap code. All the previous TARGET strings will - work as before, and I've added a few new ones for 0.9:

- -
    -
  • static - - if you need to fix a data value, you can do it without an external - text file. -
    • - -
  • cactihost - - read the up/down status of a host in Cacti -
    • - -
  • gauge - - Read RRD values without any special treatment. -
    • -
- -

The RRD plugin also has some improvements in dealing with error - conditions in this release. -

- -

There are planned plugins for Cacti (reading directly from the Cact - database), Nagios Host Status, SNMP directly and others.

- -

NODE Targets

- -

NODEs can have data now. This means you can have them change colour - according to a SCALE, just like a LINK does. Since a NODE only has one - value, you can choose which one to use (of the two that a TARGET provides), - with USEVALUE.

- -

Multiple SCALEs

- -

Because you probably don't want your nodes to change colour with the same - values as your links, you can now have multiple SCALE sets too. The default - one is DEFAULT, but you can define others and use them with USESCALE in a - NODE or LINK section.

- -

String Tokens

- -

You can embed information from Weathermap, and from your own data, in - almost any string in Weathermap. This allows you to do things like:

- -
    -
  • Show percentage CPU usage in a node LABEL
    • - -
  • Change which ICON is used depending on a datasource value
    • - -
  • Add extra "sub-NODEs" around a NODE, with addional information
    • - -
  • Use generic TARGET, INFOURL, OVERLIBGRAPH lines in the DEFAULT link - and node -
    • -
- -

Arbitrary Parameters

- -

The new SET directive lets you define new 'variables' per-NODE, per-LINK - or for the whole map. These can be used to give fine-tuning parameters to - the data source plugins, and also as additional data in String Tokens.

- -

Cacti Plugin

- -

Most of the Cacti Plugin changes are bugfixes or for more advanced - users.

- -

Non-Standard Poller Cycle Times

- -

If you are using the "<5 minute poller" patch from TheWitness, then - you may not want the time-consuming Weathermap process to run every poller - cycle. There is now an option to choose how often Weathermap redraws it's - maps, including 'Never'.

- -

Async Map Generation

- -

If you choose 'Never' above, then you need some way to redraw. The new - weathermap-cacti-rebuild.php script allows you to run a separate - cron job for Weathermap, but in the environment it would have inside the - poller process.

- -

Recalculate Now

- -

If you have your permissions set up correctly, then you can force the - redraw of all maps from within the Cacti UI, instead of waiting for a poller - cycle.

- -

Editor

- -

There are no new features in the Editor for 0.9, although a few annoying - bugs have been squashed. I have big plans for the editor, but they are a - whole project by themselves, so I've put it to one side. Otherwise 0.9 would - never have appeared :-) Now this version is released, the Editor is one the - main focus areas for the next release.

- -

Bugfixes

- -

There were a lot of bugs fixed along the way. Most were new ones, but a - few are things that existed in 0.82 too:

- -
    -
  • Wierd bug in HTML_ImageMap if you have a lot of similarly-named - NODEs or LINKs. -
    • - -
  • Floating-point limits in SCALEs work correctly now. Also, you can - specify a 0-0 SCALE line and it will always take precedence. -
    • - -
  • Cacti plugin doesn't assume 'admin' user always exists, and that - users are never deleted. -
    • - -
  • Cacti plugin's Cycle mode works in IE now.
    • - -
  • KILO was ignored in some places.
    • - -
  • Editor will let you rename nodes now!
    • - -
  • Editor deals properly with ' in node labels
    • - -
  • Editor deals properly with pathnames containing '\' on Windows.
    • - -
  • Editor lets you pick JPG and GIF images too, since we now support - them -
    • - -
  • Close-together nodes don't crash the curve-drawing anymore
    • -
-
- - - + + + + + + Changes and release history — Network Weathermap 2.0 + + + + +
+ Network Weathermap 2.0 +

Cacti plugin manual

+
+
+ +
+

Changes and release history

+

The authoritative release-by-release list is the bundled CHANGELOG.md and the published release notes. A develop + checkout can contain fixes after the 2.0 tag; it should not be described as identical to the + release archive.

+
+

2.0 at a glance

+
    +
  • Redesigned node/link properties, searchable interface assignment and clearer expert + controls.
    • +
  • Two-step per-tab Undo/Redo for saved map edits.
    • +
  • Editable notes and node display-name positioning.
    • +
  • Curved comments, bundled fonts, traffic colour presets and optional high-load + pulsing.
    • +
  • Separate upload/manage libraries for icons and backgrounds; additional bundled 96px + icons.
    • +
  • One additional link hover preview, individually clickable Cacti previews and + high-density rendering.
    • +
  • Map titles, improved gallery cards, sharper thumbnails and fit/stretch + backgrounds.
    • +
  • Safer saves/deletion, improved theme handling, Safari interaction/rendering fixes and + navigation preservation.
    • +
+

Check the release notes and installed commit for maintenance fixes after the 2.0 tag. + The bundled changelog describes the code shipped in this checkout.

+
+
+ + Historical original-project release notes (0.98 series and earlier) + +

Retained from Howard Jones’s manual for historical reference. Installation instructions, + external links and future plans inside this archive are not current 2.0 guidance.

+

Changes For This Version (0.97c to 0.98)

+

This is a roll-up of all the small bugfixes for the last couple of years, especially + those that stop Weathermap working with newer MySQL or PHP versions. There is a more + substantial 1.0 release in the works, but I will backport any simple improvements or fixes + to 0.98(abcd) releases. There are also small usability changes aimed at reducing repeat + "error reports" in the forums.

+

Another part of this change is that the Weathermap code is now hosted on github. There + is also an issue tracker. There are two branches of code there, one (0.97-maintenance) is + for this 0.98 series of smaller changes, and the other (master) branch is for the ongoing + rewrite work. For now, if you want to track useful work, that will be on the + 0.97-maintenance branch.

+

IMPORTANT NOTE - you may need to reset permissions on your users after upgrading, as + I've finally switched to the "new-style" plugin API that's been around for 5+ years. This + handles permissions differently, unfortunately. The new permissions have been in a few + releases of Weathermap already so you should check if this affects you after + installation.

+

Fixes

+
    +
  • MySQL error in table-creation. MySQL 5.6 is fussier.
    • +
  • Editor 'delete link' broken
    • +
  • + KILO was ignored when processing %k in + special tokens +
    • +
  • Various fixes for PHP deprecated or strict-mode warnings
    • +
  • Line-ending trimming in 'external script' data source
    • +
  • rounding error 'kinks' in angled VIA + links +
    • +
  • Config file path validation issue in editor (CVE-2013-3739)
    • +
  • Cloning a templated node in editor retains the template in the clone
    • +
  • cacti_use_ifspeed incorrect when interfaces > 20M and ifhighspeed available
    • +
  • More PHP 5.3/5.4/strict related errors (split -> explode)
    • +
+

Changes

+
    +
  • Finally switch to "new-style" plugin API.
    • +
  • Editor data picker improved sort (thanks shd)
    • +
  • (Cacti plugin only) images are written to a temporary file first, to avoid displaying + half-written images
    • +
  • Editor no longer uses editor-config.php
    • +
+

New Features

+
    +
  • Weathermap will use anti-aliasing if your GD supports it (php-bundled GD doesn't) + (thanks shd)
    • +
  • Special token formatting can handle timeticks and time_t formatting (%T and %t + respectively)
    • +
  • new DATAOUTPUTFILE allows + collected data to be written to a file for later use (automatically enabled in Cacti) +
    • +
  • new wmdata: datasource plugin can read data from files produced by DATAOUTPUTFILE +
    • +
  • + IMAGEOUTPUTFILE and HTMLOUTPUTFILE are honoured in Cacti + poller as a location for a second copy of those files. +
    • +
  • Editor 'tidy link' function replaces Vert & Horiz, and does much nicer job
    • +
  • 'retidy' option in editor to recalculate all links previously positioned with + 'tidy'.
    • +
  • + KEYBGCOLOR and KEYOUTLINECOLOR both accept 'none' +
    • +
  • command-line weathermap has new --no-warn option to disable warnings
    • +
  • + AICONFILLCOLOR accepts 'none' for + drawing giant transparent shapes. +
    • +
  • Extra warning for Boost users about poller_output
    • +
  • if there are actually 0 maps in the database, the 'Weathermaps' tab gives some basic + instructions.
    • +
  • Cacti data picker in editor tracks most recently used hosts (thanks Zdolny)
    • +
  • New permission in Cacti: edit maps. Maps can be edited by authorized users without + needing to enable the editor in the source code.
    • +
+

Changes For This Version (0.97b to 0.97c)

+

0.97c had no additional changes - it's just 0.97b with some silly errors fixed, and all + the CSS files included with the correct paths. There were also reports of problems with the + actual zip file.

+

Changes For This Version (0.97a to 0.97b)

+

0.97b is a special release starting from 0.97a and backporting all the quick bugfixes + from the 0.98 code. There are larger structural changes in 0.98 and new features, but these + bugfixes were useful enough to warrant a new 0.97 release (especially the mysql schema + change). A real 0.98 release will follow in due course.

+

Also late addition to 0.97b - a couple of security analysts have pointed out flaws in + the editor. First, the ability to remotely create .php files and then cross-site-scripting + vulnerabilities. Both are really facets of the same thing - lack of input validation. 0.97b + improves this a great deal.

+

Thanks to Gerry Eisenhaur and Daniel Ricardo dos Santos respectively for their security + bug reports.

+

Fixes

+
    +
  • absolute SCALE definitions didn't + support K (thanks wwwdrich) +
    • +
  • memory leak in poller code. Memory usage is MUCH lower now.
    • +
  • updated mysql schema commands to use modern ENGINE instead of TYPE
    • +
  • static datasource plugin honours KILO
    • +
  • check-gdbug.php shouldn't complain about empty ob_flush buffers anymore
    • +
  • SNMP DS should deal better with non-numeric (and blank) return values
    • +
  • NINK colours were exchanged (thanks Deathwing00!)
    • +
  • WriteConfig (i.e. editor) won't 'lose' absolute keyword from
    • +
  • fixed some function-name clashes with other plugins
    • +
  • PHP 5.3/5.4/strict related errors ("Creating default object from empty value")
    • +
+

Changes

+
    +
  • no longer shows .-prefixed files in map config picker
    • +
  • editor ignores attempts to rename nodes to have space in names
    • +
  • Manual updates for changes in Cacti, and improvements in styling.
    • +
  • The Cacti UI will warn you about fundamental file permissions problems
    • +
  • Moved all PHP that doesn't need to be web-accessible into lib. See Security notes. +
    • +
  • Editor won't deal with config files that don't have a .conf extension
    • +
  • General improvements in input validation and output escaping in editor
    • +
  • 'External Script' datasource plugin is disabled by default in new installs (NOT + upgrades though!)
    • +
+

New Features

+
    +
  • Caching for cacti data fetched by dsstats and rrdtool/poller_output DS plugins
    • +
+

Changes For This Version (0.97 to 0.97a)

+

Lots of bugs appeared the day after 0.97 was released! There are a few small features + added, but mainly this is bugfixes.

+

Fixes

+
    +
  • Incorrect action URL in 'map selector' combo box for Cacti users.
    • +
  • cacti_graph_id set to 0 instead of ID, by rrd/poller_output and dsstats plugins + (thanks sh0x)
    • +
  • 'classic' legend drew 'hidden' colour values for things like key background colour. + (thanks jmayniac)
    • +
  • PHP 5.3 deprecated code in HTML_Imagemap.class.php
    • +
  • 'Show Only First' option ignored in Cacti (thanks inko_nick)
    • +
  • Editor deals with overlapping nodes on different ZORDERS properly.
    • +
  • "property of non-object in editor.php line 466" while editing map properties (thanks + to iNeo)
    • +
  • no-data option on command-line didn't work
    • +
  • Clone Node was broken in 0.97
    • +
  • Maps with per-user permissions show up multiple times in map selector
    • +
  • Removed incorrect warning about imagefilter and USEICONSCALE.
    • +
  • string escaping bug with editor and direct config changes (thanks uhtred)
    • +
  • --imageuri was ignored on command-line (thanks Marcus Stögbauer)
    • +
  • links with targets containing spaces are broken by the editor (thanks Andreas + Braun)
    • +
  • deprecated jQuery function call in cacti-pick.php (thanks again Andreas Braun)
    • +
+

Changes

+
    +
  • Group sorting is a bit more logical and the presentation nicer.
    • +
  • cacti-integrate.php uses getopt to take more command-line params
    • +
  • Updated jQuery to latest
    • +
  • Number formatting will pick 1G over 1000M (and similar) (thanks cerbum)
    • +
  • The editor is disabled by default - see top of editor.php (and install guide)
    • +
+

New Features

+
    +
  • + LINK WIDTH accepts decimals +
    • +
  • cacti-integrate.php can generate DSStats + TARGETs too +
    • +
  • Simple VIA editing in editor (thanks to + Zdolny) +
    • +
  • + SCALE can accept G,M,K,T,m,u,n + suffixes (for absolute scales) +
    • +
+

Changes For This Version (0.96a to 0.97)

+

Fixes

+
    +
  • RRD Aggregation regexp was failing (thanks to shd)
    • +
  • Scale numerals honour locale (thanks again, shd)
    • +
  • THold plugin check failed with Thold 0.4.1 (PA 2.x, actually)
    • +
  • Uninitialized variable in ReadData when plugin is disabled
    • +
  • Zero-length link check didn't include offsets (thanks Ryan Botoluzzi)
    • +
  • Cacti-pick should get right rra path for packagers that move the rra directory (e.g. + Ubuntu, Debian *again*)
    • +
  • DS plugins that return one value and a null should work properly
    • +
  • "Strange" characters (e.g. /) in NODE + and LINK names broke the imagemap. +
    • +
  • Map Style settings in editor were broken after internal defaults changes
    • +
  • Imagemap no longer contains areas with no href defined
    • +
  • + SPLITPOS was ignored with VIASTYLE angled (thanks to uhtred) +
    • +
  • + 'AICONOUTLINECOLOR none' is actually + valid now (thanks to mgb & Leathon) +
    • +
  • readdir() loop never stops, on some systems (thanks to jerebernard)
    • +
  • bad regexp in the MRTG DS plugin (thanks to Matt McMahon)
    • +
  • 0.96 had a new 'time' DS plugin - now documented!
    • +
  • NCFPC only complains about missing scale lines on NODEs for the variable that is in use. +
    • +
+

New Features

+
    +
  • + USEICONSCALE no longer has + special dependencies - and the colours are nicer too. +
    • +
  • Option of a dropdown selector to navigate between maps (in full-size view)
    • +
  • Maps can be organised into groups in Cacti plugin. These appear as tabs in the UI for + viewing maps.
    • +
  • Extra variables can be defined per-group, so all maps in a group can have similar + settings (e.g. a "24hr average" tab).
    • +
  • + INCLUDE keyword to include a file of + common definitions (based on work by BorisL) (NOTE: this can confuse the editor + sometimes - see the manual page for INCLUDE) +
    • +
  • Warning for maps that contain OVERLIBGRAPH but not 'HTMLSTYLE overlib' +
    • +
  • Warning for use of TEMPLATE not as + the first line of an object (overwrites settings otherwise) +
    • +
  • + SCALE will accept values below 0, and + also above 100 +
    • +
  • + USESCALE has two new options: + absolute and percent, which allows you to have a SCALE of absolute values +
    • +
  • New datasource plugin to support statistics from TheWitness's DSStats Cacti Plugin. + This gets you daily,weekly,monthly and annual stats with no complicated rrdtool + stuff.
    • +
  • New converter to take a rrdtool-based map config and make it into a DSStats-based + one
    • +
  • static datasource can be used for negative values
    • +
  • SNMP datasource has configurable timeout and retry values.
    • +
  • SNMP datasource has option to give up on a failing host
    • +
  • + LABELOFFSET supports percentage + compass offsets and radial offsets, like NODES does. +
    • +
  • Percentage compass offsets (NODES and + LABELOFFSET) support > 100% + offsets +
    • +
+

Changes For This Version (0.96 to 0.96a)

+

Just the usual post-release bug reports...

+

Fixes

+
    +
  • New z-ordering code did not work correctly on PHP4. This broke (at least) the editor. + (thanks toe_cutter)
    • +
  • \n is no longer treated as a newline in + TARGETs (thanks NetAdmin) +
    • +
  • + KILO was broken completely between + 0.95b and 0.96 (thanks Jethro Binks) +
    • +
  • Link comments in certain positions could cause div-by-zero errors. (thanks again + Jethro)
    • +
  • + USEICONSCALE didn't colorise + (broken between 0.95b and 0.96 again) (thanks colejv) +
    • +
  • Managed to make LABELOFFSET + case-sensitive. +
    • +
+

Changes For This Version (0.95b to 0.96)

+

Fixes

+
    +
  • Cacti poller_output support works more reliably/at all on Windows
    • +
  • Renaming a node in the editor correctly handles other relatively-positioned nodes and + vias
    • +
  • Minor issue with CRLF in map title for Cacti Plugin
    • +
  • CLI tool set --define options incorrectly.
    • +
  • Oneway links don't draw the INCOMMENT anymore +
    • +
  • negative TIMEPOS didn't hide the + timestamp +
    • +
  • DEFAULT SCALE covers 0-100 properly + (Thanks Dan Fusselman) +
    • +
  • Scaled ICON in DEFAULT didn't get + overwritten properly in nodes (Thanks Fabrizio Carusi) +
    • +
  • No more floating-point imagemap coords (Thanks Trond Aspelund)
    • +
  • RRDtool regional output (. vs ,) workaround
    • +
  • Cacti poller_output handles NaN more gracefully now
    • +
  • SNMP datasource should work with Windows SNMP again
    • +
  • MRTG datasource tried to stat() URLs
    • +
  • Error reporting for CLI --define was bad. --help text was out of date.
    • +
  • Editor will honour LABEL from + NODE DEFAULT, if it is set. +
    • +
+

Changes

+
    +
  • Cacti plugin uses "processed" map title now (allows {} tokens in the title)
    • +
  • A NODE with no POSITION is not drawn, instead of drawn at 0,0. + Useful for templates. +
    • +
  • A LINK with no NODES is no longer an error. Also for templates. +
    • +
  • The link_bulge secret mode bulges each side of a link independently now
    • +
  • whitespace is stripped from the beginning and end of each line before parsing
    • +
+

New Features

+
    +
  • + TEMPLATE allows a node or link to + copy it's settings from another, instead of from DEFAULT. +
    • +
  • RRD datasource can take SET + rrd_default_path to make configs a little easier to read. +
    • +
  • RRD datasource can take SET + rrd_default_in_ds and rrd_default_out_ds for non-Cacti users. +
    • +
  • RRD datasource can get Cacti query information (in poller_output mode ONLY) - like + ifAlias, ifSpeed etc
    • +
  • RRD datasource can take the ifSpeed/ifHighSpeed from the above, and use it in the + map.
    • +
  • RRD datasource fills in Cacti cacti_path_rra and cacti_url with Cacti base path and + URL
    • +
  • RRD datasource can take global SET + rrd_options to add extra options to rrdtool command lines +
    • +
  • SNMP datasource also stores the raw data from the SNMP agent in + snmp_raw_in/snmp_raw_out
    • +
  • SNMP datasource allows '-' as an OID, similar to '-' targets in RRDs.
    • +
  • Control the drawing order with ZORDER.
    • +
  • New artificial icons: nink, inpie and outpie. See ICON in manual. +
    • +
  • Warning for probably-incorrect BWLABELPOS where in<out +
    • +
  • New global SET variables to disable + some common warnings you may not care about :-) +
    • +
  • Cacti management screen shows number of warnings for each map last time it ran
    • +
  • Cacti management screen also has a link to the log entries for the map in + question
    • +
  • The TARGET aggregation thing can also + take scale factors now: -5.5*myrrdfile.rrd +
    • +
  • Cacti plugin caches thumbnail sizes, improving thumbnail view rendering
    • +
  • Cacti plugin allows adding the same map twice (more useful than it sounds)
    • +
  • Cacti plugin allows setting of map-global variables in the management UI
    • +
  • Cacti plugin allows settings of global map-global (across all maps) variables + too
    • +
  • Cacti plugin adds links in 'user' pages to management screen (if you are an + admin)
    • +
  • + HTMLSTYLESHEET keyword allows + you to specify a URL for a CSS stylesheet (CLI tool only) +
    • +
  • A few extra CSS id and class attributes, to make styling the page easier.
    • +
  • New token: in/outscalecolor contains HTML colour code of node/link colours for use in + NOTES +
    • +
  • New NODES offset type - angle+radius +
    • +
  • New NODES offset type - + compass-point+percentage +
    • +
  • + "KEYSTYLE inverted" - to get a + thermometer-style vertical legend. +
    • +
  • + "COMMENTSTYLE center" to make + comments run along the centre of a link arrow. (and 'edge' for the usual) +
    • +
  • + COMMENTFONTCOLOR accepts 'contrast' as + an option, for when it's over a link +
    • +
  • + VIASTYLE angled (or curved) - you can + turn sharp corners now +
    • +
  • Comment (and pos) editing in editor (based on code by Zdolny)
    • +
  • Editor Settings dialog works, and allows you to set grid-snap and some overlays
    • +
  • + SCALE allows 'none' as a colour (for + non-gradients). Only affects LINKs so + far. +
    • +
  • fping plugin allows for changing the number of pings.
    • +
  • + TARGET strings can be enclosed in + quotes, to allow spaces in them (mainly for external ! scripts) +
    • +
  • + "KEYSTYLE tags" - like classic, but + uses the scale tags instead of percentages. +
    • +
  • scripts in random-bits to help with automatic/assisted mapping.
    • +
  • lots more pretty pictures in the manual, so you can see what I mean.
    • +
  • + IMAGEURI keyword to match + --image-uri command-line option (ignored in Cacti plugin) +
    • +
  • + MINTIMEPOS and MAXTIMEPOS to track data source times +
    • +
+

Changes For This Version (0.941 to 0.95)

+

This release has a lot of changes - most of them are small 'polishing' tweaks, but there + are a few interesting bigger ones too. Happily, although there are a quite a few more + features, this release actually has less lines of code than 0.941, due to some + internal cleaning up.

+

Known Issues

+ +

Fixes

+
    +
  • + KEYOUTLINECOLOR is actually used now + (thanks to llow once more) +
    • +
  • Editor doesn't throw away WIDTH and + HEIGHT with no BG image +
    • +
  • Cacti Data-source and Graph picker doesn't restrict scrolling or resizing + anymore
    • +
  • weathermap-cacti-rebuild.php to work on both Cacti 0.8.6 and 0.8.7
    • +
  • weathermap-cacti-rebuild.php to flat-out fail if Cacti environment is wrong.
    • +
  • SNMP DS plugin had a typo that stopped it working at all (and no-one noticed for + almost a year :-) ). (thanks to Fratissier Christophe for pointing it out)
    • +
  • Added some better controls into SNMP DS plugin. You can correctly pull interface + oper/admin status, for example, now.
    • +
+

Changes

+
    +
  • DS plugins are able to return negative results now (breaks user-developed DS + plugins)
    • +
  • the scale: prefix for the RRD DS plugin can take negative scale factors
    • +
  • (internal) plugins are each created as a single object now. Result: the plugin can + cache results internally.
    • +
  • (internal) broke out some of the larger classes (node, link) into separate + files.
    • +
+

New Features

+
    +
  • You can add a 'tag' to a SCALE line, + to be used in ICON or LABELs later. +
    • +
  • + USEICONSCALE - colorize icon + images (based on patches from llow) +
    • +
  • screenshot mode. "SET screenshot_mode + 1" at the top of the map will anonymise all labels, comments and bwlabels. +
    • +
  • + LABELFONTCOLOR can use a special value + of 'contrast' to always contrast with the label colour. +
    • +
  • Artificial Icons. Special icon 'filenames' - 'box' 'round' 'rbox' create a shaped + icon without any file. See ICON and + AICONFILLCOLOR for more. +
    • +
  • Map titles show up in browser title now.
    • +
  • a basic 'live view' function which generates a map on demand. Sometimes. It's not + very useful.
    • +
  • + LABELANGLE allows you to rotate + node labels to 90,180,270 degrees. Needs truetype font. +
    • +
  • improved data-source picker in editor: host filter
    • +
  • improved data-source picker in editor: option to aggregate data sources
    • +
  • Moved data-source picker changes across into the graph-picker for NODEs too. +
    • +
  • + SPLITPOS keyword to control position + of midpoint in links +
    • +
  • + VIA can be positioned relative to NODEs (like NODEs can) (thanks again to llow) +
    • +
  • Weathermap has a hook in the map viewing page to allow other plugins to add code + there
    • +
  • .htaccess files bundled with Weathermap to restrict direct access to configs and + output
    • +
  • filenames for output are much less guessable now (may break external + references to maps)
    • +
  • You can use 'DUPLEX half' on a link + to make the bandwidth percentage calculate work for half-duplex links +
    • +
  • + ININFOURL / OUTINFOURL, INOVERLIBGRAPH / OUTOVERLIBGRAPH, INNOTES / OUTNOTES, INOVERLIBCAPTION / OUTOVERLIBCAPTION allow you to have + different urls for the in and out side of links (based on idea from llow) +
    • +
  • + OVERLIBGRAPH (and IN/OUT + versions) can take multiple URLs separated by spaces (again from idea by llow) +
    • +
  • debug/warning log output contains the map name, and the debug output is marked + DEBUG
    • +
  • debug log output contains the calling function, file/line number, too. Making + debugging-by-mail easier.
    • +
  • fping: TARGET to do live pings of + devices. See targets.html +
    • +
  • a very basic sample 'skeleton' DS plugin
    • +
  • an additional check-gdbug.php to spot bad GD installs
    • +
  • MRTG DS plugin can do a few new tricks. See TARGET and targets.html +
    • +
+

Changes For This Version (0.94 to 0.941)

+

Fixes

+
    +
  • Added extra code to help discourage browser caching.
    • +
  • Issue with '-' DS names again.
    • +
  • Removed some extra chatty debugging code from poller_output
    • +
+

Changes For This Version (0.93 to 0.94)

+

0.94 was released early, to fix the one small issue caused by files moving around in the + recent Cacti 0.8.7 release. However, there are some nice new features even so - INBWFORMAT has been requested for quite a + while, and so has poller_output support.

+

Changes

+
    +
  • Finally a better tab image, and a red 'active' one too, for the Cacti plugin.
    • +
+

New Features

+
    +
  • + INBWFORMAT and OUTBWFORMAT allow you to format the text + for BWLABEL, same as for COMMENTs +
    • +
  • New cactithold/cactimonitor data source plugin reads data from Cacti's Threshold + plugin. (Original development for this plugin was paid for by Stellar Consulting - + Thanks!)
    • +
  • New LINKSTYLE command allows you + to have one-way (one arrow) links. +
    • +
  • RRD DS can use Cacti's poller_output to get data without running RRDtool at all. + (this also means it can work with the Boost plugin for large installations) See + targets.html for more info on this one. +
    • +
  • Editor - Align horizontal and Align-vertical for links. Calculates link offsets to + make link vertical/horizontal.
    • +
+

Fixes

+
    +
  • "Full Screen Maps" mode in Cacti Plugin was broken by me adding the "View Only First" + mode.
    • +
  • Imagemaps for horiz/vert format legend were wrong in editor (thanks to Alex Moura for + pointing this out)
    • +
  • Changes for compatibility with Cacti 0.8.7's moved config file.
    • +
+

Changes For This Version (0.92 to 0.93)

+

Changes

+
    +
  • The auth realm names for Cacti have been changed to match ReportIt and Aggregate - + easier to tell who does what (Plugin -> Weathermap: View Maps)
    • +
  • Editor warns about older editor-config.php format now
    • +
  • Formatted numbers (Mega, Kilo etc) now can include milli, micro and nano + (m,u,n).
    • +
+

New Features

+
    +
  • weathermap-cacti-plugin.php?action=viewmap&id=mapfilename works as well as a map + number - useful for crosslinks
    • +
  • Warning for duplicate node or link names
    • +
  • unique code for each warning message, and a page to explain it on the website. + Ugh.
    • +
  • warning in editor file-selector so you can tell if the file is read-only
    • +
  • click config filename to edit in editor from Cacti (thanks to streaker69)
    • +
  • cactihost: DS plugin fetches a bunch of other stats from Cacti's DB now, too (like + availability and response times)
    • +
  • Picking Cacti sources from editor has a javascript "live filter" feature now (needs a + little work)
    • +
  • node coordinates are directly editable in the editor now
    • +
  • File picker allows you to use an existing map as a template
    • +
  • Editor now allows you to clone a node with all it's styling intact.
    • +
  • When picking coordinates (new node, move node, move timestamp etc), you can see the + coordinates
    • +
  • Editor toolbar fixed to window, to make it easier to scroll around large maps
    • +
  • RRD Datasource has improved warnings for non-existent DS names
    • +
  • Editor allows you to edit raw text of nodes and links
    • +
  • Editor link in management page (warnesj)
    • +
  • Docs link in management page too (streaker69)
    • +
  • Editor has a better warning for unwriteable files and directory now.
    • +
  • When you come TO the editor from Cacti, the Change File goes BACK to Cacti
    • +
  • "Show Only First" mode in Cacti UI - useful for heirarchies of maps with a + parent.
    • +
  • scale: prefix for RRD datasource - multiply/divide by any value as you read an rrd + datasource
    • +
+

Fixes

+
    +
  • RRD doesn't consider DSes other than the ones you named when finding a valid + line.
    • +
  • editor-generated node names are a bit shorter (and easier to read) now.
    • +
  • keyboard focus switches nicely to the popup dialogs now.
    • +
  • Non-unique IDs in imagemaps, in overlib mode.
    • +
  • + COMMENTPOS 0 doesn't kill + everything anymore +
    • +
  • OVERLIB would behave incorrectly with PHP4 and relatively positioned nodes (Bernd + Ziller)
    • +
  • Better-validating HTML produced
    • +
  • angled bwlabels have the correct imagemap
    • +
  • divide-by-zero error for some (?) PHP versions in poller
    • +
  • the key_hidezero secret setting hides the zero in a gradient in a classic scale + too.
    • +
+

Changes For This Version (0.91 to 0.92)

+

New Features

+
    +
  • + BWSTYLE allows you to align the + BWLABEL boxes with their links. Looks + nice! +
    • +
  • + COMMENTPOS allows you to move + comments, much like BWLABELPOS for + BWLABELs +
    • +
  • The editor works the way you'd expect for defaults now.
    • +
  • The editor does a bunch of clever maths when moving a node that is part of a curved + link to make a sensible result (I like this one).
    • +
  • The editor will let you pick an INFOURL and OVERLIBGRAPH for a NODE from your Cacti graphs (but not a TARGET yet). +
    • +
  • The editor doesn't require an editor-config.php anymore, but if + you do have one, make sure it's based on the editor-config.php-dist in + this version. This file has changed.
    • +
  • Secret SET codes: + key_hidepercent_scalename and key_hidezero_scalename
    + You can set these at the top of the config file, for each scale (change + scalename to the scale name). SET key_hidezero_DEFAULT 1 hides the + 0->0 line if there is one, in a 'classic' style legend for that scale. + SET key_hidepercent_scalename + 1 hides the percentage signs in the 'classic' style legend for that scale. +
    • +
+

Fixes

+
    +
  • + SET in a DEFAULT node or link wasn't + inherited properly. +
    • +
  • weathermap.conf is a simple map again. I accidentally packaged my test map for 0.9 + and 0.91
    • +
  • Any unreadable files in the configs/ directory would kill the editor
    • +
  • One PHP short_tag remained, which upsets some PHP installs (seems to be mainly + Windows)
    • +
+

Changes For This Version (0.9 to 0.91)

+

After all the big changes (below for 0.9), there are a whole bunch of bugs that no-one + spotted in the testing, so this release is mostly a clean-up of those. There are a couple + of small changes for new features, and a bit more diagnostic stuff for installation + problems.

+

New Features

+
    +
  • 'Quiet Mode' Logging - in the Cacti plugin, there is a new setting to make Weathermap + log only errors in the standard 'LOW' logging setting.
    • +
  • Subtractive Aggregation - if one of the clauses in a TARGET line begins with a '-', then that value is + subtracted from the result instead of added. This can be useful to calculate a value that + couldn't be measured directly. For example, Netscreen firewalls don't give per-policy + bandwidth stats, so to find out how much traffic is going to the internet, and how much + to a VPN, you can start with the total interface traffic, and take out the VPN traffic + (which you can measure), to leave the Internet traffic. +
    • +
  • There is a new check.php script, that verifies some basic requirements of + your PHP installation. It's mainly useful during installation, so it's described in the + installation instructions.
    • +
  • A couple of additional variables are available in the 'special string tokens' - + 'inscalekey' and 'outscalekey' store the internal names of the SCALE line that was triggered for the 'in' and + 'out' values of a map object. You can use this to do some things like changing icons + based on a value, without needing to write a plugin yourself. It's pretty obscure, but + could be handy. +
    • +
+

Fixes

+
    +
  • RRD bug with '-' DS names. This was fixed in 0.9pre3, but somehow slipped + through.
    • +
  • ReadConfig doesn't complain about KEYPOS DEFAULT -1 -1 (as written by + WriteConfig) anymore +
    • +
  • The MRTG plugin made some assumptions that broke handling of MRTG html files on + remote systems. It doesn't now.
    • +
  • + NOTES was not fully tested, and broke + cactihost: targets, at least. +
    • +
  • + KILO was broken - fixed now. +
    • +
  • + BWLABELPOS was handled badly by the + editor - it would swap them over +
    • +
+

Changes For This Version (0.82 to 0.9)

+

I've divided the changes up into chunks. Most of the serious work was done in the + Structural Changes section, but there are plenty of things for + everyone. These are brief descriptions - see the Config Reference for the full detail. I've + mentioned the appropriate configuration keywords if there are any.

+

Graphical Changes

+

These tend to be smaller things, but together they make a lot of useful additions.

+

Link comments

+

You can add a comment string which runs down the side of link arrows. This is intended + for use for circuit references, or interface names. There are 4 new directives to make this + happen: INCOMMENT, OUTCOMMENT, COMMENTFONT and COMMENTFONTCOLOR. You must use a TrueType + COMMENTFONT to use this feature, as + none of the other font types allow for rotation of text.

+

Bandwidth Label Positioning

+

You can now move the bandwidth labels (those little boxes) up and down the link arrow. + You set a percentage position with BWLABELPOS.

+

Pixel-Offsets

+

You can make links end at arbitrary positions relative to a node now. Previously you + could use compass-points, now you can also use pixels for the offsets in a NODES line

+

JPEG & GIF Support

+

If your GD library supports it, then Weathermap now understands JPEG and GIF files for + BACKGROUND, ICON and IMAGEOUTPUTFILE.

+

NOTES & OVERLIBCAPTION

+

You can specify a caption string for the 'popup' overlib window now, per-node/link. You + can also have HTML-formatted text in that window, with or without the graph. See + NOTES and OVERLIBCAPTION.

+

Use it with String Tokens to make captions for your nodes, with additional + information.

+

New Legend Styles

+

The new KEYSTYLE directive allows + you to choose between 'classic' and two new styles of Legend. The new styles are neater for + showing gradient scales, or when you have a lot of different bands.

+

Relative Positioning

+

You can position a node relative to another node. This is handy for maintaining big rows + of nodes, where only one needs to be fixed in position now.

+

Structural Changes

+

The internal structure of Weathermap has changed quite a lot in this version. It started + as a few small changes, but each one showed that another was required.

+

Datasource Plugins

+

All the data-reading parts of Weathermap are now in plugins. This is to allow users to + add their own external data sources more easily, without having to change the Weathermap + code. All the previous TARGET strings will + work as before, and I've added a few new ones for 0.9:

+
    +
  • static - if you need to fix a data value, you can do it without an + external text file.
    • +
  • cactihost - read the up/down status of a host in Cacti
    • +
  • gauge - Read RRD values without any special treatment.
    • +
+

The RRD plugin also has some improvements in dealing with error conditions in this + release.

+

There are planned plugins for Cacti (reading directly from the Cact database), Nagios + Host Status, SNMP directly and others.

+

NODE Targets

+

NODEs can have data now. This means you + can have them change colour according to a SCALE, just like a LINK does. Since a NODE only has one value, you can choose which one to + use (of the two that a TARGET provides), + with USEVALUE.

+

Multiple SCALEs

+

Because you probably don't want your nodes to change colour with the same values as your + links, you can now have multiple SCALE + sets too. The default one is DEFAULT, but you can define others and use them with USESCALE in a NODE or LINK section.

+

String Tokens

+

You can embed information from Weathermap, and from your own data, in almost any string + in Weathermap. This allows you to do things like:

+
    +
  • Show percentage CPU usage in a node LABEL
    • +
  • Change which ICON is used depending on + a datasource value +
    • +
  • Add extra "sub-NODEs" around a + NODE, with addional information +
    • +
  • Use generic TARGET, INFOURL, OVERLIBGRAPH lines in the DEFAULT link and + node +
    • +
+

Arbitrary Parameters

+

The new SET directive lets you define new + 'variables' per-NODE, per-LINK or for the whole map. These can be used to + give fine-tuning parameters to the data source plugins, and also as additional data in + String Tokens.

+

Cacti Plugin

+

Most of the Cacti Plugin changes are bugfixes or for more advanced users.

+

Non-Standard Poller Cycle Times

+

If you are using the "<5 minute poller" patch from TheWitness, then you may not want + the time-consuming Weathermap process to run every poller cycle. There is now an option to + choose how often Weathermap redraws it's maps, including 'Never'.

+

Async Map Generation

+

If you choose 'Never' above, then you need some way to redraw. The new + weathermap-cacti-rebuild.php script allows you to run a separate cron job for + Weathermap, but in the environment it would have inside the poller process.

+

Recalculate Now

+

If you have your permissions set up correctly, then you can force the redraw of all maps + from within the Cacti UI, instead of waiting for a poller cycle.

+

Editor

+

There are no new features in the Editor for 0.9, although a few annoying bugs have been + squashed. I have big plans for the editor, but they are a whole project by themselves, so + I've put it to one side. Otherwise 0.9 would never have appeared :-) Now this version is + released, the Editor is one the main focus areas for the next release.

+

Bugfixes

+

There were a lot of bugs fixed along the way. Most were new ones, but a few are things + that existed in 0.82 too:

+
    +
  • Wierd bug in HTML_ImageMap if you have a lot of similarly-named NODEs or + LINKs. +
    • +
  • Floating-point limits in SCALEs work + correctly now. Also, you can specify a 0-0 + SCALE line and it will always take precedence. +
    • +
  • Cacti plugin doesn't assume 'admin' user always exists, and that users are never + deleted.
    • +
  • Cacti plugin's Cycle mode works in IE now.
    • +
  • + KILO was ignored in some places. +
    • +
  • Editor will let you rename nodes now!
    • +
  • Editor deals properly with ' in node labels
    • +
  • Editor deals properly with pathnames containing '\' on Windows.
    • +
  • Editor lets you pick JPG and GIF images too, since we now support them
    • +
  • Close-together nodes don't crash the curve-drawing anymore
    • +
+
+ +
+
+ + diff --git a/docs/pages/cli-reference.html b/docs/pages/cli-reference.html index bfe003da..2b18d0e7 100644 --- a/docs/pages/cli-reference.html +++ b/docs/pages/cli-reference.html @@ -1,117 +1,132 @@ - - - - - PHP Weathermap v0.98a - Command-line option Reference - - - - - - - -
- - - -
-

Command-line options Reference

The unix - man-style specification for weathermap is: - -
- ./weathermap [--config configfile] [--output - pngfile] [--htmloutput htmlfile] [--image-uri - URI] [--debug] [--dumpafter] [--dumpconfig - newconfigfile] [--sizedebug] [--define var=value] [--no-warn={errorcodes} -
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. - -

Options

-

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

- -

--define allows you to define additional internal variables - for this run. It is equivalent to a - SET line in the global - section of the map configuration file.

- -

--nowarn allows you to disable specific warnings by - providing a list of the WMARNxxx codes for them. You shouldn't need to do this, but if you (for example) - have an interface that can physically go above the BANDWIDTH you have set for it, you can use - this to disable the 'clipped to 100%' warning that you would get.

- -

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

- -

--image-uri specifies the URI used in an HTML file - generated. If you are generating HTML in a different directory from the - one the image is created, then weathermap will probably get the <img - src=""> tag wrong. This option allows you to override the contents of - the src attribute, if you know better.

-
-
- + + + + + Command-line reference — Network Weathermap 2.0 + + + + +
+ Network Weathermap 2.0 +

Cacti plugin manual

+
+
+ +
+

Command-line reference

+

The legacy wrapper's accepted options below are taken from its actual option parser. Run + it from the plugin directory inside Cacti; see requirements and + limitations. The default RRDtool path in the wrapper is /usr/bin/rrdtool; + verify it for your installation.

+ 
cd /path/to/cacti/plugins/weathermap
+php weathermap --config configs/example.conf --output /tmp/example.png --htmloutput /tmp/example.html
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
OptionUse
--config=FILERead a map configuration; default weathermap.conf.
--output=FILEChoose the image output path; configured output/default applies when + omitted.
--htmloutput=FILEWrite an accompanying HTML page.
--image-uri=URIOverride the image URI referenced by generated HTML.
--define=NAME=VALUESet a map hint for this run, equivalent to a global SET.
--debug / --uberdebugEnable diagnostics; uberdebug removes normal debug suppression.
--statsPrint collected processing statistics.
--dumpafterDump internal map state for diagnosis; output may be large and include sensitive + configuration.
--dumpconfig=FILESerialize the loaded configuration to another file. Back up first and inspect + changes; do not overwrite the source casually.
--sizedebug / --no-dataSkip live data reading. Both options use the same branch in this wrapper; they + are useful for checking layout without polling sources.
--randomdataGenerate random example readings; not monitoring data.
--bulgeEnable width modulation for the run.
--no-warn=CODE,CODESuppress selected warning codes, for example WMWARNxx. Correct real faults before + suppressing warnings.
--help / --versionShow usage or the wrapper version string. Some legacy wrapper text can lag the + plugin INFO version.
+
+
+

Output and permissions

+

Run under an account with the required read/write access. Configuration may specify + IMAGEOUTPUTFILE, HTMLOUTPUTFILE and HTMLSTYLE; command-line overrides are useful for + isolated tests. Do not run a second periodic rendering job alongside ordinary Cacti polling + without coordinating schedules.

+

HTMLSTYLE static produces an image map with click links. HTMLSTYLE + overlib also emits hover metadata. The integrated Cacti viewer supplies the + JavaScript that displays those previews. The legacy command-line HTML wrapper still + references overlib.js, which is no longer bundled, so its exported page is not + a complete standalone hover viewer. Use the Cacti viewer for supported interactive maps; + changing HTMLSTYLE alone does not make an exported page equivalent.

+
+ +
+
diff --git a/docs/pages/config-reference.html b/docs/pages/config-reference.html index d4aa339e..448df3f3 100644 --- a/docs/pages/config-reference.html +++ b/docs/pages/config-reference.html @@ -1,253 +1,269 @@ - - - - - PHP Weathermap v0.98a - Configuration Reference - - - - - - - -
- - -

Configuration Reference

This page is automatically compiled, and documents all the - configuration directives that are available in PHP Weathermap - v0.98a.

-

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.

-

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

TEMPLATE

-
TEMPLATE - - nodename -
-
-

By default, each new node starts with the same set of properties. You can - change the default properties by defining a node called DEFAULT.

-

You can also use the TEMPLATE keyword to make a node inherit it's settings from - any other node. The node you use must be defined earlier in the config - file than where you use it.

-

You can make template-only nodes that are not visible in the map, by not - including a NODES line in the node. Template nodes can also use templates, to - build up a hierarchy of 'types'.

-

NOTE: The TEMPLATE line should be the first line in the NODE - definition, as it will copy the configuration over the top of anything else you - have already defined for that NODE.

-
-
-

Examples

-
- - NODE Templates in use - with template-only nodes - - 
NODE server
+
+
+  
+  
+  Configuration reference — Network Weathermap 2.0
+  
+
+
+  
+  

+    Network Weathermap 2.0
+    
Cacti plugin manual

+  

+  

+    
+    

+      
Configuration reference

+      
+      

+        
2.0 configuration additions

+        
These settings use the same directives and SET name value hints as older
+        configurations. The lines below are complete examples: choose the value you need, rather
+        than copying several alternatives into the same block. Follow each link for its syntax,
+        defaults and scope.

+        

+          
+            
+            
+              
+                
+                
+              
+              
+                
+                
+              
+              
+                
+                
+              
+              
+                
+                
+              
+              
+                
+                
+              
+              
+                
+                
+              
+            
+          
Example configurationMeaning
COMMENTCURVE 1
COMMENTCURVE 0		Follow the link curve (1, the default), or use straight comment text (0).
+                Applies to a link or LINK DEFAULT. Requires a TrueType comment font.
SET background_sizing image
SET background_sizing fit
SET background_sizing stretch		Use the background image's dimensions, fit it proportionally inside the canvas,
+                or stretch it to fill the canvas. Place this setting in the global section.
SET traffic_pulse 1
SET traffic_pulse 0		Enable (1, the default) or disable (0) the viewer's high-load pulse.
+                Each direction is checked separately at 80% utilisation or above.
LABELOFFSET S60
SET editor_label_position S60		The editor's bottom label preset. Use matching N60, C or S60 values for its
+                top, middle or bottom presets. Raw LABELOFFSET remains available.
Map note metadata
SET editor_note 1		Identify a label-only node as an editable map note. The full entry describes
+                the alignment and escaping hints; Add Note writes these for you.
BANDWIDTH 1000MThe inherited default capacity in both directions when no value is configured.
+                BANDWIDTH itself is existing syntax; explicit map values and templates take precedence.

+        

+        
Complete runnable example combining
+        background sizing, curved comments, pulsing, a node label preset and an editable note.

+      

+      
Reading the syntax

+      
In syntax forms, italic text is a value you supply, | separates
+      alternatives and square brackets mark optional arguments. Do not type these notation marks.
+      Keep modifiers attached to their target: for example, TARGET first.rrd -second.rrd
+      0.5*third.rrd.

+      
This reference retains the core map syntax and adds the 2.0 controls above. The editor
+      exposes common settings; raw configuration supports additional directives.

+      
Directive index

+      

+        
+      

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

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

+          

+        

+      

+      

+        
TEMPLATE

+        

+          TEMPLATE nodename
+        

+        

+          
By
+          default, each new node starts with the same set of properties. You can change the default
+          properties by defining a node called DEFAULT.

+          
You
+          can also use the TEMPLATE keyword to make a node inherit its
+          settings from any other node. The node you use must be defined earlier in the
+          config file than where you use it.

+          
You
+          can make template-only nodes that are not visible in the map, by not including a POSITION line in the node. Template nodes can also use templates, to
+          build up a hierarchy of 'types'.

+          

+          NOTE: The TEMPLATE line should be the first
+          line in the NODE definition, as it will copy the configuration
+          over the top of anything else you have already defined for that NODE.

+        

+        

+          
Examples

+          

+            NODE Templates in use - with template-only nodes
+            
NODE server
+    ICON 48 48 images/objects/Server.png
+    LABELFONT 3
+
+NODE app_server
+    TEMPLATE server
+    LABEL Application server
+    POSITION 200 150
             

-    

-  

-  

-    
Change History

-    

-      
0.96

-      
Added template support
-        

-    

-  

-

-
-        

-  
POSITION

-  
POSITION
-
-        x-coord
-
-        y-coord
-    

-  
POSITION
-
-        nodename
-
-        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. 
 
- 
Optionally, you can also specify another node that the coordinates are 
- relative to. This allows you to have 'sub-nodes' that follow a master node 
- around as you alter the map. Relative nodes can be relative to other relative 
- nodes, as long as the node at the end of the chain is not relatively 
- positioned! 
 
-  

-  

-    
Examples

-    

-      
-        Example of a 'sub-node', that will be 20 pixels above the main
-        node, wherever that gets moved to. It is used to show additional information
-        about the main node.
-      
-      
+          

+        

+        

+          
Change History

+          

+            
0.96

+            
Added template support

+          

+        

+      

+      

+        
POSITION

+        

+          POSITION nodename anglerdistance
+        

+        
Relative polar example: POSITION core 90r100 places the node 100 map units
+        from core at 90 degrees. The reference node must resolve to a real position.

+        

+          POSITION x-coord y-coord
+        

+        

+          POSITION nodename 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.

+          

+          Optionally, you can also specify another node that the coordinates are relative to. This
+          allows you to have 'sub-nodes' that follow a master node around as you alter the map.
+          Relative nodes can be relative to other relative nodes, as long as the node at the end of
+          the chain is not relatively positioned!

+        

+        

+          
Examples

+          

+            Example of a 'sub-node', that will be 20 pixels above the main node,
+            wherever that gets moved to. It is used to show additional information about the main
+            node.
+            
 NODE main_node
     POSITION 200 320
     LABEL MAIN
@@ -256,784 +272,818 @@ 
Examples

     POSITION main_node 0 -20
     LABEL {nodes:main_node:invalue}
             

-    

-  

-  

-    
Change History

-    

-      
0.9

-      
Add relative position from other nodes.
-        

-    

-  

-

-
-        

-  
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. 
 
- 
The text for the label can contain 
- special tokens to show map data. 
 
- 
This is drawn using the font specified by LABELFONT in the colours specified 
- by LABELFONTCOLOR, LABELFONTSHADOWCOLOR, LABELBGCOLOR and LABELOUTLINECOLOR. 
 
-  

-  

-    
Change History

-    

-      
0.9

-      
Added 'special token' support.
-        

-    

-  

-

-
-        

-  
TARGET

-  
TARGET
-
-        targetspec
-    

-  
TARGET
-
-        targetspec
-
-        targetspec
-    

-  
TARGET
-
-        targetspec
-
-        -
-
-        targetspec
-    

-  
TARGET
-
-        targetspec
-
-        n*
-
-        targetspec
-    

-  
TARGET "targetspec"
-    

-  

- 
Specifies where to look for the current "throughput" information for this 
- NODE. You can also specify multiple targets, which will then be added together 
- to make the aggregate result which is then displayed. Specify the targets on one 
- TARGET line, seperated with a space. If a targetspec starts with a '-', then 
- it's value will be subtracted from the final result instead. 
 
- 
Also, if a targetspec starts with a number, then a *, then it's used a 
- scaling factor on the result. You can do basic maths with this, especially if 
- you remember that multiplying by a number below 1 is the same as dividing by 1 
- divided by that number (0.5* is the same as divide by 2). 
 
- 
For both the '-' and '*' options, 
- there must be no spaces between any modifiers and the actual target 
- string after it. 
 
- 
It's important to note, especially for NODEs, that the value that is used 
- does not have to be bandwidth. You can use data for temperature, session-counts, 
- CPU usage or anything else you can get data for. 
 
- 
The actual contents of the 
- targetspec depend on the data source plugins that are available. 
- The standard plugins are documented here. 
 
- 
To help with filenames that can contain spaces, or for the external script 
- data source, you can enclose the entire targetspec in double-quotes (") to show 
- that it is a single targetspec. 
- The quotes must be around the whole targetspec, including any 
- prefixes. 
 
-  

-  

-    
Examples

-    

-      
-        Using multiple data sources for one link
-      
-      
TARGET link1a.rrd link1b.rrd
+          

+        

+        

+          
Change History

+          

+            
0.9

+            
Add relative position from other nodes.

+          

+        

+      

+      

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

+          
The
+          text for the label can contain special tokens to show
+          map data.

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

+        

+        

+          
Change History

+          

+            
0.9

+            
Added 'special token' support.

+          

+        

+      

+      

+        
TARGET

+        

+          TARGET targetspec
+        

+        

+          TARGET targetspec targetspec
+        

+        

+          TARGET targetspec -targetspec
+        

+        

+          TARGET targetspec n*targetspec
+        

+        

+          TARGET "targetspec"
+        

+        

+          

+          Specifies where to look for the current "throughput" information for this NODE. You can also specify multiple targets, which will then be added
+          together to make the aggregate result which is then displayed. Specify the targets on one
+          TARGET line, separated with a space. If a targetspec starts
+          with a '-', then its value will be subtracted from the final result instead.

+          
Also,
+          if a targetspec starts with a number, then a *, then it's used a scaling factor on the
+          result. You can do basic maths with this, especially if you remember that multiplying by
+          a number below 1 is the same as dividing by 1 divided by that number (0.5* is the same as
+          divide by 2).

+          
For
+          both the '-' and '*' options, there must be no spaces between any modifiers and
+          the actual target string after it.

+          
It's
+          important to note, especially for NODEs, that the value that is
+          used does not have to be bandwidth. You can use data for temperature, session-counts, CPU
+          usage or anything else you can get data for.

+          
The
+          actual contents of the targetspec depend on the data source plugins that are
+          available. The standard plugins are documented here.

+          
To
+          help with filenames that can contain spaces, or for the external script data source, you
+          can enclose the entire targetspec in double-quotes (") to show that it is a single
+          targetspec. The quotes must be around the whole targetspec, including any
+          prefixes.

+        

+        

+          
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:-
+          

+          

+            Taking the input from one file, and output from another
+            
TARGET poot.rrd:-:DS1 poot2.rrd:DS0:-
             

-    

-  

-  

-    
Change History

-    

-      
0.96

-      
Added quotes option for targets with spaces.
-        

-      
0.96

-      
Added scale factors for all datasources.
-        

-      
0.91

-      
Added 'negative' datasources.
-        

-      
0.9

-      
Added plugin data sources, node targets, and added new
-        plugins.
-        

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

-    

-  

-

-
-        

-  
USESCALE

-  
USESCALE
-
-        scalename
-    

-  
USESCALE
-
-        scalename
-
-        {in,out}
-    

-  

- 
Specify which SCALE to use to decide the colour of this node. 
 
- 
After the percentage usage is calculated (using BANDWIDTH/MAXVALUE and data 
- from the TARGET line), the colour is decided by looking up the percentage 
- against this SCALE. If there is no USESCALE line, then the default scale is 
- used. 
 
- 
If you also specify 'absolute', then no percentage calculation is performed. 
- The raw values from the TARGET line are just looked up in the named SCALE. 
 
- 
For nodes, you can also specify a scalename of 'none'. This stops the node's 
- colour from changing at all. This is useful if you want to use the TARGET line 
- to fetch data that is used in the LABEL or ICON of the node, for example, 
- without changing the colour of the node itself. 
 
- 
You can also change the colour of the ICON associated with a NODE according 
- to a different SCALE, by using USEICONSCALE. 
 
-  

-  

-    
Change History

-    

-      
0.97

-      
Added absolute scale support.
-        

-      
0.95

-      
Added USEICONSCALE.
-        

-      
0.9

-      
Added named scales and USESCALE.
-        

-    

-  

-

-
-        

-  
MAXVALUE

-  
MAXVALUE
-
-        max-value
-    

-  
MAXVALUE
-
-        max-in-value
-
-        max-out-value
-    

-  

- 
Specifies the maximum value(s) for the node, in the same way that BANDWIDTH 
- does for a LINK. These are used to calculate the percentage usage value, which 
- in turn is used to decide the NODE's colour, if it has a TARGET defined. 
 
- 
The default value is 100, which has the effect of not changing the input 
- value ( (n/100)*100 = n ). 
 
-  

-  

-    
Change History

-    

-      
0.9

-      
Added TARGET and MAXVALUE for nodes.
-        

-    

-  

-

-
-        

-  
ICON

-  
ICON
-
-        iconimagefile
-    

-  
ICON
-
-        maxwidth
-
-        maxheight
-
-        iconimagefile
-    

-  
ICON none
-    

-  

- 
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, JPEG or GIF format. Alpha-transparency within 
- the icon should be honoured by Weathermap for PNG icons, to create irregular 
- shapes. 
 
- 
If you specify the word 'none' as the icon filename, then no icon is used. 
- This is useful if you have specified an ICON in the DEFAULT NODE, and want to 
- override that for a few special cases. 
 
- 
There are some special icon filenames that can be used to generate an icon 
- image without using an external file. These all 
- require you to specify a maxwidth and 
- maxheight which are then used as the size of the icon. The 'magic 
- filenames' are: 
-
- 
  • 'box' - to produce a square cornered box.
  • 'rbox' 
- - to produce a round-cornered box
  • 'round' 
- - to produce a circle or ellipse.
    •  
-
- 
  • 'inpie' & 'outpie' 
- - to produce a pie-chart of either the in or out value relative to it's 
- maximum. The colouring options on this are likely to change in a future 
- version.
    •  
-
- 
  • 'nink' 
- - to produce a circular 'yin-yang'-style symbol, with each half showing the 
- in and out values. The colouring options on this are likely to change in a 
- future version.
    •  
- 
The colours for these "artificial icons" are specified using the 
- AICONFILLCOLOR and AICONOUTLINECOLOR keywords. 
 
- 
The second form allows you to specify a maximum width and height for the 
- icon. If the PNG file that you specify is bigger or smaller than this size, then 
- it is automatically scaled up (or down) in proportion, so that it fits into a 
- box of the size you specify. 
 
- 
The size of the icon image is used by LABELOFFSET to decided how far to move 
- the label, if you use compass-point offsets. 
 
- 
The text for the filename can contain 
- special tokens to select an icon based on 
- map data. 
 
- 
You can adjust the colour of the icon according to a SCALE, by using 
- USEICONSCALE, if you are using the PHP GD library (the function required is not 
- present in the main GD library). 
 
-  

-  

-    
Change History

-    

-      
0.96

-      
Added inpie, outpie and nink.
-        

-      
0.95

-      
Added Artificial Icon support - round, rbox and box.
-        

-      
0.95

-      
Added Icon colourising support.
-        

-      
0.9

-      
Added 'special token' support.
-        

-      
0.9

-      
Added JPEG and GIF support.
-        

-      
0.9

-      
Added special icon 'none', and automatic scaling.
-        

-    

-  

-

-
-        

-  
USEICONSCALE

-  
USEICONSCALE
-
-        scalename
-    

-  
USEICONSCALE
-
-        scalename
-
-        {in,out}
-    

-  

- 
Specify which SCALE to use to decide the colour of the icon for this node. 
 
- 
After the percentage usage is calculated (using BANDWIDTH/MAXVALUE and data 
- from the TARGET line), the colour is decided by looking up the percentage 
- against this SCALE. If there is no USEICONSCALE line, then no scale is used, and 
- the icon colour does not change. 
 
- 
Hint: This facility works best when you start with greyscale images. 
 
- 
NOTE: Prior to 0.97, Icon colourising used the PHP 
- imagefilter() function. This function is 
- only available in the version of GD that is bundled with PHP, and not 
- with the official GD library. Several popular operating systems (e.g. 
- Debian/Ubuntu) use the official GD library rather than the bundled PHP library. 
- If you know that you 
- do have the imagefilter function, and you prefer the 'old-style' 
- coloring, then you can add 
- SET use_imagefilter 1 in the top section of your map config file, to use 
- imagefilter instead. 
 
-  

-  

-    
Change History

-    

-      
0.97

-      
Removed dependency on imagefilter
-        

-      
0.95

-      
Added USEICONSCALE.
-        

-    

-  

-

-
-        

-  
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. 
 
- 
 
-  
-
- 
The compass points, relative to the node's bounding-box.. 
 
- 
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
-        

-    

-  

-

-
-        

-  
LABELANGLE

-  
LABELANGLE
-
-        angle
-    

-  

- 
Specifies a rotation angle of the label for a node. Allowed angles are 0, 90, 
- 180 and 270 degrees. The rotation is around the centre of the label, after any 
- LABELOFFSET has been applied. 
 
- 
The LABELFONT 
- must be a TrueType font for angles other than 0 (the default) as these 
- are the only font type to support rotating text. 
 
- 
 
-  
-
- 
Rotated label, using LABELANGLE 90 and LABELOFFSET E
 
- 
 
-  

-  

-    
Change History

-    

-      
0.95

-      
Added LABELANGLE.
-        

-    

-  

-

-
-        

-  
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. 
 
- 
 
- The built-in GD fonts. 
 
-  

-  

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

-  
AICONOUTLINECOLOR
-
-        red
-
-        green
-
-        blue
-    

-  
AICONFILLCOLOR
-
-        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, AICONFILLCOLOR and AICONOUTLINECOLOR 
- have an additional 
- option - 'none' 
- - which stops that element of the LABEL being drawn. LABELFONTSHADOWCOLOR 
- defaults to 'none'. 
 
- 
LABELFONTCOLOR has an additional option 'contrast', which will select either 
- black or white depending on the current LABELBGCOLOR. This is especially useful 
- if you are using a SCALE to change the colour of your NODE LABELs. 
 
- 
AICONOUTLINECOLOR and AICONFILLCOLOR are used to colour an 'artificial ICON' 
- if one is defined for this node. To allow the artifical icon to 
- also follow the colour of the LABELBGCOLOR when you are using a SCALE, 
- you can also specify 'copy' as the colour for AICONFILLCOLOR. See ICON for more 
- about artificial icons. 
 
-  

-  

-    
Change History

-    

-      
0.98

-      
Added 'none' for AICONFILLCOLOR.
-        

-      
0.95

-      
Added 'contrast' and 'copy' options.
-        

-      
0.95

-      
Added AICONFILLCOLOR and AICONOUTLINECOLOR.
-        

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

-  
OVERLIBGRAPH
-
-        url
-
-        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. 
 
- 
You can also specify more than one url, in which case the images are 
- 'stacked' one after another in the popup box. 
 
- 
If a NOTES line is also specified for a node, then the image(s) specified 
- here appears with the NOTES text underneath it. 
 
- 
You can influence how Weathermap positions the popup box, using the 
- OVERLIBWIDTH and OVERLIBHEIGHT keywords. 
 
-  

-  

-    
Examples

-    

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

+        

+        

+          
Change History

+          

+            
0.96

+            
Added quotes option for targets with spaces.

+            
0.96

+            
Added scale factors for all datasources.

+            
0.91

+            
Added 'negative' datasources.

+            
0.9

+            
Added plugin data sources, node targets, and added new plugins.

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

+          

+        

+      

+      

+        
USESCALE

+        

+          USESCALE scalename [in|out] [absolute|percent]
+        

+        
Square brackets mark optional arguments; do not type the brackets. For example,
+        USESCALE temperature in absolute selects the inbound raw value instead of a
+        percentage.

+        

+          USESCALE scalename
+        

+        

+          USESCALE scalename {in,out}
+        

+        

+          

+          Specify which SCALE to use to decide the colour of this
+          node.

+          
After
+          the percentage usage is calculated (using BANDWIDTH/MAXVALUE and data from the TARGET line), the colour is decided by looking up the percentage
+          against this SCALE. If there is no USESCALE line, then the default scale is used.

+          
If you
+          also specify 'absolute', then no percentage calculation is performed. The raw values from
+          the TARGET line are just looked up in the named SCALE.

+          
For
+          nodes, you can also specify a scalename of 'none'. This stops the node's colour from
+          changing at all. This is useful if you want to use the TARGET
+          line to fetch data that is used in the LABEL or ICON of the node, for example, without changing the colour of the node
+          itself.

+          
You
+          can also change the colour of the ICON associated with a
+          NODE according to a different SCALE,
+          by using USEICONSCALE.

+        

+        

+          
Change History

+          

+            
0.97

+            
Added absolute scale support.

+            
0.95

+            
Added USEICONSCALE.

+            
0.9

+            
Added named scales and USESCALE.

+          

+        

+      

+      

+        
MAXVALUE

+        

+          MAXVALUE max-value
+        

+        

+          MAXVALUE max-in-value max-out-value
+        

+        

+          

+          Specifies the maximum value(s) for the node, in the same way that BANDWIDTH does for a LINK. These are used
+          to calculate the percentage usage value, which in turn is used to decide the NODE's colour, if it has a TARGET
+          defined.

+          
The
+          default value is 100, which has the effect of not changing the input value ( (n/100)*100
+          = n ).

+        

+        

+          
Change History

+          

+            
0.9

+            
Added TARGET and MAXVALUE for nodes.

+          

+        

+      

+      

+        
ICON

+        

+          ICON iconimagefile
+        

+        

+          ICON maxwidth maxheight iconimagefile
+        

+        

+          ICON none
+        

+        

+          

+          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, JPEG or GIF format. Alpha-transparency within the icon should
+          be honoured by Weathermap for PNG icons, to create irregular shapes.

+          
If you
+          specify the word 'none' as the icon filename, then no icon is used. This is useful if you
+          have specified an ICON in the DEFAULT NODE, and want to override that for a few special cases.

+          
There
+          are some special icon filenames that can be used to generate an icon image without using
+          an external file. These all require you to specify a maxwidth and
+          maxheight which are then used as the size of the icon. The 'magic filenames'
+          are:

+          
    
+            
  • 'box' - to produce a square cornered box.
    • 
+            
  • 'rbox' - to produce a round-cornered box
    • 
+            
  • 'round' - to produce a circle or ellipse.
    • 
+            
  • 'inpie' & 'outpie' - to produce a pie-chart of either the in or out value relative
+            to it's maximum. Use the artificial-icon colour directives below.
    • 
+            
  • 'nink' - to produce a circular 'yin-yang'-style symbol, with each half showing the
+            in and out values. Use the artificial-icon colour directives below.
    • 
+          
The colours for these "artificial icons" are specified using the AICONFILLCOLOR and AICONOUTLINECOLOR
+          keywords.
+
+          
The
+          second form allows you to specify a maximum width and height for the icon. If the PNG
+          file that you specify is bigger or smaller than this size, then it is automatically
+          scaled up (or down) in proportion, so that it fits into a box of the size you
+          specify.

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

+          
The
+          text for the filename can contain special tokens to
+          select an icon based on map data.

+          
You
+          can adjust the colour of the icon according to a SCALE, by
+          using USEICONSCALE, if you are using the PHP GD library
+          (the function required is not present in the main GD library).

+        

+        

+          
Change History

+          

+            
0.96

+            
Added inpie, outpie and nink.

+            
0.95

+            
Added Artificial Icon support - round, rbox and box.

+            
0.95

+            
Added Icon colourising support.

+            
0.9

+            
Added 'special token' support.

+            
0.9

+            
Added JPEG and GIF support.

+            
0.9

+            
Added special icon 'none', and automatic scaling.

+          

+        

+      

+      

+        
USEICONSCALE

+        

+          USEICONSCALE scalename [in|out] [absolute|percent]
+        

+        
Square brackets mark optional arguments; do not type the brackets. For example,
+        USEICONSCALE temperature in absolute selects the inbound raw value instead of
+        a percentage.

+        

+          USEICONSCALE scalename
+        

+        

+          USEICONSCALE scalename {in,out}
+        

+        

+          

+          Specify which SCALE to use to decide the colour of the icon
+          for this node.

+          
After
+          the percentage usage is calculated (using BANDWIDTH/MAXVALUE and data from the TARGET line), the colour is decided by looking up the percentage
+          against this SCALE. If there is no USEICONSCALE line, then no scale is used, and the icon colour
+          does not change.

+          
Hint:
+          This facility works best when you start with greyscale images.

+          

+          NOTE: Prior to 0.97, Icon colourising used the PHP
+          imagefilter() function. This function is only available in the
+          version of GD that is bundled with PHP, and not with the official GD library. Several
+          popular operating systems (e.g. Debian/Ubuntu) use the official GD library rather than
+          the bundled PHP library. If you know that you do have the imagefilter function,
+          and you prefer the 'old-style' coloring, then you can add SET use_imagefilter 1 in the top section of your map config file,
+          to use imagefilter instead.

+        

+        

+          
Change History

+          

+            
0.97

+            
Removed dependency on imagefilter

+            
0.95

+            
Added USEICONSCALE.

+          

+        

+      

+      

+        
LABELOFFSET

+        

+          LABELOFFSET compass-pointdistance
+        

+        

+          LABELOFFSET anglerdistance
+        

+        
Examples: LABELOFFSET N20 adds distance to a compass offset;
+        LABELOFFSET 90r30 uses a polar offset. Do not insert a space inside either
+        combined value.

+        

+          LABELOFFSET compass-point
+        

+        

+          LABELOFFSET x-offset y-offset
+        

+        

+          

+            +
+            

+              Raw LABELOFFSET N, C and S. The editor presets additionally use editor_label_position
+              to place the label within the icon. Complete runnable configuration.
+            

+          

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

+          

+          compass points example

+          The compass points, relative to the node's bounding-box..

+          
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

+          

+        

+      

+      

+        
SET editor_label_position

+        
SET editor_label_position N60|C|S60

+        

+          
Records the editor's Display name position preset for a node: N60 is
+          Top, C is Middle, and S60 is Bottom. Use it together with an
+          identical LABELOFFSET value.

+          
Default: no preset hint. Existing raw LABELOFFSET behaviour is kept.
+          When the two values match a supported preset, the label is positioned within the icon's
+          available space. Without a matching hint, the offset uses the ordinary raw calculation.

+          
The hint affects the label, not the node's POSITION. Prefer the node dialog's
+          Display name position control; use raw LABELOFFSET for other offsets. The
+          node properties guide shows the control.

+        

+        

+          
Examples

+          
NODE router
+    LABEL Core router
+    ICON 72 72 images/objects/cisco-router.png
+    POSITION 120 100
+    LABELOFFSET S60
+    SET editor_label_position S60

+        

+        

+          
Change History

+          

+            
2.0
Added editor Top, Middle and Bottom presets with matching node hints. LABELOFFSET is older syntax.

+          

+        

+      

+      

+        
Map notes: editor_note hints

+        
SET editor_note 1

+        
SET editor_note_escaped 1

+        
SET editor_note_align left|centre|right

+        

+          
A visible map note is a label-only NODE, identified by
+          SET editor_note 1. There is no new NOTE directive; the older
+          NOTES directive supplies popup text.

+          
Defaults: a node is not a map note unless editor_note is set to 1;
+          note alignment is left when omitted. Use centre or
+          right to align shorter lines within a multiline note. Alignment does not
+          change its POSITION.

+          
editor_note_escaped 1 tells the renderer to decode the editor's LABEL
+          escaping: \n starts a new line and \\ represents a literal
+          backslash. The editor writes it when saving a note. Without this hint, older label
+          handling is retained.

+          
Use Add Note to create the complete node, including its font, text colour and
+          transparent background. Use a readable TrueType font for sharp text. If NODE DEFAULT
+          defines an icon or other custom styles, the note must override those inherited values;
+          keep the complete block written by the editor. See map
+          notes and the runnable example.

+          
The raw alignment spelling is centre. This differs from the existing
+          COMMENTSTYLE center setting for link comments.

+        

+        

+          
Examples

+          
FONTDEFINE 100 docs/example/Vera.ttf 10
+
+NODE site_note
+    LABEL Example site\nTraffic overview
+    LABELFONT 100
+    LABELBGCOLOR none
+    LABELOUTLINECOLOR none
+    LABELFONTSHADOWCOLOR none
+    POSITION 330 240
+    SET editor_note 1
+    SET editor_note_escaped 1
+    SET editor_note_align centre

+        

+        

+          
Change History

+          

+            
2.0
Added editable map notes, alignment hints and escaped multiline text.

+          

+        

+      

+      

+        
LABELANGLE

+        

+          LABELANGLE angle
+        

+        

+          

+          Specifies a rotation angle of the label for a node. Allowed angles are 0, 90, 180 and 270
+          degrees. The rotation is around the centre of the label, after any LABELOFFSET has been applied.

+          
The
+          LABELFONT must be a TrueType font for angles other
+          than 0 (the default) as these are the only font type to support rotating text.

+          

+            +
+            

+              Rotated label, using LABELANGLE 90 and
+              LABELOFFSET E
+            

+          

+        

+        

+          
Change History

+          

+            
0.95

+            
Added LABELANGLE.

+          

+        

+      

+      

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

+          

+          font sizes exampleThe built-in
+          GD fonts.

+        

+        

+          
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
+        

+        

+          AICONOUTLINECOLOR red green blue
+        

+        

+          AICONFILLCOLOR 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, AICONFILLCOLOR and AICONOUTLINECOLOR have
+          an additional option - 'none' - which stops that element of the LABEL being drawn. LABELFONTSHADOWCOLOR
+          defaults to 'none'.

+          

+          LABELFONTCOLOR has an additional option 'contrast', which will
+          select either black or white depending on the current LABELBGCOLOR. This is especially useful if you are using a SCALE to change the colour of your NODE
+          LABELs.

+          

+          AICONOUTLINECOLOR and AICONFILLCOLOR are used to colour an 'artificial ICON' if one is defined for this node. To allow the artifical icon to
+          also follow the colour of the LABELBGCOLOR when you
+          are using a SCALE, you can also specify 'copy' as the colour
+          for AICONFILLCOLOR. See ICON for more
+          about artificial icons.

+        

+        

+          
Change History

+          

+            
0.98

+            
Added 'none' for AICONFILLCOLOR.

+            
0.95

+            
Added 'contrast' and 'copy' options.

+            
0.95

+            
Added AICONFILLCOLOR and AICONOUTLINECOLOR.

+            
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
+        

+        

+          OVERLIBGRAPH url 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.

+          
You
+          can also specify more than one url, in which case the images are 'stacked' one after
+          another in the popup box.

+          
If a
+          NOTES line is also specified for a node, then the image(s)
+          specified here appears with the NOTES text underneath it.

+          
You
+          can influence how Weathermap positions the popup box, using the OVERLIBWIDTH and OVERLIBHEIGHT
+          keywords.

+        

+        

+          
Examples

+          

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

-    

-  

-  

-    
Change History

-    

-      
0.95

-      
Added multiple URL support
-        

-    

-  

-

-
-        

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

-    

-  

-

-
-        

-  
OVERLIBCAPTION

-  
OVERLIBCAPTION
-
-        caption text
-    

-  

- 
Specify the caption used for the popup HTML 'window' if you have also 
- specified an OVERLIBGRAPH line. By default, this is the name of the NODE. 
 
- 
The text for the caption can contain 
- special tokens to show map data. 
 
-  

-  

-    
Change History

-    

-      
0.9

-      
Originally added OVERLIBCAPTION.
-        

-    

-  

-

-
-        

-  
NOTES

-  
NOTES
-
-        notes text
-    

-  

- 
Specifies the text or HTML notes for a node. 
 
- 
The 
- notes text appears in a popup box when the user hovers their mouse over 
- the node. If an OVERLIBGRAPH is specified too, then the text appears below the 
- graph. 
 
- 
The map HTMLSTYLE must be set to 'overlib' to enable any of the mouse-hover 
- functionality. 
 
-  

-  

-    
Change History

-    

-      
0.9

-      
Originally added NOTES.
-        

-    

-  

-

-
-        

-  
SET

-  
SET
-
-        hintname
-
-        hintvalue
-    

-  

- 
Specifies a value for a hint variable. 
 
- 
Hint Variables allow the user to pass settings to the internals of Weathermap 
- that wouldn't normally need to be changed, or that aren't part of the core 
- Weathermap application. Examples are: small rendering changes, parameters for 
- datasources plugins and similar. 
 
- 
Hint Variables are either Global for the map, or assigned to a specific link 
- or node. 
 
- 
There is more about Hint Variables in the 
- Advanced Topics section. 
 
-  

-  

-    
Change History

-    

-      
0.9

-      
Originally added SET.
-        

-    

-  

-

-
-        

-  
ZORDER

-  
ZORDER
-
-        z-coord
-    

-  

- 
Specifies the order in which to draw this item on the map. 
 
- 
By default, all nodes are drawn above all links. There are some situations 
- where you might like to change this, for example if you use a NODE as a 
- background image, and you want links to show in front of that image. 
 
- 
By default, all nodes have a Z coordinate of 600, and all links have 300. The 
- map legend is at 1000, which cannot be changed (you can move everything else 
- above it, if you like, of course). Items are drawn from lowest Z up to highest 
- Z, so if you want a particular node to appear underneath the default links, you 
- can use 'ZORDER 250' to do that. 
- 
 
-  

-  

-    
Change History

-    

-      
0.96

-      
Added Z-ordering support.
-        

-    

-  

-

-    
-
-    
-        

-  
-  
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 without an OVERLIBCAPTION, 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. 
 
-  

-

-
-        

-  
-  
TEMPLATE
-
-        linkname
-    

-  

- 
By default, each new link starts with the same set of properties. You can 
- change the default properties by defining a link called DEFAULT. 
 
- 
You can also use the TEMPLATE keyword to make a link inherit it's settings from 
- any other link. The link you use must be defined earlier in the config 
- file than where you use it. 
 
- 
You can make template-only links that are not visible in the map, by not 
- including a NODES line in the link. Template links can also use templates, to 
- build up a hierarchy of 'types'. 
 
- 
NOTE: The TEMPLATE line should be the first line in the LINK 
- definition, as it will copy the configuration over the top of anything else you 
- have already defined for that LINK. 
 
-  

-  

-    
Examples

-    

-      
-        LINK Templates in use - with template-only links
-      
-      
LINK bigpipe
+          

+        

+        

+          
Change History

+          

+            
0.95

+            
Added multiple URL support

+          

+        

+      

+      

+        
OVERLIBWIDTH

+        

+          OVERLIBWIDTH imagewidth
+        

+        

+          

+          Specify the width, in pixels of the graph image referred to by OVERLIBGRAPH line.

+          
These legacy size hints affect popup placement. Current viewers also fit previews to
+          the available viewport. To change the graph image itself, adjust its graph_image.php URL
+          or hover defaults; these directives do not request a larger Cacti graph.

+        

+        

+          
Change History

+          

+            
0.7

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

+          

+        

+      

+      

+        
OVERLIBHEIGHT

+        

+          OVERLIBHEIGHT imageheight
+        

+        

+          

+          Specify the height, in pixels of the graph image referred to by OVERLIBGRAPH line.

+          
These legacy size hints affect popup placement. Current viewers also fit previews to
+          the available viewport. To change the graph image itself, adjust its graph_image.php URL
+          or hover defaults; these directives do not request a larger Cacti graph.

+        

+        

+          
Change History

+          

+            
0.7

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

+          

+        

+      

+      

+        
OVERLIBCAPTION

+        

+          OVERLIBCAPTION caption text
+        

+        

+          

+          Specify the caption used for the popup HTML 'window' if you have also specified an
+          OVERLIBGRAPH line. By default, this is the name of the
+          NODE.

+          
The
+          text for the caption can contain special tokens to
+          show map data.

+        

+        

+          
Change History

+          

+            
0.9

+            
Originally added OVERLIBCAPTION.

+          

+        

+      

+      

+        
NOTES

+        

+          NOTES notes text
+        

+        

+          

+          Specifies the text or HTML notes for a node.

+          
The
+          notes text appears in a popup box when the user hovers their mouse over the
+          node. If an OVERLIBGRAPH is specified too, then the text
+          appears below the graph.

+          
The
+          map HTMLSTYLE must be set to 'overlib' to enable any of
+          the mouse-hover functionality.

+        

+        

+          
Change History

+          

+            
0.9

+            
Originally added NOTES.

+          

+        

+      

+      

+        
SET

+        

+          SET hintname hintvalue
+        

+        

+          
Stores hintvalue under hintname on this node. A datasource can read
+          it as a parameter, or a string token can use it in a label or URL. Node hints belong
+          inside the NODE block; map-wide hints go before the first NODE or LINK.

+          
See global SET for the shared hint-variable explanation
+          and advanced hint usage for more examples.

+        

+        

+          
Change History

+          

+            
0.9

+            
Originally added SET.

+          

+        

+      

+      

+        
ZORDER

+        

+          ZORDER z-coord
+        

+        

+          

+          Specifies the order in which to draw this item on the map.

+          
By
+          default, all nodes are drawn above all links. There are some situations where you might
+          like to change this, for example if you use a NODE as a
+          background image, and you want links to show in front of that image.

+          
By
+          default, all nodes have a Z coordinate of 600, and all links have 300. The map legend is
+          at 1000, which cannot be changed (you can move everything else above it, if you like, of
+          course). Items are drawn from lowest Z up to highest Z, so if you want a particular node
+          to appear underneath the default links, you can use 'ZORDER
+          250' to do that.

+        

+        

+          
Change History

+          

+            
0.96

+            
Added Z-ordering support.

+          

+        

+      

+      
+      

+        
+        

+          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 without an OVERLIBCAPTION, 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.

+        

+      

+      

+        
+        

+          TEMPLATE linkname
+        

+        

+          
By
+          default, each new link starts with the same set of properties. You can change the default
+          properties by defining a link called DEFAULT.

+          
You
+          can also use the TEMPLATE keyword to make a link inherit its
+          settings from any other link. The link you use must be defined earlier in the
+          config file than where you use it.

+          
You
+          can make template-only links that are not visible in the map, by not including a NODES line in the link. Template links can also use templates, to build
+          up a hierarchy of 'types'.

+          

+          NOTE: The TEMPLATE line should be the first
+          line in the LINK definition, as it will copy the configuration
+          over the top of anything else you have already defined for that LINK.

+        

+        

+          
Examples

+          

+            LINK Templates in use - with template-only links
+            
LINK bigpipe
     WIDTH 8
     ARROWSTYLE classic
 
@@ -1046,2138 +1096,1976 @@ 
Examples

     TEMPLATE bigpipe
     NODES rtr1 rtr2
             

-    

-  

-  

-    
Change History

-    

-      
0.96

-      
Added template support
-        

-    

-  

-

-
-        

-  
-  
NODES
-
-        nodename{:compassoffset}
-
-        nodename{:compassoffset}
-    

-  
NODES
-
-        nodename{:compassoffset}{percentage}
-
-        nodename{:compassoffset}{percentage}
-    

-  
NODES
-
-        nodename{:xoffset:yoffset}
-
-        nodename{:xoffset:yoffset}
-    

-  
NODES
-
-        nodename{:angle}r{radius}
-
-        nodename{:angle}r{radius}
-    

-  

- 
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 can be numeric values, to indicate the 
- relative position in pixels from the centre of the node, or are named after 
- compass-points: N,S,E,W,NE,NE,SE,SW. The compass points describe locations 
- around the edge of the box that contains the node. You can also specify a 
- percentage after the compass point, to be a certain proportion of the way from 
- the centre. The percentage must be two digits. Finally, you can also use polar 
- coordinates to specify offsets, with an angle in degrees and a radius in pixels 
- from the centre point. 0 degrees is straight up. 
- 
 
- 
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'. 
 
- 
 
-  
-
- 
The compass points, relative to the node's bounding-box.. 
 
- 
 
-  
-
- 
The default - node centre to node centre. 
 
- 
 
-  
-
- 
Using compass points - NODES node1:E node2:W 
 
- 
 
-  
-
- 
Using compass points with percentages - 
- NODES node1:E50 node2:W50 
 
- 
 
-  
-
- 
Using polar offsets - NODES node1:45r20 node2:225r20 
 
- 
 
-  
-
- 
Using offsets to make parallel links- 
- NODES node1:NE50 node2:NW50 for one link and 
- NODES node1:SE50 node2:SW50 for the other. 
 
-  

-  

-    
Examples

-    

-      
-        Defining a simple link
-      
-      
LINK mylink
+          

+        

+        

+          
Change History

+          

+            
0.96

+            
Added template support

+          

+        

+      

+      

+        
+        

+          NODES nodename{:compassoffset} nodename{:compassoffset}
+        

+        

+          NODES nodename{:compassoffset}{percentage} nodename{:compassoffset}{percentage}
+        

+        

+          NODES nodename{:xoffset:yoffset} nodename{:xoffset:yoffset}
+        

+        

+          NODES nodename{:angle}r{radius} nodename{:angle}r{radius}
+        

+        

+          
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 can be numeric values, to indicate the relative position in pixels from the
+          centre of the node, or are named after compass-points: N,S,E,W,NE,NE,SE,SW. The compass
+          points describe locations around the edge of the box that contains the node. You can also
+          specify a percentage after the compass point, to be a certain proportion of the way from
+          the centre. The percentage must be two digits. Finally, you can also use polar
+          coordinates to specify offsets, with an angle in degrees and a radius in pixels from the
+          centre point. 0 degrees is straight up.

+          
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'.

+          

+          compass points example

+          The compass points, relative to the node's bounding-box..

+          

+          linkoffset defaults example

+          The default - node centre to node centre.

+          

+          linkoffset eastwest example

+          Using compass points - NODES node1:E node2:W

+          

+          linkoffset east50west50 example

+          Using compass points with percentages - NODES node1:E50
+          node2:W50

+          

+          linkoffset radial example

+          Using polar offsets - NODES node1:45r20
+          node2:225r20

+          

+          linkoffset parallel example

+          Using offsets to make parallel links- NODES node1:NE50
+          node2:NW50 for one link and NODES node1:SE50
+          node2:SW50 for the other.

+        

+        

+          
Examples

+          

+            Defining a simple link
+            
LINK mylink
     NODES node1 node2
             

-    

-    

-      
-        Two parallel links, using offsets
-      
-      
LINK firstlink
+          

+          

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

-    

-    

-      
-        Two parallel links, using percentage compass offsets to bring
-        the links closer together
-      
-      
LINK firstlink NODES node1:E50 node2:E50
+          

+          

+            Two parallel links, using percentage compass offsets to bring the links
+            closer together
+            
LINK firstlink
+    NODES node1:E50 node2:E50
 
 LINK secondlink
     NODES node1:W50 node2:W50
             

-    

-    

-      
-        An offset link using pixel offsets
-      
-      
LINK firstlink
+          

+          

+            An offset link using pixel offsets
+            
LINK firstlink
     NODES node1:-10:10 node2:20:12
             

-    

-    

-      
-        An offset link using polar coordinates
-      
-      
LINK firstlink
+          

+          

+            An offset link using polar coordinates
+            
LINK firstlink
     NODES node1:45r20 node2:225r20
             

-    

-  

-  

-    
Change History

-    

-      
0.96

-      
Added polar offsets.
-        

-      
0.96

-      
Added fractional compass offsets.
-        

-      
0.9

-      
Added numeric pixel offsets.
-        

-      
0.8

-      
Added ability to specify node offset.
-        

-    

-  

-

-
-        

-  
-  
TARGET
-
-        targetspec
-    

-  
TARGET
-
-        targetspec
-
-        targetspec
-    

-  
TARGET
-
-        targetspec
-
-        -
-
-        targetspec
-    

-  
TARGET
-
-        targetspec
-
-        n*
-
-        targetspec
-    

-  
TARGET "targetspec"
-    

-  

- 
Specifies where to look for the current throughput information for this LINK. 
- 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. If a targetspec starts with a '-', then 
- it's value will be subtracted from the final result instead. 
 
- 
Also, if a targetspec starts with a number, then a *, then it's used a 
- scaling factor on the result. You can do basic maths with this, especially if 
- you remember that multiplying by a number below 1 is the same as dividing by 1 
- divided by that number (0.5* is the same as divide by 2). 
 
- 
For both the '-' and '*' options, 
- there must be no spaces between any modifiers and the actual target 
- string after it. 
 
- 
The actual contents of the 
- targetspec depend on the data source plugins that are available. 
- The standard plugins are documented here. 
 
- 
To help with filenames that can contain spaces, or for the external script 
- data source, you can enclose the entire targetspec in double-quotes (") to show 
- that it is a single targetspec. 
- The quotes must be around the whole targetspec, including any 
- prefixes. 
 
-  

-  

-    
Examples

-    

-      
-        Using multiple data sources for one link
-      
-      
TARGET link1a.rrd link1b.rrd
+          

+        

+        

+          
Change History

+          

+            
0.96

+            
Added polar offsets.

+            
0.96

+            
Added fractional compass offsets.

+            
0.9

+            
Added numeric pixel offsets.

+            
0.8

+            
Added ability to specify node offset.

+          

+        

+      

+      

+        
+        

+          TARGET targetspec
+        

+        

+          TARGET targetspec targetspec
+        

+        

+          TARGET targetspec -targetspec
+        

+        

+          TARGET targetspec n*targetspec
+        

+        

+          TARGET "targetspec"
+        

+        

+          

+            +
+            

+              Two sources are added separately in each direction. The map displays their total;
+              this does not create an aggregate Cacti graph. Complete runnable configuration.
+            

+          

+          
TARGET static:200M:100M static:100M:50M
+BANDWIDTH 1G

+          

+          Specifies where to look for the current throughput information for this LINK. 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, separated with a space. If a targetspec
+          starts with a '-', then its value will be subtracted from the final result
+          instead.

+          
Also,
+          if a targetspec starts with a number, then a *, then it's used a scaling factor on the
+          result. You can do basic maths with this, especially if you remember that multiplying by
+          a number below 1 is the same as dividing by 1 divided by that number (0.5* is the same as
+          divide by 2).

+          
For
+          both the '-' and '*' options, there must be no spaces between any modifiers and
+          the actual target string after it.

+          
The
+          actual contents of the targetspec depend on the data source plugins that are
+          available. The standard plugins are documented here.

+          
To
+          help with filenames that can contain spaces, or for the external script data source, you
+          can enclose the entire targetspec in double-quotes (") to show that it is a single
+          targetspec. The quotes must be around the whole targetspec, including any
+          prefixes.

+        

+        

+          
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:-
+          

+          

+            Taking the input from one file, and output from another
+            
TARGET poot.rrd:-:DS1 poot2.rrd:DS0:-
             

-    

-  

-  

-    
Change History

-    

-      
0.96

-      
Added quotes option for targets with spaces.
-        

-      
0.96

-      
Added scale factors for all datasources.
-        

-      
0.91

-      
Added 'negative' datasources.
-        

-      
0.9

-      
Added plugin data sources, node targets, and added new
-        plugins.
-        

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

-    

-  

-

-
-        

-  
-  
USESCALE
-
-        scalename
-    

-  
USESCALE
-
-        scalename
-
-        percent
-    

-  
USESCALE
-
-        scalename
-
-        absolute
-    

-  

- 
Specify which SCALE to use to decide the colour of this link. 
 
- 
After the percentage usage is calculated (using BANDWIDTH and data from the 
- TARGET line), the colour is decided by looking up the percentage against this 
- SCALE. If there is no USESCALE line, then the default scale is used. 
 
- 
If you also specify 'absolute', then no percentage calculation is performed. 
- The raw values from the TARGET line are just looked up in the named SCALE. 
 
-  

-  

-    
Change History

-    

-      
0.97

-      
Added absolute scale support.
-        

-      
0.9

-      
Added named scales and USESCALE.
-        

-    

-  

-

-
-        

-  
-  
WIDTH
-
-        width
-    

-  

- 
Specifies the width of this link when drawn. The 
- width value can be any positive number (including non-integers). 
 
- 
The actual width of the final link arrow will be 
- roughly 2*width+1 pixels, due to the way links are drawn, and rounding 
- errors as the internal floating-point values are finally forced onto an integer 
- pixel-grid. 
 
- 
 
- What it actually does is calculate a centre-line (or spine), divide that up into 
- so many segments, and then at each point along the spine, find the normal (90 
- degrees to the direction of the line). Then step WIDTH pixels along the normal 
- in each direction to get a point to draw. This apparently-complex scheme is 
- required to allow for VIAs 
- - both angled and curved links have special handling, and regular straight links 
- are treated as curved links with no VIA by default. 
 
-  

-  

-    
Change History

-    

-      
0.97a

-      
Added non-integer widths. Retconned explanation.
-        

-    

-  

-

-
-        

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

+            
Added quotes option for targets with spaces.

+            
0.96

+            
Added scale factors for all datasources.

+            
0.91

+            
Added 'negative' datasources.

+            
0.9

+            
Added plugin data sources, node targets, and added new plugins.

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

+          

+        

+      

+      

+        
+        

+          USESCALE scalename
+        

+        

+          USESCALE scalename percent
+        

+        

+          USESCALE scalename absolute
+        

+        

+          

+          Specify which SCALE to use to decide the colour of this
+          link.

+          
After
+          the percentage usage is calculated (using BANDWIDTH and
+          data from the TARGET line), the colour is decided by looking
+          up the percentage against this SCALE. If there is no USESCALE line, then the default scale is used.

+          
If you
+          also specify 'absolute', then no percentage calculation is performed. The raw values from
+          the TARGET line are just looked up in the named SCALE.

+        

+        

+          
Change History

+          

+            
0.97

+            
Added absolute scale support.

+            
0.9

+            
Added named scales and USESCALE.

+          

+        

+      

+      

+        
+        

+          WIDTH width
+        

+        

+          

+          Specifies the width of this link when drawn. The width value can be any positive
+          number (including non-integers).

+          
The
+          actual width of the final link arrow will be roughly 2*width+1 pixels, due to
+          the way links are drawn, and rounding errors as the internal floating-point values are
+          finally forced onto an integer pixel-grid.

+          
What
+          it actually does is calculate a centre-line (or spine), divide that up into so many
+          segments, and then at each point along the spine, find the normal (90 degrees to the
+          direction of the line). Then step WIDTH pixels along the normal
+          in each direction to get a point to draw. This apparently-complex scheme is required to
+          allow for VIAs - both angled and curved links have special
+          handling, and regular straight links are treated as curved links with no VIA by default.

+        

+        

+          
Change History

+          

+            
0.97a

+            
Added non-integer widths. Retconned explanation.

+          

+        

+      

+      

+        
+        
MAXVALUE is also accepted as a link-capacity alias. Prefer BANDWIDTH for
+        traffic links to make the units clear.

+        

+          BANDWIDTH max-bandwidth
+        

+        

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

+        

+          

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

+          
Default: 1000M in each direction, unless a map default or template
+          supplies a different capacity. With the default KILO 1000, 1G and 1000M are equivalent.

+          
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.9

-      
Added MAXVALUE as a synonym to match NODE MAXVALUE. No
-        change in functionality.
-        

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

-    

-  

-

-
-        

-  
-  
DUPLEX
-
-        full
-    

-  
DUPLEX
-
-        half
-    

-  

- 
'half' indicates that the bandwidth specified by the BANDWIDTH keyword is 
- half-duplex rather than the default full. 
 
- 
This means that the percentages calculated are calculated as (in+out)/max 
- instead of (in/max) and (out/max) separately. 
 
-  

-  

-    
Change History

-    

-      
0.95

-      
Added DUPLEX.
-        

-    

-  

-

-
-        

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

-    

-  

-

-
-        

-  
-  
INBWFORMAT
-
-        string
-    

-  

- 
Specifies a custom string to use for the inbound data BWLABEL bandwidth 
- labels. 
 
- 
This command is intended as an advanced alternative to the BWLABEL command, 
- for situations where you want more control over the content of the labels. 
 
- 
Instead of using bits, percent, etc, you can use any string in the label. 
- Most importantly, the text for the label can contain 
- special tokens to show map data. In most 
- normal situations you 
- need to use the tokens, or the label won't do much useful 
 
- 
There is also a matching OUTBWFORMAT command to do the ame job for the 
- outbound bandwidth label. 
 
-  

-  

-    
Examples

-    

-      
-        Providing more information in the bwlabel
-      
-      
INBWFORMAT {link:this:inpercent}% of {link:this:max_bandwidth_in:%k}b/sec
+          

+        

+        

+          
Change History

+          

+            
2.0
Changed the inherited link-capacity default to 1000M in both directions; explicit capacities are preserved.

+            
0.9

+            
Added MAXVALUE as a synonym to match NODE MAXVALUE. No change in
+            functionality.

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

+          

+        

+      

+      

+        
+        

+          DUPLEX full
+        

+        

+          DUPLEX half
+        

+        

+          
'half'
+          indicates that the bandwidth specified by the BANDWIDTH
+          keyword is half-duplex rather than the default full.

+          
This
+          means that the percentages calculated are calculated as (in+out)/max instead of (in/max)
+          and (out/max) separately.

+        

+        

+          
Change History

+          

+            
0.95

+            
Added DUPLEX.

+          

+        

+      

+      

+        
+        

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

+          

+        

+      

+      

+        
+        

+          INBWFORMAT string
+        

+        

+          

+          Specifies a custom string to use for the inbound data BWLABEL
+          bandwidth labels.

+          
This
+          command is intended as an advanced alternative to the BWLABEL
+          command, for situations where you want more control over the content of the labels.

+          

+          Instead of using bits, percent, etc, you can use any string in the label. Most
+          importantly, the text for the label can contain special
+          tokens to show map data. In most normal situations you need to use the
+          tokens, or the label won't do much useful

+          
There
+          is also a matching OUTBWFORMAT command to do the ame job
+          for the outbound bandwidth label.

+        

+        

+          
Examples

+          

+            Providing more information in the bwlabel
+            
INBWFORMAT {link:this:inpercent}% of {link:this:max_bandwidth_in:%k}b/sec
             

-    

-  

-  

-    
Change History

-    

-      
0.94

-      
Added INBWFORMAT.
-        

-    

-  

-

-
-        

-  
-  
OUTBWFORMAT
-
-        string
-    

-  

- 
Specifies a custom string to use for the outbound data BWLABEL bandwidth 
- labels. 
 
- 
See the INBWFORMAT entry for more information. 
 
-  

-  

-    
Change History

-    

-      
0.94

-      
Added OUTBWFORMAT.
-        

-    

-  

-

-
-        

-  
-  
BWSTYLE
-
-        formatname
-    

-  

- 
Specifies the style used to draw the box around the 'bandwidth' label shown 
- on each link. 
 
- 
Two styles are currently available: 'classic' leaves the box horizontal, 
- regardless of the direction of the link. 'angled' rotates the box to follow the 
- directiong of the link arrow. 
 
- 
The BWFONT 
- must be a TrueType font as these are the only font type to support 
- rotating text. 
 
- 
To change the contents of the label, use BWLABEL or INBWFORMAT/OUTBWFORMAT. 
 
- 
 
-  Classic label style 
 
- 
 
-  Angled label style 
 
-  

-  

-    
Change History

-    

-      
0.92

-      
Added BWSTYLE.
-        

-    

-  

-

-
-        

-  
-  
BWLABELPOS
-
-        inposition
-
-        outposition
-    

-  

- 
Specifies the position of the 'bandwidth' labels shown on each link. 
 
- 
The two position values are percentages along the link arrow, from the first 
- to the second node. Therefore BWLABELPOS 75 25 is the default. 
 
- 
Weathermap will produce a warning if the outpostion is greater than the 
- inposition. In most cases, you have probably made a mistake, but if you have a 
- good reason to do this, then you can disable that warning using 'SET 
- nowarn_bwlabelpos 1' in the top section of you map config file. 
 
-  

-  

-    
Change History

-    

-      
0.96

-      
Added warning for proably-wrong positions
-        

-      
0.9

-      
Added BWLABELPOS
-        

-    

-  

-

-
-        

-  
-  
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. 
 
- 
 
- The built-in GD fonts. 
 
-  

-

-
-        

-  
-  
INCOMMENT
-
-        string
-    

-  

- 
Specifies a comment for the input side of a LINK. 
 
- 
The link comment appears as text running alongside the link arrow. The font 
- used is governed by COMMENTFONT and the colour by COMMENTFONTCOLOR. 
 
- 
The text for the comment can contain 
- special tokens to show map data. 
 
- 
The COMMENTFONT 
- must be a TrueType font as these are the only font type to support 
- rotating text. 
 
-  

-  

-    
Change History

-    

-      
0.9

-      
Added link comments
-        

-    

-  

-

-
-        

-  
-  
OUTCOMMENT
-
-        string
-    

-  

- 
Specifies a comment for the output side of a LINK. 
 
- 
The link comment appears as text running alongside the link arrow. The font 
- used is governed by COMMENTFONT and the colour by COMMENTFONTCOLOR. 
 
- 
The text for the comment can contain 
- special tokens to show map data. 
 
- 
The COMMENTFONT 
- must be a TrueType font as these are the only font type to support 
- rotating text. 
 
-  

-  

-    
Change History

-    

-      
0.9

-      
Added link comments
-        

-    

-  

-

-
-        

-  
-  
COMMENTFONT
-
-        fontnumber
-    

-  

- 
Specify the font used for drawing the INCOMMENT and OUTCOMMENT 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. 
 
- 
For Link Comments, you 
- must define a TrueType font. These are the only font that can rotate 
- text through any angle, as required by comments. You can change the colour used 
- to render the font with COMMENTFONTCOLOR 
 
-  

-  

-    
Change History

-    

-      
0.9

-      
Added link comments
-        

-    

-  

-

-
-        

-  
-  
COMMENTPOS
-
-        inposition
-
-        outposition
-    

-  

- 
Specify the position along the link used for drawing the INCOMMENT and 
- OUTCOMMENT text. 
 
- 
The positions are specified as a percentage position along the link, like 
- BWLABELPOS. The default positions are equivalent to 
- COMMENTPOS 95 5. 
 
-  

-  

-    
Change History

-    

-      
0.92

-      
Added COMMENTPOS
-        

-    

-  

-

-
-        

-  
-  
COMMENTCURVE 0|1

-  
Use 1 to draw link comments along the link's curve,
-  including curved VIA points. The default is 1 (follow link curve); use 0 for straight comments. This requires
-  a TrueType COMMENTFONT. Text stays upright and uses COMMENTPOS and COMMENTSTYLE;
-  tight bends, multiline comments, unsupported fonts and text longer than the link
-  fall back to straight comments. In the editor, use Map Style > Link Defaults
-  > Follow link curve.

-

-        

-  
-  
COMMENTSTYLE edge
-    

-  
COMMENTSTYLE center
-    

-  

- 
Specify whether link comments run along the outside edge of the link, or down 
- the centre of the link arrow. 
 
- 
 
-  'edge' comment style 
 
- 
 
-  'center' comment style 
 
-  

-  

-    
Change History

-    

-      
0.96

-      
Added COMMENTSTYLE
-        

-    

-  

-

-
-        

-  
-  
SPLITPOS
-
-        position
-    

-  

- 
Specify the position of the 'split' between the in and out arrows in a link. 
- position is a percentage, and defaults to 50. 
 
-  

-  

-    
Change History

-    

-      
0.95

-      
Added SPLITPOS
-        

-    

-  

-

-
-        

-  
-  
OUTLINECOLOR
-
-        red
-
-        green
-
-        blue
-    

-  
BWOUTLINECOLOR
-
-        red
-
-        green
-
-        blue
-    

-  
BWFONTCOLOR
-
-        red
-
-        green
-
-        blue
-    

-  
BWBOXCOLOR
-
-        red
-
-        green
-
-        blue
-    

-  
COMMENTFONTCOLOR
-
-        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. 
 
- 
COMMENTFONTCOLOR also has an extra option - 'contrast' 
- - which will choose black or white, depending on the colour of the link. This is 
- most useful with COMMENTSTYLE center. 
 
- 
The colours are used as follows: 
 
-  
- 
 
-  COMMENTFONTCOLOR contrast with 
- COMMENTSTYLE center 
 
-  

-  

-    
Change History

-    

-      
0.96

-      
Added COMMENTFONTCOLOR contrast.
-        

-      
0.93

-      
Added correction
-        - COMMENTCOLOR was shown instead of COMMENTFONTCOLOR.
-        

-      
0.9

-      
Added COMMENTCOLOR.
-        

-      
0.8

-      
Added OUTLINECOLOR, BWOUTLINECOLOR, BWFONTCOLOR and
-        BWBOXCOLOR.
-        

-    

-  

-

-
-        

-  
-  
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. 
 
- 
It is also possible to specify the INFOURL for the 'in' and 'out' halves of a 
- link individually, using ININFOURLand OUTINFOURL. 
 
-  

-  

-    
Change History

-    

-      
0.95

-      
Added IN/OUT support
-        

-    

-  

-

-
-        

-  
-  
ININFOURL
-
-        url
-    

-  
ININFOURL
-
-        url
-    

-  

- 
Same as INFOURL, but specifies a hyperlink for only the 'in' side of a 
- link. 
 
-  

-  

-    
Change History

-    

-      
0.95

-      
Added IN/OUT support
-        

-    

-  

-

-
-        

-  
-  
OUTINFOURL
-
-        url
-    

-  
OUTINFOURL
-
-        url
-    

-  

- 
Same as INFOURL, but specifies a hyperlink for only the 'out' side of a 
- link. 
 
-  

-  

-    
Change History

-    

-      
0.95

-      
Added IN/OUT support
-        

-    

-  

-

-
-        

-  
-  
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. 
 
- 
You can also specify more than one url, in which case the images are 
- 'stacked' one after another in the popup box. 
 
- 
If a NOTES line is also specified for a link, then the image specified here 
- appears with the NOTES text underneath it. 
 
- 
It is also possible to specify the OVERLIBGRAPH for the 'in' and 'out' halves 
- of a link individually, using INOVERLIBGRAPH and OUTOVERLIBGRAPH. 
 
- 
You can influence how Weathermap positions the popup box, using the 
- OVERLIBWIDTH and OVERLIBHEIGHT keywords. 
 
-  

-  

-    
Examples

-    

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

+        

+        

+          
Change History

+          

+            
0.94

+            
Added INBWFORMAT.

+          

+        

+      

+      

+        
+        

+          OUTBWFORMAT string
+        

+        

+          

+          Specifies a custom string to use for the outbound data BWLABEL bandwidth labels.

+          
See
+          the INBWFORMAT entry for more information.

+        

+        

+          
Change History

+          

+            
0.94

+            
Added OUTBWFORMAT.

+          

+        

+      

+      

+        
+        

+          BWSTYLE formatname
+        

+        

+          

+          Specifies the style used to draw the box around the 'bandwidth' label shown on each
+          link.

+          
Two
+          styles are currently available: 'classic' leaves the box horizontal, regardless of the
+          direction of the link. 'angled' rotates the box to follow the direction of the link
+          arrow.

+          
The
+          BWFONT must be a TrueType font as these are the only
+          font type to support rotating text.

+          
To
+          change the contents of the label, use BWLABEL or
+          INBWFORMAT/OUTBWFORMAT.

+          

+          bwstyle classic example
+          Classic label style

+          

+          bwstyle angled example
+          Angled label style

+        

+        

+          
Change History

+          

+            
0.92

+            
Added BWSTYLE.

+          

+        

+      

+      

+        
+        

+          BWLABELPOS inposition outposition
+        

+        

+          

+          Specifies the position of the 'bandwidth' labels shown on each link.

+          
In the editor, set Traffic Label Positions under Map Style for map defaults, or under
+          Link Properties → Advanced settings for one link. Use map default restores inheritance.

+          
The
+          two position values are percentages along the link arrow, from the first to the second
+          node. Therefore BWLABELPOS 75 25 is the
+          default.

+          

+          Weathermap will produce a warning if the outposition is greater than the inposition. In
+          most cases, you have probably made a mistake, but if you have a good reason to do this,
+          then you can disable that warning using 'SET nowarn_bwlabelpos 1'
+          in the top section of you map config file.

+        

+        

+          
Change History

+          

+            
2.0.1
Added Map Style defaults and per-link Advanced controls for traffic-label positions; BWLABELPOS syntax is unchanged.

+            
0.96

+            
Added warning for probably-wrong positions

+            
0.9

+            
Added BWLABELPOS

+          

+        

+      

+      

+        
+        

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

+          

+          font sizes exampleThe built-in
+          GD fonts.

+        

+      

+      

+        
+        

+          INCOMMENT string
+        

+        

+          

+          Specifies a comment for the input side of a LINK.

+          
The
+          link comment appears as text running alongside the link arrow. The font used is governed
+          by COMMENTFONT and the colour by COMMENTFONTCOLOR.

+          
The
+          text for the comment can contain special tokens to
+          show map data.

+          
The
+          COMMENTFONT must be a TrueType font as these are
+          the only font type to support rotating text.

+        

+        

+          
Change History

+          

+            
0.9

+            
Added link comments

+          

+        

+      

+      

+        
+        

+          OUTCOMMENT string
+        

+        

+          

+          Specifies a comment for the output side of a LINK.

+          
The
+          link comment appears as text running alongside the link arrow. The font used is governed
+          by COMMENTFONT and the colour by COMMENTFONTCOLOR.

+          
The
+          text for the comment can contain special tokens to
+          show map data.

+          
The
+          COMMENTFONT must be a TrueType font as these are
+          the only font type to support rotating text.

+        

+        

+          
Change History

+          

+            
0.9

+            
Added link comments

+          

+        

+      

+      

+        
+        

+          COMMENTFONT fontnumber
+        

+        

+          

+          Specify the font used for drawing the INCOMMENT and
+          OUTCOMMENT 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.

+          
For
+          Link Comments, you must define a TrueType font. These are the only font that can
+          rotate text through any angle, as required by comments. You can change the colour used to
+          render the font with COMMENTFONTCOLOR

+        

+        

+          
Change History

+          

+            
0.9

+            
Added link comments

+          

+        

+      

+      

+        
+        

+          COMMENTPOS inposition outposition
+        

+        

+          

+          Specify the position along the link used for drawing the INCOMMENT and OUTCOMMENT text.

+          
The
+          positions are specified as a percentage position along the link, like BWLABELPOS. The default positions are equivalent to
+          COMMENTPOS 95 5.

+        

+        

+          
Change History

+          

+            
0.92

+            
Added COMMENTPOS

+          

+        

+      

+      

+        
+        

+          COMMENTCURVE 0|1
+        

+        

+          

+            +
+            

+              COMMENTCURVE 0 (upper link) and 1 (lower link), using a TrueType COMMENTFONT.
+              Complete runnable configuration.
+            

+          

+          
Use 1 to draw link comments along the link's curve, including curved VIA points. The
+          default is 1 (follow link curve); use 0 for straight comments. This requires a TrueType
+          COMMENTFONT. Text stays upright and uses COMMENTPOS and COMMENTSTYLE; tight bends,
+          multiline comments, unsupported fonts and text longer than the link fall back to straight
+          comments. In the editor, use Map Style > Link Appearance Defaults > Follow link curve.

+        

+        

+          
Examples

+          
FONTDEFINE 100 docs/example/Vera.ttf 9
+
+LINK DEFAULT
+    COMMENTFONT 100
+    COMMENTCURVE 1
+
+LINK straight_comments
+    NODES core access
+    COMMENTCURVE 0

+          
Define core and access as nodes in the map. The default follows curves; this link
+          overrides it with straight comments. See the illustrated configuration above for a
+          complete map.

+        

+        

+          
Change History

+          

+            
2.0
Added COMMENTCURVE and the Follow link curve editor control.

+          

+        

+      

+      

+        
+        

+          COMMENTSTYLE edge
+        

+        

+          COMMENTSTYLE center
+        

+        

+          

+          Specify whether link comments run along the outside edge of the link, or down the centre
+          of the link arrow.

+          
In the editor, Link Comment Style in Map Style sets the map default. Comment Style
+          in Link Properties overrides it for that link; Use map default restores inheritance.

+          

+          commentstyle edge example 'edge' comment style

+          

+          commentstyle center example 'center' comment style

+        

+        

+          
Change History

+          

+            
2.0.1
Added Map Style defaults and per-link Comment Style controls; COMMENTSTYLE syntax is unchanged.

+            
0.96

+            
Added COMMENTSTYLE

+          

+        

+      

+      

+        
+        

+          SPLITPOS position
+        

+        

+          

+          Specify the position of the 'split' between the in and out arrows in a link.
+          position is a percentage, and defaults to 50.

+        

+        

+          
Change History

+          

+            
0.95

+            
Added SPLITPOS

+          

+        

+      

+      

+        
+        

+          OUTLINECOLOR red green blue
+        

+        

+          BWOUTLINECOLOR red green blue
+        

+        

+          BWFONTCOLOR red green blue
+        

+        

+          BWBOXCOLOR red green blue
+        

+        

+          COMMENTFONTCOLOR 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.

+          

+          COMMENTFONTCOLOR also has an extra option - 'contrast' - which
+          will choose black or white, depending on the colour of the link. This is most useful with
+          COMMENTSTYLE center.

+          
The
+          colours are used as follows:

+          
+          

+          contrast example COMMENTFONTCOLOR contrast with COMMENTSTYLE center

+        

+        

+          
Change History

+          

+            
0.96

+            
Added COMMENTFONTCOLOR contrast.

+            
0.93

+            
Added correction - COMMENTCOLOR was shown instead of COMMENTFONTCOLOR.

+            
0.9

+            
Added COMMENTCOLOR.

+            
0.8

+            
Added OUTLINECOLOR, BWOUTLINECOLOR, BWFONTCOLOR and BWBOXCOLOR.

+          

+        

+      

+      

+        
+        

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

+          
It is
+          also possible to specify the INFOURL for the 'in' and 'out'
+          halves of a link individually, using ININFOURL and OUTINFOURL.

+        

+        

+          
Change History

+          

+            
0.95

+            
Added IN/OUT support

+          

+        

+      

+      

+        
+        

+          ININFOURL url
+        

+        

+          
Same
+          as INFOURL, but specifies a hyperlink for only the 'in' side
+          of a link.

+        

+        

+          
Change History

+          

+            
0.95

+            
Added IN/OUT support

+          

+        

+      

+      

+        
+        

+          OUTINFOURL url
+        

+        

+          
Same
+          as INFOURL, but specifies a hyperlink for only the 'out' side
+          of a link.

+        

+        

+          
Change History

+          

+            
0.95

+            
Added IN/OUT support

+          

+        

+      

+      

+        
+        

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

+          
You
+          can also specify more than one url, in which case the images are 'stacked' one after
+          another in the popup box.

+          
If a
+          NOTES line is also specified for a link, then the image
+          specified here appears with the NOTES text underneath it.

+          
It is
+          also possible to specify the OVERLIBGRAPH for the 'in'
+          and 'out' halves of a link individually, using INOVERLIBGRAPH and OUTOVERLIBGRAPH.

+          
You
+          can influence how Weathermap positions the popup box, using the OVERLIBWIDTH and OVERLIBHEIGHT
+          keywords.

+        

+        

+          
Examples

+          

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

-    

-  

-  

-    
Change History

-    

-      
0.95

-      
Added multiple URL support
-        

-      
0.95

-      
Added IN/OUT support
-        

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

-    

-  

-

-
-        

-  
-  
INOVERLIBGRAPH
-
-        url
-    

-  
INOVERLIBGRAPH
-
-        url
-
-        url...
-    

-  

- 
Same as OVERLIBGRAPH, but specifies a pop-up graph for only the 'in' side of 
- a link. 
 
-  

-  

-    
Change History

-    

-      
0.95

-      
Added multiple URL support
-        

-      
0.95

-      
Added IN/OUT support
-        

-    

-  

-

-
-        

-  
-  
OUTOVERLIBGRAPH
-
-        url
-    

-  
OUTOVERLIBGRAPH
-
-        url
-
-        url...
-    

-  

- 
Same as OVERLIBGRAPH, but specifies a pop-up graph for only the 'out' side of 
- a link. 
 
-  

-  

-    
Change History

-    

-      
0.95

-      
Added multiple URL support
-        

-      
0.95

-      
Added IN/OUT support
-        

-    

-  

-

-
-        

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

-    

-  

-

-
-        

-  
-  
OVERLIBCAPTION
-
-        caption text
-    

-  

- 
Specify the caption used for the popup HTML 'window' if you have also 
- specified an OVERLIBGRAPH line. By default, this is the name of the LINK. 
 
- 
The text for the caption can contain 
- special tokens to show map data. 
 
-  

-  

-    
Change History

-    

-      
0.9

-      
Originally added OVERLIBCAPTION.
-        

-    

-  

-

-
-        

-  
-  
INOVERLIBCAPTION
-
-        caption text
-    

-  

- 
Same as OVERLIBCAPTION, but specifies a pop-up graph caption for only the 
- 'in' side of a link. 
 
-  

-  

-    
Change History

-    

-      
0.95

-      
Added multiple URL support
-        

-      
0.9

-      
Originally added OVERLIBCAPTION.
-        

-    

-  

-

-
-        

-  
-  
OUTOVERLIBCAPTION
-
-        caption text
-    

-  

- 
Same as OVERLIBCAPTION, but specifies a pop-up graph caption for only the 
- 'out' side of a link. 
 
-  

-  

-    
Change History

-    

-      
0.95

-      
Added multiple URL support
-        

-      
0.9

-      
Originally added OVERLIBCAPTION.
-        

-    

-  

-

-
-        

-  
-  
NOTES
-
-        notes text
-    

-  

- 
Specifies the text or HTML notes for a link. 
 
- 
The 
- notes text appears in a popup box when the user hovers their mouse over 
- the link. If an OVERLIBGRAPH is specified too, then the text appears below the 
- graph. 
 
- 
The map HTMLSTYLE must be set to 'overlib' to enable any of the mouse-hover 
- functionality. 
 
- 
It is also possible to specify the NOTES for the 'in' and 'out' halves of a 
- link individually, using INNOTES and OUTNOTES. 
 
-  

-  

-    
Change History

-    

-      
0.95

-      
Added IN/OUT support
-        

-      
0.9

-      
Originally added NOTES.
-        

-    

-  

-

-
-        

-  
-  
INNOTES
-
-        url
-    

-  
INNOTES
-
-        notes text
-    

-  

- 
Same as NOTES, but specifies a text box for only the 'in' side of a link. 
 
-  

-  

-    
Change History

-    

-      
0.95

-      
Added IN/OUT support
-        

-    

-  

-

-
-        

-  
-  
OUTNOTES
-
-        url
-    

-  
OUTNOTES
-
-        notes text
-    

-  

- 
Same as NOTES, but specifies a pop-up text box for only the 'out' side of a 
- link. 
 
-  

-  

-    
Change History

-    

-      
0.95

-      
Added IN/OUT support
-        

-    

-  

-

-
-        

-  
-  
VIA
-
-        x-coord
-
-        y-coord
-    

-  
VIA
-
-        nodename
-
-        x-offset
-
-        y-offset
-    

-  

- 
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. 
 
- 
You can choose between curved or angled links with VIASTYLE. 
 
- 
Any VIA can also be specified relative to a NODE on the map. This makes it 
- easier to have curves keep the intended shape as you re-organise a map. 
 
-  

-  

-    
Change History

-    

-      
0.96

-      
Added angled VIAs.
-        

-      
0.95

-      
Added relative-positioned VIA.
-        

-      
0.8

-      
Originally added VIA.
-        

-    

-  

-

-
-        

-  
-  
VIASTYLE curved
-    

-  
VIASTYLE angled
-    

-  

- 
When using VIA to define a non-straight LINK, you can choose to have a curved 
- link, where the curve passes through each VIA point, or an angled link where 
- each VIA point is a 'corner'. The default is for a curved link. 
 
- 
 
- Curved VIA 
 
- 
 
- Angled VIA 
 
-  

-  

-    
Change History

-    

-      
0.96

-      
Added 'angled' style, and VIASTYLE.
-        

-    

-  

-

-
-        

-  
-  
LINKSTYLE oneway
-    

-  
LINKSTYLE twoway
-    

-  

- 
Specifies the whether the link should be drawn with one or two arrows. 
 
- 
A 'standard' (twoway) link has two arrows 
- - one for inbound data and one for outbound data. In some situations (e.g. 
- round-trip latency), you might only want an arrow in one direction. 
 
- 
One-way arrows only show the outbound BWLABEL, but they show it in the 
- standard position 
- - 25% of the way along. Change the position of the label with BWLABELPOS as 
- usual (you still need to specify 
- two positions in the BWLABELPOS line, however). 
 
-  

-  

-    
Change History

-    

-      
0.94

-      
Added LINKSTYLE.
-        

-    

-  

-

-
-        

-  
-  
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'. 
 
- 
 
-  Classic arrow style 
 
- 
 
-  Compact arrow style 
 
-  

-  

-    
Change History

-    

-      
0.8

-      
Added custom numeric form.
-        

-      
0.7

-      
First added.
-        

-    

-  

-

-
-        

-  
-  
SET
-
-        hintname
-
-        hintvalue
-    

-  

- 
Specifies a value for a hint variable. 
 
- 
Hint Variables allow the user to pass settings to the internals of Weathermap 
- that wouldn't normally need to be changed, or that aren't part of the core 
- Weathermap application. Examples are: small rendering changes, parameters for 
- datasources plugins and similar. 
 
- 
Hint Variables are either Global for the map, or assigned to a specific link 
- or node. 
 
- 
There is more about Hint Variables in the 
- Advanced Topics section. 
 
-  

-  

-    
Change History

-    

-      
0.9

-      
Originally added SET.
-        

-    

-  

-

-
-        

-  
-  
ZORDER
-
-        z-coord
-    

-  

- 
Specifies the order in which to draw this item on the map. 
 
- 
By default, all nodes are drawn above all links. There are some situations 
- where you might like to change this, for example if you use a NODE as a 
- background image, and you want links to show in front of that image. 
 
- 
By default, all nodes have a Z coordinate of 600, and all links have 300. The 
- map legend is at 1000, which cannot be changed (you can move everything else 
- above it, if you like, of course). Items are drawn from lowest Z up to highest 
- Z, so if you want a particular node to appear underneath the default links, you 
- can use 'ZORDER 250' to do that. 
- 
 
-  

-  

-    
Change History

-    

-      
0.96

-      
Added Z-ordering support.
-        

-    

-  

-

-    
-
-    
Global Configuration Directives

-        

-  
BACKGROUND

-  
BACKGROUND imagefile

-  

- 
Specify an PNG, JPEG or GIF 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. 
 
-  

-  

-    
Change History

-    

-      
0.9

-      
Added JPEG and GIF support for backgrounds.
-        

-    

-  

-

-
-        

-  
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

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

-  

-    
Change History

-    

-      
0.98

-      
This now creates a second copy of the file in the location specified, when using the
-            Cacti plugin.
-        

-      
0.7

-      
Added HTMLOUTPUTFILE.
-        

-    

-  

-

-        

-  
DATAOUTPUTFILE

-  
DATAOUTPUTFILE
-
-        datafile
-    

-  

- 
Specifies a file to write a dump of all the data collected 
- during the rendering of the map. 
 
- 
The file is in a tab-separated file format suitable for reading using the 
- wmdata datasource plugin, which allows one map to refer to data in another map. 
 
- 
If you are using the Cacti plugin, this data is always saved in the output/ directory, in addition to anywhere you specify with this command. 
 
-  

-  

-    
Change History

-    

-      
0.98

-      
Added DATAOUTPUTFILE
-        

-    

-  

-

-
-        

-  
HTMLSTYLESHEET

-  
HTMLSTYLESHEET
-
-        URL
-    

-  

- 
Specifies a CSS stylesheet to reference, when generating HTML. 
 
- 
When HTML output is enabled, this allows you to include your own CSS 
- stylesheet in the result, allowing for customisation of the output without 
- needing to use awk/perl/etc to modify the HTML. 
 
- 
If you are generating maps using the Cacti plugin, then this directive is 
- ignored. 
 
-  
- Added HTMLSTYLESHEET. 
-  
-  
-  

-

-
-        

-  
IMAGEOUTPUTFILE

-  
IMAGEOUTPUTFILE
-
-        imagefile
-    

-  

- 
This specifies the name of the PNG, JPEG or GIF file that will be generated. 
- The format chosen is based on the file-extension. 
 
- 
The equivalent command-line option takes precedence over this configuration 
- line, if both are used. 
 
-  

-  

-    
Change History

-    

-      
0.98

-      
This now creates a second copy of the file in the location specified, when using the Cacti plugin.

-      
0.9

-      
Added JPEG and GIF support.
-        

-      
0.7

-      
Added IMAGEOUTPUTFILE.
-        

-    

-  

-

-
-        

-  
IMAGEURI

-  
IMAGEURI 
-        image-uri
-    

-  

- 
If you are generating output files using HTMLOUTPUTFILE and IMAGEOUTPUTFILE 
- that are in a different directory to the weathermap installation, then the HTML 
- will probably contain an incorrect IMG tag. This keyword allows you to replace 
- the IMG SRC attribute in the HTML output with a corrected one. 
 
- 
The equivalent command-line option (--image-uri) takes precedence over this 
- configuration line, if both are used. 
 
- 
If you are generating maps using the Cacti plugin, then this directive is 
- ignored, as the filename and uri are calculated instead. 
 
-  

-  

-    
Change History

-    

-      
0.96

-      
Added IMAGEURI.
-        

-    

-  

-

-
-        

-  
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.
    •  
- 
 
-
- 
If you have a font in the Weathermap directory as above and it's not loading, also 
- try: ./FontName.ttf 
 
-
- 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.95

+            
Added multiple URL support

+            
0.95

+            
Added IN/OUT support

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

+          

+        

+      

+      

+        
+        

+          INOVERLIBGRAPH url
+        

+        

+          INOVERLIBGRAPH url url...
+        

+        

+          
Same
+          as OVERLIBGRAPH, but specifies a pop-up graph for only
+          the 'in' side of a link.

+        

+        

+          
Change History

+          

+            
0.95

+            
Added multiple URL support

+            
0.95

+            
Added IN/OUT support

+          

+        

+      

+      

+        
+        

+          OUTOVERLIBGRAPH url
+        

+        

+          OUTOVERLIBGRAPH url url...
+        

+        

+          
Same
+          as OVERLIBGRAPH, but specifies a pop-up graph for only
+          the 'out' side of a link.

+        

+        

+          
Change History

+          

+            
0.95

+            
Added multiple URL support

+            
0.95

+            
Added IN/OUT support

+          

+        

+      

+      

+        
+        

+          OVERLIBWIDTH imagewidth
+        

+        

+          

+          Specify the width, in pixels of the graph image referred to by OVERLIBGRAPH line.

+          
These legacy size hints affect popup placement. Current viewers also fit previews to
+          the available viewport. To change the graph image itself, adjust its graph_image.php URL
+          or hover defaults; these directives do not request a larger Cacti graph.

+        

+        

+          
Change History

+          

+            
0.7

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

+          

+        

+      

+      

+        
+        

+          OVERLIBHEIGHT imageheight
+        

+        

+          

+          Specify the height, in pixels of the graph image referred to by OVERLIBGRAPH line.

+          
These legacy size hints affect popup placement. Current viewers also fit previews to
+          the available viewport. To change the graph image itself, adjust its graph_image.php URL
+          or hover defaults; these directives do not request a larger Cacti graph.

+        

+        

+          
Change History

+          

+            
0.7

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

+          

+        

+      

+      

+        
+        

+          OVERLIBCAPTION caption text
+        

+        

+          

+          Specify the caption used for the popup HTML 'window' if you have also specified an
+          OVERLIBGRAPH line. By default, this is the name of the
+          LINK.

+          
The
+          text for the caption can contain special tokens to
+          show map data.

+        

+        

+          
Change History

+          

+            
0.9

+            
Originally added OVERLIBCAPTION.

+          

+        

+      

+      

+        
+        

+          INOVERLIBCAPTION caption text
+        

+        

+          
Same
+          as OVERLIBCAPTION, but specifies a pop-up graph
+          caption for only the 'in' side of a link.

+        

+        

+          
Change History

+          

+            
0.95

+            
Added multiple URL support

+            
0.9

+            
Originally added OVERLIBCAPTION.

+          

+        

+      

+      

+        
+        

+          OUTOVERLIBCAPTION caption text
+        

+        

+          
Same
+          as OVERLIBCAPTION, but specifies a pop-up graph
+          caption for only the 'out' side of a link.

+        

+        

+          
Change History

+          

+            
0.95

+            
Added multiple URL support

+            
0.9

+            
Originally added OVERLIBCAPTION.

+          

+        

+      

+      

+        
+        

+          NOTES notes text
+        

+        

+          

+          Specifies the text or HTML notes for a link.

+          
The
+          notes text appears in a popup box when the user hovers their mouse over the
+          link. If an OVERLIBGRAPH is specified too, then the text
+          appears below the graph.

+          
The
+          map HTMLSTYLE must be set to 'overlib' to enable any of
+          the mouse-hover functionality.

+          
It is
+          also possible to specify the NOTES for the 'in' and 'out'
+          halves of a link individually, using INNOTES and OUTNOTES.

+        

+        

+          
Change History

+          

+            
0.95

+            
Added IN/OUT support

+            
0.9

+            
Originally added NOTES.

+          

+        

+      

+      

+        
+        

+          INNOTES notes text
+        

+        

+          
Same
+          as NOTES, but specifies a text box for only the 'in' side of a
+          link.

+        

+        

+          
Change History

+          

+            
0.95

+            
Added IN/OUT support

+          

+        

+      

+      

+        
+        

+          OUTNOTES notes text
+        

+        

+          
Same
+          as NOTES, but specifies a pop-up text box for only the 'out'
+          side of a link.

+        

+        

+          
Change History

+          

+            
0.95

+            
Added IN/OUT support

+          

+        

+      

+      

+        
+        

+          VIA x-coord y-coord
+        

+        

+          VIA nodename x-offset y-offset
+        

+        

+          

+          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 separate 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.

+          
You
+          can choose between curved or angled links with VIASTYLE.

+          
Any
+          VIA can also be specified relative to a NODE on the map. This makes it easier to have curves keep the intended
+          shape as you re-organise a map.

+        

+        

+          
Change History

+          

+            
0.96

+            
Added angled VIAs.

+            
0.95

+            
Added relative-positioned VIA.

+            
0.8

+            
Originally added VIA.

+          

+        

+      

+      

+        
+        

+          VIASTYLE curved
+        

+        

+          VIASTYLE angled
+        

+        

+          
When
+          using VIA to define a non-straight LINK,
+          you can choose to have a curved link, where the curve passes through each VIA point, or an angled link where each VIA point
+          is a 'corner'. The default is for a curved link.

+          

+          viastyle curved exampleCurved VIA

+          

+          viastyle angled exampleAngled VIA

+        

+        

+          
Change History

+          

+            
0.96

+            
Added 'angled' style, and VIASTYLE.

+          

+        

+      

+      

+        
+        

+          LINKSTYLE oneway
+        

+        

+          LINKSTYLE twoway
+        

+        

+          

+          Specifies the whether the link should be drawn with one or two arrows.

+          
A
+          'standard' (twoway) link has two arrows - one for inbound data and one for outbound data.
+          In some situations (e.g. round-trip latency), you might only want an arrow in one
+          direction.

+          

+          One-way arrows only show the outbound BWLABEL, but they show
+          it in the standard position - 25% of the way along. Change the position of the label with
+          BWLABELPOS as usual (you still need to specify
+          two positions in the BWLABELPOS line,
+          however).

+        

+        

+          
Change History

+          

+            
0.94

+            
Added LINKSTYLE.

+          

+        

+      

+      

+        
+        

+          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'.

+          

+          arrowstyle classic example Classic arrow style

+          

+          arrowstyle compact example Compact arrow style

+        

+        

+          
Change History

+          

+            
0.8

+            
Added custom numeric form.

+            
0.7

+            
First added.

+          

+        

+      

+      

+        
+        

+          SET hintname hintvalue
+        

+        

+          
Assigns a hint to this link, for example a datasource option or a value used by
+          {link:this:hintname} in a comment or URL. Put it in the relevant LINK block.

+          
The same name/value syntax is used for node hints and
+          global hints. The global entry explains the shared mechanism;
+          Advanced Topics shows how hints adjust map behaviour.

+        

+        

+          
Change History

+          

+            
0.9

+            
Originally added SET.

+          

+        

+      

+      

+        
+        

+          ZORDER z-coord
+        

+        

+          
Sets this link's drawing layer. Links start at 300, nodes at 600 and legends at
+          1000; lower values are drawn first. Changing a link's ZORDER affects its whole arrow,
+          independently of its traffic values.

+          
For background-image nodes and examples of arranging objects above or below each
+          other, see node ZORDER. The same layer ordering applies.

+        

+        

+          
Change History

+          

+            
0.96

+            
Added Z-ordering support.

+          

+        

+      

+      
Global Configuration Directives

+      

+        
BACKGROUND

+        

+          BACKGROUND imagefile
+        

+        

+          
Use a PNG, JPEG or GIF background. With SET background_sizing image (the
+          legacy default), a successfully loaded image sets the map dimensions. With
+          fit or stretch, WIDTH and HEIGHT define the canvas: fit
+          preserves the image aspect ratio; stretch fills both dimensions. See background sizing.

+        

+        

+          
Change History

+          

+            
0.9

+            
Added JPEG and GIF support for backgrounds.

+          

+        

+      

+      

+        
SET background_sizing

+        
SET background_sizing image|fit|stretch

+        

+          
Controls how a BACKGROUND image is drawn. This is a
+          map-global SET hint: put it before the first NODE or LINK.

+          
Default: image in the renderer, preserving the older
+          image-sized canvas. New blank maps created by the editor explicitly select
+          fit.

+          
    
+            
  • image uses the loaded image's dimensions as the map size.
    • 
+            
  • fit keeps the configured WIDTH and
+            HEIGHT, scaling the image proportionally to fit inside.
+            Unused space shows the map background colour.
    • 
+            
  • stretch keeps WIDTH and HEIGHT and scales the image in both directions
+            to fill them. This can distort the image.
    • 
+          

+          
Without a background image, the setting has no image to scale. It does not move node
+          coordinates. In the editor, use Map Properties → Background sizing. See
+          background and canvas controls.

+        

+        

+          
Examples

+          
WIDTH 660
+HEIGHT 300
+BACKGROUND docs/example/background.png
+SET background_sizing fit

+        

+        

+          
Change History

+          

+            
2.0
Added fit and stretch modes; image mode keeps the previous behaviour.

+          

+        

+      

+      

+        
SET traffic_pulse

+        
SET traffic_pulse 0|1

+        

+          
Enables or disables the high-load link pulse in the normal browser viewer.
+          Default: 1 (enabled). Use 0 to disable it.

+          
This is a map-global SET hint: place it before the first NODE or LINK. The threshold
+          is 80% utilisation or above, calculated separately for each direction from its
+          BANDWIDTH. Management hint overrides can take precedence
+          over the file setting.

+          
The effect does not change measured traffic, scale colours or polling frequency.
+          The editor design preview and static image exports do not animate. In the editor, use
+          Manage Colors → Pulse links at 80%+. See the animated
+          illustration and troubleshooting.

+        

+        

+          
Examples

+          
SET traffic_pulse 1
+
+LINK DEFAULT
+    BANDWIDTH 1G

+        

+        

+          
Change History

+          

+            
2.0
Added optional high-load pulsing to the integrated viewer.

+          

+        

+      

+      

+        
WIDTH

+        

+          WIDTH map-width
+        

+        

+          
Sets the logical map width in pixels; the engine default is 800. A loaded background
+          overrides this only in image sizing mode. In fit or stretch mode the configured width
+          remains the canvas width. The editor may explicitly choose a larger preset for new
+          maps.

+        

+      

+      

+        
HEIGHT

+        

+          HEIGHT map-height
+        

+        

+          
Sets the logical map height in pixels; the engine default is 600. A loaded background
+          overrides this only in image sizing mode. In fit or stretch mode the configured height
+          remains the canvas height. The editor may explicitly choose a different preset for new
+          maps.

+        

+      

+      

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

+        

+        

+          
Change History

+          

+            
0.98

+            
This now creates a second copy of the file in the location specified, when using
+            the Cacti plugin.

+            
0.7

+            
Added HTMLOUTPUTFILE.

+          

+        

+      

+      

+        
DATAOUTPUTFILE

+        

+          DATAOUTPUTFILE datafile
+        

+        

+          

+          Specifies a file to write a dump of all the data collected during the rendering of the
+          map.

+          
The
+          file is in a tab-separated file format suitable for reading using the wmdata datasource plugin, which allows one map to refer to data
+          in another map.

+          
If you
+          are using the Cacti plugin, this data is always saved in the output/ directory, in
+          addition to anywhere you specify with this command.

+        

+        

+          
Change History

+          

+            
0.98

+            
Added DATAOUTPUTFILE

+          

+        

+      

+      

+        
HTMLSTYLESHEET

+        

+          HTMLSTYLESHEET URL
+        

+        

+          

+          Specifies a CSS stylesheet to reference, when generating HTML.

+          
When
+          HTML output is enabled, this allows you to include your own CSS stylesheet in the result,
+          allowing for customisation of the output without needing to use awk/perl/etc to modify
+          the HTML.

+          
If you
+          are generating maps using the Cacti plugin, then this directive is ignored.

+          

+            
Added HTMLSTYLESHEET.

+          

+        

+      

+      

+        
IMAGEOUTPUTFILE

+        

+          IMAGEOUTPUTFILE imagefile
+        

+        

+          
This
+          specifies the name of the PNG, JPEG or GIF file that will be generated. The format chosen
+          is based on the file-extension.

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

+        

+        

+          
Change History

+          

+            
0.98

+            
This now creates a second copy of the file in the location specified, when using
+            the Cacti plugin.

+            
0.9

+            
Added JPEG and GIF support.

+            
0.7

+            
Added IMAGEOUTPUTFILE.

+          

+        

+      

+      

+        
IMAGEURI

+        

+          IMAGEURI image-uri
+        

+        

+          
If you
+          are generating output files using HTMLOUTPUTFILE and
+          IMAGEOUTPUTFILE that are in a different directory
+          to the weathermap installation, then the HTML will probably contain an incorrect IMG tag.
+          This keyword allows you to replace the IMG SRC attribute in the HTML output with a
+          corrected one.

+          
The
+          equivalent command-line option (--image-uri) takes precedence over this configuration
+          line, if both are used.

+          
If you
+          are generating maps using the Cacti plugin, then this directive is ignored, as the
+          filename and uri are calculated instead.

+        

+        

+          
Change History

+          

+            
0.96

+            
Added IMAGEURI.

+          

+        

+      

+      

+        
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.
    • 
+          

+          
If you have a font in the Weathermap directory as above and it's not loading, also
+          try: ./FontName.ttf
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. 
 
- 
 
- The built-in GD fonts. 
 
-  

-  

-    
Change History

-    

-      
0.8

-      
Originally added TITLEFONT.
-        

-      
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 

-  
KEYOUTLINECOLOR none
-    

-  
KEYBGCOLOR
-
-        red
-
-        green
-
-        blue
-    

-  
KEYBGCOLOR none
-    

-  

- 
Specify the colours used for drawing the global elements of the map. 
 
- 
red, green and blue are numbers from 0 to 255. 
 
- 
You can also choose not to draw either the outline or background rectangle for 
- keys by specifying 'none' for those. 
- 
 
-  

-  

-    
Change History

-    

-      
0.98

-      
Added 'none' option for KEYBGCOLOR and KEYOUTLINECOLOR

-      
0.8

-      
Added TIMECOLOR, TITLECOLOR, KEYTEXTCOLOR,
-            KEYOUTLINECOLOR and KEYBGCOLOR.
-        

-      
0.7

-      
Added BGCOLOR.
-        

-    

-  

-

-
-        

-  
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. 
 
- 
You can control the font used to draw the timestamp with TIMEFONT, and the 
- colour that it is drawn in, using TIMECOLOR. 
 
-  

-  

-    
Change History

-    

-      
0.6

-      
Added ability to change text.
-        

-      
0.5

-      
Originally added TIMEPOS
-        

-    

-  

-

-
-        

-  
MINTIMEPOS

-  
MINTIMEPOS
-
-        x-pos
-
-        y-pos
-    

-  
MINTIMEPOS
-
-        x-pos
-
-        y-pos
-
-        formatstring
-    

-  

- 
Specifies where to draw the 'oldest data' timestamp on the map. 
 
- 
The data collection part of weathermap collects a timestamp for each piece of 
- data, alongside the actual data. This is intended to signify the time that the 
- data was actually valid 
- - it would be the file modification date if it was a text file, or the current 
- time if it was a live SNMP query. The minimum and maximum of these times are 
- collated, and can be shown on the map with MINTIMEPOS and MAXTIMEPOS. 
 
- 
If no MINTIMEPOS line is given, then the timestamp is not drawn. 
 
- 
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 
- Oldest Data: %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. 
 
- 
You can control the font used to draw the timestamp with TIMEFONT, and the 
- colour that it is drawn in, using TIMECOLOR. 
 
-  

-  

-    
Change History

-    

-      
0.96

-      
Originally added MINTIMEPOS
-        

-    

-  

-

-
-        

-  
MAXTIMEPOS

-  
MAXTIMEPOS
-
-        x-pos
-
-        y-pos
-    

-  
MAXTIMEPOS
-
-        x-pos
-
-        y-pos
-
-        formatstring
-    

-  

- 
Specifies where to draw the 'newest data' timestamp on the map. 
 
- 
The data collection part of weathermap collects a timestamp for each piece of 
- data, alongside the actual data. This is intended to signify the time that the 
- data was actually valid 
- - it would be the file modification date if it was a text file, or the current 
- time if it was a live SNMP query. The minimum and maximum of these times are 
- collated, and can be shown on the map with MINTIMEPOS and MAXTIMEPOS. 
 
- 
If no MAXTIMEPOS line is given, then the timestamp is not drawn. 
 
- 
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 
- Newest Data: %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. 
 
- 
You can control the font used to draw the timestamp with TIMEFONT, and the 
- colour that it is drawn in, using TIMECOLOR. 
 
-  

-  

-    
Change History

-    

-      
0.96

-      
Originally added MAXTIMEPOS
-        

-    

-  

-

-
-        

-  
TITLE

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

-

-
-        

-  
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. 
 
- 
You can control the font used to draw the title with TITLEFONT, and the 
- colour that it is drawn in, using TITLECOLOR. 
 
-  

-  

-    
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
-
-        scalename
-
-        min
-
-        max
-
-        red
-
-        green
-
-        blue
-    

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

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

-  
SCALE
-
-        min
-
-        max
-
-        red
-
-        green
-
-        blue
-
-        tagtext
-    

-  
SCALE
-
-        scalename
-
-        min
-
-        max
-
-        red
-
-        green
-
-        blue
-
-        tagtext
-    

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

-  
SCALE
-
-        scalename
-
-        min
-
-        max
-
-        red
-
-        green
-
-        blue
-
-        red2
-
-        green2
-
-        blue2
-
-        tagtext
-    

-  
SCALE
-
-        min
-
-        max
-
-        none
-    

-  

- 
Defines one 'span' within the link colour-coding table. 
 
- 
SCALE is used to specify how NODEs and 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. 
 
- 
In combination with the 'absolute' option of USESCALE, you can also use raw 
- data from TARGET lines. Just use the absolute values for min and max in SCALE 
- lines. In this format, min and max can use the same abbreviations for mega, giga 
- etc as BANDWIDTH and MAXVALUE can. 
 
- 
If you specify 
- two colours on the line (the third and fourth forms 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 specify the word 'none' instead of a colour, then a transparent colour 
- is used for that range of values. 
 
- 
Without a scalename, 
- the SCALE line will add a definition to the scale named 'DEFAULT'. If you define 
- any other named scales, you can then use the USESCALE directive to specify that 
- a particular NODE or LINK use your new scale. 
 
- 
With any of the formats, you can specify a 'tag' on the end of the line. When 
- the colour is decided for the 'in' and 'out' parts of a NODE or LINK, then a 
- special SET variable is defined called {node:this:inscaletag} (or outscaletag, 
- or link:this...) which contains the tagtext from the SCALE line that matched. 
- You can use this to do things like choose an icon, or change the label of a node 
- or link based on a percentage. There are examples of this (and most other 
- node-related formatting things) in the suite-1.conf map found in the 
- random-bits/ folder of the weathermap distribution. 
 
- 
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. 
 
- 
You can specify a colour for an 
- exact percentage (e.g. zero) by using that value for both the min and 
- max values. The scale lines are sorted by min then max, and scanned from top to 
- bottom. The first match wins. 
 
- 
To show a legend in the map for a given SCALE, you should use KEYPOS and 
- KEYSTYLE. 
 
- 
You can also apply SCALEs to colorise ICON images. You do this using 
- USEICONSCALE. 
 
-  

-  

-    
Examples

-    

-      
-        Setting up a (very simple) colour scale. Colours run smoothly
-        from green to red.
-      
-      
SCALE 0 100 0 255 0 255 0 0
+          

+        

+        

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

+          

+          font sizes exampleThe built-in
+          GD fonts.

+        

+        

+          
Change History

+          

+            
0.8

+            
Originally added TITLEFONT.

+            
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
+        

+        

+          KEYOUTLINECOLOR none
+        

+        

+          KEYBGCOLOR red green blue
+        

+        

+          KEYBGCOLOR none
+        

+        

+          

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

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

+          
You
+          can also choose not to draw either the outline or background rectangle for keys by
+          specifying 'none' for those.

+        

+        

+          
Change History

+          

+            
0.98

+            
Added 'none' option for KEYBGCOLOR and KEYOUTLINECOLOR

+            
0.8

+            
Added TIMECOLOR, TITLECOLOR, KEYTEXTCOLOR, KEYOUTLINECOLOR and KEYBGCOLOR.

+            
0.7

+            
Added BGCOLOR.

+          

+        

+      

+      

+        
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 use strftime-style notation, implemented by the renderer’s Intl-based formatter.
+          For the token notation see the PHP manual page.

+          
You
+          can control the font used to draw the timestamp with TIMEFONT,
+          and the colour that it is drawn in, using TIMECOLOR.

+        

+        

+          
Change History

+          

+            
0.6

+            
Added ability to change text.

+            
0.5

+            
Originally added TIMEPOS

+          

+        

+      

+      

+        
MINTIMEPOS

+        

+          MINTIMEPOS x-pos y-pos
+        

+        

+          MINTIMEPOS x-pos y-pos formatstring
+        

+        

+          

+          Specifies where to draw the 'oldest data' timestamp on the map.

+          
The
+          data collection part of weathermap collects a timestamp for each piece of data, alongside
+          the actual data. This is intended to signify the time that the data was actually valid -
+          it would be the file modification date if it was a text file, or the current time if it
+          was a live SNMP query. The minimum and maximum of these times are collated, and can be
+          shown on the map with MINTIMEPOS and MAXTIMEPOS.

+          
If no
+          MINTIMEPOS line is given, then the timestamp is not
+          drawn.

+          
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 Oldest Data: %b %d %Y %H:%M:%S. The
+          tokens use strftime-style notation, implemented by the renderer’s Intl-based formatter.
+          For the token notation see the PHP manual page.

+          
You
+          can control the font used to draw the timestamp with TIMEFONT,
+          and the colour that it is drawn in, using TIMECOLOR.

+        

+        

+          
Change History

+          

+            
0.96

+            
Originally added MINTIMEPOS

+          

+        

+      

+      

+        
MAXTIMEPOS

+        

+          MAXTIMEPOS x-pos y-pos
+        

+        

+          MAXTIMEPOS x-pos y-pos formatstring
+        

+        

+          

+          Specifies where to draw the 'newest data' timestamp on the map.

+          
The
+          data collection part of weathermap collects a timestamp for each piece of data, alongside
+          the actual data. This is intended to signify the time that the data was actually valid -
+          it would be the file modification date if it was a text file, or the current time if it
+          was a live SNMP query. The minimum and maximum of these times are collated, and can be
+          shown on the map with MINTIMEPOS and MAXTIMEPOS.

+          
If no
+          MAXTIMEPOS line is given, then the timestamp is not
+          drawn.

+          
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 Newest Data: %b %d %Y %H:%M:%S. The
+          tokens use strftime-style notation, implemented by the renderer’s Intl-based formatter.
+          For the token notation see the PHP manual page.

+          
You
+          can control the font used to draw the timestamp with TIMEFONT,
+          and the colour that it is drawn in, using TIMECOLOR.

+        

+        

+          
Change History

+          

+            
0.96

+            
Originally added MAXTIMEPOS

+          

+        

+      

+      

+        
TITLE

+        

+          TITLE 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.

+        

+      

+      

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

+          
You
+          can control the font used to draw the title with TITLEFONT,
+          and the colour that it is drawn in, using TITLECOLOR.

+        

+        

+          
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' enables
+          popup-compatible HTML output so that pop up graphs can work, too. This requires
+          Javascript, which is why 'static' is the default.

+          
The Cacti viewer provides the current popup behaviour. A command-line HTML export does
+          not include the same viewer setup; see the standalone
+          output limitations.

+        

+      

+      

+        
SCALE

+        

+          SCALE min max red
+          green blue
+        

+        

+          SCALE scalename min max
+          red green blue
+        

+        

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

+        

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

+        

+          SCALE min max red
+          green blue tagtext
+        

+        

+          SCALE scalename min max
+          red green blue
+          tagtext
+        

+        

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

+        

+          SCALE scalename min max
+          red green blue
+          red2 green2 blue2
+          tagtext
+        

+        

+          SCALE min max none
+        

+        

+          

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

+          

+          SCALE is used to specify how NODEs
+          and 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.

+          
In
+          combination with the 'absolute' option of USESCALE, you can
+          also use raw data from TARGET lines. Just use the absolute
+          values for min and max in SCALE lines. In this format, min
+          and max can use the same abbreviations for mega, giga etc as BANDWIDTH and MAXVALUE can.

+          
If you
+          specify two colours on the line (the third and fourth forms 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
+          specify the word 'none' instead of a colour, then a transparent colour is used for that
+          range of values.

+          

+          Without a scalename, the SCALE line will add a
+          definition to the scale named 'DEFAULT'. If you define any other named scales, you can
+          then use the USESCALE directive to specify that a particular
+          NODE or LINK use your new scale.

+          
With
+          any of the formats, you can specify a 'tag' on the end of the line. When the colour is
+          decided for the 'in' and 'out' parts of a NODE or LINK, then a special SET variable is defined
+          called {node:this:inscaletag} (or outscaletag, or link:this...) which contains the
+          tagtext from the SCALE line that matched. You can use this to
+          do things like choose an icon, or change the label of a node or link based on a
+          percentage. There are examples of this (and most other node-related formatting things) in
+          the suite-1.conf example configuration.

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

+          
You
+          can specify a colour for an exact percentage (e.g. zero) by using that value for
+          both the min and max values. The scale lines are sorted by min then max, and scanned from
+          top to bottom. The first match wins.

+          
To
+          show a legend in the map for a given SCALE, you should use
+          KEYPOS and KEYSTYLE.

+          
You
+          can also apply SCALEs to colorise ICON images. You do this using USEICONSCALE.

+        

+        

+          
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
-      
-      
+          

+          

+            The default scale set
+            
 SCALE 0 0 192 192 192
 SCALE 0 1 255 255 255
 SCALE 1 10 140 0 255
@@ -3188,285 +3076,249 @@ 
Examples

 SCALE 70 85 255 192 0
 SCALE 85 100 255 0 0
             

-    

-  

-  

-    
Change History

-    

-      
0.97

-      
Added absolute scale support.
-        

-      
0.96

-      
Added 'none' colour option.
-        

-      
0.95

-      
Added USEICONSCALE.
-        

-      
0.95

-      
Added scale tags.
-        

-      
0.9

-      
Added named scales.
-        

-      
0.9

-      
Added considtently sorted scales.
-        

-      
0.8

-      
Added interpolated scale colours.
-        

-      
0.5

-      
Changed to allow min and max to be fractional.
-        

-    

-  

-

-
-        

-  
KEYPOS

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

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

-  
KEYPOS
-
-        scalename
-
-        x-pos
-
-        y-pos
-    

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

-  

- 
Specifies the position of the key, or legend, that shows what each 
- colour-range in a scale means. If a scalename is not given, then "DEFAULT" is 
- assumed. If no KEYPOS line is given for a scale, then no legend is drawn 
- - handy if you have many many colour ranges. You can also hide any legend by 
- giving it a position with negative coordinates. 
 
- 
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. If a scalename is given, then you 
- must also specify a title 
- - there is no useful default title for non-DEFAULT scales. 
 
- 
You can control the font used to draw the key with KEYFONT, and the colours 
- that it is drawn in, using KEYTEXTCOLOR, KEYBGCOLOR and KEYOUTLINECOLOR. 
 
-  

-  

-    
Change History

-    

-      
0.9

-      
Added support for multiple SCALEs.
-        

-      
0.6

-      
Added ability to change text.
-        

-    

-  

-

-
-        

-  
KEYSTYLE

-  
KEYSTYLE
-
-        stylename
-    

-  
KEYSTYLE
-
-        stylename
-
-        size
-    

-  
KEYSTYLE
-
-        scalename
-
-        stylename
-    

-  
KEYSTYLE
-
-        scalename
-
-        stylename
-
-        size
-    

-  

- 
Specifies the style of the key, or legend, that shows what each colour-range 
- means. If a scalename is not given, then "DEFAULT" is assumed. Valid stylenames 
- are: 'classic', 'horizontal', 'vertical', 'inverted' and 'tags'. 
 
- 
Classic has a line for each SCALE range defined. 'vertical' and 'horizontal' 
- are fixed-size, showing a continuous block from 0-100% usage, which is much more 
- useful when gradient SCALEs are used, or when you have a large number of SCALE 
- lines in one scale. 'inverted' is the same as 'vertical', but with the zero 
- point at the bottom, thermometer-style. Finally, 'tags' is the same style as 
- 'classic', but instead of percentages, it shows the tag string from the end of 
- the SCALE lines, if there are any. 
 
- 
 
- For 'horizontal' and 'vertical' styles, you can optionally add an additional 
- parameter, which specifies the longer dimension of the legend in pixels. That 
- is, for a horizontal legend, it specifies the width. The other dimension is 
- calculated from the size of the font used (see KEYFONT). 
- 
 
- 
 
- Classic Style 
 
- 
 
- Horizontal Style 
 
- 
 
- Vertical Style 
 
- 
 
- Inverted Style 
 
- 
 
- Tags Style 
 
- 
You can hide the percentage signs in the key, by setting 
- key_hidepercent_scalename to 1 
 
- 
If you have a 0->0 line in your SCALE, then you can hide that in the key, by 
- setting key_hidezero_scalename to 1 
 
-  

-  

-    
Examples

-    

-      
-        Hiding percentage signs, and the 'absolute zero' SCALE entry
-        in a key.
-      
-      
SET key_hidezero_DEFAULT 1
+          

+        

+        

+          
Change History

+          

+            
0.97

+            
Added absolute scale support.

+            
0.96

+            
Added 'none' colour option.

+            
0.95

+            
Added USEICONSCALE.

+            
0.95

+            
Added scale tags.

+            
0.9

+            
Added named scales.

+            
0.9

+            
Added considtently sorted scales.

+            
0.8

+            
Added interpolated scale colours.

+            
0.5

+            
Changed to allow min and max to be fractional.

+          

+        

+      

+      

+        
KEYPOS

+        

+          KEYPOS x-pos y-pos
+        

+        

+          KEYPOS x-pos y-pos headingstring
+        

+        

+          KEYPOS scalename x-pos y-pos
+        

+        

+          KEYPOS scalename x-pos y-pos headingstring
+        

+        

+          

+          Specifies the position of the key, or legend, that shows what each colour-range in a
+          scale means. If a scalename is not given, then "DEFAULT" is assumed. If no KEYPOS line is given for a scale, then no legend is drawn - handy if
+          you have many many colour ranges. You can also hide any legend by giving it a position
+          with negative coordinates.

+          
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. If a
+          scalename is given, then you must also specify a title - there is no useful
+          default title for non-DEFAULT scales.

+          
You
+          can control the font used to draw the key with KEYFONT, and
+          the colours that it is drawn in, using KEYTEXTCOLOR,
+          KEYBGCOLOR and KEYOUTLINECOLOR.

+        

+        

+          
Change History

+          

+            
0.9

+            
Added support for multiple SCALEs.

+            
0.6

+            
Added ability to change text.

+          

+        

+      

+      

+        
KEYSTYLE

+        

+          KEYSTYLE stylename
+        

+        

+          KEYSTYLE stylename size
+        

+        

+          KEYSTYLE scalename stylename
+        

+        

+          KEYSTYLE scalename stylename size
+        

+        

+          

+          Specifies the style of the key, or legend, that shows what each colour-range means. If a
+          scalename is not given, then "DEFAULT" is assumed. Valid stylenames are: 'classic',
+          'horizontal', 'vertical', 'inverted' and 'tags'.

+          

+          Classic has a line for each SCALE range defined. 'vertical'
+          and 'horizontal' are fixed-size, showing a continuous block from 0-100% usage, which is
+          much more useful when gradient SCALEs are used, or when you
+          have a large number of SCALE lines in one scale. 'inverted'
+          is the same as 'vertical', but with the zero point at the bottom, thermometer-style.
+          Finally, 'tags' is the same style as 'classic', but instead of percentages, it shows the
+          tag string from the end of the SCALE lines, if there are
+          any.

+          
For
+          'horizontal' and 'vertical' styles, you can optionally add an additional parameter, which
+          specifies the longer dimension of the legend in pixels. That is, for a horizontal legend,
+          it specifies the width. The other dimension is calculated from the size of the font used
+          (see KEYFONT).

+          

+          keystyle classic exampleClassic Style

+          

+          keystyle horizontal exampleHorizontal Style

+          

+          keystyle vertical exampleVertical Style

+          

+          keystyle inverted exampleInverted Style

+          

+          keystyle tags exampleTags
+          Style

+          
You
+          can hide the percentage signs in the key, by setting key_hidepercent_scalename
+          to 1

+          
If you
+          have a 0->0 line in your SCALE, then you can hide that in
+          the key, by setting key_hidezero_scalename to 1

+        

+        

+          
Examples

+          

+            Hiding percentage signs, and the 'absolute zero' SCALE entry in a
+            key.
+            
SET key_hidezero_DEFAULT 1
 SET key_hidepercent_DEFAULT 1
             

-    

-  

-  

-    
Change History

-    

-      
0.96

-      
Added tags and inverted styles.
-        

-      
0.92

-      
Added hidepercent and hidezero SET variables.
-        

-      
0.9

-      
Added support for multiple key styles (classic,
-        horizontal, vertical).
-        

-    

-  

-

-
-        

-  
SET

-  
SET
-
-        hintname
-
-        hintvalue
-    

-  

- 
Specifies a value for a hint variable. 
 
- 
Hint Variables allow the user to pass settings to the internals of Weathermap 
- that wouldn't normally need to be changed, or that aren't part of the core 
- Weathermap application. Examples are: small rendering changes, parameters for 
- datasources plugins and similar. 
 
- 
Hint Variables are either Global for the map, or assigned to a specific link 
- or node. 
 
- 
There is more about Hint Variables in the 
- Advanced Topics section. 
 
-  

-  

-    
Examples

-    

-      
-        Enabling 'bulging link mode' in the link-rendering
-        code.
-      
-      
SET link_bulge 1
+          

+        

+        

+          
Change History

+          

+            
0.96

+            
Added tags and inverted styles.

+            
0.92

+            
Added hidepercent and hidezero SET variables.

+            
0.9

+            
Added support for multiple key styles (classic, horizontal, vertical).

+          

+        

+      

+      

+        
SET

+        

+          SET hintname hintvalue
+        

+        

+          

+          Specifies a value for a hint variable.

+          
Hint
+          Variables allow the user to pass settings to the internals of Weathermap that wouldn't
+          normally need to be changed, or that aren't part of the core Weathermap application.
+          Examples are: small rendering changes, parameters for datasources plugins and
+          similar.

+          
Hint
+          Variables are either Global for the map, or assigned to a specific link or node.

+          
There
+          is more about Hint Variables in the Advanced Topics
+          section.

+        

+        

+          
Examples

+          

+            Enabling 'bulging link mode' in the link-rendering code.
+            
SET link_bulge 1
             

-    

-    

-      
-        Enabling 'screenshot mode' to anonymise a map in 0.95 or
-        newer.
-      
-      
SET screenshot_mode 1
+          

+          

+            Enabling 'screenshot mode' to anonymise a map in 0.95 or
+            newer.
+            
SET screenshot_mode 1
             

-    

-    

-      
-        Disabling 'WMWARN50' messages from appearing
-      
-      
SET nowarn_WMWARN50 1
+          

+          

+            Disabling 'WMWARN50' messages from appearing
+            
SET nowarn_WMWARN50 1
             

-    

-  

-  

-    
Change History

-    

-      
0.9

-      
Originally added SET.
-        

-    

-  

-

-
-        

-  
INCLUDE

-  
INCLUDE
-
-        filename
-    

-  

- 
Include the contents of an additional file within the current map 
- configuration file. 
 
- 
Allows you to use a common set of definition across several map files. There 
- are several restrictions: 
-
- 
     
- 
  • INCLUDE can 
- only be used in the 'global' section of the the map configuration 
- file - that is, before the first NODE or LINK.
    •  
-
- 
  • INCULDEd files must contain complete NODE or LINK definitions.
    •  
-
- 
  • If you intend to use the web-based editor, then you can't currently use 
- any commands other than NODE or LINK definitions 
- - that is, no SCALEs or FONTDEFINEs etc.
    •  
- 
 
-
- The INCLUDE file can still be useful to define a set of standard templates that 
- can then be used across maps. Some of the other restrictions will hopefully be 
- lifted in a future version. The reason for the restrictions is that the way 
- config files are read and written doesn't keep track of where a particular 
- setting came from, apart from at the NODE/LINK level. This is also the reason 
- why comments are 'lost' by the editor. 
- 
 
-  

-  

-    
Change History

-    

-      
0.96b

-      
Originally added INCLUDE.
-        

-    

+
+
+
+

Change History

+
+
0.9
+
Originally added SET.
+
+
+
+
+

INCLUDE

+
+ INCLUDE filename +
+
+

Reads another configuration file. Place INCLUDE in the global section, before the + first NODE or LINK. Included files may supply global settings, scales, fonts and complete + node/link templates; define a template before using it.

+

Use paths appropriate to the plugin's working directory and keep the files available + to both editor and poller. Relative directive paths remain relative when saved. The + editor tracks included configuration dependencies and refuses stale saves when those + files change.

+

Shared colour scales can be shown as locked in Manage Colors. Edit the include + deliberately to change all maps that use it, or create an explicit override where the + form allows one. Saving the root map is not a general editor for the included file. Keep + backups before reorganising includes. Saving through the editor rewrites the root + configuration: hand-written # comments and original spacing are not + preserved. This does not refer to visible map notes or IN/OUT link comments.

+
+
+

Change History

+
+
0.96b
+
Originally added INCLUDE.
+
+
+
+ +
+

ORIGIN

+

Not supported by the active 2.0 configuration reader. ORIGIN appears in + an unused keyword table but is not implemented by ReadConfig. Do not add it to maps. Use + POSITION for node coordinates and LABELOFFSET or Display name position for icon labels.

+
+ +
- - - - diff --git a/docs/pages/editor.html b/docs/pages/editor.html index 74f5e69b..0cffcf6b 100644 --- a/docs/pages/editor.html +++ b/docs/pages/editor.html @@ -1,135 +1,433 @@ - - - - - - PHP Weathermap v0.98a - The Map Editor - - - - - - - -
- - -

The Map Editor

- -

Note: This section is basically unaltered from - the v0.7 manual. The editor hasn't really changed since then, except to fix - some bugs, and work with the new config directives - - that is to say, it won't edit them, but nor will it remove/damage them. - It's still true to say that the editor is the easiest way to initially lay - out your map, and pick your TARGETs if you use Cacti, but after that, some - hand-editing will help with cosmetics. -

- -

New in version 0.7, there is a partially-complete interactive editor - included. In this release, it allows for visual layout of nodes and links, - modification of most parameters, and some integration with Cacti for picking - data-sources. - It is not integrated into Cacti's management pages, OR access - control.

- -

To use the editor, you need to make a few extra considerations beyond - those needed by the command-line weathermap software, as detailed in the - Installation Guide. -

- -

- Once you have all that taken care of, put a copy of one of your - configuration files into the configs directory you just created, and then go - to: http://www.your.web.server/cacti/php-weathermap/editor.php (or - whereever you put it). You should get a menu to either create a map, or open - the ones you just put in that directory. -

- -

- Hopefully, the actual editor is fairly self-explanatory. - -

    -
  • You can click on any existing node or link to get it's properties - and change them.
  • You can delete a node or link from the - properties box. For nodes, you can move them from the properties box - too.
  • You can move the key or timestamp by clicking on them, - also.
  • If you set up the Cacti-related options in the - editor-config.php file, then you should also see an additional option to - pick a data source directly from Cacti, in the Link Properties - box.
  • To create a new node, choose the 'Add Node' button at the - top and then click on the map where you want the node to be.
  • To - create a new link, choose the 'Add Link' button then click on the two - nodes to link together, in turn. There are separate buttons at the top - for changing various global parameters.
    • - -
  • There is no save - - Every change is written back to the configuration file immediately. - Make a backup copy if you feel the need to.
    • -
-

- -

- There are a number of things not editable in the editor currently: - -

    -
  • background images and icons - - it's intended that the editor will allow you to upload image files to - the server, which will then appear in a list where appropriate.
    • - -
  • colours - - there's no way to pick colours currently, either for the map elements - or for the scale.
    • - -
  • defaults - - the editor lags behind the current command-line software here. It - generates 'old-style' global options for some features where the correct - thing to do is make changes to the DEFAULT link and node definitions. - Similarly, there is no per-node or per-link adjustment of things like - font, label style or label offset.
    • - -
  • NODE TARGETs
    • - -
  • Multiple SCALEs
    • - -
  • Curves
    • - -
  • Link offsets or Label offsets
    • -
- - Luckily, the editor shouldn't damage any of these things that you put into - the configuration file by hand, so it's safe to do some work in the editor - where it's quicker or more intuitive, and then fine-tune the file by hand. -

- -
- - - + + + + + + Using the map editor — Network Weathermap 2.0 + + + + +
+ Network Weathermap 2.0 +

Cacti plugin manual

+
+
+ +
+

Using the map editor

+

Start by placing nodes and connecting them with links. For a traffic link, + choose an interface and set its capacity in Link Properties. Use Additional hover graphs when + you want another preview, or Advanced settings when you need custom measurements or URLs.

+ +
+

Opening, saving and placement

+

Enter from Edit Map in the viewer or map management. Return to + Map/Manage keeps the navigation context. Choose a toolbar placement action, then click the + canvas or requested endpoints. Save or cancel any open dialog before another action. Use + Editor Settings for grid snapping and editing overlays; these are personal editor + preferences, not map appearance settings.

+

A successful action saves the configuration and refreshes the editor snapshot. + Poller-generated viewer output is separate. If a save reports an error, address it before + relying on the preview. If another tab or administrator has changed the map, reopen it + before editing further. Undo is useful for recent mistakes, but keep backups for + recovery.

+
+
+

The editor toolbar

+

The green bar contains the editing actions. Choose a placement action, then follow the + instruction shown in the bar. Click an existing object to open its properties.

+
+ + +
+ The complete toolbar above a generic example map. Undo and Redo are at the far right. + Select the image to read the toolbar at full size; every control is explained below. + Traffic labels are hidden in this example to keep the layout clear. +
+
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ControlWhat it does
Return to Map / Return to ManageLeave the editor and return to the map viewer or management page, depending on + where you opened it.
Add Node + Choose this action, then click the canvas to place a node. Click the new node to + choose its name and icon. See Node properties. +
Add Link + Click the first existing node, then the second, to connect them. Open Link Properties to assign the traffic interface and capacity. +
Add Note + Click the canvas to place editable text. Set its wording, alignment and + appearance in Note Properties. +
Position LegendClick the canvas to move the default traffic-colour legend. Click an existing + legend to reposition that particular legend.
Position TimestampClick the canvas to move the map generation timestamp. Its wording and + appearance are separate map settings.
Map Properties + Set the map title, canvas dimensions and background image, including its sizing + mode. See Map Properties and + backgrounds. +
Map Style + Set this map’s default fonts, node labels, link appearance and legend style. + Link Appearance Defaults includes Follow link curve. See Map + Style. +
Manage Colors + Set this map’s traffic colours, colour presets, background, outlines and comment + colours. Link Appearance also controls high-load pulsing. See Manage Colors. +
Manage Images + Upload and manage node icons and background images in separate libraries. + Uploading makes an image available; choose it in Node Properties or Map + Properties to use it. See Image libraries. +
Editor SettingsChoose grid snapping and overlays for via points and relative node positions. + These are personal editing preferences; Map Style controls the map’s + appearance.
PositionShows the pointer’s map coordinates to help with placement. This is a readout, + not a button.
Help textThe message beside the controls explains the next click for the selected + action. Follow it when placing objects or connecting nodes.
Undo / Redo + Move backwards or forwards through the last two saved map changes. An unavailable + action is greyed out. See Undo and Redo for limits and + protection against newer changes. +
+
+
+ + +
+ A closer view of the same example canvas, showing the nodes, link comments and an + independent text note. +
+
+
+
+

Node properties

+

Click a node to edit its Display name, searchable Icon + and Display name position. The label can sit above, over the centre or + below the icon. Map position is the node's X/Y coordinate from the + canvas's top-left corner, not the label position.

+

Move places the node at a new point; Clone creates a + separate node. Open Advanced settings to see the internal ID or configure a custom click + destination and hover graphs. CPU or memory graphs belong naturally on device nodes, but an + extra link preview can also show them. Choosing a graph is separate from applying + Add/Replace.

+

The right-click menu provides move, raw configuration and deletion actions. + Delete Node removes that map node and its connected map links. It does not + delete the Cacti device, RRD data or graphs.

+
+
+ + +
+ Node Properties in 2.0. Display name position moves the label; Map position moves the + whole node. +
+
+ + +
+

Additional hover graphs

+

The Link Properties form manages two hover graphs in total: the main + traffic preview and one extra preview, such as CPU or latency. Open Additional + hover graphs, optionally filter by graph type, choose a graph and apply it.

+
    +
  1. Click Additional hover graphs below the comment controls. Search by + device or graph name; use Filter by graph type to narrow the results.
    2. +
  2. Select a result, then click Add hover graph. The extra appears below + the picker with its graph name and available RRD filenames. A graph can use more than one + RRD file; that still counts as one preview.
    3. +
  3. To change the extra, select a different result and click Replace hover + graphs. To clear it, click Remove graph beside the listed entry.
    4. +
  4. Click Save in Link Properties to apply the changes to the map.
    5. +
+

The applied extra is listed by graph title and RRD filename where Cacti can resolve + them. Choosing a result in the search box does not change this list until you press Add or + Replace. The listed entry is the preview that will be saved. Adding a preview changes + neither the measured traffic nor the map-link click destination.

+ +

In the viewer, each recognised Cacti graph preview opens its own full graph when + clicked. Clicking the map link itself uses the configured click destination. Custom image + URLs do not necessarily have a corresponding Cacti graph to open. High-density previews + request more image detail without enlarging their displayed size; collector and + graph-rendering capabilities can require ordinary previews.

+

Opening Advanced settings closes the additional-graphs panel, and vice versa. The + two-preview limit belongs to this link form; raw configuration and older maps can contain + other arrangements. Do not use the form to assume that custom legacy hover lists have been + converted.

+
+
+

Advanced settings: combine measurements

+

Click Advanced settings below the comment controls. For a normal + traffic link, Use interface in the main form sets the source and graph URLs + together; you do not need to fill these fields by hand. Open Advanced when you want to + combine measurements, move the traffic labels or deliberately use different URLs.

+

Current graph is the Cacti graph ID associated with the link, such as + 108; it is not an RRD filename or a traffic reading. Internal link ID + identifies this link in the map configuration.

+

Advanced also contains Traffic Label Positions. Choose Custom positions to move the IN/OUT + utilisation boxes for this link, or Use map default to inherit the positions from Map Style. + This does not move the IN/OUT comment text. Comment Style, beside the comment controls in + the main form, offers Edge, Centre or Use map default.

+ +

Extra measured sources add traffic to the link total; they do not add lines to a Cacti + graph. The primary source is changed with Use interface in the main form. + Remove source removes an extra source only.

+ +

To add a source, search under Add additional traffic sources, select + a result and click Add traffic source. Check that it appears in the list, + then Save. Selecting a search result alone does not add it. The editable text below the + list is the raw measured-source list (TARGET); it is for custom data-source + syntax, not hover image URLs. Removing an extra changes the map total after Save, without + deleting the Cacti interface, graph or RRD file.

+
+ + + + + + + + + + + + + + + + + + + + + + + + + +
ActionMap readingHover/click graphs
Add another measured sourceAdds its IN and OUT readings to the respective totalsUnchanged
Add a hover graphUnchangedAdds the extra preview
Use interfaceChanges the primary source; retains extra sourcesChanges main traffic preview and click destination; retains extra preview
+
+

For example, 200M IN on one source plus 100M IN on another gives 300M IN. At 1G capacity + this is 30%. Set a capacity that makes sense for the combined service. This is useful for + parallel circuits or a logical bundle. A main circuit and standby backup are often clearer + as separate links.

+

No combined Cacti graph is created. If users need historical totals, create a matching + aggregate graph in Cacti separately, then set its click destination and hover image URLs. + The form does not infer which aggregate graph matches your sources.

+
+
+

Advanced settings: URLs and custom data

+

Click destination URL controls where clicking the map link goes. + Main hover graph URL is the first preview, normally supplied by Use + interface. Additional graph URL(s) represents the same extra preview + managed by Additional hover graphs. These fields accept URLs, not RRD paths. Leave them + alone for a standard interface link; use them for a deliberate custom graph or page.

+ +

When copying a Cacti URL, use graph.php for a full graph page and + graph_image.php for the image shown on hover. The + local_graph_id must identify the graph you intend to show; the numbers in the + screenshot are examples from this installation. Changing a URL does not make that graph + measure the combined sources. If you need a historical total, create the matching + aggregate graph in Cacti first. Click Save after editing these fields.

+

Custom measurements require appropriate TARGET syntax and units. A non-traffic RRD may + need explicit data-source names and the gauge: prefix. See data sources. Changing an image or graph URL does not change TARGET or + capacity.

+
+
+

Map notes

+

Choose Add Note, click the canvas, enter text and save. Notes support + multiple lines, left/centre/right alignment, font, colour and coordinates. Click an + existing note to edit or move it. Alignment controls the text within the note; it is + separate from a node's display-name position.

+

Notes use logical map coordinates and TrueType text rendering. Their configuration is + represented by label-only nodes with editor-note metadata; the legacy NOTES + directive is popup text and is a different feature. Use the note dialog rather than + manually changing its internal metadata.

+
+
+ + + +
+ Edit a visible map note in this dialog. Text alignment and Map position serve different + purposes; editing the note does not change a traffic measurement. +
+
+
+

Undo and Redo

+

Use the toolbar buttons or Ctrl/Cmd+Z and + Ctrl/Cmd+Shift+Z after closing the current dialog. The last two saved map + changes can be reversed and reapplied. Text fields retain normal text-editing shortcuts. + Disabled controls mean no corresponding action is available.

+

History covers saved configuration changes: node/link/note creation and deletion, + movement, via points, properties, styles, colours and raw object edits. Undoing a node + deletion also restores its connected links. A new change after Undo clears Redo; no-op or + failed saves do not consume a step.

+

History belongs to a map, browser tab and authenticated session. Reloading the same tab + retains it; duplicate tabs have independent histories. External edits invalidate stale + history instead of overwriting them. Included configurations and managed image references + are checked before restoration. History is temporary, expires after four hours of + inactivity, and is not a backup.

+

Uploads and library-file deletion, deleting configuration files, Cacti devices/graphs + and personal editor preferences are outside Undo/Redo. Private server temporary storage + must be writable. If the browser cannot coordinate history safely between tabs, + editing remains available but Undo/Redo is disabled. See history troubleshooting.

+
+
+

Raw configuration and deletion

+

Edit Raw Configuration opens the underlying syntax for the selected + object. It is also available in node/link right-click menus. Use it for settings beyond the + form, with the configuration reference nearby. Cancel + returns to properties without applying those raw edits. Check the saved result and any + warnings after editing syntax directly.

+

The editor rewrites configuration from the settings it has read. Hand-written + # comments and original spacing are not preserved in a saved file. Keep a copy + of an annotated configuration before editing it; visible map notes and IN/OUT link comments + are separate settings and are saved.

+

Delete Link removes the selected map line. Delete Node also removes its + connected lines. Both require confirmation and leave Cacti data intact. Deleting the + configuration file is a separate management operation and has no editor Undo.

+
+ +
+
+ + diff --git a/docs/pages/errorcodes.html b/docs/pages/errorcodes.html index 3d5fb93e..d31f434e 100644 --- a/docs/pages/errorcodes.html +++ b/docs/pages/errorcodes.html @@ -1,982 +1,773 @@ - - - - - - PHP Weathermap v0.98a - Error Code Reference - - - - - - - -
- - - -

Error Code Reference

- -

This page is mainly here so that Google can find it, but here's a - complete list of all the error codes that Weathermap can produce, and what - each one means.

- -

I added this after I noticed a lot of google searches for error messages, - that were not hitting a useful page in the manual. This page should be the - useful page.

- -
-
[WMWARN01]
- -

"Skipping drawing very short link (linkname). Impossible - to draw! Try changing WIDTH or ARROWSTYLE? "

- -

Weathermap draws the arrowheads on links in proportion to the width - of the link. If your link is fat, then the arrowhead will be bigger. If - you have a very short link (nodes close together), you can get a - situation where there is not enough room to draw the - arrowheads.

If you reduce the width of the link, using WIDTH then - you might be able to make the arrowheads small enough so that they fit. - You can also use ARROWSTYLE to choose a smaller style of arrowhead - - ARROWSTYLE 1 1 is the smallest.

- -

The most common cause of this error is that you have accidentally - placed two nodes on top of each other. In that case, move one of the - nodes.

- -

In previous versions (0.8 to 0.82), this would result in the infamous - "FELL THROUGH Howie's crappy binary search is wrong after all" error - message. The solution is the same - - move the nodes, or change the link width

- -
- -
[WMWARN02], - [WMWARN04]
- -

"Angled text doesn't work with non-FreeType fonts "

- -

The standard fonts used by Weathermap are the ones bundled with the - GD graphics library. These fonts (number 1-5 when you select fonts) can - only be drawn 'flat', and not at an angle.

- -

If you are using link comments, or the 'angled' BWSTYLE, then - Weathermap needs to be able to drawn text at any angle. To do this, it - needs a Truetype font to be used for that part of the map (the bwlabel, - or comment), which is drawn using the FreeType library.

- -

To do this, you need to find a Truetype font, put it in your - weathermap folder, and then define a new font in your map config file: - FONTDEFINE 100 Vera 9

- -

Then you can use that new font (no. 100) in COMMENTFONT or BWFONT - lines.

- -

You can find some TrueType fonts, and an example.conf that does this - in the docs/example folder.

The reason the default comment font is - not a TrueType font is that the FreeType library is an - optional part of the GD library, so I can't assume that it will - be available.

- -
- -
[WMWARN03]
- -

"Using a non-existent special font (fontnumber) - - falling back to internal GD fonts "

- -

If you use a font number that doesn't exist by default(e.g. larger - than 5), and you haven't got a valid FONTDEFINE line, then you will get - this error. Weathermap will use font 5 instead of the font you asked - for.

- -

Most common reason for this error is that the font file could not be - found, or could not be loaded. Check the log for another error (WMWARN30 - or WMWARN31).

- -
- -
[WMWARN05]
- -

"ProcessString: key refers to unknown item "

- -

You used a 'Special Token' string, like {node:this:something}, but - the 'something' you used isn't defined for the node or link you - specified. This is usually a typographical error.

- -
- -
[WMWARN06]
- -

"Couldn't open plugin-type Plugin directory - (dir). Things will probably go wrong. "

- -

Parts of Weathermap are loaded from plugins. If these plugin - directories don't exist, or are not readable due to file permissions, - then the plugins can't be loaded. All data-reading is done by plugins, - so without the data-source plugin directory, Weathermap won't do very - much.

- -

Check that lib/datasources, lib/pre and lib/post folders all exist - inside your Weathermap folder. Check that they (and their contents) are - readable by the user that Weathermap runs as (e.g. your Cacti poller - user). On a Unix system, the directories should also be - executable by that user, so that the contents of the directory - can be seen.

- -
- -
[WMWARN07]
- -

"ReadData: type name, target: - targetstring on config line - linenumber was recognised as a valid TARGET by a plugin that is - unable to run (pluginname) "

- -

When the datasource plugins are loaded, each one is given a chance to - check if everything it needs is available. If something is missing, that - plugin can decline to load. If you have a TARGET line that is aimed at a - particular plugin, and that plugin declined to load, you will get this - message.

- -

Examples of this type of problem would be: Using cactihost: TARGETs - but with the command-line tool where cactihost: can't load, or using the - rrdtool DS from the command-line, without correctly setting a path to - rrdtool in the weathermap command-line tool.

- -
- -
[WMWARN08]
- -

"ReadData: type name, target: - targetstring[4] on config line - linenumber was not recognised as a valid TARGET "

- -

You have specified a TARGET that - none of the datasource plugins recognised. This is usually a - typographical error.

- -
- -
[WMWARN09]
- -

"ColourFromPercent: Attempted to use non-existent scale: - scalename for itemname "

- -

You have added a USESCALE line to a NODE or LINK, but the scale name - wasn't defined using SCALE lines first. Define the SCALE, or check your - spelling.

- -
- -
[WMWARN10]
- -

"NODE - nodename has a relative position to an unknown node! "

- -

You have used the relative POSITION for a NODE, but you did it - relative to a node that doesn't exist. Probably you have a typographical - error/spelling error...

- -
- -
[WMWARN11]
- -

"There are Circular dependencies in relative POSITION lines for - number nodes. "

- -

You are using relative POSITION for nodes, but somewhere you have a - node that is relative to another node that is relative to the first one - again - a loop. None of the nodes in the loop can be positioned correctly. - Solution: make at least one node in the loop have a normal absolute - position.

- -
- -
[WMWARN12]
- -

"Failed to write map image. No function existed for the image - format you requested. "

- -

You specified a particular format to write the map image with - IMAGEFILE, but your php/GD installation doesn't have support for that - image format.

- -

You'll need to either choose a different image format, or - recompile/reinstall your php, php-gd and GD libraries to support that - image format.

- -
- -
[WMWARN13],[WMWARN15],[WMWARN16]
- -

"Failed to overwrite existing image file - filename - permissions of existing file are wrong? "

- -

Most likely when using the Cacti plugin. The files in the output/ - directory are owned by a different user from the one running weathermap, - and so it can't overwrite those files.

- -

The most common way to get into this situation is by using the - "Recalculate Now" button in the Cacti plugin. This creates files that - are owned by the user that your webserver runs as. When the poller - process comes along a few minutes later, it can no longer write over - those files with the new data. Solution: make sure that the directory, - and it's contents are owned by the poller user (or 'cactiuser') and - don't use the 'Recalculate Now' button any more.

- -
- -
[WMWARN14]
- -

"Failed to create image file - filename - permissions of output directory are wrong? "

- -

Again, usually in Cacti plugin.

- -

Weathermap is unable to create files in the directory that the output - file should go - - this is the plugins/weathermap/output/ directory if you are using the - Cacti plugin. Make sure that directory is owned/writable by the user - that runs your poller process. This is the same permissions that you - would have set on the rra/ directory when installing Cacti itself.

- -
- -
[WMWARN17]
- -

"Skipping thumbnail creation, since we don't have the necessary - function. "

- -

Your php/php-gd/GD library doesn't include the imagecopyresampled() - function, which is required to make the thumbnail images used in the - Cacti plugin. To get that function , - you'll need to update/recompile/reinstall your php, php-gd and GD - libraries.

- -
- -
[WMWARN20]
- -

"No image (gd) extension is loaded. This is required by - weathermap. "

- -

All the graphics work in Weathermap is done using the gd PHP - extension. Your php installation doesn't have this extension, or it is - not enabled.

- -

You'll need to install or enable that extension to use Weathermap.

- -
- -
[WMWARN21]
- -

"Your GD php module doesn't support PNG format. "

- -

You specified an ICON or BACKGROUND image in PNG format, and your - php-gd extension doesn't support PNG format images.

- -

You'll need to either choose a different image format, or - recompile/reinstall your php, php-gd and GD libraries to support that - image format.

- -
- -
[WMWARN22]
- -

"Your GD php module doesn't support truecolor. "

- -

Weathermap requires that your GD library and php-gd extension support - 24-bit colour (or "TrueColor"). To get that function , - you'll need to update/recompile/reinstall your php, php-gd and GD - libraries. Most likely, this is the result of an older version of GD.

- -
- -
[WMWARN23]
- -

"Your GD php module doesn't support thumbnail creation - (imagecopyresampled). "

- -

See WMWARN17

- -
- -
[WMWARN24]
- -

"Duplicate node name nodename at line - linenumber - only the last one defined is used. "

- -

You have used the same name for two or more NODE lines in your - config. This is probably a typo or cut & paste error. One of the two - NODEs will not show up in the map.

- -
- -
[WMWARN25]
- -

"Duplicate link name linkname at line - linenumber - only the last one defined is used. "

- -

You have used the same name for two or more LINK lines in your - config. This is probably a typo or cut & paste error. One of the two - LINKs will not show up in the map.

- -
- -
[WMWARN26]
- -

"LINK DEFAULT is not the first LINK. Defaults will not apply to - earlier LINKs. "

- -

You should usually specify your DEFAULT LINK - before all your 'real' LINKs. The reason is that when a new - LINK is defined, it copies whatever the default settings are at that - point in reading down the config file, so you will end up with - inconsistent results.

- -
- -
[WMWARN27]
- -

"NODE DEFAULT is not the first NODE. Defaults will not apply to - earlier NODEs. "

- -

You should usually specify your DEFAULT NODE - before all your 'real' NODEs. The reason is that when a new - NODE is defined, it copies whatever the default settings are at that - point in reading down the config file, so you will end up with - inconsistent results.

- -
- -
[WMWARN28]
- -

"Dropping LINK linkname - it hasn't got 2 NODES! "

- -

You defined a link where one or both of the nodes in the NODES line - don't exist.

- -

Or you forgot to add a NODES line altogether.

- -

A link goes between two nodes, so you need to tell weathermap which - two nodes, and they need to exist.

- -
- -
[WMWARN30]
- -

"Failed to load ttf font filename - at config line - linenumber"

- -

You defined a TrueType/FreeType font with FONTDEFINE, but the file - doesn't exist, or can't be loaded due to permissions issues.

- -
- -
[WMWARN31]
- -

"imagettfbbox() is not a defined function. You don't seem to have - FreeType compiled into your gd module. "

- -

You tried to use a TrueType/FreeType font, but your GD library - (and/or php-gd extension) don't understand FreeType.

- -

You'll need to either choose a different font format, or - recompile/reinstall your php, php-gd, GD and perhaps freetype2 libraries - to support that font format.

- -
- -
[WMWARN32]
- -

"Failed to load GD font: filename (errorcode) - at config line linenumber "

- -

You defined a .gdf font with FONTDEFINE, but the file doesn't exist, - or can't be loaded due to permissions issues.

- -
- -
[WMWARN33]
- -

"NewColourFromPercent: Clipped number% to 100% for item - itemname"

- -

You are using a regular SCALE with a value that is calculated as a - percentage of the MAXVALUE or BANDWIDTH. That calculated value was - higher than 100%. You could fix this with one of:

- -
    -
  • Change BANDWIDTH or MAXVALUE to the correct value.
    • - -
  • Use an absolute SCALE (see USESCALE)
    • - -
  • Disable the warning by adding 'SET nowarn_clip 1' at the top of - the map config file.
    • -
- -
- -
[WMWARN34]
- -

"NewColourFromPercent: Clipped number% to 0% for item - itemname"

- -

You are using a regular SCALE with a value that is calculated as a - percentage of the MAXVALUE or BANDWIDTH. That calculated value was below - 0%. You could fix this with one of:

- -
    -
  • Use a '-' prefix on the TARGET to make the value positive, if it's - always negative, like attentuation readings.
    • - -
  • Use an absolute SCALE (see USESCALE)
    • - -
  • Disable the warning by adding 'SET nowarn_clip 1' at the top of - the map config file.
    • -
- -
- -
[WMWARN35]
- -

"LINK linkname uses a NODE with no POSITION!"

- -

Some nodes have no position, because they are used purely as a - TEMPLATE for other nodes. You have used one of these for a real link, - and as a result, Weathermap can't figure out where to draw the link.

- -
- -
[WMWARN36]
- -

"Using a non-existent special font (number) - - falling back to internal GD fonts"

- -

You have used a command like COMMENTFONT, TITLEFONT or LABELFONT to - change the font to a custom-defined one (number - > 5) but there is no FONTDEFINE line for that font number, OR the font - could not be loaded. Check back in the logs, for WMWARN30 or WMWARN31.

- -
- -
[WMWARN37]
- -

"Couldn't open ICON: 'filename' - - is it a PNG, JPEG or GIF?"

- -

The file you specified to use as an ICON does exist, but couldn't be - loaded by the GD image library. Check that the file really is an image - file.

- -
- -
[WMWARN38]
- -

"ICON 'filename' does not exist, or is not readable. - Check path and permissions."

- -

You specified an ICON, but the file couldn't be opened or couldn't be - found at all.

- -
- -
[WMWARN39]
- -

"line - number: TEMPLATE is not first line of object. Some data may be - lost."

- -

The TEMPLATE command works by copying the settings from another node - or link over the top of the existing items. If you use some other - configuration commands, then use TEMPLATE, the results of those commands - may be overwritten by the equivalent settings in the template item.

- -
- -
[WMWARN40]
- -

"line number: NODE or LINK TEMPLATE - 'name' doesn't exist! (if it does exist, check it's defined - first)"

- -

You specified a TEMPLATE, but the node or link doesn't exist. Also, - possibly, that the template node is further down in the config file. - Best practice is to keep the templates together near the top of the - file, along with DEFAULTs.

- -
- -
[WMWARN41]
- -

"OVERLIBGRAPH is used, but HTMLSTYLE is static. This is probably - wrong."

- -

To generate the 'popup' graphs, the Overlib javascript is required. - The default HTML output from Weathermap doesn't include this for - historical reasons. If you specify OVERLIBGRAPH, you must also add - 'HTMLSTYLE overlib' to the top section of the config file.

- -
- -
[WMWARN42]
- -

"IN/OUTOVERLIBGRAPH make no sense for a NODE!"

- -

NODEs don't have a input and output area on the image, so you can't - specify separate OVERLIBGRAPHs for each.

- -
- -
[WMWARN43]
- -

"FindScaleExtent: non-existent SCALE scalename"

- -

Somehow, Weathermap is trying to draw a legend for a scale that - doesn't exist. This is probably a bug - please report.

- -
- -
[WMWARN43]
- -

"You can't make a contrast with 'none'."

- -

The 'contrast' option picks black or white depending on what colour - the background is. When you set a background of 'none', there is no - correct answer, so Weathermap complains. Change 'contrast' to '0 0 0' or - '255 255 255' as appropriate.

- -
- -
[WMWARN44]
- -

"ReadData: NODE/LINK - name: You're using asymmetric bandwidth AND half-duplex in the - same link. That makes no sense."

- -

Half-duplex calculates the percentage usage based on - (input+output)/max_bandwidth. You have specified different bandwidth in - each direction, but also half-duplex. The calculation is not possible.

- -
- -
[WMWARN45]
- -

"Zero-length link name skipped."

- -

You have a link from a node to the same node without any VIAs. It - isn't possible to draw.

- -
- -
[WMWARN50]
-
-

"Skipping too-short line"

-

To draw a link correctly with arrows, requires a certain distance between nodes. If your nodes are too close together, Weathermap will just skip drawing the link. This distance depends on the width of - the link (because the arrows are in proportion to the width). Try reducing the WIDTH of the link, changing to ARROWSTYLE compact, or moving the nodes further apart.

-
- -
[WMWARN70]
-
-

"ReadData: {map item} target: {target} on config line {line} of {file} had no valid data, according to {plugin}"

-

- This tells you that for a given map item defined on that line of that config file, there is no data. Weathermap - has figured out which datasource plugin should be used, but that plugin was unable to get data for this target. It could - be a NaN in an rrd file, a non-existent file for several data sources, or a network timeout for some others. Usually the - plugin will also log some detail just before this, but you might need to turn on DEBUG loggging to see that. -

-
- - -
[WMWARN99]
- -

"something not implemented yet"

- -

A planned feature has been partially implemented, and you've tried to - use it. Wait for the next release.

- -

Because of the way I write Weathermap, there are sometimes parts of - the code that are waiting ready for me to finish writing a new feature. - If it's the only thing holding back a release, I'll just disable that - feature for now.

- -
- -
[WMEDIT01]
- -

"The map config directory is not writable by the web server user. - You will not be able to edit any files until this is corrected."

-

- -
- -
[WMEDIT02]
- -

"OLD editor config file format. The format of this file changed - in version 0.92 - - please check the new editor-config.php-dist and update your - editor-config.php file."

-

- -
- -
[WMIMG01]
- -

"Image file - filename is GIF, but GIF is not supported by your GD library. - "

-

- -
- -
[WMIMG02]
- -

"Image file - filename is JPEG, but JPEG is not supported by your GD library. - "

-

- -
- -
[WMIMG03]
- -

"Image file - filename is PNG, but PNG is not supported by your GD library. - "

-

- -
- -
[WMIMG04]
- -

"Image file filename wasn't recognised - (type=type). Check format is supported by your GD library. "

-

- -
- -
[WMIMG05]
- -

"Image file - filename is unreadable. Check permissions. "

-

- -
- -
[WMPOLL01]
- -

"About to write image file. If this is the last message in your - log, increase memory_limit in php.ini"

- -

PHP has a hard memory limit, to stop runaway scripts from killing - your server. Depending on the version of PHP, this can be quite low (8M - in older versions). Weathermap uses a lot (relatively) of memory to - produce the large image files. If it hits the PHP memory limit, then PHP - just kills the script with no warning. Because it can't log that it is dead - (because it is dead), it logs just before the 'risk' happens. - If this log message is - not the last message in your log file, then - nothing is wrong!

- -

You can disable some messages like this one by changing settings in - Cacti. Go to Settings..Misc and set Weathermap Logging to 'Quiet'. If - you suddenly get a mystery where Weathermap is only updating some maps, - turn it back to 'Chatty' to see what is happening.

- -
- -
[WMPOLL02]
- -

"Failed to overwrite - filename - permissions of existing file are wrong? "

- -

Weathermap couldn't overwrite an output file. Files in the - weathermap/output/ directory should be writable by the Cacti poller - user.

- -
- -
[WMPOLL03]
- -

"Failed to create - filename - permissions of output directory are wrong?"

- -

The weathermap/output/ directory should be writable by the Cacti - poller user.

- -
- -
[WMPOLL04]
- -

"Mapfile filename is not readable or doesn't exist"

- -

The mapfile could not be opened. That could be because it is not - readable by the Cacti poller user, or because the file no longer exists - but is still in the database (check the Manage..Weathermaps screen in - Cacti).

- -
- -
[WMPOLL05]
- -

"No activated maps found. "

- -

There are no maps in the database, or no maps that are enabled at the - moment. There is also a scheduling facility, so if no maps are due to be - updated according to their schedule, you will get this message. The - scheduling feature is not yet in use in 0.97.

- -
- -
[WMPOLL06]
- -

"Output directory (directory) isn't writable (tried to - create 'filename'). No maps created. You probably need to make - it writable by the poller process (like you did with the RRA - directory)"

- -

The weathermap/output/ directory should be writable by the Cacti - poller user.

- -
- -
[WMPOLL07]
- -

"Output directory (directory) doesn't exist!. No maps - created. You probably need to create that directory, and make it - writable by the poller process (like you did with the RRA directory)"

- -

The weathermap/output/ directory doesn't exist. It is part of the - standard zip package, so you probably deleted or renamed it.

- -
- -
[WMPOLL08]
- -

"Required modules for PHP Weathermap - versionnumber were not present. Not running."

- -

Run 'php check.php' from the command-line, to find out what modules - are missing.

- -
- -
[WMFPING01]
- -

"RRD DS: RRDTool exists but is not executable? "

-

- -
- -
[WMFPING02]
- -

"FPing ReadData: Can't find fping executable. Check path at line - 19 of WeatherMapDataSource_fping.php"

-

- -
- -
[WMFPING03]
- -

"FPing ReadData: No lines read. Bad hostname? - (target)"

-

- -
- -
[WMRRD01]
- -

"RRD DS: RRDTool exists but is not executable? "

- -

Somehow you have the right path for rrdtool, but the rrdtool binary - is not executable by the user that runs weathermap (e.g. your Cacti - poller user). Check permissions on your rrdtool binary.

- -
- -
[WMRRD02]
- -

"RRD DS: Can't find RRDTOOL. Check line 29 of the 'weathermap' - script. RRD-based TARGETs will fail. "

- -

You are using the command-line - weathermap tool, but the path near the top of that file (around - line 29) is not the correct path to your rrdtool binary. Edit that file - and put in the correct path if you need Weathermap to be able to read - .rrd files.

- -
- -
[WMRRD03]
- -

"RRD DS: Can't find RRDTOOL. Check your Cacti config. "

- -

You have Weathermap integrated into Cacti, but your Cacti settings - include an incorrect path to rrdtool. Probably you have a Cacti that - doesn't update properly at this stage too, so change the path in - Console..Settings..Paths (in Cacti) to point to the right location.

- -
- -
[WMRRD04]
- -

"RRD ReadData: failed to open pipe to RRDTool: - phperrormsg "

- -

This is probably a Weathermap bug. It was unable to get rrdtool to - read a .rrd file even though the file exists. It - might be that the user running Weathermap (or the poller) - doesn't have execute permission for rrdtool.

- -
- -
[WMRRD06]
- -

"Target rrdfile doesn't exist. Is it a file? "

- -

You have given an RRD TARGET which is a directory instead of a file, - or something else unusual like that...

- -
- -
[WMRRD07]
- -

"RRD ReadData: poller_output: - dsname is not a valid DS name for - rrdfilename - valid names are: dsnames"

- -

This is explained in - this - article

- -
- -
[WMRRD08]
- -

"RRD ReadData: poller_output: - filename is not a valid RRD filename within this Cacti install. - <path_rra> is pathname"

- -

The poller_output support works by looking in the Cacti database for - a filename that matches your TARGET line. However, Cacti stores the - filenames relative to the rra/ directory. Weathermap tries to convert - your filename to that format, so it can find it in the database, but it - sometimes gets it wrong. The <path_rra> is the path that it is - expecting to be on the beginning of absolute paths in your TARGET.

- -
- -
[WMRRD09]
- -

"Not enough output from RRDTool."

- -

Weathermap ran rrdtool to read the rrd file for your TARGET, but only - got one line of output, probably an error message. Run with debug - logging to see what the output was, which should help figuring out what - is wrong.

- -
- -
[WMRRD10]
- -

"Can't use poller_output for rrd-aggregated data - - disabling rrd_use_poller_output"

-

- -
- -
[WMRRD12]
- -

"RRD ReadData: poller_output - Cacti environment is not right"

-

- -
- -
[WMDSSTATS01]
- -

"DSStats ReadData: Failed to find a filename for DS id - number"

-

- -
- -
[WMEXT01]
- -

"ExternalScript ReadData: Failed to run external script."

-

- -
- -
[WMEXT02]
- -

"ExternalScript ReadData: Not enough lines read from external - script (number read, 4 expected)"

-

- -
- -
[WMSNMP01]
- -

"SNMP for hostname has reached - number failures. Skipping."

- -

The SNMP datasource has a special feature to keep track of how many - failures each host has had. This is to avoid the Weathermap process - timing out 400 times on a chassis switch that is down. After the first - few, it assumes that all requests to that device will fail. See the - SNMP DS documentation for information - on how to tune this.

- -
- -
[WMTIME01]
- -

"Time DS Plugin recognised a TARGET, but needs PHP5+ to run."

- -

The Time DS plugin uses a PHP function that was introduced in PHP 5, - and can't run on PHP 4.

- -
- -
[WMTIME02]
- -

"Time ReadData: Couldn't recognize - string as a valid timezone name"

- -

The timezone string you used was not correct. Probably a typo.

- -
-
-
- - - + + + + + + Error-code reference — Network Weathermap 2.0 + + + + +
+ Network Weathermap 2.0 +

Cacti plugin manual

+
+
+ +
+

Error-code reference

+ +

Find the code from the Cacti log below. Some entries are historical and are retained to + explain older logs.

+
+
[WMWARN01]
+
+

"Skipping drawing very short link (linkname). Impossible to draw! Try + changing WIDTH or ARROWSTYLE? "

+

Weathermap draws the arrowheads on links in proportion to the width of the link. If + your link is fat, then the arrowhead will be bigger. If you have a very short link (nodes + close together), you can get a situation where there is not enough room to draw the + arrowheads.

+

If you reduce the width of the link, using WIDTH then you might be able to make the + arrowheads small enough so that they fit. You can also use ARROWSTYLE to choose a smaller style of + arrowhead - ARROWSTYLE 1 1 is the + smallest.

+

The most common cause of this error is that you have accidentally placed two nodes on + top of each other. In that case, move one of the nodes.

+

In previous versions (0.8 to 0.82), this would result in the infamous "FELL THROUGH + Howie's crappy binary search is wrong after all" error message. The solution is the same + - move the nodes, or change the link width

+
+
[WMWARN02], [WMWARN04]
+
+

"Angled text doesn't work with non-FreeType fonts "

+

The standard fonts used by Weathermap are the ones bundled with the GD graphics + library. These fonts (number 1-5 when you select fonts) can only be drawn 'flat', and not + at an angle.

+

If you are using link comments, or the 'angled' BWSTYLE, then Weathermap needs to be able to + drawn text at any angle. To do this, it needs a Truetype font to be used for that part of + the map (the bwlabel, or comment), which is drawn using the FreeType library.

+

To do this, you need to find a Truetype font, put it in your weathermap folder, and + then define a new font in your map config file: FONTDEFINE 100 docs/example/Vera.ttf 9

+

Then you can use that new font (no. 100) in COMMENTFONT or BWFONT lines.

+

You can find some TrueType fonts, and an example.conf that does this in the + docs/example folder.

+

The reason the default comment font is not a TrueType font is that the FreeType + library is an optional part of the GD library, so I can't assume that it will be + available.

+
+
[WMWARN03]
+
+

"Using a non-existent special font (fontnumber) - falling back to internal GD + fonts "

+

If you use a font number that doesn't exist by default(e.g. larger than 5), and you + haven't got a valid FONTDEFINE + line, then you will get this error. Weathermap will use font 5 instead of the font you + asked for.

+

Most common reason for this error is that the font file could not be found, or could + not be loaded. Check the log for another error (WMWARN30 or WMWARN31).

+
+
[WMWARN05]
+
+

"ProcessString: key refers to unknown item "

+

You used a 'Special Token' string, like {node:this:something}, but the 'something' you + used isn't defined for the node or link you specified. This is usually a typographical + error.

+
+
[WMWARN06]
+
+

"Couldn't open plugin-type Plugin directory (dir). Things will + probably go wrong. "

+

Parts of Weathermap are loaded from plugins. If these plugin directories don't exist, + or are not readable due to file permissions, then the plugins can't be loaded. All + data-reading is done by plugins, so without the data-source plugin directory, Weathermap + won't do very much.

+

Check that lib/datasources, lib/pre and lib/post folders all exist inside your + Weathermap folder. Check that they (and their contents) are readable by the user that + Weathermap runs as (e.g. your Cacti poller user). On a Unix system, the directories + should also be executable by that user, so that the contents of the directory + can be seen.

+
+
[WMWARN07]
+
+

"ReadData: type name, target: targetstring on config line + linenumber was recognised as a valid TARGET by a plugin that is unable to run + (pluginname) "

+

When the datasource plugins are loaded, each one is given a chance to check if + everything it needs is available. If something is missing, that plugin can decline to + load. If you have a TARGET line that is + aimed at a particular plugin, and that plugin declined to load, you will get this + message.

+

Examples of this type of problem would be: Using cactihost: TARGETs but with the command-line tool where + cactihost: can't load, or using the rrdtool DS from the command-line, without correctly + setting a path to rrdtool in the weathermap command-line tool.

+
+
[WMWARN08]
+
+

"ReadData: type name, target: targetstring[4] on config + line linenumber was not recognised as a valid TARGET "

+

You have specified a TARGET that + none of the datasource plugins recognised. This is usually a typographical + error.

+
+
[WMWARN09]
+
+

"ColourFromPercent: Attempted to use non-existent scale: scalename for + itemname "

+

You have added a USESCALE line to a + NODE or LINK, but the scale name wasn't defined using + SCALE lines first. Define the SCALE, or check your spelling.

+
+
[WMWARN10]
+
+

"NODE nodename has a relative + position to an unknown node! "

+

You have used the relative POSITION + for a NODE, but you did it relative to a + node that doesn't exist. Probably you have a typographical error/spelling error...

+
+
[WMWARN11]
+
+

"There are Circular dependencies in relative POSITION lines for number nodes. "

+

You are using relative POSITION for + nodes, but somewhere you have a node that is relative to another node that is relative to + the first one again - a loop. None of the nodes in the loop can be positioned correctly. + Solution: make at least one node in the loop have a normal absolute position.

+
+
[WMWARN12]
+
+

"Failed to write map image. No function existed for the image format you requested. + "

+

You specified a particular format to write the map image with IMAGEFILE, but your + php/GD installation doesn't have support for that image format.

+

You'll need to either choose a different image format, or recompile/reinstall your + php, php-gd and GD libraries to support that image format.

+
+
[WMWARN13],[WMWARN15],[WMWARN16]
+
+

"Failed to overwrite existing image file filename - permissions of existing + file are wrong? "

+

Most likely when using the Cacti plugin. The files in the output/ directory are owned + by a different user from the one running weathermap, and so it can't overwrite those + files.

+

The most common way to get into this situation is by using the "Recalculate Now" + button in the Cacti plugin. This creates files that are owned by the user that your + webserver runs as. When the poller process comes along a few minutes later, it can no + longer write over those files with the new data. Solution: make sure that the directory, + and it's contents are owned by the poller user (or 'cactiuser') and don't use the + 'Recalculate Now' button any more.

+
+
[WMWARN14]
+
+

"Failed to create image file filename - permissions of output directory are + wrong? "

+

Again, usually in Cacti plugin.

+

Weathermap is unable to create files in the directory that the output file should go - + this is the plugins/weathermap/output/ directory if you are using the Cacti plugin. Make + sure that directory is owned/writable by the user that runs your poller process. This is + the same permissions that you would have set on the rra/ directory when installing Cacti + itself.

+
+
[WMWARN17]
+
+

"Skipping thumbnail creation, since we don't have the necessary function. "

+

Your php/php-gd/GD library doesn't include the imagecopyresampled() function, which is + required to make the thumbnail images used in the Cacti plugin. To get that function , + you'll need to update/recompile/reinstall your php, php-gd and GD libraries.

+
+
[WMWARN20]
+
+

"No image (gd) extension is loaded. This is required by weathermap. "

+

All the graphics work in Weathermap is done using the gd PHP extension. Your php + installation doesn't have this extension, or it is not enabled.

+

You'll need to install or enable that extension to use Weathermap.

+
+
[WMWARN21]
+
+

"Your GD php module doesn't support PNG format. "

+

You specified an ICON or BACKGROUND image in PNG format, and your + php-gd extension doesn't support PNG format images.

+

You'll need to either choose a different image format, or recompile/reinstall your + php, php-gd and GD libraries to support that image format.

+
+
[WMWARN22]
+
+

"Your GD php module doesn't support truecolor. "

+

Weathermap requires that your GD library and php-gd extension support 24-bit colour + (or "TrueColor"). To get that function , you'll need to update/recompile/reinstall your + php, php-gd and GD libraries. Most likely, this is the result of an older version of + GD.

+
+
[WMWARN23]
+
+

"Your GD php module doesn't support thumbnail creation (imagecopyresampled). "

+

See WMWARN17

+
+
[WMWARN24]
+
+

"Duplicate node name nodename at line linenumber - only the last one + defined is used. "

+

You have used the same name for two or more NODE lines in your config. This is probably a typo + or cut & paste error. One of the two NODEs + will not show up in the map.

+
+
[WMWARN25]
+
+

"Duplicate link name linkname at line linenumber - only the last one + defined is used. "

+

You have used the same name for two or more LINK lines in your config. This is probably a typo + or cut & paste error. One of the two LINKs + will not show up in the map.

+
+
[WMWARN26]
+
+

"LINK DEFAULT is not the first LINK. Defaults will not apply to earlier LINKs. "

+

You should usually specify your DEFAULT LINK before all your 'real' LINKs. The reason is that when a new LINK is defined, it copies whatever the default + settings are at that point in reading down the config file, so you will end up with + inconsistent results.

+
+
[WMWARN27]
+
+

"NODE DEFAULT is not the first NODE. Defaults will not apply to earlier NODEs. "

+

You should usually specify your DEFAULT NODE before all your 'real' NODEs. The reason is that when a new NODE is defined, it copies whatever the default + settings are at that point in reading down the config file, so you will end up with + inconsistent results.

+
+
[WMWARN28]
+
+

"Dropping LINK linkname - it + hasn't got 2 NODES! "

+

You defined a link where one or both of the nodes in the NODES line don't exist.

+

Or you forgot to add a NODES line + altogether.

+

A link goes between two nodes, so you need to tell weathermap which two nodes, and + they need to exist.

+
+
[WMWARN30]
+
+

"Failed to load ttf font filename - at config line linenumber"

+

You defined a TrueType/FreeType font with FONTDEFINE, but the file doesn't exist, or + can't be loaded due to permissions issues.

+
+
[WMWARN31]
+
+

"imagettfbbox() is not a defined function. You don't seem to have FreeType compiled + into your gd module. "

+

You tried to use a TrueType/FreeType font, but your GD library (and/or php-gd + extension) don't understand FreeType.

+

You'll need to either choose a different font format, or recompile/reinstall your php, + php-gd, GD and perhaps freetype2 libraries to support that font format.

+
+
[WMWARN32]
+
+

"Failed to load GD font: filename (errorcode) at config line + linenumber "

+

You defined a .gdf font with FONTDEFINE, but the file doesn't exist, or + can't be loaded due to permissions issues.

+
+
[WMWARN33]
+
+

"NewColourFromPercent: Clipped number% to 100% for item + itemname"

+

You are using a regular SCALE with a + value that is calculated as a percentage of the MAXVALUE or BANDWIDTH. That calculated value was higher + than 100%. You could fix this with one of:

+
    +
  • Change BANDWIDTH or MAXVALUE to the correct value. +
    • +
  • Use an absolute SCALE (see + USESCALE) +
    • +
  • Disable the warning by adding 'SET + nowarn_clip 1' at the top of the map config file. +
    • +
+
+
[WMWARN34]
+
+

"NewColourFromPercent: Clipped number% to 0% for item itemname"

+

You are using a regular SCALE with a + value that is calculated as a percentage of the MAXVALUE or BANDWIDTH. That calculated value was below 0%. + You could fix this with one of:

+
    +
  • Use a '-' prefix on the TARGET to + make the value positive, if it's always negative, like attentuation readings. +
    • +
  • Use an absolute SCALE (see + USESCALE) +
    • +
  • Disable the warning by adding 'SET + nowarn_clip 1' at the top of the map config file. +
    • +
+
+
[WMWARN35]
+
+

"LINK linkname uses a NODE with no POSITION!"

+

Some nodes have no position, because they are used purely as a TEMPLATE for other nodes. You have used one of + these for a real link, and as a result, Weathermap can't figure out where to draw the + link.

+
+
[WMWARN36]
+
+

"Using a non-existent special font (number) - falling back to internal GD + fonts"

+

You have used a command like COMMENTFONT, TITLEFONT or LABELFONT to change the font to a + custom-defined one (number > 5) but there is no FONTDEFINE line for that font number, OR + the font could not be loaded. Check back in the logs, for WMWARN30 or WMWARN31.

+
+
[WMWARN37]
+
+

"Couldn't open ICON: 'filename' + - is it a PNG, JPEG or GIF?"

+

The file you specified to use as an ICON + does exist, but couldn't be loaded by the GD image library. Check that the file really is + an image file.

+
+
[WMWARN38]
+
+

"ICON 'filename' does not + exist, or is not readable. Check path and permissions."

+

You specified an ICON, but the file + couldn't be opened or couldn't be found at all.

+
+
[WMWARN39]
+
+

"line number: TEMPLATE is + not first line of object. Some data may be lost."

+

The TEMPLATE command works by + copying the settings from another node or link over the top of the existing items. If you + use some other configuration commands, then use TEMPLATE, the results of those commands may be + overwritten by the equivalent settings in the template item.

+
+
[WMWARN40]
+
+

"line number: NODE or + LINK TEMPLATE 'name' + doesn't exist! (if it does exist, check it's defined first)"

+

You specified a TEMPLATE, but the + node or link doesn't exist. Also, possibly, that the template node is further down in the + config file. Best practice is to keep the templates together near the top of the file, + along with DEFAULTs.

+
+
[WMWARN41]
+
+

"OVERLIBGRAPH is used, but + HTMLSTYLE is static. This is + probably wrong."

+

To generate the 'popup' graphs, the Overlib javascript is required. The default HTML + output from Weathermap doesn't include this for historical reasons. If you specify + OVERLIBGRAPH, you must also add + 'HTMLSTYLE overlib' to the top + section of the config file.

+
+
[WMWARN42]
+
+

"IN/OUTOVERLIBGRAPH make no sense for a NODE!"

+

NODEs don't have a input and output area + on the image, so you can't specify separate OVERLIBGRAPHs for each.

+
+
[WMWARN43]
+
+

"FindScaleExtent: non-existent SCALE + scalename"

+

Somehow, Weathermap is trying to draw a legend for a scale that doesn't exist. This is + probably a bug - please report.

+
+
[WMWARN43]
+
+

"You can't make a contrast with 'none'."

+

The 'contrast' option picks black or white depending on what colour the background is. + When you set a background of 'none', there is no correct answer, so Weathermap complains. + Change 'contrast' to '0 0 0' or '255 255 255' as appropriate.

+
+
[WMWARN44]
+
+

"ReadData: NODE/LINK name: You're using asymmetric bandwidth AND + half-duplex in the same link. That makes no sense."

+

Half-duplex calculates the percentage usage based on (input+output)/max_bandwidth. You + have specified different bandwidth in each direction, but also half-duplex. The + calculation is not possible.

+
+
[WMWARN45]
+
+

"Zero-length link name skipped."

+

You have a link from a node to the same node without any VIAs. It isn't possible to draw.

+
+
[WMWARN50]
+
+

"Skipping too-short line"

+

To draw a link correctly with arrows, requires a certain distance between nodes. If + your nodes are too close together, Weathermap will just skip drawing the link. This + distance depends on the width of the link (because the arrows are in proportion to the + width). Try reducing the WIDTH of the + link, changing to ARROWSTYLE compact, + or moving the nodes further apart.

+
+
[WMWARN70]
+
+

"ReadData: {map item} target: {target} on config line {line} of {file} had no valid + data, according to {plugin}"

+

This tells you that for a given map item defined on that line of that config + file, there is no data. Weathermap has figured out which datasource plugin should be + used, but that plugin was unable to get data for this target. It could be a NaN in an rrd + file, a non-existent file for several data sources, or a network timeout for some others. + Usually the plugin will also log some detail just before this, but you might need to turn + on DEBUG loggging to see that.

+
+
[WMWARN99]
+
+

"something not implemented yet"

+

A planned feature has been partially implemented, and you've tried to use it. Wait for + the next release.

+

Because of the way I write Weathermap, there are sometimes parts of the code that are + waiting ready for me to finish writing a new feature. If it's the only thing holding back + a release, I'll just disable that feature for now.

+
+
[WMEDIT01]
+
+

"The map config directory is not writable by the web server user. You will not be able + to edit any files until this is corrected."

+ +
+
[WMEDIT02]
+
+

"OLD editor config file format. The format of this file changed in version 0.92 - + please check the new editor-config.php-dist and update your editor-config.php file."

+ +
+
[WMIMG01]
+
+

"Image file filename is GIF, but GIF is not supported by your GD library. + "

+ +
+
[WMIMG02]
+
+

"Image file filename is JPEG, but JPEG is not supported by your GD library. + "

+ +
+
[WMIMG03]
+
+

"Image file filename is PNG, but PNG is not supported by your GD library. + "

+ +
+
[WMIMG04]
+
+

"Image file filename wasn't recognised (type=type). Check format is + supported by your GD library. "

+ +
+
[WMIMG05]
+
+

"Image file filename is unreadable. Check permissions. "

+ +
+
[WMPOLL01]
+
+

"About to write image file. If this is the last message in your log, increase + memory_limit in php.ini"

+

PHP has a hard memory limit, to stop runaway scripts from killing your server. + Depending on the version of PHP, this can be quite low (8M in older versions). Weathermap + uses a lot (relatively) of memory to produce the large image files. If it hits the PHP + memory limit, then PHP just kills the script with no warning. Because it can't log that + it is dead (because it is dead), it logs just before the 'risk' happens. If this log + message is not the last message in your log file, then nothing + is wrong!

+

You can disable some messages like this one by changing settings in Cacti. Go to + Settings..Misc and set Weathermap Logging to 'Quiet'. If you suddenly get a mystery where + Weathermap is only updating some maps, turn it back to 'Chatty' to see what is + happening.

+
+
[WMPOLL02]
+
+

"Failed to overwrite filename - permissions of existing file are wrong? "

+

Weathermap couldn't overwrite an output file. Files in the weathermap/output/ + directory should be writable by the Cacti poller user.

+
+
[WMPOLL03]
+
+

"Failed to create filename - permissions of output directory are wrong?"

+

The weathermap/output/ directory should be writable by the Cacti poller user.

+
+
[WMPOLL04]
+
+

"Mapfile filename is not readable or doesn't exist"

+

The mapfile could not be opened. That could be because it is not readable by the Cacti + poller user, or because the file no longer exists but is still in the database (check the + Manage..Weathermaps screen in Cacti).

+
+
[WMPOLL05]
+
+

"No activated maps found. "

+

There are no maps in the database, or no maps that are enabled at the moment. Check + active status and rendering schedules; no eligible maps may be due for this cycle.

+
+
[WMPOLL06]
+
+

"Output directory (directory) isn't writable (tried to create + 'filename'). No maps created. You probably need to make it writable by the + poller process (like you did with the RRA directory)"

+

The weathermap/output/ directory should be writable by the Cacti poller user.

+
+
[WMPOLL07]
+
+

"Output directory (directory) doesn't exist!. No maps created. You probably + need to create that directory, and make it writable by the poller process (like you did + with the RRA directory)"

+

The weathermap/output/ directory doesn't exist. It is part of the standard zip + package, so you probably deleted or renamed it.

+
+
[WMPOLL08]
+
+

"Required modules for PHP Weathermap versionnumber were not present. Not + running."

+

Run 'php check.php' from the command-line, to find out what modules are missing.

+
+
[WMFPING01]
+
+

"RRD DS: RRDTool exists but is not executable? "

+ +
+
[WMFPING02]
+
+

"FPing ReadData: Can't find fping executable. Check path at line 19 of + WeatherMapDataSource_fping.php"

+ +
+
[WMFPING03]
+
+

"FPing ReadData: No lines read. Bad hostname? (target)"

+ +
+
[WMRRD01]
+
+

"RRD DS: RRDTool exists but is not executable? "

+

Somehow you have the right path for rrdtool, but the rrdtool binary is not executable + by the user that runs weathermap (e.g. your Cacti poller user). Check permissions on your + rrdtool binary.

+
+
[WMRRD02]
+
+

"RRD DS: Can't find RRDTOOL. Check line 29 of the 'weathermap' script. RRD-based + TARGETs will fail. "

+

You are using the command-line weathermap tool, but the path near the top + of that file (around line 29) is not the correct path to your rrdtool binary. Edit that + file and put in the correct path if you need Weathermap to be able to read .rrd + files.

+
+
[WMRRD03]
+
+

"RRD DS: Can't find RRDTOOL. Check your Cacti config. "

+

You have Weathermap integrated into Cacti, but your Cacti settings include an + incorrect path to rrdtool. Probably you have a Cacti that doesn't update properly at this + stage too, so change the path in Console..Settings..Paths (in Cacti) to point to the + right location.

+
+
[WMRRD04]
+
+

"RRD ReadData: failed to open pipe to RRDTool: phperrormsg "

+

This is probably a Weathermap bug. It was unable to get rrdtool to read a .rrd file + even though the file exists. It might be that the user running Weathermap (or + the poller) doesn't have execute permission for rrdtool.

+
+
[WMRRD06]
+
+

"Target rrdfile doesn't exist. Is it a file? "

+

You have given an RRD TARGET which is + a directory instead of a file, or something else unusual like that...

+
+
[WMRRD07]
+
+

"RRD ReadData: poller_output: dsname is not a valid DS name for + rrdfilename - valid names are: dsnames"

+

Data-source names and explicit RRD syntax are explained in the RRD guide

+
+
[WMRRD08]
+
+

"RRD ReadData: poller_output: filename is not a valid RRD filename within + this Cacti install. <path_rra> is pathname"

+

The poller_output support works by looking in the Cacti database for a filename that + matches your TARGET line. However, Cacti + stores the filenames relative to the rra/ directory. Weathermap tries to convert your + filename to that format, so it can find it in the database, but it sometimes gets it + wrong. The <path_rra> is the path that it is expecting to be on the beginning of + absolute paths in your TARGET.

+
+
[WMRRD09]
+
+

"Not enough output from RRDTool."

+

Weathermap ran rrdtool to read the rrd file for your TARGET, but only got one line of output, probably + an error message. Run with debug logging to see what the output was, which should help + figuring out what is wrong.

+
+
[WMRRD10]
+
+

"Can't use poller_output for rrd-aggregated data - disabling + rrd_use_poller_output"

+ +
+
[WMRRD12]
+
+

"RRD ReadData: poller_output - Cacti environment is not right"

+ +
+
[WMDSSTATS01]
+
+

"DSStats ReadData: Failed to find a filename for DS id number"

+ +
+
[WMEXT01]
+
+

"ExternalScript ReadData: Failed to run external script."

+ +
+
[WMEXT02]
+
+

"ExternalScript ReadData: Not enough lines read from external script (number + read, 4 expected)"

+ +
+
[WMSNMP01]
+
+

"SNMP for hostname has reached number failures. Skipping."

+

The SNMP datasource has a special feature to keep track of how many failures each host + has had. This is to avoid the Weathermap process timing out 400 times on a chassis switch + that is down. After the first few, it assumes that all requests to that device will fail. + See the SNMP DS documentation for information on how to + tune this.

+
+
[WMTIME01]
+
+

"Time DS Plugin recognised a TARGET, + but needs PHP5+ to run."

+

The Time DS plugin uses a PHP function that was introduced in PHP 5, and can't run on + PHP 4.

+
+
[WMTIME02]
+
+

"Time ReadData: Couldn't recognize string as a valid timezone name"

+

The timezone string you used was not correct. Probably a typo.

+
+
+
+

Additional messages in the Cacti fork

+

These entries cover messages absent from the original manual. Refer to the exact log + text as well as the code; some historical codes were reused.

+
+
WMWARN29 — scale does not cover the value
+
Add the missing scale range or correct the value/capacity and chosen scale. Values + outside every configured range cannot be assigned their intended colour.
+
WMPOLL09 — background migration failed
+
Check the old/new background paths and directory/file permissions before retrying the + upgrade or repair. Preserve a backup.
+
WMPOLL10 — background file not found
+
Restore the image or correct its BACKGROUND path; the log identifies the missing + file.
+
WMPOLL11 — icon migration failed
+
Check the source and destination icon files and permissions. Do not delete the + original until references have been updated successfully.
+
WMPOLL12 — icon file not found
+
Restore the icon or correct the ICON path in the relevant configuration.
+
WMPOLL13 — configuration repair could not lock or save
+
Check destination-directory access, lock availability and concurrent edits. The + repair must not be treated as successful until the save succeeds.
+
WMDSTATS01 — DSStats data-source filename unresolved
+
Check the local data-source ID and the Cacti/DSStats data available for that source. + This spelling differs from the older WMDSSTATS01 entry.
+
WMFPING04 — rejected fping target
+
Use a valid host target without illegal command characters. Do not bypass target + validation.
+
WMWMDATA01 — data file missing
+
Correct the wmdata filename or create the expected file.
+
WMWMDATA02 — file cannot be opened
+
Check read permissions for the map-rendering account.
+
WMWMDATA03 — named reading missing
+
Check that the requested data name exists in the first tab-separated column.
+
WMWMDATA04 — invalid target format
+
+ Use wmdata:filename:dataname. See the data-source + format. +
+
+

Editor save, upload, stale-history and deletion failures may use descriptive translated + messages rather than a bracketed code. See troubleshooting for those + workflows.

+
+ +
+
+ + diff --git a/docs/pages/faq.html b/docs/pages/faq.html index 0206a494..ff366fa4 100644 --- a/docs/pages/faq.html +++ b/docs/pages/faq.html @@ -1,337 +1,211 @@ - - - - - - PHP Weathermap v0.98a - FAQ & Useful Tips - - - - - - - -
- - -

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.

- -

If something isn't described here, - check the cacti.log for errors. Weathermap usually produces a - useful error message if there is a problem. Next, try setting Cacti's Log - Level to DEBUG for 10 minutes, and then have a look in cacti.log. Don't - forget to turn the Log Level back down again!

- -
-
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 still have a non-working - command-line PHP - - Debian and derivatives (Ubuntu) can suffer from this.

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?). Also, some packaged PHP systems (MAMP, - XAMPP, WAMP etc) have the module installed, but disabled by default. - Check your php.ini to see if there is a commented-out line like - 'extension=php_gd.dll'.

- -

In 0.91 and newer, you may find the check.php to be useful when - figuring out which php.ini and php version you should be looking at - - http://yourserver/plugins/weathermap/check.php for the webserver - (editor/rebuild now) version, and - php check.php from the command-line for the CLI (Cacti - Poller/command-line tool) version.

- -
- -
I don't see ANYTHING in the logs when - using the Cacti plugin.
- -

Check if this is still the case when Weathermap is the only - plugin. If a plugin dies completely, it takes the poller and any - remaining plugins with it. This appears to be a problem with some older - versions of 'Reports' in particular, where anything listed after Reports - in the plugins[] list will not be run.

- -
- -
I get an error message about - function_exists()
- -

This is PHP telling you that a function that Weathermap requires - is not available in your PHP installation. Usually, it's to do with - either GD, or FreeType. It can be that you have those libraries, but not - current enough versions, or versions compiled without particular - options. For example, it's possible to have FreeType installed, GD - installed, the php-gd module installed, but that the GD library wasn't - compiled with FreeType - support so they don't know how to talk to each other. This - tends to be less of a problem on packaged systems than where you build - your own libraries.

- -

In 0.91 and newer, you may find the check.php to be useful when - figuring out which php.ini and php version you should be looking at, and - which functions might be missing - - http://yourserver/plugins/weathermap/check.php for the webserver - (editor/rebuild now) version, and - php check.php from the command-line for the CLI (Cacti - Poller/command-line tool) version.

- -
- -
My maps don't get created/updated (or "This - map hasn't been created yet")
- -

This is almost always a permissions problem. Look in your - cacti.log for lines starting WEATHERMAP to see what is going - wrong.

- -
I've defined some OVERLIBGRAPH lines, but - nothing appears in the map HTML when I use the command-line tool.
- -

For historical reasons, the default format for HTMLSTYLE is - 'static' which avoids javascript. To get the overlib graphs to appear - you need to have 'HTMLSTYLE overlib' near the top of your map - configuration file.

- -
When I use OVERLIBGRAPH and the - pointer is near the right side of the screen, the floating graph - disappears off the side of the screen...
- -

If you set OVERLIBWIDTH and OVERLIBHEIGHT correctly, then - Weathermap can make a better guess about whether to show the map to the - left or right. Be careful to set them to the correct value, or you may - see strange 'flashing' graphs. The easiest way is to right-click on the - graph in your browser and read the sizes from the Properties panel.

- -

Typically one size is right for all your graphs, so this is a good - example of something you can add into NODE DEFAULT (or LINK DEFAULT).

- -
- -
The value from my RRD data is much too - big!
- -

Is it about 8 times too big, by any chance? Historically, - Weathermap was mainly used for SNMP Interface statistics, which use - bytes-per-second counters ("octet counters" in SNMP-speak). Because of - this, the standard RRD datasource plugin multiplies everything by 8, to - get back to bits-per-second. New in 0.9, you can get the 'raw' value - from an RRD file by using - 'gauge:' as a prefix.

If the - value is wrong by some other constant factor, you can use the 'scale:' - prefix to multiply or divide by that factor - - e.g divide by 1000 to turn a milliseconds value into a 'real' seconds - value, or multiply by 1024 to get a kilobytes values from a megabytes - one.

- -
The timestamp on my map is all wrong!
- -

I have not seen this one myself, but a Chinese user has, and it - seems that PHP doesn't always use your system timezone correctly. The - fix is to edit php.ini to change date.timezone

- -
Weathermap just dies without warning on my - Debian/Ubuntu system - -
OR... I get a blank screen in the editor when I add a node - -
OR... I get a segmentation fault when Weathermap runs
- -

- It's a GD bug. It's documented - here, - and the reason it mainly affects Debian is that Debian links to the - system GD (version 2.0.33) not the built-in PHP one (2.0.28ish). For - whatever reason, the problems aren't present in the PHP GD library, - which has a different alpha-blending implementation as far as I can see - from the docs.

- -

The bugs are apparently fixed in GD 2.0.34, which has been released - and is in Debian unstable. Users report that upgrading to the version of - libgd2-xpm from unstable will fix this problem if you can't wait, or - recompile PHP to use it's own GD library.

- -

Since 0.95, there is a small program supplied with Weathermap to test - for this problem. Run - php check-gdbug.pgp in the weathermap directory to see if - it really is this problem that affects you.

- -

There is more information about fixing this issue for Debian Etch - (and perhaps also Ubuntu Edgy) in - this Cacti - Forum thread.

- -
- -
Where can I find some icons to use with - Weathermap? Why don't you have any supplied with it?
- -

- There are plenty of sources online. A good google search would be 'visio - network icons'. Some to get you started: - -

As for the second part, I can't draw, and I don't know of any - freely distributable icons. Feel free to draw some for me, and make them - open source.

- -
- - - -

You can create a NODE with no links and no label, but with an - ICON. The ICON is your logo. You can also use this to embed images from - somewhere else - even dynamically produced ones - - how about MRTG graphs or RRD stripgraphs embedded in your map?

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

- You can use the VIA keyword to make a link go - around corners.: - -

- 
LINK bendylink 
- NODES node1 node2 
- VIA 200 300 
- VIA 360 240 
-
-

- -
- -
I need to have more than one link from node - A to node B, but they just overlap...how can I do this?
- -

See - this - article for more about parallel links.

- -
- -
I still have two links, but I use MLPPP, - and I want to see a single link on the map for both physical lines.
- -

See - this - article for more about parallel and aggregated links.

- -
- -
When will you make the editor work - like XYZ?
- -

Adding the editor in 0.7 has made adding a new core weathermap - into something that needs more consideration. Anything that dramatically - changes how you make a map (like the LINK DEFAULT and NODE DEFAULT - changes for 0.7) should mean a similarly big change in the editor. All - the options should really be editable from the editor too. In reality, - just getting the editor to run smoothly on more than one browser is - sometimes painful, let alone re-tooling it to add new features. With - that all said, there very likely will be a new version of the editor in - 0.9, with drag & drop editing, and (more) complete support for all - the new features since 0.6 (which is the version that the editor really - was written for - - it was written before I added new 0.7 features. D'oh!).

- -
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 an open source 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. Obviously, things that - I want are always sensible and useful:-) .

- -

In the past, people have paid to have features added. I have a day - job which pays for my food and my mortgage, so this isn't - always a possibility, but it sometimes is. If it's a good idea, - then I'll probably add it anyway, but if it's something special to you, - or that you want in a particular timescale, then maybe we can talk!

- -
- -
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, feel free to - make a - donation, or send a gift, though. However, I do like to - hear from - users anyway - - it's nice to know that people do use this thing.

-
-
- - - + + + + + + Troubleshooting and common questions — Network Weathermap 2.0 + + + + +
+ Network Weathermap 2.0 +

Cacti plugin manual

+
+
+ +
+

Troubleshooting and common questions

+

Start with the WEATHERMAP messages in Cacti's log and the timestamp on the map. A saved + editor change, a newly rendered map and an updated Cacti graph happen at different stages. + Checking which one has stopped updating will help narrow down the problem.

+
+

The viewer is blank or stale

+

Check registration, active status, map permissions, rendering interval and the poller + log. Confirm the poller can read the configuration, images/fonts and RRDs and write output. + A successful editor save does not force a poller run. Check that the browser is showing the + intended map and installation.

+
+
+

There are no Weathermap log messages

+

Confirm the plugin is installed/enabled and the Cacti poller is running. Check whether + rendering is disabled or scheduled less frequently. Enable the plugin Debug Mode + temporarily when needed, reproduce one cycle, then restore the setting to avoid unnecessary + log volume.

+
+
+

Changes do not save or selection does not apply

+

In a properties dialog, select a candidate then click Use interface/Add/Replace as + appropriate, followed by Save. Cancel discards dialog edits. Check errors, + destination-directory write permissions and concurrent changes in other tabs. Refresh and + reopen the object to verify the saved result. Do not repeatedly overwrite a map someone + else is editing.

+
+
+

An interface is missing from search

+

Use a shorter phrase from the device/data-source name, interface index or description. + Browse all and use Next/Previous results; only up to 100 matches are returned per page. + Confirm graph permissions and that Cacti has created the interface graph and data source. + The interface picker uses the standard interface query; an arbitrary graph template is not + necessarily an assignable traffic interface. Identical graph titles need clearer names in + Cacti.

+
+
+

Hover graphs are missing or show the wrong data

+

Confirm the map has the intended OVERLIBGRAPH URL and the viewer account can open that + Cacti graph directly. Graph IDs and data-source IDs are different. Traffic sources set the + map reading; preview URLs set images. If a wrong preview remains, inspect main versus + additional preview separately. A CPU preview does not replace traffic measurements. Custom + or remote preview URLs depend on their target server and authentication.

+
+
+

A hover popup is too wide or goes off screen

+

The current viewer fits previews to the browser window. First check the graph URL's + graph_width and graph_height, and try the popup at normal browser + zoom. A custom image can have very different dimensions from a Cacti graph.

+

The older OVERLIBWIDTH and + OVERLIBHEIGHT directives are still + recognised. They supply size hints; they do not request a different graph from Cacti. + Change the image URL or hover defaults to change the graph itself.

+
+
+

Values are eight times too large, or utilisation is wrong

+

Ordinary RRD traffic values are bytes/sec and are converted to bits/sec. Use gauge: for + values that should not receive that conversion, such as percentage CPU. Check DS names, + first-endpoint direction, capacity, aggregation and any scale factors. 1G equals 1000M with + KILO 1000. An Errors graph is not a traffic graph. See the data-source guide.

+
+
+

A traffic spike is visible now but absent from a preview

+

Map snapshots and graphs may cover different timestamps or consolidation intervals. + Compare the map's render time with graph time range, resolution and cache/Boost state. + Refresh the full Cacti graph and compare the same period before concluding that the + measurement is lost. Sharper preview images do not create additional historical + samples.

+
+
+

Undo/Redo is unavailable or refuses a restore

+

Close the dialog first. Only the last two saved changes in that map/tab/session are + available. A new edit after Undo clears Redo; concurrent map or dependency changes + invalidate old snapshots. Check writable private PHP temporary storage and browser + tab-coordination support. Storage limits retain up to eight histories and 8 MiB per + authenticated session; inactive histories expire after four hours. Image uploads and + configuration-file deletion are not covered.

+

History uses the browser's Web Locks API, with a SharedWorker fallback, to coordinate + tabs safely. If neither is available, the editor disables history while keeping normal + editing available. Check browser support and the page's secure context when both buttons + remain unavailable after a successful edit.

+
+
+

Curved comments remain straight

+

Use a TrueType comment font and enable Follow link curve in Map Style. Via Style + determines the route separately. Text uses straight fallback for unsafe bends or + insufficient space. Move the comment percentage, shorten it or adjust the route. Bitmap + fonts cannot provide the same curved glyph rendering.

+
+
+

Uploading or deleting an image fails

+

Use PNG/JPEG/GIF within 5 MB and four million pixels; PHP/web-server limits can be + lower. Check the library directory permissions. Referenced images cannot be deleted, + including references found through includes. Remove assignments first. SVG uploads and + symlink management are not supported by the image form.

+
+
+

Rendering fails, fonts are missing or labels are unreadable

+

Check GD image-format support, FreeType, font file paths and PHP memory limits in the + actual rendering environment. Large canvases and images need more memory. Web PHP and + poller CLI PHP can differ. Review logs for the concrete error rather than applying old + Debian/PHP 4 workarounds. Cacti themes style the UI; map colours and fonts are configured + separately.

+
+
+

A data-source dependency is unavailable

+

Check the selected source's requirements: local RRD access/RRDtool, PHP SNMP, fping or a + Cacti integration. Do not install an unrelated PHP module just because an old manual says + so. Read the exact source warning and confirm whether the dependency exists under the + poller account.

+
+
+

A PHP function or class is missing

+

Confirm the installed plugin files belong to one consistent release and that Cacti/PHP + versions meet requirements. Verify required extensions under both PHP environments. Do not + copy random older libraries into the plugin to silence the error.

+
+ +
+

How do I bend a link around other objects?

+

Open Link Properties and choose Via, then click the canvas to place a + bend. Via Style chooses a curved or angled route. In raw configuration, each VIA adds a point along the route:

+ 
LINK uplink
+ NODES router switch
+ VIA 200 100
+ VIA 360 100
+

The endpoints must already exist. Moving a comment along a link changes its text + position; it does not add a bend.

+
+
+

Two links between the same nodes overlap

+

Give each link its own via point so the paths pass on different sides. For more control, + use endpoint offsets in NODES; the reference + includes pictures and examples of parallel links. Each link keeps its own traffic source, + capacity and graph URLs.

+

If you want one arrow showing the total instead, use combined traffic sources. That changes what is measured, rather + than just separating the lines visually.

+
+
+

Combining sources did not combine the graphs

+

This is expected: TARGET sums readings separately for IN and OUT, while INFOURL and + OVERLIBGRAPH remain independent. Create a matching aggregate graph in Cacti if you want a + historical total, then configure its URLs. Separate links are often clearer for main/backup + circuits.

+
+
+

A setting is not exposed by the form

+

Use Edit Raw Configuration and the configuration reference for supported expert options. + Report missing workflows or unclear labels to the Cacti plugin issue tracker with a + concrete example; older claims that the editor cannot upload images, edit colours or work + with curves no longer apply.

+
+
+

Timestamp timezone or locale looks wrong

+

Compare the PHP timezone and locale used by the poller with those used by web PHP. The + renderer uses Intl-based strftime-style formatting for timestamps. A timezone name in a + time: target is separate from the server timezone. Use a valid PHP timezone identifier and + check the displayed map timestamp after rendering.

+
+
+

Report a reproducible problem

+

Include Cacti, Weathermap, PHP and RRDtool versions, browser/theme, exact steps, + expected/actual results and relevant log lines. Identify release tag versus develop commit. + Provide a minimal sanitised map when practical. Remove community strings, passwords, tokens + and private addresses before posting publicly.

+
+ +
+
+ + diff --git a/docs/pages/install-cacti-editor.html b/docs/pages/install-cacti-editor.html index f842c5da..a7a5454d 100644 --- a/docs/pages/install-cacti-editor.html +++ b/docs/pages/install-cacti-editor.html @@ -1,206 +1,52 @@ - - - - - PHP Weathermap v0.98a - Installation - Cacti Plugin & Editor - - - - - - - -
- - - -

Installation

- -

Cacti plugin and Editor

- -

Requirements

- -

Before doing anything else, please verify that your - Plugin Architecture is working - properly with a simpler plugin, like - Links or - Tools. Weathermap is relatively - complex, and fault-finding both your Cacti Plugin Architecture and - Weathermap at the same time will make life harder for you!

- -

You will need the 'pcre' and 'gd' PHP modules in - both your command-line and server-side (mod_php/ISAPI) PHP. The - poller-process runs using the command-line PHP, and the editor uses the - server-side one. In some situations it is possible to have two completely - different PHP installations serving these two - - if you install from a package, then re-install from source, but to a - different directory, for example. The editor and the poller process should - both warn you if the part they need is not present.

- -

You can then use the pre-install checker to see if your PHP environment - has everything it needs. To do this, you need to run a special - check.php script, twice...

- -

First, go to http://yourcactiserver/plugins/weathermap/check.php to see - if your webserver PHP (mod_php, ISAPI etc) is OK. Then, from a - command-prompt run - php check.php to see if your command-line PHP is OK. If any modules - or functions are missing, you will get a warning, and an explanation of what - will be affected (not all of the things that are checked are deadly - problems).

- -

Before you start using it, you might want to change one PHP setting. - Weathermap uses a fair bit of memory by PHP standards, as it builds the - image for the map in memory before saving it. As a result, your PHP process - may run out of memory. PHP has a 'safety valve' built-in, to stop - runaway scripts from killing your server, which defaults to 8MB in most - versions (this has changed in 5.2.x). This is controlled by the - 'memory_limit =' line in php.ini. You may need to increase this to 32MB or - even more if you have problems. In fact, the current Cacti manual suggests - 128MB. These problems will typically show up as the poller process just - dying with no warning or error message, as PHP kills the script.

- -

Installation

- -

To use the Cacti plugin, you - must unpack the zip file into a directory called - '<cacti_root>/plugins/weathermap'. The zip contains a folder - called 'weathermap' already, so unzipping it in the plugins folder should do - the job.

- -

File Permissions

- -

- You will need to change the permissions on the - output directory, so that the Cacti poller process can write to it. - This is the same as you would have done for the - rra directory while installing Cacti itself originally. For a *nix - system, it will be something like: - -

- 
-                                chown cactiuser output
-
-
- -

Getting Started

- -

Log in to the Cacti application, and go to the Plugin Management page. - You should see the Weathermap plugin as an uninstalled plugin. Click the 'install' icon -next to its name, and then click the 'enable' icon that appears next to that. If you are logged in -as the 'admin' user, you should see the 'Weathermap' tab appear at the top of the Cacti page.

- -

That's it! The Weathermap plugin is installed.

-

To allow other users to see it, you need to go to the User Management page in Cacti, and grant those users -the extra permissions that should appear there now, to either View Weathermaps (for customers) and/or Manage Weathermaps (for admin users).

- -

To go further, you need - some weathermap configuration files to define your maps. You can do this in - two ways - - using the Web-based map editor, or by editing the text-based configuration - files directly.

- -

To use the editor, you need to make a few more changes (see below).

- -

To learn more about actually using the Cacti plugin, see the - Cacti Plugin page.

- -

The Editor

- -

Once you have weathermap itself working, continue onto the editor:

- -

- Copy the editor-config.php-dist file to - editor-config.php. If you want to be able to pick data sources from - your Cacti installation by name, edit the file and make sure that the line - that sets - $cacti_base is correct, and that the base URI below that is also - correct for your Cacti installation (these two lines are marked CHANGE in - the file). -

- -

- Make sure that your webserver can write to the configs directory. To do - this, you need to know which user your webserver runs as (maybe 'nobody', - 'www' or 'httpd' on most *nixes) and then run: - -

- 
chown www configs
-                                chmod u+w configs
-
- - In a pinch, you can just chmod 777 configs, but this - really isn't a recommended solution for a production system.

- -

On Windows, the same applies - - the user that runs the webserver runs as should have permissions to write - new files, and change existing files in the configs folder.

-

- -

Since version 0.98, you no longer need to edit the editor.php to enable it unless - you want to use the editor outside of Cacti. Otherwise, you can edit existing maps - by clicking on their name in the list of maps in the Cacti Manage..Weathermaps page, or - by clicking the 'Weathermap Editor' link at the bottom of the page to create new - maps or edit maps not currently being used.

-

You will need to have the Cacti permission 'Edit Weathermaps' to be able to do this.

- -

Please see the - editor manual page for more about - using the editor! And check the 'CLI Editor installation' page for information - about using the editor without Cacti integration. -

- -

You can also edit an existing map from the Cacti web interface, by - choosing Manage..Weathermaps and then clicking on the name of a config file - in the list of active maps. The editor will open with that map loaded.

- -

- Important Security Note: The editor allows - anyone who can access editor.php to change the configuration files - for your network weathermaps. There is no authentication built-in for - editing, except with the Cacti Plugin. This is why direct access to the - editor is disabled by default - - the editor won't work until you choose to make it work, or give permissions in Cacti. It's recommended - that you either: - -

  • change the ownership of configuration files so that the editor can't - write to them once they are complete, or
  • use your webserver's - authentication and access control facilities to limit who can access the - editor.php URL. On apache, this can be done using the FilesMatch directive - and mod_access.
    • -
-

- -
- + + + + + Enabling the Cacti map editor — Network Weathermap 2.0 + + + + +
+ Network Weathermap 2.0 +

Cacti plugin manual

+
+
+ +
+

Enabling the Cacti map editor

+

The 2.0 editor is part of the integrated Cacti plugin. There is no separate editor.php + installation or editor-config.php setup.

+
    +
  1. Complete plugin installation. +
    2. +
  2. Grant management access through Cacti, then review map permissions.
    3. +
  3. Give the web service account the configuration and optional image-library permissions + described in the installation guide.
    4. +
  4. Open a map using Edit Map. Add a test node, save, reopen and confirm the change. Test + Undo/Redo, then verify poller-generated viewer output separately.
    5. +
+

Use the editor guide for the current controls. The troubleshooting guide covers denied access, failed saves and blank output.

+ +
+
diff --git a/docs/pages/install-cacti.html b/docs/pages/install-cacti.html index 0457f63d..03f2af38 100644 --- a/docs/pages/install-cacti.html +++ b/docs/pages/install-cacti.html @@ -1,140 +1,141 @@ - - - - - PHP Weathermap v0.98a - Installation - Cacti Plugin - - - - - - - -
- - - -

Installation

- -

Cacti plugin

- -

Requirements

- -

Before doing anything else, please verify that your - Plugin Architecture is working - properly with a simpler plugin, like - Links or - Tools. Weathermap is relatively - complex, and fault-finding both your Cacti Plugin Architecture and - Weathermap at the same time will make life harder for you!

- -

You will need the 'pcre' and 'gd' PHP modules in - your command-line PHP. The poller-process runs using the - command-line PHP which is not always the same as the server-side one. In - some situations it is possible to have two completely different PHP - installations serving these two - - if you install from a package, then re-install from source, but to a - different directory, for example. The poller process should warn you if the - part it needs is not present.

- -

Before you start using it, you might want to change one PHP setting. - Weathermap uses a fair bit of memory by PHP standards, as it builds the - image for the map in memory before saving it. As a result, your PHP process - may run out of memory. PHP has a 'safety valve' built-in, to stop - runaway scripts from killing your server, which defaults to 8MB in most - versions (this has changed in 5.2.x). This is controlled by the - 'memory_limit =' line in php.ini. You may need to increase this to 32MB or - even more if you have problems. In fact, the current Cacti manual suggests - 128MB. These problems will typically show up as the poller process just - dying with no warning or error message, as PHP kills the script.

- -

Installation

- -

To use the Cacti plugin, you - must unpack the zip file into a directory called - '<cacti_root>/plugins/weathermap'. The zip contains a folder - called 'weathermap' already, so unzipping it in the plugins folder should do - the job.

- -

You can then use the pre-install checker to see if your PHP environment - has everything it needs. To do this, you need to run a special - check.php script, twice...

- -

First, go to http://yourcactiserver/plugins/weathermap/check.php to see - if your webserver PHP (mod_php, ISAPI etc) is OK. Then, from a - command-prompt run - php check.php to see if your command-line PHP is OK. If any modules - or functions are missing, you will get a warning, and an explanation of what - will be affected (not all of the things that are checked are deadly - problems).

- -

File Permissions

- -

- You will need to change the permissions on the - output directory, so that the Cacti poller process can write to it. - This is the same as you would have done for the - rra directory while installing Cacti itself originally. For a *nix - system, it will be something like: - -

- 
-                                chown cactiuser output
-
-
- -

Getting Started

- -

Log in to the Cacti application, and go to the Plugin Management page. - You should see the Weathermap plugin as an uninstalled plugin. Click the 'install' icon - next to its name, and then click the 'enable' icon that appears next to that. If you are logged in - as the 'admin' user, you should see the 'Weathermap' tab appear at the top of the Cacti page.

- -

That's it! The Weathermap plugin is installed.

-

To allow other users to see it, you need to go to the User Management page in Cacti, and grant those users - the extra permissions that should appear there now, to either View Weathermaps (for customers) and/or Manage Weathermaps (for admin users).

- -

To go further, you need - some weathermap configuration files to define your maps. You can do this in - two ways - - using the Web-based map editor, or by editing the text-based configuration - files directly.

- -

To use the editor, you need to make a few more changes.

- -

To learn more about actually using the Cacti plugin, see the - Cacti Plugin page.

- -
- + + + + + Installing with Cacti — Network Weathermap 2.0 + + + + +
+ Network Weathermap 2.0 +

Cacti plugin manual

+
+
+ +
+

Installing with Cacti

+

Install this plugin inside an existing Cacti installation. Follow the + requirements of that Cacti release as well as the plugin requirements below.

+
+

Requirements

+
    +
  • Cacti 1.2.29 or later, as declared in the plugin's INFO file.
    • +
  • A PHP version and extensions compatible with your Cacti release. GD must support the + image formats you use; FreeType is needed for TrueType labels and curved comments. Enable + PHP intl for the renderer’s locale-aware timestamp formatting.
    • +
  • A working Cacti poller and configured RRDtool executable for RRD-based maps.
    • +
  • Filesystem permissions for configuration saves, generated output and optional image + uploads. The web and poller service accounts may differ.
    • +
+

Do not follow the old PHP 4, Cacti 0.8.x or separate Plugin Architecture instructions. + Do not install PEAR solely on the assumption that the integrated editor requires it; the + legacy command-line wrapper has its own dependencies.

+
+
+

Install and enable

+
    +
  1. Back up an existing plugin before replacing files; use the + upgrade checklist for existing installations. +
    2. +
  2. Download the desired release from the official releases. Place its + contents under <cacti_root>/plugins/weathermap/. GitHub archives can + have a versioned top-level directory: rename that directory to weathermap. + Verify that INFO and setup.php sit directly inside it, not in a nested folder. +
    3. +
  3. Configure the permissions described below.
    4. +
  4. In Cacti Plugin Management, install and enable Weathermap. Database setup/upgrades + are handled by the plugin.
    5. +
  5. Grant the necessary view/manage permissions through Cacti User Management or User + Groups. Review per-map permissions too.
    6. +
  6. Create a small map, register it in management if needed, and confirm rendering during + a normal poller cycle.
    7. +
+
+
+

Filesystem permissions

+

Identify the actual PHP web account and poller account first. Use ownership, a dedicated + shared group or ACLs appropriate to your system; avoid blanket chmod 777 + instructions.

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
LocationAccess needed
configs/ and filesWeb account needs read/write for editing and permission to create replacement + files in the destination directory. Poller needs read access. Included files + require their own appropriate permissions.
output/Poller needs write access for rendered maps and thumbnails; the web server + needs access to serve them.
images/objects/ and images/backgrounds/Web account needs write access for uploads/deletion; renderer needs read + access.
PHP service temporary directoryPrivate history storage must be writable by the web account. It must not be + published by the web server.
Fonts and RRD filesRendering account needs read access; RRDtool and any selected data-source tools + must be executable.
+
+

SELinux/AppArmor policy and filesystem mount options may also affect writes. Check them + if ownership looks correct but saves fail. Preserve the application's web-server + protections; do not publish backup archives or configuration copies.

+

The bundle includes .htaccess restrictions in private directories such as + configs/ and lib/. Apache must be configured to honour those + files; other web servers need equivalent rules. Check a known private file URL, not just a + directory listing: it should be denied rather than reveal its contents. Keep the + documentation, viewer and image endpoints available as intended.

+
+
+

Verify installation

+

Check both the web PHP and CLI PHP environments: they may use different configuration + files and extensions. Validate GD/FreeType and RRDtool availability through your normal + Cacti/PHP diagnostics. The bundled legacy check.php is a supplemental + diagnostic, not proof that every modern requirement is satisfied, and its output includes + server details.

+

In the editor, save a node and reopen it. In the viewer, confirm the generated map and + timestamp. Assign a traffic interface and verify the graph, direction and capacity. Review + WEATHERMAP messages in Cacti's log. A saved configuration is not proof that the poller can + render it.

+
+ +
+
diff --git a/docs/pages/install-cli-editor.html b/docs/pages/install-cli-editor.html index 78955494..ae57e63a 100644 --- a/docs/pages/install-cli-editor.html +++ b/docs/pages/install-cli-editor.html @@ -1,208 +1,45 @@ - - - - - PHP Weathermap v0.98a - Installation - Command-Line Tool and Editor - - - - - - - -
- - -

Installation

- -

Command-Line Tool and Editor

- -

Requirements

- -

You will need the 'pcre' and 'gd' PHP modules in - both your command-line and server-side (mod_php/ISAPI) PHP. The - command-line tool runs using the command-line PHP, and the editor uses the - server-side one. In some situations it is possible to have two completely - different PHP installations serving these two - - if you install from a package, then re-install from source, but to a - different directory, for example. The editor and the CLI tool should both - warn you if the part they need is not present.

> - -

The command-line tool uses the Console_Getopt - PEAR module. This comes as standard - with PEAR, so you should be able to just install PEAR to get it. This may be - a seperate package/port/RPM on your system, or you may need to install it - from pear.php.net

- -

Before you start using it, you might want to change one PHP setting. - Weathermap uses a fair bit of memory by PHP standards, as it builds the - image for the map in memory before saving it. As a result, your PHP process - may run out of memory. PHP has a 'safety valve' built-in, to stop - runaway scripts from killing your server, which defaults to 8MB in most - versions (this has changed in 5.2.x). This is controlled by the - 'memory_limit =' line in php.ini. You may need to increase this to 32MB or - even more if you have problems. These problems will typically show up as the - process just dying with no warning or error message, as PHP kills the - script.

- -

Installation

- -

Unpack the zip file into a directory somewhere. If you are intending to - use the browser-based editor, then the directory that you unpack the zip - file into should be within the 'web space' on the web server that runs your - data-collection application (that is, Cacti, MRTG, or similar) - - /var/www/html, /usr/local/www/data or whatever it is for you.

- -

You can then use the pre-install checker to see if your PHP environment - has everything it needs. To do this, you need to run a special - check.php script, twice...

- -

First, go to http://yourcactiserver/plugins/weathermap/check.php to see - if your webserver PHP (mod_php, ISAPI etc) is OK. Then, from a - command-prompt run - php check.php to see if your command-line PHP is OK. If any modules - or functions are missing, you will get a warning, and an explanation of what - will be affected (not all of the things that are checked are deadly - problems).

- -

- 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 (usr/bin/php, or /usr/local/bin/php usually).
    • - -
  • Around line 30 or so, you may need to change the path to your - rrdtool executable, if you are intending to use RRD-based datasources - for your maps.
    • -
-

- -

Testing

- - That should be it! You should be able to run - -

- -
- ./weathermap - -
- - or - -
- - php weathermap (on Windows you will need this one) -

from a shell or command prompt, and get a (rather boring) - weathermap.png file in return. If you don't, you - should get some kind of error to help you figure out why.

- -

Editor

- -

Once you have weathermap itself working, continue onto the editor:

- -

- If you use Cacti, and want to be able to pick - data sources from your Cacti installation by name, you should use the - integrated access to the editor described on the 'Install Cacti + Editor' page. -

- -

- Make sure that your webserver can write to the configs directory. To do - this, you need to know which user your webserver runs as (maybe 'nobody', - 'www' or 'httpd' on most *nixes) and then run: - -

- 
chown www configs
-                                chmod u+w configs
-
- - In a pinch, you can just chmod 777 configs, but this - really isn't a recommended solution for a production system.

- -

On Windows, the same applies - - the user that runs the webserver runs as should have permissions to write - new files, and change existing files in the configs folder.

- -

- -

Since version 0.97, you now also need to enable the editor. The reason is - so that you can't have the editor enabled without knowing about it. The - editor allows access to your config files without authentication, so you - should consider using features in your webserver to limit who can access - editor.php. For example, on an Apache server, something like: - - 

-                            <Directory /var/www/html/weathermap>
-                                <Files editor.php>
-                                    Order Deny,Allow
-                                    Deny from all
-                                    Allow from 127.0.0.1
-                                </FilesMatch>
-                            </Directory>
-
- When you are happy that the world can't edit your maps, then enable the - editor. This is done by editing the top of editor.php and changing - $ENABLED=false; to $ENABLED=true;

- -

- You should now be able to go to - http://yourserver/wherever-you-unpacked-weathermap/editor.php in a browser, - and get a welcome page that offers to load or create a config file. That's - it. All done. Please see the - editor manual page for more about - using the editor! -

- -

- Important Security Note: The editor allows - anyone who can access editor.php to change the configuration files - for your network weathermaps. There is no authentication built-in for - editing, except with the Cacti Plugin. This is why direct access to the - editor is disabled by default - - the editor won't work until you choose to make it work, or give permissions in Cacti. It's recommended - that you either: - -

  • change the ownership of configuration files so that the editor can't - write to them once they are complete, or
  • use your webserver's - authentication and access control facilities to limit who can access the - editor.php URL. On apache, this can be done using the FilesMatch directive - and mod_access.
    • -
-

- -
- + + + + + About the former standalone editor — Network Weathermap 2.0 + + + + +
+ Network Weathermap 2.0 +

Cacti plugin manual

+
+
+ +
+

About the former standalone editor

+

Older manuals described a separate editor.php and editor-config.php. Those are not the + integrated editor entry points supplied by this Cacti-maintained 2.0 bundle.

+

Use the Cacti editor, which uses Cacti + authentication and permissions. Do not expose an old standalone editor from a previous + release alongside it. For scripted rendering, see command-line + use. The original separate project has its own distribution and documentation.

+ +
+
diff --git a/docs/pages/install-cli.html b/docs/pages/install-cli.html index 961b58e5..ed26a438 100644 --- a/docs/pages/install-cli.html +++ b/docs/pages/install-cli.html @@ -1,123 +1,50 @@ - - - - - PHP Weathermap v0.98a - Installation - Command-Line Tool Only - - - - - - - -
- - -

Installation

- -

Command-Line Tool Only

- -

Requirements

- -

You will need the 'pcre' and 'gd' PHP modules in - your command-line PHP. The command-line tool runs using the - command-line PHP which is not always the same as the server-side one. In - some situations it is possible to have two completely different PHP - installations serving these two - - if you install from a package, then re-install from source, but to a - different directory, for example. The CLI tool should warn you if the part - it needs is not present.

- -

The command-line tool uses the Console_Getopt - PEAR module. This comes as standard - with PEAR, so you should be able to just install PEAR to get it. This may be - a seperate package/port/RPM on your system, or you may need to install it - from pear.php.net

- -

Before you start using it, you might want to change one PHP setting. - Weathermap uses a fair bit of memory by PHP standards, as it builds the - image for the map in memory before saving it. As a result, your PHP process - may run out of memory. PHP has a 'safety valve' built-in, to stop - runaway scripts from killing your server, which defaults to 8MB in most - versions (this has changed in 5.2.x). This is controlled by the - 'memory_limit =' line in php.ini. You may need to increase this to 32MB or - even more if you have problems. These problems will typically show up as the - process just dying with no warning or error message, as PHP kills the - script.

- -

You can then use the pre-install checker to see if your PHP environment - has everything it needs. To do this, you need to run a special - check.php script. From a command-prompt run - php check.php to see if your command-line PHP is OK. If any modules - or functions are missing, you will get a warning, and an explanation of what - will be affected (not all of the things that are checked are deadly - problems).

- -

Installation

- -

Unpack the zip file into a directory somewhere. If you intend to just use - the 'traditional' hand-written text configuration files, then it can be - anywhere on the same server that runs your data-collection software (MRTG, - Cricket, Cacti).

- -

- 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 (usr/bin/php, or /usr/local/bin/php usually).
    • - -
  • Around line 30 or so, you may need to change the path to your - rrdtool executable, if you are intending to use RRD-based datasources - for your maps.
    • -
That should be it! You should be able to run -

- -
- ./weathermap - -
- - or - -
- - php weathermap (on Windows you will need this one) -

from a shell or command prompt, and get a (rather boring) - weathermap.png file in return. If you don't, you - should get some kind of error to help you figure out why.

- -
- + + + + + Command-line use in a Cacti installation — Network Weathermap 2.0 + + + + +
+ Network Weathermap 2.0 +

Cacti plugin manual

+
+
+ +
+

Command-line use in a Cacti installation

+

The bundled weathermap wrapper loads Cacti's + include/cli_check.php using a relative path and imports PEAR Console/Getopt. It + is not a self-contained modern installation package. Keep it in the Cacti plugin directory + and run from there.

+

For normal production generation, use the Cacti poller. To rebuild registered maps, use + php weathermap-cacti-rebuild.php under the poller account. See rendering.

+

For a one-off map, check wrapper dependencies and the configured RRDtool path first, then + use the command-line reference. Use explicit output paths + and avoid overwriting a registered map's output. A standalone-style generated page does not + add Cacti map access control to a publicly served file.

+ +
+
diff --git a/docs/pages/main.html b/docs/pages/main.html index 930be47d..e9e1088e 100644 --- a/docs/pages/main.html +++ b/docs/pages/main.html @@ -1,532 +1,183 @@ - - - - - PHP Weathermap v0.98a - Introduction - - - - - - - -
- - -
-

PHP Weathermap is licensed under the MIT license. See LICENSE file for complete license.

- -

Parts of this software distribution are by other authors. Please see - the README file for attribution and license details.

-
- -
-
-

PHP Weathermap

- -

-

- -

Sample output from php-weathermap, using data - collected by Cacti and MRTG. - -
Larger - version

-
- -

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, plain tab-seperated text 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 popup 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.

- -

To get a better idea of what is possible, see the - example map that comes with this manual.

- -

Requirements

- -

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, TrueColour and FreeType - support
  • You will need command-line (aka shell/ssh/telnet) access - to the server which will host the maps.
    • -
  • You will need the PEAR PHP extension system - this comes with PHP when it's built from source, but it is sometimes a separate package - if you install PHP from modules (e.g. php-pear on Debian/Ubuntu Linux).
    • -
  • 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. - -

To use the Cacti plugin, you will need a recent version of Cacti, and - possibly the matching Cacti Plugin Architecture, from - Jimmy Conner's Cactiusers.org. From Cacti 0.8.8 onwards, - the Plugin Architecture is built-in.

- -

Support

- -

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. Typically contains - discussion of test or beta versions too, when they are - circulating.
- -
php-weathermap-announce@thingy.com
- -
Very low volume list for new version announcements and other - similarly rare events!
-
- - More information about how to subscribe to the mailing lists is - at - the website.

- -

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

- -

How to install Weathermap depends on how you intend to use it: - -

- -

Security

-

Weathermap has several features that can potentially give users more access than you intended to. This section describes - the risks, and possible ways to mitigate them.

-

First of all, there are quite a few folders in the weathermap distribution that don't need to be web-accessible. If you aren't' using the - Cacti plugin, then practically all of it can be blocked or moved elsewhere. If you are using Weathermap with Cacti, then you can still - deny ALL access from web users for the configs, output, lib and random-bits directories. The distribution comes with .htaccess files that - will do this for you if you have Apache, and you have enabled "AllowOverride All" for the Weathermap directory (it may be on by default - - you can test by trying to access http://yourserver/cacti/plugins/weathermap/lib/ - you should get a 403 Forbidden error.

-

Secondly, you should use additional access control (by IP or authentication) to limit who can access the editor.php and cacti-pick.php pages. The second of those - will allow someone accessing the page to see a list of all the datasources in your Cacti installation. The first one allows - anyone who can access it to edit your maps (logically enough). However, Weathermap includes a datasource plugin that - allow someone who can change the TARGET lines in a map to potentially run any command as the Cacti poller user. As of version 0.97b, this plugin - (external) is disabled by default.

- -

Any user with access to the editor can also see all your maps. In a shared or service provider environment, this may be - a Bad Thing.

- -

Running Weathermap

- -

There are two ways to run Weathermap.

If you are using the - Cacti plugin, then it will be run for you as part of the Cacti poller - cycle. You don't need to do anything special apart from add your map - configuration files, as explained in the - Cacti plugin notes.

- -

If you are using weathermap as a standalone tool, you do it using the - command line version. See the - CLI Reference for all possible - options, but a good starting point is something like:

- -
- 
php ./weathermap --config myconfigfile.conf --output mymap.png --htmloutput mymap.html
-
- -

You can skip the htmloutput and output parts if you have - HTMLOUTPUTFILE and IMAGEOUTPUTFILE lines in your configuration file.

- -

Usually, people want to run weathermap regularly (it's not a - requirement though!). To do that, you need to create a 'cron job' or - 'Task Scheduler Task' to run a command-line like the one above on a - regular basis. You probably already have a similar task setup to collect - the data that weathermap is reading. This is the same kind of thing.

- -

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

- -
- A simple NODE - 
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

- -
- A simple LINK - 
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.
    • -
- - 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
-

There are also settings to set which fonts and colours are used - for various elements of the map, where to position the colour-legend (if - at all), what files to output, and more advanced layout techniques. The - full list is in the - Config Reference.

- -

A Sample Config

Here's a - sample configuration, and here's what it produces (modified to work - a little better). 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 configuration file is also - in the docs directory of the distribution, should you want it. - - -
-A Sample Configuration File -
-# some initial comments...
-#
-# This sample configuration file demonstrates most of the basic features of
-# PHP Weathermap, along with some of the cosmetic and layout changes possible
-#
-#
-BACKGROUND background.png
-HTMLOUTPUTFILE example.html
-IMAGEOUTPUTFILE example.png
-TITLE Network Overview
-HTMLSTYLE overlib
-KEYPOS 10 400
-
-# define some new TrueType fonts - built-in ones go from 1 to 5, so start high
-FONTDEFINE 100 VeraIt 8
-FONTDEFINE 101 Vera 12
-FONTDEFINE 102 Vera 9
-
-KEYFONT 102
-
-LINK DEFAULT
-	BANDWIDTH 100M
-	BWLABEL bits
-	BWFONT 100
-	OVERLIBWIDTH 395
-	OVERLIBHEIGHT 153
-	WIDTH 4
-
-NODE DEFAULT
-	LABELFONT 101
-
-NODE transit
-	POSITION 400 180
-	LABEL TRANSIT
-
-# a little splash of background colour for these nodes
-NODE isp1
-	POSITION 250 100
-	LABEL ISP1
-		INFOURL http://www.isp1.com/support/lookingglass.html
-	LABELBGCOLOR 255 224 224
-
-NODE isp2
-	POSITION 550 100
-	LABEL ISP2
-	INFOURL http://www.isp2.net/portal/
-	LABELBGCOLOR 224 255 224
-
-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
-
-# this node has an icon, and so we push the label to the South edge of it, so it
-# can still be read
-NODE sync
-	LABEL Sync
-	ICON my_router.png
-	LABELOFFSET S
-	LABELFONT 2
-	POSITION 550 370
-# the icon is taken from a Nagios icon pack:
-#   http://www.nagiosexchange.org/Image_Packs.75.0.html?&tx_netnagext_pi1[p_view]=110&tx_netnagext_pi1[page]=10%3A10
-
-NODE site1
-	LABEL site1
-	POSITION 700 220
-
-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
-#
-# Site1 has two E1s, so we use NODE-offsets to allow them to run parallel
-#
-
-LINK sync-site1a
-	NODES sync:N site1:W
-	WIDTH 3
-	TARGET data/sync_traffic_in_257.rrd
-	BANDWIDTH 2M
-	OVERLIBGRAPH http://support.mynet.net/cacti/graph_image.php?local_graph_id=254&rra_id=0&graph_nolegend=true&graph_height=100&graph_width=
-	INFOURL http://support.mynet.net/cacti/graph.php?rra_id=all&local_graph_id=126
-
-LINK sync-site1b
-	NODES sync:E site1:SE
-	WIDTH 3
-	OVERLIBGRAPH http://support.mynet.net/cacti/graph_image.php?local_graph_id=255&rra_id=0&graph_nolegend=true&graph_height=100&graph_width=
-	TARGET data/sync_traffic_in_258.rrd
-	BANDWIDTH 2M
-	INFOURL http://support.mynet.net/cacti/graph.php?rra_id=all&local_graph_id=56
-
-#
-# site2 also has two links, but this time we use the VIA to curve the links
-#
-LINK sync-site2a
-	NODES sync site2
-	WIDTH 3
-	VIA 650 380
-	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
-	BANDWIDTH 1M
-	INFOURL http://support.mynet.net/cacti/graph.php?rra_id=all&local_graph_id=252
-
-LINK sync-site2b
-	NODES sync site2
-	WIDTH 3
-	VIA 650 420
-	TARGET data/sync_traffic_in_252.rrd
-	OVERLIBGRAPH http://support.mynet.net/cacti/graph_image.php?local_graph_id=228&rra_id=0&graph_nolegend=true&graph_height=100&graph_width=300
-	BANDWIDTH 1M
-	INFOURL http://support.mynet.net/cacti/graph.php?rra_id=all&local_graph_id=561
-
-#
-# ISP 1 has a several links, again, but they prefer to see one arrow, and the aggregate bandwidth
-#   so we use multiple TARGETs on one line, here, to sum the data
-
-LINK transit-isp1
-	NODES transit isp1
-	TARGET data/trans1_traffic_in_352.rrd data/trans1_traffic_in_378.rrd data/trans1_traffic_in_420.rrd
-	BANDWIDTH 10M
-	OVERLIBGRAPH http://support.mynet.net/cacti/graph_image.php?local_graph_id=355&rra_id=0&graph_nolegend=true&graph_height=100&graph_width=
-	INFOURL http://support.mynet.net/cacti/graph.php?rra_id=all&local_graph_id=633
-
-LINK transit-isp2
-	NODES transit isp2
-	TARGET data/trans1_traffic_in_438.rrd
-	BANDWIDTH 34M
-	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=265
-
-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=122
-
-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=237
-
-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=222
-
-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=228
-
-
- - -

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

-
- -
- + + + + + Getting started — Network Weathermap 2.0 + + + + +
+ Network Weathermap 2.0 +

Cacti plugin manual

+
+
+ +
+

Getting started

+ +

Weathermap turns monitored data into a diagram: nodes identify places or + devices; links show direction, traffic and utilisation. Cacti collects the data and generates + historical graphs. Weathermap presents an overview alongside those graphs.

+
+

Before you begin

+

Use Cacti 1.2.29 or later and the PHP environment required by your Cacti version, with + GD image support. The poller and web server may use different PHP configurations. See + installation and upgrading + before changing an existing system.

+

This is the Cacti-maintained fork. The separate Howard Jones project and its older + releases have different compatibility requirements.

+
+ +
+

Create a traffic map

+
    +
  1. Open Weathermap management with an account allowed to manage maps. Click the + + at the right of the green Weather Maps heading. Create a configuration + with a filename and title, then use the + beside that file to register it. + Back on the management page, click the map title to open its editor. See the + illustrated create-and-register walkthrough for each step.
    2. +
  2. Choose Add Node, then click its position on the canvas. Set a + display name and icon. Add the second endpoint.
    3. +
  3. Choose Add Link, then click the first and second node. The first + node defines the reference direction for IN and OUT.
    4. +
  4. Open the link properties. Search for the traffic interface by device, port or + description. Select a result, then click Use interface. Selection alone + does not apply it.
    5. +
  5. Set the link capacity, for example 1G or 500M into the + first node and 200M out. Choose Same As 'In' when both + capacities are equal.
    6. +
  6. Save. Check the map in the viewer after its next render, and confirm the selected + Cacti graph is the intended interface.
    7. +
+

The editor saves individual actions; there is no final whole-map Save button. Dialog + changes require their Save button. Viewer traffic changes when the map is generated, not + continuously as packets pass.

+
+
+

How to read a map

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ElementMeaning
NodesAn icon or label at a map coordinate. A node can also represent a device + measurement such as CPU, memory or host status.
LinksDirectional arrows between nodes. The measured values come from TARGET sources; + capacity determines the utilisation percentage.
Colour scaleMaps utilisation or another numeric value to a colour. A warm colour does not + by itself prove a device fault; inspect the configured scale and capacity.
CommentsDescriptive IN/OUT text, such as a circuit name or capacity. These are separate + from the numeric utilisation labels.
Hover and clickHover previews and click destinations show historical graphs or pages. They are + separate from the measurement used to colour the map.
+
+
+
+

Directions, units and capacity

+

IN means traffic into the first node in NODES first second; OUT + means traffic out of that node. Verify direction against the corresponding Cacti interface + graph. A reversed endpoint order can make a correct reading look backwards.

+

BANDWIDTH is capacity in bits per second. With the default KILO + 1000, 1G equals 1000M. K, M, G and T are supported. If a + custom map changes KILO, the conversion changes too. New implicit link capacities are 1000M + in each direction; loading a map retains explicitly configured capacities. Changing defaults + through Map Properties is a separate operation: see the + capacity-editing limitation before doing so.

+

A 200M reading on a 1G link is 20%. Adding a CPU preview does not change that reading. + Adding another measured traffic source does; see combining + sources.

+
+
+

A small configuration example

+

This example uses fixed values, so it needs no live interface. It illustrates the format + rather than providing a production monitoring configuration.

+ 
WIDTH 800
+HEIGHT 450
+TITLE Demonstration network
+KILO 1000
+KEYPOS 20 330 Traffic utilisation
+SCALE DEFAULT 0 50 0 180 0
+SCALE DEFAULT 50 80 255 180 0
+SCALE DEFAULT 80 100 220 0 0
+
+NODE router
+ LABEL Router
+ POSITION 180 180
+NODE switch
+ LABEL Switch
+ POSITION 620 180
+
+LINK uplink
+ NODES router switch
+ BANDWIDTH 1G
+ TARGET static:200M:100M
+ OUTCOMMENT Example uplink
+

For a live map, use the interface picker to insert your actual RRD source and graph + URLs. Do not copy graph IDs or RRD filenames from someone else's installation.

+
+
+

Access and safe administration

+

Cacti authentication, plugin realms and map permissions govern the integrated plugin. + Viewing a map does not grant permission to manage it or view every graph referenced by it. + Grant management only to trusted users: raw map syntax and advanced data sources can refer + to server files and external resources.

+

Use the normal Cacti login and permissions; do not expose old standalone editor scripts + or install an extra Plugin Architecture package. Keep backups outside the web root, follow + Cacti's web-server guidance, and avoid world-writable configuration or image directories. + The external-script data source is disabled in the bundle.

+
+ +
+

Help and reporting problems

+

Read troubleshooting and the error-code + reference. Report reproducible problems to the Cacti Weathermap issue tracker, or + ask on the Cacti forums. Include versions, relevant + WEATHERMAP log messages and a minimal configuration with credentials and private details + removed.

+
+ +
+
diff --git a/docs/pages/targets.html b/docs/pages/targets.html index e2de060f..0e841d23 100644 --- a/docs/pages/targets.html +++ b/docs/pages/targets.html @@ -1,685 +1,650 @@ - - - - - - PHP Weathermap v0.98a - Specifying <a href="config-reference.html#LINK_TARGET">TARGET</a> lines - - - - - - - -
- - -

Specifying TARGET lines

- -

The actual data-reading part of Weathermap is handled by Data Source - Plugins since version 0.9. These allow users or third-parties to easily add - new data sources into Weathermap without altering the core code.

- -

There are a number of plugins supplied as standard, which will be - described here. Each one uses a different format of TARGET string, which - contains the parameters the plugin needs to find your data. - All plugins return an 'in' and 'out' value, and some may set other - variables that can be accessed by - Special Tokens in strings. For - situations where there is only really one output, the 'out' value may just - be the same as the 'in'.

- -

Here are the details of the standard data source plugins:

- - - -
- - -

Static value

- -
TARGET static:invalue:outvalue -
- -
TARGET static:value -
- -

The simplest of all the plugins, static allows you to just set a value in - the config file itself. Sometimes this is useful for testing, or simple maps - of things like OSPF metrics. If only a single value is specified, it is used - for both input and output, just like the BANDWIDTH parameter.

- -

The values in the target string can use the same K,M,G,T suffixes as - BANDWIDTH.

- -
- -

RRDtool files

- -
TARGET - rrdfile.rrd:in_ds:out_ds -
- -
TARGET - gauge:rrdfile.rrd:in_ds:out_ds -
- -
TARGET - rrd:rrdfile.rrd:in_ds:out_ds -
- -
TARGET - scale:factor:rrdfile.rrd:in_ds:out_ds -
- -

This is the 'core' plugin for Weathermap. It reads data from rrd files, - created using Tobi Oetiker's RRDtool, - by tools like Cacti, MRTG, Cricket, NRG and so on.

- -

First of all, Weathermap needs to be able to find your rrdtool - executable. If you are using the Cacti plugin, then this information is - taken automatically from Cacti. If you are using the command-line tool, you - will need to edit - weathermap around line 29 to point to your rrdtool executable.

- -

TARGET formats

- -

If you only specify a filename, and no DS-names, the default DS names for - RRD files are 'traffic_in' and 'traffic_out', which works with the majority - of Cacti RRD files (those produced by the Interface Traffic template). For - MRTG-produced RRD files, the names are 'DS0' and 'DS1'. For Cricket - standard-interface RRD files, it would be '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, where you can - take the input data from one rrd file, and the output data from another.

- -

With no prefix, or with just 'rrd:' as a prefix, the data read - from the rrd file is assumed to be a standard SNMP interface counter, which - is a byte-rate. It automatically multiplies these by 8 to get a bit-rate for - the map. With the 'gauge:' prefix, this multiplication doesn't - happen, which is useful for non-bandwidth values, like SNR or - session-counts. Finally, you can use the 'scale:' prefix to multiply - by any factor - - suppose you have a value in seconds, and you want to show it in - milliseconds for example. Of course, you can also divide using this, by - using a scale factor that is less than 1 - - multiplying by 1/x is the same as dividing by x. Since 0.95, you can also - use negative scale factors - - useful to turn dB SNR into something weathermap can deal with.

- -

rrdtool adjustments

- -

By default, the plugin will read the last 800 seconds of data, and find - the most recent within that to use. You might need to make it read back - further, if you are updating your rrd files slowly. You can do this with the - SET command, by adding 'SET rrd_period 3000' (any value in seconds) at the - top of your map config file, before any NODE or LINK lines.

- -

Similarly, you can change the time that the plugin looks for data at from - the present to the past, by using 'SET rrd_start -1d' in the top section of - the config file. The full range of time-specification strings is at the - bottom of the - rrdfetch - manual page.

- -

If you are using a tool other than Cacti, then the default DS names of - traffic_in and traffic_out are probably wrong. You can change the defaults - for the whole config file by adding two SET lines to the top of the map - config file. For example, 'SET rrd_default_in_ds DS0' and 'SET - rrd_default_in_ds DS1' will make the default DS names DS0 and DS1 - respecively so MRTG users don't need to specify the DS names in every TARGET - line.

- -

For any other special rrdtool 'tweaks', you can SET rrd_options to a - string which is added directly to the rrdtool command-line. This should - allow for any changes that I haven't expected!

- -

Finally, if the TARGET filename doesn't begin with a - / it is usually assumed to be a relative path from the weathermap directory. - If you SET rrd_default_path to some other path in the global (top) section - of the map config file, you can change that assumption so that the DS plugin - looks somewhere else.

- -

Cacti-specific additions

- -

If the plugin detects that it is running within the Cacti poller process, - it defines a couple of useful global Hint Variables for Cacti users - - {map:cacti_path_rra} contains the path to the rra/ directory in your Cacti - installation, with no trailing slash, and {map:cacti_url} is the URL to the - front page of your Cacti installation, as known to the Plugin Architecture. - These can be used in the TARGET, INFOURL and OVERLIBGRAPH commands in - particular, to reduce a lot of duplication.

- -

Cacti poller_output support (aka Boost - support)

- -

If you are using Cacti as your data collector, and running Weathermap - from Cacti's poller, then there is another special feature, called - poller_output. Weathermap can intercept data as it is collected by Cacti, - and therefore avoid running lots of external rrdtool processes to collect - the data it needs to display your map. This is - especially useful if you are using TheWitness' Boost plugin, as the - data isn't written to the rrd files until some time after it is collected. - Even without Boost, it should provide a performance improvement, - particularly with large installations of Weathermap.

- -

To use this feature, a map-global variable needs to be set. Near the top - of your map config file, add 'SET rrd_use_poller_output 1'. The setting will - take a few poller cycles to take effect: during the first one, the - appropriate cacti data sources are identified based on the rrd filenames, on - the second cycle values will be collected, and on the third we'll have two - values, so any COUNTER datasources will begin to work properly. If the - poller_output feature fails to collect data, then the regular - rrdtool-running method will be attempted too.

- -

Because in poller_output mode, Weathermap is pulling data directly from - the Cacti database, it can also collect some other information that you - might find useful in your map. It takes all the data stored in the - host_snmp_cache table for the specified datasource, and dumps that into Hint - Variables. This table contains all the columns that you see when you are - picking which datasource to graph in Cacti, so for normal interface traffic, - it contains things like the interface speed, operational status, interface - description (your 'comment' name, usually) and so on. These are stored in - Hint Variables called 'cacti_cache variable' - - e.g. cacti_ifSpeed, or cacti_ifIP. It also sets cacti_host_id to be the - internal host_id from Cacti for the host containing this data source, and - the cacti_graph_id to be the local_graph_id of a graph that uses this DS in - Cacti. You can then use those to automatically add correct OVERLIBGRAPH and - INFOURL lines: -

- -
- 
 
- SET rrd_use_poller_output 1 
-
- LINK DEFAULT 
- SET cacti_use_ifspeed 1 
- INFOURL {map:cacti_url}/graph.php?local_graph_id={link:this:cacti_graph_id} 
- OVERLIBGRAPH {map:cacti_url}/graph_image.php?local_graph_id={link:this:cacti_graph_id}&rra_id=0&graph_nolegend=true 
-
- LINK uplink1 
- NODES a b 
- TARGET {map:cacti_path_rra}/router1_345_traffic_in.rrd 
-
- LINK uplink2 
- NODES a c 
- TARGET {map:cacti_path_rra}/router1_377_traffic_in.rrd 
-
- -

In this example, all each link needs to have defined is the TARGET - rrdfile, and which nodes it joins. The rest is supplied by this - plugin.

-
- -

As an additional sub-feature, if you add 'SET cacti_use_ifspeed 1' to either the - link or node, or any item it inherits settings from (e.g. DEFAULT) then - Weathermap will take the value of ifSpeed (or ifHighSpeed for 4G+ links) and - use it in place of the value defined in the map config file - - this allows you to do some basic dynamic configuration of Weathermap based - on Cacti, which in turn should pick up changes from the network device.

- -

Note that since the rrdtool program is not being run in - this mode, you can't use the "time-shifting" features described above - - those rely on using - real rrdtool files. If you are using poller_output to allow - Weathermap to work alongside Boost, then there is no workaround - - the data isn't in the .rrd files until Boost's own update process puts it - there sometime later.

- -

Performance Note:The additional queries to fill in the - interface information from the Cacti database can sometimes add significantly - to the runtime for the map. If you know you don't need the information, you - can disable those queries, while still using the poller_output support. To do this, - add 'SET rrd_no_cacti_extras 1' to the top of the map config file.

- -

RRDtool Aggregation

- -

XXX THIS NEEDS TO BE WRITTEN!

- -
- -

Tab-separated text

- -
TARGET textfile -
- -

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.

- -
-
A suitable tab-delimited data file
- -
link1 3M 4M 
-link2 66K 1.8M 
-link3 34.6K 113
-
- -
- -

MRTG .html file

- -
TARGET htmlfile -
- -

This plugin reads data from special comments in the HTML files generated - by MRTG. This is intended mainly for people using the 'old-style' MRTG .log - files. If you are using MRTG with an RRDtool backend, then it's probably - better to use the RRDtool plugin.

- -

The file should have an extension of .html or .htm to be recognised as an - MRTG file by Weathermap.

- -

Since 0.95, there are a few hint variables that will adjust the behaviour - of this datasaource:

- -
    -
  • SET mrtg_swap 1 - - (per-link/node) will swap the in and out values over
    • - -
  • SET mrtg_negate 1 - - (per-link/node) will make negate the value from the MRTG file. - Weathermap doesn't deal well with negative values yet, so this is - sometimes useful.
    • - -
  • SET mrtg_period d - - (per-link/node) allows you to choose between daily, monthly, weekly, - and yearly values - use 'd','m','w','y' - default is 'd'
    • - -
  • SET mrtg_value av - - (per-link/node) allows you to choose between average, minimum, maximum - and current values - use 'av','min','max','cu' - default is 'cu'
    • -
- -
- -

Cacti host status

- -
TARGET cactihost:hostid -
- -

This plugin reads the current status of a host from your Cacti database. - The hostid is visible in Cacti URLs when you click on links in the Devices - page. The return values for this plugin are numeric codes. It also sets a - Hint Variable called - state to a string, that can be nicer to use in an ICON filename, - for example - - possible values are 'up','down','disabled', and 'recovering'.

- - - - - - - - - - - - - - - - - - - - - - - - - -
Codestate value
0disabled
1down
2recovering
3up
5unknown
- -

It also sets the following additional Hint Variables, to use in a LABEL, - COMMENT or NOTES section as you see fit: - cacti_hostname, cacti_description, cacti_curtime, - cacti_avgtime, cacti_mintime, cacti_maxtime, - cacti_availability, cacti_faildate, and - cacti_recdate

. - -

An appropriate SCALE definition to get red, green, yellow and grey labels - based on the state of a host would be:

- -
-
SCALE cactiupdown 0 0.5 192 192 192 
-SCALE cactiupdown 0.5 1.5 255 0 0 
-SCALE cactiupdown 1.5 2.5 0 0 255 
-SCALE cactiupdown 2.5 3.5 0 255 0 
-SCALE cactiupdown 4.5 5.5 128 128 128
-
- -
- -

Cacti threshold status

- -
TARGET cactimonitor:hostid -
- -
TARGET cactithold:tholdid -
- -
TARGET cactithold:rra_id:data_id -
- -

When used with cactimonitor: prefix, this plugin takes data from both - Cacti's host table and from the THold plugin's data to produce a composite - state, similar to the one used by the Monitor plugin.

- -

It sets all the same Hint Variables as cactihost: plus a couple more: - thold_failcount is the number of thresholds failing on this host, and - thold_failpercent is the percentage of thresholds set on this host - that are failing. Bear in mind that if you have both a minimum and maximum - set on the same variable, then you will never get 100% failure.

- -

It also has a new value possible for the state Hint Variable - - 'tholdbreached', and adds a new state number 4, for "threshold - breached".

- -

In the second and third forms, with the cactithold: prefix, the plugin - simply returns either a 0 or 1 for the 'input bandwidth' value. 0 if the - threshold has not been breached, 1 if it has. You can supply either the - internal THold id number for a threshold (not easily visible), or the - rra_id and data_id values which can be seen at the end of URLs within THold's - web pages.

- -

You can provide a similar output to the Monitor plugin by using the - cactimonitor: TARGET and multiple icons. Create a set of coloured (or - otherwise different) icons for your node - - they should have 'up','down','disabled','recovering' and 'tholdbreached' - in the names. Then:

- -
- 
NODE myserver 
-LABEL Server 1 
-POSITION 100 100 
-TARGET cactimonitor:77 
-ICON images/server_{node:this:state}.png 
-LABELOFFSET S 
-USESCALE none 
-
-
-

- Will allow you to change the icon between images/server_up.png, - images/server_down.png etc.. as the state in Cacti changes and thresholds - are breached. The 'USESCALE none' on the end stops the label for the node - from changing colour as well.

- -

You can make use of the TARGET aggregation features of weathermap to make - a value that is effectively a 'percentage badness' for a set of thresholds. - Suppose you have a set of load-balanced firewalls, and you want to see how - many of the set have exceeded their session count. You would set up - thresholds on each firewall as normal, and then:

- -
- 
SCALE badness 0 100 0 255 0 255 0 0 
-
-NODE firewall_status 
- TARGET cactithold:334:22 cactithold:34:255 cactithold:337:235 cactithold:33:254 
- MAXVALUE 4 
- USESCALE badness in 
-
-
-

- defines a scale where 0 is green and 100% is red and in between is a smooth - gradient. Each target will return either 0 or 1, so 100% failed thresholds - gives a value of 4. Setting the MAXVALUE to 4 makes that 100% within - weathermap. -

- -
- -

Cacti DSStats data collection plugin

- -
TARGET - dsstats:dsid:in_ds:out_ds -
- -
TARGET - dsstats:source:dsid:in_ds:out_ds -
- -

The - DSStats Cacti plugin - stores data as the poller collects it, and also collates periodic average - and maximums. Which are all stored in tables in the Cacti database. This - makes collecting data (especially the periodic data) much more efficient. - This DS plugin will read that data, saving a lot of external calls to - rrdtool. This is similar to the 'poller_output' mode of the rrdtool - DS, except that this way will allow you to easily make monthly or weekly - summary maps. On the downside you need to supply the Cacti internal - datasource ID for each target, rather than the rrd filename.

- -

The dsid parameter is the 'local_data_id' in Cacti - - you can see this in the URLs on the datasource management page. The - 'in_ds' and 'out_ds' are the names of the RRD DS that Cacti will update with - these values (e.g. traffic_in and traffic_out for normal Interface Traffic). - Either of the in_ds or out_ds can be a single hyphen (-) to indicate that - you don't care about filling in a value for that direction.

- -

The - source parameter defines what data to use for this query. 'last' - fetches the most-recently collected value for that dsid. The remaining - possibilities all combine a period and a type. The possible periods are - 'hourly','daily','weekly','monthly' and 'yearly'. The types are 'average' - and 'peak'. So to get the maximium value over the last week, use - 'weeklypeak' as your - source. If one is not specified at all (as in the first format - above), then 'last' is assumed. You can change that default by setting the - global SET variable "dsstats_default_type" to the required default.

- -

The DSStats datasource also sets the same additional variables described - in for poller_output support in the rrdtool - plugin.

- -

NOTE: One important difference between this and - poller_ouput mode or regular rrdtool targets is that this plugin fetches the - raw data from the poller. If you collecting octet counter data (like - interface traffic) then you will need to multiply that data by 8 to get bits - per second:

- -
- 
TARGET 8*dsstats:4455:traffic_in:traffic_out
-
- -

Performance Note:As with the rrdtool poller_output support, - the additional queries to fill in the - interface information from the Cacti database can sometimes add significantly - to the runtime for the map. If you know you don't need the information, you - can disable those queries, while still using DSStats support. To do this, - add 'SET dsstats_no_cacti_extras 1' to the top of the map config file.

- -
- -

SNMP value

- -
TARGET - snmp:community:host:in_oid:out_oid -
- -

This is a fairly experimental plugin. It requires the PHP snmp extension - to be installed and enabled. Even then, it's hit & miss whether it will work - on a particular system - - some versions of PHP have better support for SNMP than others, and on some - platforms it is different to others, too.

- -

This plugin can directly query an SNMP-manageable device and fetch an OID - from it. You can specify '-' in place of either of the OIDs if you only need - to fetch one value.

- -

It returns the numeric values for each OID as the in and out values. It - does not currently understand COUNTER types, so you will just get - the total bytes rather than a rate, for example.

- -

It also sets snmp_in_raw and snmp_out_raw to the 'raw' results from the - SNMP library, before the plugin tried to force them to be numbers.

- -

You can adjust the behaviour of the SNMP plugin with some global SET - values. 'snmp_timeout' sets the timeout for a request in - microseconds (so the default 1000000=1 second). 'snmp_retries' - changes the number of retries per request from the default (2). Finally, you - can set 'snmp_abort_count' to an integer value - - this is the number of failures for a given host before weathermap gives up - on that host. The default is 0 (unlimited). This can improve performance if - you are polling a lot of switch ports on a device that has gone down, for - example.

- -
- -

External script

- -
TARGET !scriptname -
- -

This plugin is fairly experimental and not thoroughly tested. Due to the - risks involved with using it (it allows someone who can create configs to - run arbitrary commands as the user who updates your maps - e.g. the Cacti - poller user), it is disabled by default in new installs of version 0.97b and - above. To enable it, rename WeatherMapDataSource_external.php.disabled to - WeatherMapDataSource_external.php in the lib/datasources directory. Please see - the Security notes elsewhere in this manual before - doing that. -

- -

This plugin allows you to write small external scripts, and pass the - value from the script into Weathermap. The output format of the script is - the same one that MRTG uses for - it's external scripts, so it's possible that you can even find an - existing script to do what you want, somewhere else.

- -

MRTG external scripts produce 4 lines of output. Line 1 is the state of - the first (in) variable, line 2 is the state of the second (out) variable, - line 3 is the uptime of the device, and line 4 is the name of the device. - This plugin only cares about the first 2 lines, but it - does expect there to be 4 lines.

- -

This plugin also sets a few Hint Variables - - external_line1, external_line2, external_line3, and external_line4 are the - raw output of your script. This can be useful if your script really is - intended for MRTG, as the 3rd line would be the device uptime and the 4th - line would be it's name.

- -
- -

FPING

- -
TARGET fping:hostname -
- -

This plugin is fairly experimental and not thoroughly tested. It's also - rather slow, as each node takes 5 seconds or so to run. There are planned - improvements to take advantage of fping's parallelisation support in a - future version.

- -

This plugin uses the 'fping' command-line tool - [http://fping.sourceforge.net/] - to ping a host, and returns various statistics about it's state.

- -

You can adjust the number of pings (the default is 5), by setting the - 'fping_ping_count' global variable to another number.

- -

After it has been run, the 'in' value is the average ping time in - milliseconds, the 'out' value is the percentage packet loss from 5 pings (or - whatever you have set), the 'fping_min' Hint Variable is the minimum ping - time in milliseconds, and 'fping_max' is the maximum.

- -

Current Time

- -
TARGET time:zonename -
- -

This plugin allows you to embed the current time in any timezone in your - maps.

- -

The 'in' value is the hours, the 'out' value is minutes.

- -

The format for specifying timezones is the same as most unix systems - - Europe/London, US/Eastern, Japan and Etc/GMT+10 are all valid. These names - are usually stored in /usr/share/zoneinfo on a unix-based system.

- -

This plugin also sets a few Hint Variables - - time_time12, time_time24, time_time12ap. These are the current time in - 12-hour, 24-hour and 12-hour-with-am/pm, respectively.

- -

XXX Add in new offset and time_t related options. Mention %t

- -

A typical use is: - NODE timelabel LABEL {node:this:time_time12ap} USESCALE none TARGET - time:Europe/Paris -

- -

NOTE:The timezone handling code requires at least PHP - version 5.

- -

Weathermap Data

- -
TARGET wmdata:filename -
- -

TODO

- - -
- - - + + + + + + Data-source reference — Network Weathermap 2.0 + + + + +
+ Network Weathermap 2.0 +

Cacti plugin manual

+
+
+ +
+

Data-source reference

+ +

Specifying TARGET lines

+

The actual data-reading part of Weathermap is handled by Data Source Plugins since version + 0.9. These allow users or third-parties to easily add new data sources into Weathermap + without altering the core code.

+

There are a number of plugins supplied as standard, which will be described here. Each one + uses a different format of TARGET string, + which contains the parameters the plugin needs to find your data. All plugins return + an 'in' and 'out' value, and some may set other variables that can be accessed by Special Tokens in strings. For situations where there is only + really one output, the 'out' value may just be the same as the 'in'.

+

Here are the details of the standard data source plugins:

+ +
+

Static value

+
+ TARGET + static:invalue:outvalue +
+
+ TARGET static:value +
+

The simplest of all the plugins, static allows you to just set a value in the config file + itself. Sometimes this is useful for testing, or simple maps of things like OSPF metrics. If + only a single value is specified, it is used for both input and output, just like + the BANDWIDTH parameter.

+

The values in the target string can use the same K,M,G,T suffixes as BANDWIDTH.

+
+

RRDtool files

+
+ TARGET + rrdfile.rrd:in_ds:out_ds +
+
+ TARGET + gauge:rrdfile.rrd:in_ds:out_ds +
+
+ TARGET + rrd:rrdfile.rrd:in_ds:out_ds +
+
+ TARGET + scale:factor:rrdfile.rrd:in_ds:out_ds +
+

This is the 'core' plugin for Weathermap. It reads data from rrd files, created using + Tobi Oetiker's RRDtool, by tools like Cacti, + MRTG, Cricket, NRG and so on.

+

First of all, Weathermap needs to be able to find your rrdtool executable. If you are + using the Cacti plugin, then this information is taken automatically from Cacti. If you are + using the command-line tool, you will need to edit weathermap around line 29 to + point to your rrdtool executable.

+

TARGET formats

+

If you only specify a filename, and no DS-names, the default DS names for RRD files are + 'traffic_in' and 'traffic_out', which works with the majority of Cacti RRD files (those + produced by the Interface Traffic template). For MRTG-produced RRD files, the names are 'DS0' + and 'DS1'. For Cricket standard-interface RRD files, it would be '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, where you can take the input data from one rrd file, and the output + data from another.

+

With no prefix, or with just 'rrd:' as a prefix, the data read from the rrd file is + assumed to be a standard SNMP interface counter, which is a byte-rate. It automatically + multiplies these by 8 to get a bit-rate for the map. With the 'gauge:' prefix, this + multiplication doesn't happen, which is useful for non-bandwidth values, like SNR or + session-counts. Finally, you can use the 'scale:' prefix to multiply by any factor - + suppose you have a value in seconds, and you want to show it in milliseconds for example. Of + course, you can also divide using this, by using a scale factor that is less than 1 - + multiplying by 1/x is the same as dividing by x. Since 0.95, you can also use negative scale + factors - useful to turn dB SNR into something weathermap can deal with.

+

rrdtool adjustments

+

By default, the plugin will read the last 800 seconds of data, and find the most recent + within that to use. You might need to make it read back further, if you are updating your rrd + files slowly. You can do this with the SET + command, by adding 'SET rrd_period 3000' (any + value in seconds) at the top of your map config file, before any NODE or LINK lines.

+

Similarly, you can change the time that the plugin looks for data at from the present to + the past, by using 'SET rrd_start -1d' in the + top section of the config file. The full range of time-specification strings is at the bottom + of the rrdfetch manual + page.

+

If you are using a tool other than Cacti, then the default DS names of traffic_in and + traffic_out are probably wrong. You can change the defaults for the whole config file by + adding two SET lines to the top of the map + config file. For example, 'SET + rrd_default_in_ds DS0' and 'SET + rrd_default_out_ds DS1' will make the default DS names DS0 and DS1 respecively so MRTG users + don't need to specify the DS names in every TARGET line.

+

For any other special rrdtool 'tweaks', you can SET rrd_options to a string which is added directly to + the rrdtool command-line. This should allow for any changes that I haven't expected!

+

Finally, if the TARGET filename doesn't + begin with a / it is usually assumed to be a relative path from the weathermap directory. If + you SET rrd_default_path to some other path in + the global (top) section of the map config file, you can change that assumption so that the + DS plugin looks somewhere else.

+

Cacti-specific additions

+

If the plugin detects that it is running within the Cacti poller process, it defines a + couple of useful global Hint Variables for Cacti users - {map:cacti_path_rra} contains the + path to the rra/ directory in your Cacti installation, with no trailing slash, and + {map:cacti_url} is the URL to the front page of your Cacti installation, as known to the + Plugin Architecture. These can be used in the TARGET, INFOURL and OVERLIBGRAPH commands in particular, to reduce + a lot of duplication.

+

Cacti poller_output support (aka Boost support)

+

If you are using Cacti as your data collector, and running Weathermap from Cacti's poller, + then there is another special feature, called poller_output. Weathermap can intercept data as + it is collected by Cacti, and therefore avoid running lots of external rrdtool processes to + collect the data it needs to display your map. This is especially useful if you are + using TheWitness' Boost plugin, as the data isn't written to the rrd files until some time + after it is collected. Even without Boost, it should provide a performance improvement, + particularly with large installations of Weathermap.

+

To use this feature, a map-global variable needs to be set. Near the top of your map + config file, add 'SET rrd_use_poller_output + 1'. The setting will take a few poller cycles to take effect: during the first one, the + appropriate cacti data sources are identified based on the rrd filenames, on the second cycle + values will be collected, and on the third we'll have two values, so any COUNTER datasources + will begin to work properly. If the poller_output feature fails to collect data, then the + regular rrdtool-running method will be attempted too.

+

Because in poller_output mode, Weathermap is pulling data directly from the Cacti + database, it can also collect some other information that you might find useful in your map. + It takes all the data stored in the host_snmp_cache table for the specified datasource, and + dumps that into Hint Variables. This table contains all the columns that you see when you are + picking which datasource to graph in Cacti, so for normal interface traffic, it contains + things like the interface speed, operational status, interface description (your 'comment' + name, usually) and so on. These are stored in Hint Variables called 'cacti_cache + variable' - e.g. cacti_ifSpeed, or cacti_ifIP. It also sets cacti_host_id to be the + internal host_id from Cacti for the host containing this data source, and the cacti_graph_id + to be the local_graph_id of a graph that uses this DS in Cacti. You can then use those to + automatically add correct OVERLIBGRAPH + and INFOURL lines:

+
+ 
+ SET rrd_use_poller_output 1
+
+ LINK DEFAULT
+ SET cacti_use_ifspeed 1
+ INFOURL {map:cacti_url}/graph.php?local_graph_id={link:this:cacti_graph_id}
+ OVERLIBGRAPH {map:cacti_url}/graph_image.php?local_graph_id={link:this:cacti_graph_id}&rra_id=0&graph_nolegend=true
+
+ LINK uplink1
+ NODES a b
+ TARGET {map:cacti_path_rra}/router1_345_traffic_in.rrd
+
+ LINK uplink2
+ NODES a c
+ TARGET {map:cacti_path_rra}/router1_377_traffic_in.rrd
+
+

In this example, all each link needs to have defined is the TARGET rrdfile, and which nodes it joins. The rest + is supplied by this plugin.

+
+

As an additional sub-feature, if you add 'SET cacti_use_ifspeed 1' to either the link or node, + or any item it inherits settings from (e.g. DEFAULT) then Weathermap will take the value of + ifSpeed (or ifHighSpeed for 4G+ links) and use it in place of the value defined in the map + config file - this allows you to do some basic dynamic configuration of Weathermap based on + Cacti, which in turn should pick up changes from the network device.

+

Note that since the rrdtool program is not being run in this mode, you + can't use the "time-shifting" features described above - those rely on using + real rrdtool files. If you are using poller_output to allow Weathermap to work + alongside Boost, then there is no workaround - the data isn't in the .rrd files until Boost's + own update process puts it there sometime later.

+

Performance Note:The additional queries to fill in the interface + information from the Cacti database can sometimes add significantly to the runtime for the + map. If you know you don't need the information, you can disable those queries, while still + using the poller_output support. To do this, add 'SET rrd_no_cacti_extras 1' to the top of the map + config file.

+

RRDtool Aggregation

+

Put multiple targets on a single TARGET line, separated by spaces. Weathermap sums IN + values separately from OUT values. For example, TARGET first.rrd second.rrd combines two + standard traffic sources. Use explicit DS names where necessary; a hyphen omits one + direction. Set a meaningful combined BANDWIDTH. Hover and click URLs remain separate and no + aggregate Cacti graph is created.

+
+

Tab-separated text

+
+ TARGET textfile +
+

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.

+
+
A suitable tab-delimited data file
+ 
link1 3M 4M
+link2 66K 1.8M
+link3 34.6K 113
+
+
+

MRTG .html file

+
+ TARGET htmlfile +
+

This plugin reads data from special comments in the HTML files generated by MRTG. This is + intended mainly for people using the 'old-style' MRTG .log files. If you are using MRTG with + an RRDtool backend, then it's probably better to use the RRDtool plugin.

+

The file should have an extension of .html or .htm to be recognised as an MRTG file by + Weathermap.

+

Since 0.95, there are a few hint variables that will adjust the behaviour of this + datasaource:

+
    +
  • SET mrtg_swap 1 - (per-link/node) + will swap the in and out values over
    • +
  • SET mrtg_negate 1 - + (per-link/node) will make negate the value from the MRTG file. Weathermap doesn't deal well + with negative values yet, so this is sometimes useful.
    • +
  • SET mrtg_period d - + (per-link/node) allows you to choose between daily, monthly, weekly, and yearly values - + use 'd','m','w','y' - default is 'd'
    • +
  • SET mrtg_value av - + (per-link/node) allows you to choose between average, minimum, maximum and current values - + use 'av','min','max','cu' - default is 'cu'
    • +
+
+

Cacti host status

+
+ TARGET cactihost:hostid +
+

This plugin reads the current status of a host from your Cacti database. The hostid is + visible in Cacti URLs when you click on links in the Devices page. The return values for this + plugin are numeric codes. It also sets a Hint Variable called state to a string, + that can be nicer to use in an ICON filename, + for example - possible values are 'up','down','disabled', and 'recovering'.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Codestate value
0disabled
1down
2recovering
3up
5unknown
+

It also sets the following additional Hint Variables, to use in a LABEL, COMMENT or NOTES section as you see fit: cacti_hostname, + cacti_description, cacti_curtime, cacti_avgtime, + cacti_mintime, cacti_maxtime, cacti_availability, + cacti_faildate, and cacti_recdate

. +

An appropriate SCALE definition to get + red, green, yellow and grey labels based on the state of a host would be:

+
+ 
SCALE cactiupdown 0 0.5 192 192 192
+SCALE cactiupdown 0.5 1.5 255 0 0
+SCALE cactiupdown 1.5 2.5 0 0 255
+SCALE cactiupdown 2.5 3.5 0 255 0
+SCALE cactiupdown 4.5 5.5 128 128 128
+
+
+

Cacti threshold status

+
+ TARGET cactimonitor:hostid +
+
+ TARGET cactithold:tholdid +
+
+ TARGET + cactithold:rra_id:data_id +
+

When used with cactimonitor: prefix, this plugin takes data from both Cacti's host table + and from the THold plugin's data to produce a composite state, similar to the one used by the + Monitor plugin.

+

It sets all the same Hint Variables as cactihost: plus a couple more: + thold_failcount is the number of thresholds failing on this host, and + thold_failpercent is the percentage of thresholds set on this host that are failing. + Bear in mind that if you have both a minimum and maximum set on the same variable, then you + will never get 100% failure.

+

It also has a new value possible for the state Hint Variable - 'tholdbreached', + and adds a new state number 4, for "threshold breached".

+

In the second and third forms, with the cactithold: prefix, the plugin simply returns + either a 0 or 1 for the 'input bandwidth' value. 0 if the threshold has not been breached, 1 + if it has. You can supply either the internal THold id number for a threshold (not easily + visible), or the rra_id and data_id values which can be seen at the end of URLs within + THold's web pages.

+

You can provide a similar output to the Monitor plugin by using the cactimonitor: TARGET and multiple icons. Create a set of coloured + (or otherwise different) icons for your node - they should have + 'up','down','disabled','recovering' and 'tholdbreached' in the names. Then:

+
+ 
NODE myserver
+LABEL Server 1
+POSITION 100 100
+TARGET cactimonitor:77
+ICON images/server_{node:this:state}.png
+LABELOFFSET S
+USESCALE none
+
+
+

Will allow you to change the icon between images/server_up.png, images/server_down.png + etc.. as the state in Cacti changes and thresholds are breached. The 'USESCALE none' on the end stops the label for the + node from changing colour as well.

+

You can make use of the TARGET aggregation + features of weathermap to make a value that is effectively a 'percentage badness' for a set + of thresholds. Suppose you have a set of load-balanced firewalls, and you want to see how + many of the set have exceeded their session count. You would set up thresholds on each + firewall as normal, and then:

+
+ 
SCALE badness 0 100 0 255 0 255 0 0
+
+NODE firewall_status
+ TARGET cactithold:334:22 cactithold:34:255 cactithold:337:235 cactithold:33:254
+ MAXVALUE 4
+ USESCALE badness in
+
+
+

defines a scale where 0 is green and 100% is red and in between is a smooth gradient. Each + target will return either 0 or 1, so 100% failed thresholds gives a value of 4. Setting the + MAXVALUE to 4 makes that 100% within + weathermap.

+
+

Legacy DSStats integration

+
+ TARGET + dsstats:dsid:in_ds:out_ds +
+
+ TARGET + dsstats:source:dsid:in_ds:out_ds +
+

The legacy DSStats Cacti plugin stores data + as the poller collects it, and also collates periodic average and maximums. Which are all + stored in tables in the Cacti database. This makes collecting data (especially the periodic + data) much more efficient. This DS plugin will read that data, saving a lot of external calls + to rrdtool. This is similar to the 'poller_output' mode of the rrdtool DS, + except that this way will allow you to easily make monthly or weekly summary maps. On the + downside you need to supply the Cacti internal datasource ID for each target, rather than the + rrd filename.

+

The dsid parameter is the 'local_data_id' in Cacti - you can see this in the URLs + on the datasource management page. The 'in_ds' and 'out_ds' are the names of the RRD DS that + Cacti will update with these values (e.g. traffic_in and traffic_out for normal Interface + Traffic). Either of the in_ds or out_ds can be a single hyphen (-) to indicate that you don't + care about filling in a value for that direction.

+

The source parameter defines what data to use for this query. 'last' fetches the + most-recently collected value for that dsid. The remaining possibilities all combine a period + and a type. The possible periods are 'hourly','daily','weekly','monthly' and 'yearly'. The + types are 'average' and 'peak'. So to get the maximium value over the last week, use + 'weeklypeak' as your source. If one is not specified at all (as in the first format + above), then 'last' is assumed. You can change that default by setting the global SET variable "dsstats_default_type" to the required + default.

+

The DSStats datasource also sets the same additional variables described in for poller_output support in the rrdtool plugin.

+

NOTE: One important difference between this and poller_ouput mode or + regular rrdtool targets is that this plugin fetches the raw data from the poller. If you + collecting octet counter data (like interface traffic) then you will need to multiply that + data by 8 to get bits per second:

+
+ 
TARGET 8*dsstats:4455:traffic_in:traffic_out
+
+

Performance Note:As with the rrdtool poller_output support, the + additional queries to fill in the interface information from the Cacti database can sometimes + add significantly to the runtime for the map. If you know you don't need the information, you + can disable those queries, while still using DSStats support. To do this, add 'SET dsstats_no_cacti_extras 1' to the top of the map + config file.

+
+

SNMP value

+
+ TARGET + snmp:community:host:in_oid:out_oid +
+

This is a fairly experimental plugin. It requires the PHP snmp extension to be installed + and enabled. Even then, it's hit & miss whether it will work on a particular system - some + versions of PHP have better support for SNMP than others, and on some platforms it is + different to others, too.

+

This plugin can directly query an SNMP-manageable device and fetch an OID from it. You can + specify '-' in place of either of the OIDs if you only need to fetch one value.

+

It returns the numeric values for each OID as the in and out values. It does not + currently understand COUNTER types, so you will just get the total bytes rather than a rate, + for example.

+

It also sets snmp_in_raw and snmp_out_raw to the 'raw' results from the SNMP library, + before the plugin tried to force them to be numbers.

+

You can adjust the behaviour of the SNMP plugin with some global SET values. 'snmp_timeout' sets the timeout for a + request in microseconds (so the default 1000000=1 second). 'snmp_retries' changes + the number of retries per request from the default (2). Finally, you can set + 'snmp_abort_count' to an integer value - this is the number of failures for a given host + before weathermap gives up on that host. The default is 0 (unlimited). This can improve + performance if you are polling a lot of switch ports on a device that has gone down, for + example.

+
+

External script

+
+ TARGET !scriptname +
+

This plugin is fairly experimental and not thoroughly tested. Due to the risks involved + with using it (it allows someone who can create configs to run arbitrary commands as the user + who updates your maps - e.g. the Cacti poller user), it is disabled by default in new + installs of version 0.97b and above. To enable it, rename + WeatherMapDataSource_external.php.disabled to WeatherMapDataSource_external.php in the + lib/datasources directory. Please see the Security notes + elsewhere in this manual before doing that.

+

This plugin allows you to write small external scripts, and pass the value from the script + into Weathermap. The output format of the script is the same one that MRTG uses for + it's external scripts, so it's possible that you can even find an existing script to + do what you want, somewhere else.

+

MRTG external scripts produce 4 lines of output. Line 1 is the state of the first (in) + variable, line 2 is the state of the second (out) variable, line 3 is the uptime of the + device, and line 4 is the name of the device. This plugin only cares about the first 2 lines, + but it does expect there to be 4 lines.

+

This plugin also sets a few Hint Variables - external_line1, external_line2, + external_line3, and external_line4 are the raw output of your script. This can be useful if + your script really is intended for MRTG, as the 3rd line would be the device uptime and the + 4th line would be it's name.

+
+

FPING

+
+ TARGET fping:hostname +
+

This plugin is fairly experimental and not thoroughly tested. It's also rather slow, as + each node takes 5 seconds or so to run. Allow for its per-target runtime when planning map + generation.

+

This plugin uses the 'fping' command-line tool [https://fping.org/] to ping a host, and returns various statistics + about it's state.

+

You can adjust the number of pings (the default is 5), by setting the 'fping_ping_count' + global variable to another number.

+

After it has been run, the 'in' value is the average ping time in milliseconds, the 'out' + value is the percentage packet loss from 5 pings (or whatever you have set), the 'fping_min' + Hint Variable is the minimum ping time in milliseconds, and 'fping_max' is the maximum.

+

Current Time

+
+ TARGET time:zonename +
+

This plugin allows you to embed the current time in any timezone in your maps.

+

The 'in' value is the hours, the 'out' value is minutes.

+

The format for specifying timezones is the same as most unix systems - Europe/London, + US/Eastern, Japan and Etc/GMT+10 are all valid. These names are usually stored in + /usr/share/zoneinfo on a unix-based system.

+

This plugin also sets a few Hint Variables - time_time12, time_time24, time_time12ap. + These are the current time in 12-hour, 24-hour and 12-hour-with-am/pm, respectively.

+

For date/time formatting tokens, see the advanced formatting section; the source + implementation defines the additional available hints.

+

A typical use is: NODE timelabel + LABEL {node:this:time_time12ap} USESCALE none TARGET time:Europe/Paris

+

NOTE:Use an identifier supported by PHP DateTimeZone in the installed + runtime. The plugin’s current PHP requirements still apply.

+

Weathermap Data

+
+ TARGET + wmdata:filename:dataname +
+

Use TARGET wmdata:filename:dataname. The file is tab-separated: a name, an IN + numeric value and an OUT numeric value on each line. Unlike the plain tabfile source, the + name to select is explicit and need not match the node/link name. The file modification time + supplies the data timestamp.

+ 
# Configuration:
+TARGET wmdata:/path/to/readings.tsv:uplink
+
+# readings.tsv (separate columns with actual tab characters):
+uplink  12000000        5000000
+

Values are used as numeric measurements; choose units and BANDWIDTH/MAXVALUE consistently. + This reader does not convert a cumulative counter to a rate.

+
+

SNMP v2c

+
TARGET snmp2c:community:host:in_oid:out_oid
+

Reads numeric values using Cacti's SNMP helper with version 2. Supply the community, + device address and numeric OIDs; use - for an unused direction. This needs a + working Cacti SNMP environment and a reachable device that permits the request.

+

The values are direct readings, not calculated counter rates. For interface traffic, + use Cacti's polled RRD data instead of reading an octet counter directly.

+

Defaults: the global hints snmp_timeout, + snmp_retries and snmp_abort_count default to 1000000 microseconds + (one second), 2 retries and 0 (no failure-count cutoff), respectively. The cutoff counts + failed requests to a host during map generation; it does not disable Cacti polling.

+

Example

+ 
NODE port_state
+    POSITION 100 100
+    LABEL Port state: {node:this:bandwidth_in:%d}
+    TARGET snmp2c:replace_me:192.0.2.10:1.3.6.1.2.1.2.2.1.8.1:-
+    MAXVALUE 7
+

This reads ifOperStatus for interface index 1: 1 means up and 2 means down; + other state codes are possible. Replace the example community, address and interface index. + The label displays the state code, not utilisation. Keep community strings private. See + SNMP v3 for authenticated profile-based requests.

+
+
+

SNMP v3

+
TARGET snmp3:profile:host:in_oid:out_oid
+

Reads numeric OID values using an SNMPv3 profile. Use - for an unused + direction. As with v2c, this reads values directly; it does not turn counters into rates. + Timeout, retry and failure-count hints have the same defaults as v2c.

+

Define a profile through global hints before the first NODE or LINK. For a profile named + site, the available hints are snmp3_site_username, + snmp3_site_seclevel, snmp3_site_authproto, + snmp3_site_authpass, snmp3_site_privproto and + snmp3_site_privpass. The default security level is noAuthNoPriv; + the other profile fields default to empty. Configure the level and credentials required + by your device. Supported levels include authNoPriv and authPriv; + authentication and privacy protocols depend on Cacti's SNMP environment.

+

Alternatively, SET snmp3_site_import device_id imports the profile + from an SNMPv3 Cacti device instead of using the explicit profile fields. This is a device + ID, not a graph or data-source ID. Verify the imported profile against the target device.

+

Example

+ 
# Global section: replace 42 with the SNMPv3 Cacti device ID.
+SET snmp3_site_import 42
+
+NODE port_state
+    POSITION 100 100
+    LABEL Port state: {node:this:bandwidth_in:%d}
+    TARGET snmp3:site:192.0.2.10:1.3.6.1.2.1.2.2.1.8.1:-
+    MAXVALUE 7
+

Replace the address and interface index with values for that device. Configuration and + verbose diagnostics can contain credentials. Direct SNMP requests extend map generation + time and do not replace Cacti's historical polling.

+
+
+

Cacti cached data by ID

+
TARGET cacti:local_data_id
+

Reads the plugin's weathermap_data cache in Cacti context. The ID identifies + a local data source, not a graph. The cache must already contain readings for that source; + an arbitrary graph ID cannot be substituted. This source is unavailable outside Cacti.

+

The reader returns the cached values and timestamp without an additional unit + conversion. Choose BANDWIDTH or MAXVALUE to match those stored measurements. For ordinary + editor traffic links, keep the source assigned by Use interface unless + you deliberately need this cache-based form.

+

Example

+ 
LINK cached_uplink
+    NODES core access
+    TARGET cacti:42
+    BANDWIDTH 1G
+

Define the two endpoint nodes first. Replace 42 with a source present in the cache; + the 1G capacity is appropriate only when that source supplies traffic in bits/sec. + This TARGET changes measurements only. Configure hover and click URLs separately; see + Advanced settings: URLs and custom data.

+
+ +
+
+ + diff --git a/docs/pages/upgrading.html b/docs/pages/upgrading.html index e26d9885..2da3d97c 100644 --- a/docs/pages/upgrading.html +++ b/docs/pages/upgrading.html @@ -1,72 +1,91 @@ - - - - - PHP Weathermap v0.98a - Upgrading - - - - - - - -
- - - -

Upgrading From Previous Versions

- -

Make a backup of your working weathermap directory before you do - this! Just in case you do need to roll back.

- -

You should be able to upgrade from any previous version by simply - unpacking the new one over the top. The files that will need to be changed - afterwards are the same ones you edited when you first installed: - -

    -
  • If you use the editor, then copy your editor-config.php out of the - way, copy the new editor-config.php-dist over the top of the in-place - editor-config.php and then make the same changes you made in your - original install (cacti path and URI). - This is especially important when upgrading to 0.92
    • - -
  • If you use the command-line tool, you will need to put the path to - rrdtool back in, around line 30 of the 'weathermap' file.
    • -

- -

Any necessary database updates for Cacti users should be taken care of - automatically.

- -
- + + + + + Upgrading to 2.0 — Network Weathermap 2.0 + + + + +
+ Network Weathermap 2.0 +

Cacti plugin manual

+
+
+ +
+

Upgrading to 2.0

+

An upgrade replaces application files; it should preserve your maps, images + and monitoring data. Prepare a recoverable backup before replacing anything.

+
+

Before upgrading

+
    +
  1. Record your Cacti, PHP, RRDtool and Weathermap versions and the release/commit you + plan to install. A develop checkout may contain changes after a release tag.
    2. +
  2. Back up the entire plugin directory, including configs, output, uploaded images, + custom fonts, INCLUDE files outside that directory and local modifications. Back up + Cacti's database using your normal procedure. Keep backups outside the web root.
    3. +
  3. Check Cacti compatibility and release notes. Coordinate the update with + administrators so no one edits maps while files are replaced or migrations run.
    4. +
  4. Compare local code changes before overwriting them. Preserve custom data, but do not + copy old application code back over the new release.
    5. +
+
+
+

Install and migrate

+

Replace the plugin's application files with the selected official release, preserving + user configuration and assets. The plugin's upgrade path performs schema/configuration work + and removes known obsolete application paths through its packaged manifest; it is not a + backup of arbitrary local modifications.

+

Older background/icon paths may be migrated into images/backgrounds/ and + images/objects/, with configuration references updated. Ensure the relevant + accounts can perform migration, and inspect customised paths and INCLUDE files afterward. + Do not move images by hand without updating every reference.

+

The old cacti-resources/editor-resources and OverLib dependency are no longer the + current UI implementation. Do not restore old editor-config.php instructions. Current + editor access uses Cacti authentication and permissions.

+
+
+

After upgrading

+
    +
  • Verify the installed version and enablement in Plugin Management; review logs for + migration errors.
    • +
  • Refresh the browser so JavaScript and CSS match the new PHP files.
    • +
  • Check representative maps, custom images/fonts, included templates, graph links and + hover previews.
    • +
  • Test one save and Undo/Redo on a disposable map. Confirm rendering under the poller + account.
    • +
  • Check view-only and management accounts and group/map permissions.
    • +
  • Verify asymmetric bandwidth and explicitly set capacities. Existing explicit values + are retained on upgrade; 1000M is the implicit default. If you then change map defaults in + the editor, recheck asymmetric links as described under + default capacity.
    • +
  • Review curved comment positioning and font availability. Straight fallback at unsafe + bends is intentional.
    • +
+

If rollback is necessary, restore a consistent plugin and database backup as appropriate + to the migrations performed. Do not mix arbitrary old PHP files with new JavaScript. Report + failures with versions and relevant logs.

+
+ +
+
diff --git a/lib/editor.inc.php b/lib/editor.inc.php index bc76bcb5..e3bcea8e 100644 --- a/lib/editor.inc.php +++ b/lib/editor.inc.php @@ -413,7 +413,7 @@ function show_editor_startpage() { html_start_box(__('Welcome to the PHP Weathermap %s Editor', $weathermap_version, 'weathermap'), '100%', false, 3, 'center', ''); print ''; print ''; - print '
' . __('NOTE: This editor is not finished! There are many features of Weathermap that you will be missing out on if you choose to use the editor only. These include: curves, node offsets, font definitions, colour changing, per-node/per-link settings and image uploading. You CAN use the editor without damaging these features if you added them by hand, however.', 'weathermap') . '
'; + print '
' . __('Use the editor to manage nodes, links, notes, colours and image uploads. Edit Raw Configuration provides settings beyond the forms. See the local documentation for workflows and configuration details.', 'weathermap') . '
'; print ''; print ''; html_end_box(); diff --git a/lib/viewer.controls.php b/lib/viewer.controls.php new file mode 100644 index 00000000..00fbb8c4 --- /dev/null +++ b/lib/viewer.controls.php @@ -0,0 +1,23 @@ +|bool $map Map metadata, or false when unavailable. + * + * @return string The map heading with management shortcuts when authorized. + */ +function weathermap_map_title_controls($maptitle, $map) { + $heading = '[' . __esc('Docs', 'weathermap') . ']' . $maptitle . ''; + + if (!is_array($map) || !isset($map['id'], $map['configfile']) || !is_string($map['configfile']) || !api_user_realm_auth('weathermap-cacti-plugin-mgmt.php')) { + return $heading; + } + $id = (int) $map['id']; + $heading .= ' [ ' . __esc('Manage Weathermaps', 'weathermap') . ' | '; + $heading .= '' . __esc('Map Settings', 'weathermap') . ' | '; + $heading .= '' . __esc('Map Permissions', 'weathermap') . ' | '; + $heading .= '' . __esc('Edit Map', 'weathermap') . ' ]'; + + return $heading; +} diff --git a/locales/po/cacti.pot b/locales/po/cacti.pot index 9ee4b8e9..9f9967e8 100644 --- a/locales/po/cacti.pot +++ b/locales/po/cacti.pot @@ -264,7 +264,7 @@ msgid "Welcome to the PHP Weathermap %s Editor" msgstr "" #: lib/editor.inc.php -msgid "NOTE: This editor is not finished! There are many features of Weathermap that you will be missing out on if you choose to use the editor only. These include: curves, node offsets, font definitions, colour changing, per-node/per-link settings and image uploading. You CAN use the editor without damaging these features if you added them by hand, however." +msgid "Use the editor to manage nodes, links, notes, colours and image uploads. Edit Raw Configuration provides settings beyond the forms. See the local documentation for workflows and configuration details." msgstr "" #: lib/editor.inc.php @@ -3071,3 +3071,7 @@ msgstr "" #: lib/editor.inc.php msgid "Undo and Redo require browser session storage." msgstr "" + +#: lib/viewer.controls.php weathermap-cacti-plugin-mgmt.php +msgid "Docs" +msgstr "" diff --git a/tests/Support/DocumentationNavigationRegression.php b/tests/Support/DocumentationNavigationRegression.php new file mode 100644 index 00000000..7c202c2c --- /dev/null +++ b/tests/Support/DocumentationNavigationRegression.php @@ -0,0 +1,27 @@ + 7, 'configfile' => 'A&B +é.conf']] as $map) { + $html = weathermap_map_title_controls(htmlspecialchars('Demo ', ENT_QUOTES), $map); + $document = new DOMDocument(); + $document->loadHTML('' . $html, LIBXML_NOERROR | LIBXML_NOWARNING); + $xpath = new DOMXPath($document); + $docs = $xpath->query('//a[contains(concat(" ", normalize-space(@class), " "), " wm-docs-link ")]'); + if ($docs->length !== 1 || $docs[0]->getAttribute('href') !== 'docs/index.html' || $docs[0]->getAttribute('target') !== '_blank' || $docs[0]->getAttribute('rel') !== 'noopener') throw new RuntimeException('Missing or unsafe documentation shortcut.'); + $edit = $xpath->query('//a[@class="wm-edit-map"]'); + if ($edit->length !== (int)($allowed && is_array($map))) throw new RuntimeException('Documentation shortcut changed management access.'); + if ($edit->length) { + parse_str(parse_url($edit[0]->getAttribute('href'), PHP_URL_QUERY), $query); + if ($query['mapname'] !== $map['configfile']) throw new RuntimeException('Editor filename no longer round-trips.'); + } + } +} +echo "Documentation access preserves management permissions and navigation.\n"; diff --git a/tests/Support/DocumentationReferenceVariants.conf b/tests/Support/DocumentationReferenceVariants.conf new file mode 100644 index 00000000..bd171811 --- /dev/null +++ b/tests/Support/DocumentationReferenceVariants.conf @@ -0,0 +1,25 @@ +WIDTH 800 +HEIGHT 600 +KILO 1000 +HTMLSTYLE overlib +SET background_sizing fit +SET traffic_pulse 1 +SCALE temperature 0 100 0 255 0 +NODE core + POSITION 200 200 + ICON 50 50 images/objects/cisco-router.png + LABELOFFSET N20 + USESCALE temperature in absolute + USEICONSCALE temperature out percent + MAXVALUE 100 + TARGET static:50:25 +NODE remote + POSITION core 90r100 + LABELOFFSET 90r30 +LINK calc + NODES core remote + TARGET static:100M:80M -static:20M:10M 0.5*static:40M:20M + BANDWIDTH 1G + COMMENTCURVE 0 +LINK defaults + NODES core remote diff --git a/tests/Unit/DocumentationLinksTest.php b/tests/Unit/DocumentationLinksTest.php new file mode 100644 index 00000000..0eb5f325 --- /dev/null +++ b/tests/Unit/DocumentationLinksTest.php @@ -0,0 +1,14 @@ +not->toBeFalse(); + exec(escapeshellarg(PHP_BINARY) . ' ' . escapeshellarg($path) . ' 2>&1', $lines, $status); + expect($status)->toBe(0, implode("\n", $lines)); +})->with([ + 'links and anchors' => ['bin/check-doc-links.php'], + 'permissions and navigation' => ['Support/DocumentationNavigationRegression.php'], + 'rendered examples and units' => ['bin/render-doc-examples.php'], +]); diff --git a/tests/bin/check-doc-links.php b/tests/bin/check-doc-links.php new file mode 100644 index 00000000..b14541a5 --- /dev/null +++ b/tests/bin/check-doc-links.php @@ -0,0 +1,47 @@ +getExtension() !== 'html') continue; + $dom = new DOMDocument(); + $dom->loadHTML(file_get_contents($file->getPathname())); + $ids = []; + foreach ((new DOMXPath($dom))->query('//*[@id] | //a[@name]') as $element) { + foreach (['id', 'name'] as $attribute) { + if (!$element->hasAttribute($attribute)) continue; + $id = $element->getAttribute($attribute); + if (isset($ids[$id]) && $ids[$id] !== $element) $errors[] = $file->getPathname() . ': duplicate anchor ' . $id; + $ids[$id] = $element; + } + } + $pages[$file->getRealPath()] = ['dom' => $dom, 'ids' => $ids]; +} +$count = 0; +foreach ($pages as $path => $page) { + foreach ((new DOMXPath($page['dom']))->query('//*[@href or @src]') as $element) { + foreach (['href', 'src'] as $attribute) { + if (!$element->hasAttribute($attribute)) continue; + $url = $element->getAttribute($attribute); + if ($url === '' || preg_match('~^(?:[a-z][a-z0-9+.-]*:|//)~i', $url)) continue; + $parts = parse_url($url); + if ($parts === false) { $errors[] = "$path: malformed URL $url"; continue; } + $destination = isset($parts['path']) && $parts['path'] !== '' ? dirname($path) . '/' . rawurldecode($parts['path']) : $path; + if (is_dir($destination)) $destination .= '/index.html'; + $destination = realpath($destination); + $count++; + if ($destination === false) { $errors[] = "$path: missing target $url"; continue; } + if (isset($parts['fragment'], $pages[$destination]) && !isset($pages[$destination]['ids'][rawurldecode($parts['fragment'])])) $errors[] = "$path: missing anchor $url"; + } + } +} +libxml_clear_errors(); +libxml_use_internal_errors($previousErrors); +if ($errors) { + fwrite(STDERR, implode(PHP_EOL, $errors) . PHP_EOL); + exit(1); +} +fwrite(STDOUT, count($pages) . " HTML pages; $count local references checked.\n"); diff --git a/tests/bin/render-doc-examples.php b/tests/bin/render-doc-examples.php new file mode 100644 index 00000000..a09b440c --- /dev/null +++ b/tests/bin/render-doc-examples.php @@ -0,0 +1,105 @@ +rrdtool = PHP_BINARY; +if (!$variants->ReadConfig('tests/Support/DocumentationReferenceVariants.conf')) throw new RuntimeException('Cannot parse reference variants.'); +$variants->ReadData(); +$distance = hypot($variants->nodes['remote']->x - $variants->nodes['core']->x, $variants->nodes['remote']->y - $variants->nodes['core']->y); +if (abs($distance - 100) > .001 || $variants->nodes['core']->labeloffset !== 'N20') throw new RuntimeException('Reference polar/label offset syntax differs from the engine.'); +if ($variants->nodes['core']->scaletype !== 'absolute' || $variants->nodes['core']->iconscaletype !== 'percent') throw new RuntimeException('Reference scale syntax differs from the engine.'); +if (abs($variants->links['calc']->inpercent - 10) > .001 || abs($variants->links['calc']->outpercent - 8) > .001) throw new RuntimeException('Reference signed/scaled source arithmetic is incorrect.'); +if (abs($variants->links['defaults']->max_bandwidth_in - 1000000000) > .001 || $variants->links['defaults']->commentcurve != 1) throw new RuntimeException('Reference implicit defaults differ from the engine.'); +if ($GLOBALS['weathermap_warncount']) throw new RuntimeException('Warnings in reference variants.'); +$examples = [ + 'label-positions-2.0' => [660, 210], + 'curved-comments-2.0' => [660, 380], + 'combined-sources-2.0' => [660, 160], + 'traffic-pulse-2.0' => [660, 180], + 'editor-settings-2.0' => [1320, 600], // Notes render at 2× resolution for sharp text., +]; +foreach ($examples as $name => [$width, $height]) { + $GLOBALS['weathermap_warncount'] = 0; + $map = new WeatherMap(); + // Static sources do not invoke RRDtool; supply an existing executable for its Init check. + $map->rrdtool = PHP_BINARY; + if (!$map->ReadConfig("docs/example/$name.conf")) throw new RuntimeException("Cannot parse $name"); + $map->ReadData(); + if ($name === 'editor-settings-2.0') { + $note = $map->nodes['site_note']; + if ($map->get_hint('background_sizing') !== 'fit' || $map->nodes['core']->labeloffset !== 'S60' || $map->nodes['core']->get_hint('editor_label_position') !== 'S60') throw new RuntimeException('Published background sizing or editor label preset is incorrect.'); + if ($note->get_hint('editor_note') !== '1' || $note->get_hint('editor_note_escaped') !== '1' || $note->get_hint('editor_note_align') !== 'centre' || wm_note_decode_text($note->label) !== "Example site\nTraffic overview") throw new RuntimeException('Published note syntax or alignment is incorrect.'); + if (abs($map->links['uplink']->inpercent - 90) > .001 || abs($map->links['uplink']->outpercent - 20) > .001) throw new RuntimeException('Published settings example has incorrect inherited capacity.'); + } + if ($name === 'combined-sources-2.0') { + $link = $map->links['combined']; + if (abs($link->inpercent - 30) > .001 || abs($link->outpercent - 15) > .001) throw new RuntimeException('Combined example has incorrect units or arithmetic.'); + } + if ($update) { + $output = "docs/images/reference-$name.png"; + } else { + $temporary = tempnam(sys_get_temp_dir(), 'wm-doc-'); + $output = $temporary . '.png'; + unlink($temporary); + } + try { + $map->DrawMap($output); + if ($name === 'traffic-pulse-2.0') { + require_once $root . '/lib/WeatherMap.animation.php'; + $data = wm_traffic_animation_data($map); + if (count($data['regions']) !== 1 || abs($map->links['uplink']->inpercent - 90) > .001 || abs($map->links['uplink']->outpercent - 20) > .001) throw new RuntimeException('Pulse example must highlight only the 90% direction.'); + if ($update) file_put_contents('docs/images/reference-traffic-pulse-2.0.svg', documentationPulseSvg($data, file_get_contents($output))); + $map->add_hint('traffic_pulse', '0'); + if (wm_traffic_animation_data($map)['enabled']) throw new RuntimeException('Pulse disable example differs from the engine.'); + } + $size = getimagesize($output); + if ($size[0] !== $width || $size[1] !== $height || $GLOBALS['weathermap_warncount']) throw new RuntimeException("Invalid example render: $name"); + } finally { + if (!$update && is_file($output)) unlink($output); + } +} +echo "Five published map examples render without warnings; source totals, pulse eligibility, editor presets and note syntax verified.\n"; + +/** Illustrated animation uses the engine's real polygon/mask output and the viewer's glow style. */ +function documentationPulseSvg($data, $png) { + $width = (int)$data['width']; $height = (int)$data['height']; + $document = new DOMDocument('1.0', 'UTF-8'); + $svg = $document->createElementNS('http://www.w3.org/2000/svg', 'svg'); + $svg->setAttribute('viewBox', "0 0 $width $height"); + $svg->setAttribute('width', (string)$width); $svg->setAttribute('height', (string)$height); + $svg->setAttribute('role', 'img'); $svg->setAttribute('aria-labelledby', 'title description'); + $document->appendChild($svg); + $add = function ($parent, $name, $attributes = [], $text = null) use ($document) { + $element = $document->createElementNS('http://www.w3.org/2000/svg', $name); + foreach ($attributes as $key => $value) $element->setAttribute($key, (string)$value); + if ($text !== null) $element->appendChild($document->createTextNode($text)); + $parent->appendChild($element); return $element; + }; + $points = fn($list) => implode(' ', array_map(fn($p) => implode(',', $p), $list)); + $add($svg, 'title', ['id'=>'title'], 'High-load pulse example'); + $add($svg, 'desc', ['id'=>'description'], 'Illustrated map with 90 percent inbound utilisation and 20 percent outbound. Only the 90 percent arrow pulses. Values are fixed demonstration data.'); + $add($svg, 'style', [], '.pulse{opacity:.25;animation:pulse 2.5s ease-in-out infinite}@keyframes pulse{0%,100%{opacity:.2}50%{opacity:1}}@media(prefers-reduced-motion:reduce){.pulse{animation:none;opacity:.65}}'); + $defs = $add($svg, 'defs'); + $mask = $add($defs, 'mask', ['id'=>'labels','maskUnits'=>'userSpaceOnUse','maskContentUnits'=>'userSpaceOnUse','mask-type'=>'luminance','x'=>-30,'y'=>-30,'width'=>$width+60,'height'=>$height+60]); + $add($mask, 'rect', ['x'=>-30,'y'=>-30,'width'=>$width+60,'height'=>$height+60,'fill'=>'white']); + foreach ($data['occlusions'] as $polygon) $add($mask, 'polygon', ['points'=>$points($polygon),'fill'=>'black','stroke'=>'black','stroke-width'=>2]); + $filter = $add($defs, 'filter', ['id'=>'glow','filterUnits'=>'userSpaceOnUse','x'=>-30,'y'=>-30,'width'=>$width+60,'height'=>$height+60,'color-interpolation-filters'=>'sRGB']); + foreach ([2,5,9] as $radius) $add($filter, 'feGaussianBlur', ['in'=>'SourceGraphic','stdDeviation'=>$radius,'result'=>"glow-$radius"]); + $merge = $add($filter, 'feMerge'); + foreach ([2,5,9] as $radius) $add($merge, 'feMergeNode', ['in'=>"glow-$radius"]); + $add($merge, 'feMergeNode', ['in'=>'SourceGraphic']); + $add($svg, 'image', ['href'=>'data:image/png;base64,'.base64_encode($png),'width'=>$width,'height'=>$height]); + $group = $add($svg, 'g', ['mask'=>'url(#labels)']); + foreach ($data['regions'] as $region) $add($group, 'polygon', ['points'=>$points($region['points']),'fill'=>'none','stroke'=>$region['colour'],'stroke-width'=>2,'stroke-linejoin'=>'round','filter'=>'url(#glow)','class'=>'pulse']); + return $document->saveXML(); +} diff --git a/weathermap-cacti-plugin-mgmt.php b/weathermap-cacti-plugin-mgmt.php index b47ac718..7d12182c 100644 --- a/weathermap-cacti-plugin-mgmt.php +++ b/weathermap-cacti-plugin-mgmt.php @@ -792,6 +792,7 @@ function wm_filter() { ' title=''> ' title=''> ' title=''> + '> diff --git a/weathermap-cacti-plugin.php b/weathermap-cacti-plugin.php index 13a71d2a..2ec761d2 100644 --- a/weathermap-cacti-plugin.php +++ b/weathermap-cacti-plugin.php @@ -44,6 +44,7 @@ include_once('../../include/auth.php'); require_once __DIR__ . '/setup.php'; +require_once __DIR__ . '/lib/viewer.controls.php'; global $config; include_once($config['base_path'] . '/plugins/weathermap/lib/WeatherMap.class.php'); @@ -998,30 +999,6 @@ function weathermap_tabs($current_tab) { return false; } } -/** - * Build the same escaped map heading and authorized shortcuts in each view. - * - * @param string $maptitle HTML-escaped heading. - * @param array|bool $map Map metadata, or false when unavailable. - * - * @return string The map heading with management shortcuts when authorized. - */ -function weathermap_map_title_controls($maptitle, $map) { - $heading = '' . $maptitle . ''; - - if (!is_array($map) || !isset($map['id'], $map['configfile']) || !is_string($map['configfile']) || !api_user_realm_auth('weathermap-cacti-plugin-mgmt.php')) { - return $heading; - } - $id = (int) $map['id']; - $heading .= ' [ ' . __esc('Manage Weathermaps', 'weathermap') . ' | '; - $heading .= '' . __esc('Map Settings', 'weathermap') . ' | '; - $heading .= '' . __esc('Map Permissions', 'weathermap') . ' | '; - $heading .= '' . __esc('Edit Map', 'weathermap') . ' ]'; - - return $heading; -} - - /** * Render translated, keyboard-accessible cycle controls. *