Weathermap

h6. Overview

The Weathermap package is an open source toolkit for creating dynamic maps of network traffic and is integrated into GroundWork Monitor.{section}
{column:width=40%}CONTENTS
{toc:minLevel=1|maxLevel=1|printable=false}
{column}{column:width=35%}RELATED RESOURCES
* [Cacti]

h1. 1.0 About Weathermap

In simple terms, Weathermap is an integrated toolkit for creating overhead maps that display the network traffic levels between selected devices. Whereas most of the components in GroundWork Monitor are designed for the purpose of monitoring the devices on a network (such as measuring the available resources on a host and then generating alarms when conditions require it), Weathermap is designed to help administrators visualize the traffic between network devices.

More specifically, the graphing component of Weathermap uses user-generated configuration files to build dynamic graphical maps of a network, including the nodes and links on a network, and then reads existing databases of network traffic to display the traffic levels on each link. Meanwhile, the editing component of Weathermap provides a web-based graphical front-end to the configuration files, and allows users to build the maps quickly and easily.

Weathermap is primarily intended to be used with the GroundWork Cacti package, which provides direct support for executing the Weathermap graphing component through a plugin. However, Weathermap generates maps as PNG images with DHTML wrappers that provide interactive features such as hyperlinks and pop-up charts, so the map output can be used anywhere that a web page or PNG image can be used. For example, the resulting maps can be used to provide a background image for a GroundWork Dashboard applet, if the user wishes to do so.

This document discusses the basic configuration and operation of Weathermap. For more detailed discussion, refer to the [online Weathermap documentation|http://www.network-weathermap.com/manual/latest/pages/main.html].

h1. 2.0 Configuring the Weathermap Package

The GroundWork NMS Weathermap package has its own unique configuration process.

h6. Managing User Access

The Weathermap web pages are provided by a NMS-specific instance of Apache, although the Weathermap web front-end is also integrated into GroundWork Monitor through the use of the JBoss Portal. As such, users who have been granted the appropriate role-based permission to access the Weathermap object can do so by logging into GroundWork Monitor, and then choosing the "Weathermap" entry from the main drop-down menu.

Weathermap does not provide any user accounts or access controls itself, although you can restrict access to the map editor with GroundWork role privileges, and you can also restrict access to the Weathermap plugin for Cacti from within Cacti as well. For information on configuring user access to the "Weathermap" menu item, refer to the "Configuring Roles" section of the Administration documentation. Refer to the NMS Cacti chapter for more information on the Weathermap plugin for Cacti.

h6. Setting the Editor Defaults

By default, the Weathermap Editor uses internal defaults and compile-time switches to determine program behavior. However, the program is able to use a configuration file to override some of the predefined settings, if needed. By default, the configuration file does not exist and must be created, although a sample configuration file is provided which can be copied into place. The sample configuration file is {{/usr/local/groundwork/nms/applications/cacti/plugins/weathermap/editor-config.php-dist}}, which can be renamed to {{editor-config.php}} once it has been edited to reflect your specific requirements.
{Note}The Weathermap {{generator}} does not use a configuration file for the program itself, but instead uses command-line switches and the map control files to determine the map behavior. For information on the important command-line switches to the map generator, refer to the Automating the Map Generator section below.{Note}

h6. Automating the Map Generator

Since the graphical maps that are generated by Weathermap use static PNG files, they only represent the network state at the moment they are created. In order to keep the map files up to date, they must be regenerated somewhat frequently.

Normally this process is handled by the Weathermap plugin for Cacti, which executes the Weathermap generator during every polling run (once every five minutes by default). However, you can also automate the map creation separately by adding the program to the {{nagios}} user's {{crontab}} file. To do this, perform the following steps:
# Login to the GroundWork server with root privileges.
# From a command prompt, issue the {{crontab \-u nagios \-e}} command to edit the {{crontab}} file associated with the {{nagios}} account.
# For each map that you want to automatically generate, create a separate {{crontab}} entry for the {{/usr/local/groundwork/nms/applications/cacti/plugins/weathermap/weathermap}} program with the necessary command-line parameters (see below), and the desired time interval.
# Save the {{crontab}} file and exit the editor. The {{cron}} daemon will automatically incorporate the new command-line parameters into its current schedule.
{Note}The map control files that are used by the Weathermap generator store all of the information that is needed to create the PNG and DHTLM output files, so the only necessary command-line argument is to identify the configuration file that should be read. However, you can also specify the output filenames on the command-line if necessary or desired.{Note}

The important command-line arguments are {{\--config <filename>}} (where {{<filename>}} is the path to the map configuration file that you want to process), {{\--output <filename>}} (where {{<filename>}} is the path to the desired image file), and {{\--htmloutput <filename>}} (where {{<filename>}} is the path to the desired HTML web page).

For a list of the available command-line parameters, execute the {{weathermap}} program with the {{\--help}} command-line argument. For more information about the Weathermap command-line parameters, refer to the [online Weathermap documentation|http://www.network-weathermap.com/manual/latest/pages/main.html]. For information on the Cacti plugin, refer to the Cacti NMS chapter.

h1. 3.0 Using the Weathermap Editor

Although the map configuration files are simple text files that can be edited with any tool, Weathermap also includes a graphical, web-based editor that makes it easy to create simple maps. However, the editor is very lightweight and only has a handful of options, so building more complicated maps often requires additional editing.

By default, the map configuration files are stored in and loaded from the {{/usr/local/groundwork/nms/applications/cacti/plugins/weathermap/configs}} directory, and that is where the map generator and the Cacti plugin will look for new maps.
{Note}The list of available maps includes a file called {{index.php}}, which is used by the Apache web server, and is not a map file.{Note}
{Note}:Do not modify the {{index.php}} file in the weathermap editor.{Note}

As can be seen, the map editor is not particular about file name extensions, and any file name extension can be used. However most maps have historically used a {{.conf}} extension, and it's a good practice to use that syntax in case another program eventually requires it.

Once a map has been created or loaded for editing, the screen will be reloaded with the main editor window. From here you can add a device, add links between devices, add or move a bandwidth color legend, move the embedded timestamp, or modify the global map properties.
{Note}The map files cannot be deleted from inside the editor.{Note}

h6. Setting Map Properties

Each map has certain global settings that affect how the overall map appears. For example, each map has a title, a height and width, and so forth.

The size of the map can also be adjusted here if needed.
{Note}If you choose a background image, the map will inherit the image's dimensions and the values in the "Map Size" field will be ignored.{Note}

If you want to hard-code the output PNG and HTML files, you can do so here as well. However, this is not necessary unless you are planning to use the output files in another application. By default, the Cacti plugin uses its own output naming rules.

h6. Managing Map Devices

Weathermap "nodes" are used to represent the devices on the network, such as routers and hosts. They do not typically change appearance dynamically, although they can have dynamic properties such as mouse-over graphs.

To add a new device, click the "Add Node" menu item. The mouse cursor will change into a cross-hair, allowing you to click and place a device on the map. Once you place the device, a new boxed element labeled "Node" will appear on the map.

The "Info URL" field stores a hyperlink for the node. When a user clicks on the node graphic, the specified URL will be opened in the web browser. By default, this field is overwritten with a relative URL that is based on the "Hover Graph URL" field below it, but it can link to any valid URL.

The "Hover Graph URL" field stores a URL for an object that should be displayed in a JavaScript pop-up whenever a user hovers their mouse cursor over the device (a good use for this is to show a CPU load graph, or some other kind of other dynamic data). The editor assumes that this will be a Cacti graph and provides a hyperlink for "\[Pick from Cacti\]" that lists all the known Cacti graph definitions. However, this can field can point to any graphic object that can be displayed in the user's web browser.

The "Icon Filename" field allows you to place a graphic element behind the node label. By default, the editor provides a list of the files in the "images" subdirectory, but you can use any image on the local computer that the nagios user account has permission to access.
{Note}The "Edit" button allows you to view and modify the actual configuration text for the selected device entry. If you need to override any of the default values (such as the icon path or the node's hyperlink), you can use this entry form.{Note}

To delete a node from the map, open the properties dialog for the device and click the "Delete" button.

h6. Managing Device Links

Weathermap uses "links" to represent the network connections between nodes. The links will typically change color to reflect the amount of traffic being exchanged between those nodes, and they can also have dynamic properties such as mouse-over graphs.

To add a new link between two devices, click the "Add Link" menu item. The mouse cursor will change into a cross-hair, allowing you to click on a beginning device, and remain as a cross-hair until you also click the ending device. Once you place the link between the two nodes, a new element with arrows facing towards each other will appear on the map.

The "Data Source" field is primarily used to point to a round-robin database (RRD) file that contains information about the traffic activity on the selected network link. Typically this is a Cacti data source for a specific network interface on a specific device, which includes individual fields for the amount of traffic that has been sent and received by that device. The weathermap generator then maps the sent and received data to the beginning and ending nodes associated with the link, thereby allowing it to correctly associate in-bound and out-bound traffic with the correct node.

The editor assumes that the "Data Source" will be a Cacti graph and provides a hyperlink for "\[Pick from Cacti\]" that lists all the known Cacti RRD files. However, this can field can point to any RRD file on the local computer that the {{nagios}} user account has permission to access (such as RRD files that have been created by Nagios), and can also fetch data from sources other than RRD files with some extra effort. If you use a data source that is not a Cacti RRD, you will likely need to edit the configuration file by hand. For more information about the data sources that are available, refer to the [online Weathermap documentation|http://www.network-weathermap.com/manual/latest/pages/main.html].

The "Info URL" field stores a hyperlink for the link. When a user clicks on the link graphic, the specified URL will be opened in the web browser. By default, this field is overwritten with a relative URL that is based on the "Data Source" field above it, but it can link to any valid URL.

The "Hover Graph URL" field stores a URL for an object that should be displayed in a JavaScript pop-up whenever a user hovers their mouse cursor over the link. By default, this field is overwritten with a relative URL that is based on the "Data Source" field above it, but it can link to any graphic object that can be displayed in the user's web browser.
{Note}The "Edit" button allows you to view and modify the actual configuration text for the selected link entry. If you need to override any of the default values, you can use this entry form.{Note}

To delete a link from the map, open the properties dialog for the link and click the "Delete" button.

h1. 4.0 Integrating Maps with GroundWork Monitor

At the present time, the GroundWork NMS Weathermap package does not include any tools for automatically integrating maps into other GroundWork applications. However, the GroundWork Cacti package does provide a plugin that allows the maps to be displayed inside Cacti. Furthermore, GroundWork applications such as the Dashboard toolkit can use the PNG images generated by Weathermap, and it is feasible to automate some parts of this process.