NagVis Automap

Introduction

The NagVis Automap was introduced in NagVis 1.3. The main topic of this feature is to replace the builtin map in Nagios. The main problem of the Nagios map is that it is not scalable. In big Nagios installations the automap is not usable. This is e.g. caused by missing configuration options like selecting a defined scope of elements to display. NagVis handles the objects and defines a configuration for Graphviz. The map image and the HTML-Code for the links are generated by graphviz and passed on to NagVis.

Prerequisites

Graphviz >= 2.14 for the automap (lower versions have problems with truecolor rendering). You also need more packages like gd,libpng,freetype, ... but if you get graphviz compiled/installed it should work.
You have to define dependencies between hosts starting with the Nagios server. Please have a look at the Nagios documentation on how to do this
Use the directive "defaultroot=..." in the [automap] section in nagvis.ini.php to specify the name of your monitoring server (or any other host which should be the starting point). Please make sure that you use the name you specified in the host_name directive of the host definition. In most real life setups it is not called "localhost" ;-).

First call

The automap can be called like this:

http://<nagios-server>/<path-to-nagvis>/frontend/nagvis-js/index.php?mod=AutoMap&act=view&show=__automap

If everything is configured properly the root host and 2 levels of child hosts should be displayed on the automap.

Main configuration

Some parameters for the automap can be set in the main configuration of NagVis. For further information see Main Config Format Description.

Map configuration

The automaps can be configured by special configuration files located in etc/automaps. The default map configuration file is named __automap.cfg. All values can be found in the Automap Config Format Description. The values like iconset etc. are inherited to all objects on the map.

URL Parameters

The automap can be called with several url parameters. Here is a list of all available options:

parameter	default	description
show		The name of the automap. Since NagVis 1.5 different automap configuration files can be defined. The automap to view needs to be set here. (New in 1.5)
backend	default backend	The backend-id of the backend to fetch the objects from. For details see the [backend_*] section in the Main Config Format Description
root	see root object definition	This is the name of the root object. It is not essential to set the host here. There are some more ways to tell the root object. For details see the root object definition chapter on this page.
maxLayers	2	This option is deprecated. Use childLayers instead (See below).
childLayers	2	Maximum layers of child hosts to be displayed. (New in 1.5)
parentLayers	0	Maximum layers of parent hosts to be displayed. (New in 1.5)
renderMode	undirected	Set the render mode of the map. For details see available render modes
width	1024	width of the automap in pixels
height	786	height of the automap in pixels
ignoreHosts	none	comma separated list of hosts (including children) not to display
filterByState	none	Set to 1 to enable the "problem automap" mode. When it is set to 1 it will filter all branches out which have only OK/UP hosts. This will result in a "problem automap" which only shows up a tree where each branch has at least one problem. (New in 1.5)
filterGroup	none	Provide a hostgroup name. Only hosts in this hostgroup will be shown on the map.
search	none	Search for a map object on map load. Matching objects will be highlighted. (New in 1.5)
rotation	none	Rotate in the given rotation pool when the map is a step in the pool. (New in 1.5)
enableHeader	none	Enable/Disable the header menu. To be given as integer (1/0). Overrides the configuration. (New in 1.5)
enableHover	none	Enable/Disable the hover menus. To be given as integer (1/0). Overrides the configuration. (New in 1.5)
enableContext	none	Enable/Disable the context menus. To be given as integer (1/0). Overrides the configuration. (New in 1.5)

Root object definition

The approach of the automap is to start at one root object and go down the dependency-tree like defined in Nagios and show all these objects on the map. There are several ways to get the root object:

URL-Parameter: The root object can be set by the parameter root.
Main configuration: The defaultroot option can be set in the [automap]-section.
Auto detection: Ask the backend for a host without parent. This only works when there is ONE host in your Nagios installation without any parent object.

The list above is ordered by priority.

Available render modes

There are several render modes available:

Mode	Example image
directed
undirected
radial
circular
undirected2

Automap to Map export (New in 1.5)

Since NagVis 1.5 it is possible to export the current automap view as a classic NagVis map. Exporting automaps to classic maps you get the advantages of both worlds.

You can start with the automap to get all the object positioned on your maps using the automap render modes. Once you finished the rendering you can export the automap including the generated background image to a regular map using the "Export to map" which can be found in the "Actions" submenu in your header menu.

With the exported map you can add design elements as you want and customize your layout according to your needs.

A map can be exported multiple times to the same target map. But it will overwrite all changes you made to the target map before. You can only overwrite maps you have edit permissions on.

A classic map can not be turned into an automap.

Host URLs

The URLs of the host objects are used for identifying the host objects during automap rendering. Especially the "host=" parameter is important. When this parameter is missing in the host URLs the object positions can not be gathered.

By default this information should not of interest to you. But when you customize the host URLs in your NagVis installation it is important to know that your custom URL needs to have the "host=" parameter set to the hostname of the object to be able to use the hosts on the automap.