Map configuration format description

General Information

The NagVis configuration file format is very similiar to the format used by Nagios®.

Configuration statements start with the keyword "define" followed by a type field and a left curly bracket ({). Every following line defines variable-value pairs, separated by an equal sign (=) until a right curly bracket (}) is found.

Hashes (#) are used to mark comments, note that a comment line MUST start with a hash not with other chars like whitespaces!

Object types

• Global
• Host
• Service
• Hostgroup
• Servicegroup
• Map
• Textbox
• Shape
• Line
• Template
• Container (New in 1.7.1)
• Dynamic Group (New in 1.8b1)
• Aggregation (New in 1.8rc2)

Description of the object types

Global

The first definition in every config file should be of the special type "global". Options which are defined at this paragraph are valid for the whole map and are getting inherited to other types defined later.

Example with all options which have to be set:

define global {
 map_image=lan.png
}

Host

Example with all options which have to be set (note that options already defined in the global section are optional):

define host {
 host_name=localhost
 x=100
 y=200
}

Service

Example with all options which have to be set (note that option already defined in the global section are optional):

define service {
 host_name=localhost
 service_description=ping
 iconset=std_big
 x=100
 y=200
}

Hostgroup

Example with all options which have to be set (note that options already defined in the global section are optional):

define hostgroup {
 hostgroup_name=servers
 x=100
 y=200
}

Servicegroup

Example with all options which have to be set (note that options already defined in the global section are optional):

define servicegroup {
 servicegroup_name=servicegroup1
 x=100
 y=200
}

Map

Example with all options which have to be set (note that options already defined in the global section are optional):

define map {
 map_name=webserver
 x=77
 y=156
}

Textbox

Example with major options:

define textbox {
  text="This is an informational text which can be placed anywhere on the map, HTML can also be used for formatting purposes"
 x=200
 y=100
}

Shape

Basicaly shapes are simple images which can be moved and positioned on the map. The shapes are meant to be layout elements. The shapes were added to give the users the option to create less static maps.

Example with all values which have to be set:

define shape {
 icon="test"
 x=200
 y=100
}

Line

The line is a stateless layout element to connect elements and visualize stateless connections between other objects. The objecttype has been created to make the design less static.

Example with all values which have to be set:

define line {
    line_type=1
    x=200
    y=100
}

Template

With this object you have the ability to define all values except the must-have-attributes in one object for many others. You can set all attributes to the value you need and inherit them with the use attribute to each object.

Please note: When editing objects using object templates using the web based editing functions the values configured in the template will be copied to the edited objects. From this time the values set in the object are not used anymore. It is not recommended to use the web editing frontend and template objects at the same time.

Example with all values which have to be set:

define template {
 name=generic-template
}

Container (New in 1.7.1)

Example with major options:

define container {
  url="std_hello.php"
  x=200
  y=100
}

Script: std_lq.php (New in 1.7.1)

This script is delivered with NagVis. It can be used to list data fetched via livestatus on your maps to e.g. display lists of items or just raw numbers.

Please note: By default all queries get the current username added with the AuthUser livestatus filer. Resulting from this a user can only see the hosts and services he is a contact of. To change this behaviour you can customize (copy) the std_lq.php and change the setAuthUser to the following definition:

$setAuthUser = true;

To add the script to your maps you need to add std_lq.php with additional parameters to the url parameter in a container object. The parameters are given as URL parameters.

You have to call this script with at least two parameters:

Optional parameters:

Example calls to this script:

std_lq.php?backend_id=live_1&query=GET hosts\\nLimit: 1\\nColumns: host_name\\n&type=cell

std_lq.php?backend_id=live_1&query=GET hosts\\nLimit: 1\\nColumns: host_name address state\\n&type=row

std_lq.php?backend_id=live_1&query=GET hosts\\nLimit: 2\\nColumns: host_name\\n&type=column

std_lq.php?backend_id=live_1&query=GET hosts\\nLimit: 2\\nColumns: host_name state address\\n&type=list

Dynamic Group

Please note: Dynamic groups can only be used with livestatus backends.

This example creates a dynamic group named "My Dynamic Group" which engroups all services which have the name "CPU load". All used options have to be set (note that options already defined in the global section are optional):

define dyngroup {
 name=My Dynamic Group
 object_types=service
 object_filter=Filter: service_description = CPU load\n
 x=100
 y=200
}

Aggregation

Please note: Aggregations can currently only be used with the "mkbi" backend.

This example creates an object showing the state of a Check_MK BI Aggregation which is named "Host localhost". All used options have to be set (note that options already defined in the global section are optional):

define aggr {
 name=Host localhost
 x=100
 y=200
}

Variable Types

This chapter explains the different variable types used in the map configuration file.

Coordinates

The objects on the NagVis maps are positioned using coordinates. By default each coordinate is a single integer which defines the offset from the upper left corner of the map in px (Pixels).
The example below is a host object which is positioned 100px from the left and 100px from the top of the map:

define host {
 object_id=41790e
 host_name=localhost
 x=100
 y=100
}

It is possible to define multiple coordinates for one object. This is needed for drawing lines on the maps. One example of a line which starts at 100/100 and ends at 200/200:

define service {
 object_id=1dd76b
 host_name=localhost
 service_description=Interface eth0
 view_type=line
 line_type=10
 x=110,200
 y=110,200
}

When lines have one part (e.g. --->) there must be two coords set. When using lines with two (e.g. ---><---) parts it is possible to set two coordinates for direct lines or three coordinates to reposition the middle of the line to a custom place.

Since NagVis 1.6 it is possible to position objects depending on other objects. A relationship between two objects is defined from the "childs" view. This means the configuration needs to be done in the object which belongs to another object.
To define a relationship the coordinate is not given as integer anymore. Instead of the px offset the object_id of the parent object is used to define a relative position.

We adapt the examples above and give the start of the line a relative position to the host object:

define host {
 object_id=41790e
 host_name=localhost
 x=100
 y=100
}

define service {
 object_id=1dd76b
 host_name=localhost
 service_description=Interface eth0
 view_type=line
 line_type=10
 x=41790e,200
 y=41790e,200
}

With the configuration above the beginning of the line is attached to the host object and moved every time the host object is moved.

The above example does not result in exactly the same positions as the first example. The line beginning in the first example is 10px more to the left and 10px more to the bottom. To get that fixed it is possible to define an optional offset to the parent object.

Set the following coordinates to configure an offset of 10px in both directions:

x=41790e%+10,200
y=41790e%+10,200

It is also possible to set a negative offset by replacing the plus (+) sign with a minus (-) sign.

Exclude Regex (New in 1.6b4)

The exclude regular expressions can be used to filter out one or several members of objects. For example it is possible to filter out one specific service of a host, like in this simple example where the service "CPU load" is excluded:

define host {
  object_id=5932ab
  host_name=localhost
  x=123
  y=123
  exclude_members=CPU load
}

exclude_members=^DB_test

The same is possible for hostgroups, servicegroups and so on.

Another more advanced task is to exclude just one service of one host from a hostgroup. This can be seen as a member element of a member. Let's exclude "CPU load" of the host "localhost".

define hostgroup {
  object_id=b5932a
  hostgroup_name=mygroup
  x=42
  y=23
  exclude_members=localhost~~CPU load
}

When excluding members of members you need to use the string "~~" as separator between the two expressions for matching the member name (host_name in this case) and the regex for the name of the members member (service description in this case).