PHP Weathermap is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
PHP Weathermap is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with PHP Weathermap; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
Parts of this software distribution are by other authors. Please see the README file for attribution and license details.
Sample output from php-weathermap, using data collected by Cacti and MRTG.
Larger version
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 'DHTML' overlays of historical data and links into your other monitoring/statistics system. It also has a interactive map editor, so you can largely avoid the text configuration files, if you prefer.
To get a better idea of what is possible, see the example map that comes with this manual.
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.
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 new Cacti plugin, you will need a recent version of Cacti, and the matching Cacti Plugin Architecture, from Jimmy Conner's Cactiusers.org.
I've broken the rest of this manual up into sections - an Installation guide and quick-start basic introduction with example (this page), a reference of command-line options, a reference of all the configuration options, an introduction to the new editor, and a FAQ/Tips section.
There are two mailing lists for php-weathermap:
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.
Since most of the integration features are optional, there are a number of ways to install Weathermap.
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:
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.
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!
To use the Cacti plugin, you must unpack the zip file into a directory called '<cacti_root>/plugins/weathermap'.
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
Then, edit your cacti config.php file and add a line:
$plugins = array(); $plugins[] = 'monitor'; $plugins[] = 'weathermap';
Now, refresh your Cacti page, to be sure that everything is still working right. If not, remove the line you just added and you should return to normal. Make a note of any error message and let me know!
Assuming it all looks fine (but not very different), you can start to enable Weathermap. Log in as 'admin' or another user with User Management rights, go to the User Management section under Tools in the Cacti console, and then choose your own username from the list. Check the two new 'realms' boxes that should be there - View Weathermaps, and Manage Weathermaps - and then click Save. A 'Weathermap' tab should appear at the top of the page.
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. This is controlled by the 'memory_limit =' line in php.ini. You may need to increase this to 16MB or 32MB if you have problems.
That's it! The Weathermap plugin is installed. 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.
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).
Start by following the instructions above for either a Standalone or Cacti Plugin installation. You will be running weathermap just the same way, but once you have a working weathermap (or plugin), you need to continue below:
Copy the editor-config.php-dist file to editor-config.php. If you use Cacti, and 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
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.
You should now be able to go to http://yourserver/wherever-you-unpacked-weathermap/editor.php (or http://yourserver/cacti/plugins/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, even with the Cacti Plugin. This is why the configuration file doesn't exist by default - the editor won't work until you choose to make it work. It's recommended that you either:
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.
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.
NODE nycore1 LABEL NYC POSITION 30 30A simple NODE
Nodes are the points on your network that are joined together. Depending on the detail in the map, they might be cities or individual routers. In a basic map, a node has 3 pieces of information - an internal name which must be unique to this node, it's position from the top-left corner of the map, in pixels, and optionally a label, which will appear within the box marking the position of the node. Nodes without a label don't appear on the map at all, but can still be used as an endpoint for a link.
LINK backbone1 NODES nycore1 paix1 BANDWIDTH 3M TARGET ../my-mrtg-data/backbone1.htmlA simple LINK
Links are the network routes between the Nodes. Typically they are actual network links, but they can be anything that you can get numbers for that make sense on map.
An absolute minimal link has 3 pieces of information too. They are the unique internal name for this link, and unique node names for the two endpoints. To show current usage on the map, you'll need to give two more pieces: the maximum bandwidth on the link, and a way to get the current throughput. The BANDWIDTH is measured in bits/sec, and can include the usual K,M,G and T suffixes for large values. The data-source is given in the TARGET line, and can be one of
These settings usually live at the top of the text file, and specify basic information about the map. The minimum settings are:
WIDTH 800 HEIGHT 600
This is specifies the size of the map in pixels. If you want something a bit fancier than a plain white background, you can make up a background image to use in PNG format. In that case, the map will be the size of the background image:
There are also 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.
# 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=228A Sample Configuration File
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.