Overview

This section reviews NagVis Interfaces - Automap. 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.

The Nagvis Automap currently creates problems for medium to large size deployments and should only be used for small deployments. For this reason, the Automap has been disabled. For more information see technical bulletin: Nagvis Overview.

CONTENTS

1.0 Automap Interface
2.0 Configuration
3.0 NagVis Authentication
4.0 NagVis Advanced
5.0 NagVis Extending

RELATED RESOURCES

WAS THIS PAGE HELPFUL?

Leave Feedback

1.0 Automap Interface

First Call - 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.
Map Configuration - The automaps can be configured by special configuration files located in etc/automaps. The default map configuration file is named __automap.cfg. 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. Different automap configuration files can be defined. The automap to view needs to be set here.
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 below	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 in the next section.
maxLayers	2	This option is deprecated. Use childLayers instead (See below).
childLayers	2	Maximum layers of child hosts to be displayed.
parentLayers	0	Maximum layers of parent hosts to be displayed.
renderMode	undirected	Set the render mode of the map. For details see available render modes two sections below.
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.
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.
rotation	none	Rotate in the given rotation pool when the map is a step in the pool.
enableHeader	none	Enable/Disable the header menu. To be given as integer (1/0). Overrides the configuration.
enableHover	none	Enable/Disable the hover menus. To be given as integer (1/0). Overrides the configuration.
enableContext	none	Enable/Disable the context menus. To be given as integer (1/0). Overrides the configuration.

Root Object Definition - The approach of the automap is to start at one root object and go down the dependency-tree like defined in GroundWork Monitor and show all these objects on the map. There are several ways to get the root object (list ordered by priority):
- 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 GroundWork Monitor installation without any parent object.

Available Render Modes - There are several render modes available:

Mode Example image

directed

undirected

radial

circular

undirected2

Automap to Map Export - 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.

2.0 Configuration

2.1 Main Configuration

The main configuration file is designed in plain text ini-like format. There are sections which are marked by the surrounding brackets [ ] and variables which have an assigned value. The variables have to be in the correct section so you need to ensure and have un-commented the section. Semicolons (;) are used to mark comments. And, sections and variables with a leading semicolon are commented out and will not be recognized by NagVis.

In a fresh NagVis installation there is not a file with the default configuration. The default configuration is stored in the PHP-Code of NagVis. If there is a file etc/nagvis.ini.php, which has stored configuration information, it will override the default configurations. There is a file etc/nagvis.ini.php-sample with sample configuration values. All values are commented out.

Section Descriptions

global
General options which affect the whole NagVis installation. All values which are used throughout NagVis are stored in the global section.

Value	Default	Description
audit_log	1	Enable/Disable logging of security related user actions in Nagvis. For example user logins and logouts are logged in var/nagvis-audit.log.
authmodule	CoreAuthModSQLite	Defines the authentication module to use. By default NagVis uses the built-in SQLite authentication module. On delivery there is no other authentication module available. It is possible to add own authentication modules for supporting other authentication mechanism. For details have a look at the authentication module documentation.
authorisationmodule	CoreAuthorisationModSQLite	Defines the authorisation module to use. By default NagVis uses the built-in SQLite authorisation module. On delivery there is no other authorisation module available. It is possible to add own authorisation modules for supporting other authorisation mechanism. For details have a look at the authorisation module documentation.
dateformat	Y-m-d H:i:s	The format of date and time shown in NagVis. Available options like in date function of php.
language_detection	user,session,browser,config	This controls how NagVis tries to detect the language of the user to translate NagVis. NagVis knows several mechanisms to detect the language: - user: Explict user selected language - session: When the user selects a language it is stored in the current session - browser: NagVis tries to detect the user language by the browser agent - config: The installation default language The order you set the options determines how NagVis uses the different mechanisms.
language_available	de_DE,en_US,es_ES,fr_FR,pt_BR	You may want to give your users a limited number of languages to choose from. You can control the behavior without deleting the language files from your NagVis installation. If this value is left empty NagVis will fallback to all configured in languages. If you like to add a new language to your NagVis installation you need to add it to the list here.
language	en_US	Select default language to use in NagVis. There are several translations delivered by default: en_US (English), de_DE (German), fr_FR (French) and pt_BR (Brazilian Portuguese; since 1.4.4). Since NagVis 1.4 you have to select the languages in a new format ("en_US" instead of "english")
logonmodule	FrontendLogonDialog	Defines the logon module to use. By default NagVis uses the HTML logon dialog for requesting authentication information from the user. On delivery there is no other logon module available. It is possible to add own logon modules for serving other dialogs. For details take a look at the logon module documentation.
refreshtime	60	Refresh time of maps or reloading the next map in map rotation
sesscookiedomain	auto-detect	You may need to control for which domain NagVis will store the session cookie. By default NagVis tries to auto detect this option value by using the webservers environment variables. This should work in most environments but may be changed e.g. when using url rewriting.
sesscookiepath	auto-detected	You may need to control the path on which the cookie will be set. By default NagVis uses the paths/htmlbase value for setting the cookie. This should work in most environments but may be changed e.g. when using url rewriting.
sesscookieduration	86400	Lifetime of the NagVis session cookie in seconds. The default value is set to 24 hours. The value the NagVis session cookie contains will be renewed on every page visit. If a session is idle for more time than configured here it will become invalid.
startmodule	overview	The default module to show when none is given by the user.
startaction	view	The default action to do when none is given by the user.

paths
Path definitions. In this section all necessary path variables are defined.

Value	Default	Description
base	/usr/local/groundwork/nagvis/share/	Absolute physical NagVis path
htmlbase	/usr/local/groundwork/nagvis	Absolute html NagVis path
htmlcgi	/usr/local/groundwork/nagvis/cgi-bin	Absolute html NagVis cgi path

defaults
Default values which are inherited to the maps and its objects. If there is no value set in the map or an element on the map the default value is used.

Value	Default	Description
backend	live_1	Default backend (ID of the backend - copy the text from which <backend-id> stands for in [backend_<backend-id>] )
backgroundcolor	transparent	Default background color of maps
contextmenu	0	Enable/Disable the context menu on your map objects.
contexttemplate	default	Default context template
eventbackground	0	Enable/Disable changing background color on state changes (Configured color is shown when summary state is PENDING, OK or UP)
eventhighlight	1	Enable/Disable highlighting of the state changing object by adding a flashing border
eventhighlightduration	10000	Duration of the highlighting in miliseconds
eventhighlightinterval	500	Interval of the highlighting in miliseconds
eventlog	0	Enable/Disable the eventlog in the new javascript frontend. The eventlog keeps track of important actions and information
eventloglevel	info	Loglevel of the eventlog (Available: debug, info, warning, critical)
eventlogheight	100	Height of the javascript eventlog in px
eventloghidden	1	Hide/Show the eventlog on map loading
eventscroll	1	Enable/Disable scrolling to the icon which changed the state when the icon is out of the visible scope
eventsound	1	Enable/Disable sound signals on state changes
headermenu	1	Enable/Disable the header menu
headertemplate	default	Default header template
hovermenu	1	Enable/Disable the hover menu
hovertemplate	default	Default hover template
hoverdelay	0	Delay of hover menu appearance in seconds
hoverchildsshow	1	Enable/Disable the child objects in hover menu
hoverchildslimit	10	Limit hover child objects to this maximum value
hoverchildsorder	asc	Order of the child objects (Available: asc/desc)
hoverchildssort	a	Sort method of the child objects (Available: "s": State, "a": Alphabet )
icons	std_medium	Default iconset
onlyhardstates	0	Recognize only hard states (not soft)
recognizeservices	1	Recognize service states in host/hostgroup objects
showinlists	1	Show the maps in lists (dropdowns,index page,...)
stylesheet	(The file needs to be located in: /usr/local/groundwork/nagvis/share/userfiles/styles	Filename of the custom stylesheet to use on the maps
urltarget	_self	Target of the Icon link, this option adapts <a target=""> (_self is same window)
hosturl	[htmlcgi]/status.cgi?host=[host_name]	The default url to follow when a user left-clicks on an host object. Available Macros: [htmlcgi], [htmlbase], [host_name], [backend_id]
hostgroupurl	[htmlcgi]/status.cgi?hostgroup=[hostgroup_name]	The default url to follow when a user left-clicks on an hostgroup object. Available Macros: [htmlcgi], [htmlbase], [hostgroup_name], [backend_id]
serviceurl	[htmlcgi]/extinfo.cgi?type=2&host=[host_name]&service=[service_description]	The default url to follow when a user left-clicks on an service object. Available Macros: [htmlcgi], [htmlbase], [host_name], [service_description], [backend_id]
servicegroupurl	[htmlcgi]/status.cgi?servicegroup=[servicegroup_name]	The default url to follow when a user left-clicks on an servicegroup object. Available Macros: [htmlcgi], [htmlbase], [servicegroup_name], [backend_id]
mapurl	[htmlbase]/index.php?mod=Map&act=view&show=[map_name]	The default url to follow when a user left-clicks on an map object. Available Macros: [htmlcgi], [htmlbase], [map_name]

index
Options to configure the Overview page of NagVis.

Value	Default	Description
backgroundcolor	#fff	Configure the background color of the overview page
cellsperrow	4	Maps per row in map listing
headermenu	1	Enable/Disable the header menu
headertemplate	default	Default header template
showautomaps	1	Enable/Disable the listing of automaps
showmaps	1	Enable/Disable the listing of maps
showmapthumbs	1	Enable/Disable the listing of map thumbnails
showrotations	1	Enable/Disable the listing of defined rotations

automap
Sets the automap options.

Value	Default	Description
defaultparams	&maxLayers=2	These are the parameters for the automap views and links in the lists (map index page, dropdown menus in header)
defaultroot	localhost	Default value for the root object. For details see Automap documentation.
graphvizpath	/usr/local/bin	If the graphviz binaries (dot,neato,twopi,...) could not be found in the PATH the path has to be set here
showinlists	1	Enable/Disable the automap in map lists (map index page, dropdown menus in header)

wui
These are the options for the WUI.

Value	Default	Description
autoupdatefreq	25	In this interval the map gets backuped by the WUI.
grid_show	0	Enable/Disable a grid to make the alignment of objects easier in the WUI. Objects are aligned to the upper left corner after moving.
grid_color	#F7F7F7	The color of the grid lines.
grid_steps	32	Scale of the grid in px.
headermenu	1	Enable/Disable the header menu in the WUI.
headertemplate	default	Default header template to use in the WUI.
maplocktime	5	Time in minutes a map is locked by an editing user.

worker
Options for the new worker in the javascript frontend of NagVis.

Value	Default	Description
interval	5	The interval in seconds in which the worker will check for objects which need to be updated.
requestmaxparams	0	The maximum number of parameters used in ajax http requests Some intrusion detection/prevention systems have a problem with too many parameters in the url. Give 0 for no limit.
requestmaxlength	1900	The maximum length of http request URLs during AJAX HTTP requests. Some intrusion detection/prevention systems have a problem with too long queries.
updateobjectstates	15	The retention time of the states in seconds in the frontend. The state information will be refreshed after this time is over on next worker interval.

backend_*
The backend sections to define the backends are all named []. In the example the backend_id is live_1. Depending on the value in backendtype the valid values for the backends have to be set. In this example it is the MKLivestatus backend. For the backendtype specific options see the backends documentation.

[backend_live_1]
backendtype="mklivestatus"
htmlcgi="/nagios/cgi-bin"
; the following options depend on the selected backendtype, in this case it is MKLivestatus
socket="unix:/usr/local/nagios/var/rw/live"

Value	Default	Description
backendtype	mklivestatus	type of backend - MUST be set
htmlcgi	/nagios/cgi-bin	Path to the cgi-bin directory of this backend (interesting for multiple backends)
custom_1		First custom variable which is available in the context and hover menus. With this option different custom URLs can be added to the context/hover menus based on the backend used. Might be interesting when adding links to different Nagios instances.
custom_2		Second custom variable. Same as above.
custom_3		Third custom variable. Same as above.

rotation_*
Defines several map rotation pools. In this example the browser switches between the maps demo and demo2 every 15 seconds. The rotation is enabled by url: index.php?rotation=<rotation-id> in this case the rotation id is: demo .

[rotation_demo]
maps="demo,demo2"
interval=15

Value	Default	Description
interval	15	Map rotation interval in seconds
maps		Comma separated list of maps to rotate in this pool. You can also add external URLs surrounded by [ and ] (e.g. maps="demo1,[http://localhost/test.php]". The URL has to be reachable and accessible by the server which NagVis is running on. You can add labels in the following format <label>:<map> and <label>:<[url]>. The labels are displayed in the rotation list. It is also possible to add automaps to rotations. Simply add an @ sign before the automap name to add an automap to the rotation.

states
Options which affect the handling and appearance of the different states in the NagVis installation. These settings define the state handling behavior. Mainly it is possible to configure which state will cover another state changing these values. The state with the highest value will become the "summary state" for an object. For example a critical state (5) will cover a warning state (4). Another example: An acknowledged critical state (2) will not cover a warning state (4).

Value	Default
unreachable	8
unreachable_ack	5
unreachable_downtime	5
down	7
down_ack	5
down_downtime	5
critical	7
critical_ack	5
critical_downtime	5
warning	6
warning_ack	4
warning_downtime	4
unknown	3
unknown_ack	2
unknown_downtime	2
error	3
error_ack	2
error_downtime	2
ok	1
up	1
pending	0

These settings define the behavior of states in the frontend.

*_bgcolor: The bgcolor option is used in the background color changing eventhandler.
*_color: You can configure the foreground colors which are used for example as line colors and also in the highlight eventhandler.

*_sound: The sound file is being played on changes to the mentioned state (Needs to be MP3 format).

Value	Default
unreachable_bgcolor	#F1811B
unreachable_color	#F1811B
unreachable_sound	std_unreachable.mp3
down_bgcolor	#FF0000
down_color	#FF0000
down_sound	std_down.mp3
critical_bgcolor	#FF0000
critical_color	#FF0000
critical_sound	std_critical.mp3
warning_bgcolor	#FFFF00
warning_color	#FFFF00
warning_sound	std_warning.mp3
unknown_bgcolor	#FFCC66
unknown_color	#FFCC66
unknown_sound
error_bgcolor	#0000FF
error_color	#0000FF
error_sound
ok_bgcolor	#00FF00
ok_color	#00FF00
ok
up_bgcolor	#00FF00
up_color	#00FF00
up_sound
pending_bgcolor	#C0C0C0
pending_color	#C0C0C0
pending_sound

2.2. Map Configuration

The NagVis configuration file format is very similar 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 a " = " until a right curly bracket is found. Hashes " # " are used to mark comments, note that a comment line MUST start with a hash and not with other chars like whitespaces.

Object Type Descriptions

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
}

Value	Default	Description
map_image		The name of the map image displayed in the background of the NagVis map, for example a Visio (TM) drawing. The value can even be "none" or empty for no background image. It is also possible to add URLs here. The URL has to be surrounded by [ and].
alias	map name	The alias is the label for each map. If it is defined it is shown everywhere in NagVis frontend and WUI.
backend_id	inherited (nagvis.ini.php)	Backend-ID defined in Main Configuration file where NagVis should search for the object states. If this parameter is not given, the Backend defined as "defaultbackend" at the Main Configuration file is used.
background_color	inherited (nagvis.ini.php)	Background color of this map. If this is not set backgroundcolor from Main Configuration file is taken.
context_menu	inherited (nagvis.ini.php)	Enable/Disable the context menu on your map objects.
context_template	inherited (nagvis.ini.php)	Default context template to be used on this map.
event_background	inherited (nagvis.ini.php)	Enable/Disable changing background color on state changes (Configured color is shown when summary state is PENDING, OK or UP).
event_highlight	inherited (nagvis.ini.php)	Enable/Disable highlighting of the state changing object by adding a flashing border.
event_highlight_duration	inherited (nagvis.ini.php)	Set the highlight duration in milliseconds.
event_highlight_interval	inherited (nagvis.ini.php)	Set the highlight interval in milliseconds.
event_log	inherited (nagvis.ini.php)	Enable/Disable the eventlog in the new javascript frontend. The eventlog keeps track of important actions and information.
event_log_level	inherited (nagvis.ini.php)	Loglevel of the eventlog (Available: debug, info, warning, critical).
event_log_height	inherited (nagvis.ini.php)	Height of the javascript eventlog in px
event_log_hidden	inherited (nagvis.ini.php)	Hide/Show the eventlog on map loading
event_scroll	inherited (nagvis.ini.php)	Enable/Disable scrolling to the icon which changed the state when the icon is out of the visible scope.
event_sound	inherited (nagvis.ini.php)	Enable/Disable sound signals on state changes.
grid_show	inherited (nagvis.ini.php)	Enable/Disable a grid to make the alignment of objects easier in the WUI. Objects are aligned to the upper left corner after moving.
grid_color	inherited (nagvis.ini.php)	The color of the grid lines.
grid_steps	inherited (nagvis.ini.php)	Scale of the grid in px.
header_menu	inherited (nagvis.ini.php)	Enable/Disable the header menu
header_template	inherited (nagvis.ini.php)	header template to be used on ths map
hover_menu	inherited (nagvis.ini.php)	Enable/Disable the hover menu
hover_delay	inherited (nagvis.ini.php)	Delay of hover menu appearance in seconds
hover_template	inherited (nagvis.ini.php)	Default hover template to be used on this map
hover_childs_show	inherited (nagvis.ini.php)	Enable/Disable displaying child objects
hover_childs_limit	inherited (nagvis.ini.php)	Number of maximum children to be displayed. Set to -1 to disable the limit
hover_childs_order	inherited (nagvis.ini.php)	Order direction of child objects
hover_childs_sort	inherited (nagvis.ini.php)	Sort method of child objects
iconset	inherited (nagvis.ini.php)	Iconset to use as default for all objects placed on the map. Can be overwritten on a per object base. In the example "std_small" is used which means an OK state will be displayed using "std_small_ok.png", a CRITICAL state will be displayed by using "std_small_critical.png" and so on.
in_maintenance	0	Enable/Disable the maintenance mode of this map. If a map is in maintenance mode only a message gets displayed instead of the map.
label_show	0	Enable/Disable labels for the maps objects
label_x	-20	Default x-position of the labels in px (with prefix + or - relative to the upper left corner of the icons, otherwise absolute position)
label_y	+20	Default y-position of the labels in px (with prefix + or - relative to the upper left corner of the icons, otherwise absolute position)
label_width	auto	Default width of the labels in px
label_background	transparent	Default background color of the labels. The color should be given in hexcode. Can also be "transparent".
label_border	#000000	Default border color of the labels. The color should be given in hexcode. Can also be "transparent".
label_style		Custom styling for the label text. To be given like HTML style attribute contents. E.g. font-family:sans;font-weight:bold;
only_hard_states	inherited (nagvis.ini.php)	Sets whether soft states should be ignored. Default setting is 0.
recognize_services	inherited (nagvis.ini.php)(The file needs to be located in:/usr/local/groundwork/nagvis/share/userfiles/styles	Sets whether the states of the services on hosts, hostgroup objects should be recognized. If this is not given in the config it's set to 1.
show_in_lists	inherited (nagvis.ini.php)	Show the maps in lists (dropdowns, index page, ...)
stylesheet	inherited (nagvis.ini.php)	Filename of the custom stylesheet to use on the maps
url_target	_self	Target of the Icon link, this option adapts <a target=""> (_self is same window)

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
}

Value	Default	Description
host_name		Name of the host as defined in Nagios
x		X axis coordinate
y		Y axis coordinate
backend_id	inherited (global)	Backend-ID defined in Main Configuration file where NagVis should search for the object states. If this parameter is not given, the Backend which was set in global section of the map is taken.
context_menu	inherited (nagvis.ini.php)	Enable/Disable the context menu for this object.
context_template	inherited (nagvis.ini.php)	Context template for this object.
hover_menu	inherited (nagvis.ini.php)	Enable/Disable the hover menu
hover_delay	inherited (nagvis.ini.php)	Delay of hover menu appearance in seconds
hover_template	inherited (global)	Hover template for this object
hover_url		URL which should be displayed in hover menu instead of standard information. There are some macros available: [host_name]: This macro stands for the object name.
hover_childs_show	inherited (nagvis.ini.php)	Enable/Disable displaying child objects
hover_childs_sort	inherited (nagvis.ini.php)	Sort method of child objects
hover_childs_order	inherited (nagvis.ini.php)	Order direction of child objects
hover_childs_limit	inherited (nagvis.ini.php)	Maximum number of children to be displayed. Set to -1 to disable the limit.
iconset	inherited (global)	Special iconset. Is inherited from global paragraph if not specified.
label_show	inherited (global)	Enable/Disable label for this object
label_text	[name]	Text of the label. Available macros: [name], [alias], [output]
label_x	inherited (global)	Label X-Position (with prefix + or - relative to the upper left corner of the icons, otherwise absolute position)
label_y	inherited (global)	Label Y-Position (with prefix + or - relative to the upper left corner of the icons, otherwise absolute position)
label_width	inherited (global)	Width of the label in px
label_background	inherited (global)	Background color of the label. The color should be given in hexcode. Can also be "transparent".
label_border	inherited (global)	Border color of the labels. The color should be given in hexcode. Can also be "transparent".
label_style	inherited (global)	Custom styling for the label text. To be given like HTML style attribute contents. E.g. font-family:sans;font-weight:bold;
line_type		Specifies the type of line when view_type=line. Valid values are: "11" for lines with one arrow at the end of a line. "10" for lines with two arrows pointing to each other in the middle of the line. "12" for plain lines without arrow.
line_width	3	This defines the width of the line when this object is being displayed as line.
only_hard_states	inherited (global)	Sets whether soft states should be ignored. Default setting is 0.
recognize_services	inherited (global)	Defines if the services of the host affect the displayed state. If set to "1" a critical service on the host will result in a host state display as critical too. If set to "0" only the Nagios Host State (UP or DOWN) will be used and the services of the host will be ignored.
url		URL where the Icon should link to. Default link is to the Nagios CGIs. Macros [host_name], [htmlcgi] and [htmlbase] are available. The value can be empty to disable the link.
url_target	_self	Target of the Icon link, this option adapts <a target=""> (_self is same window). Macro [name] is available.
use		Comma separated list of object templates to use. For details see template objects
view_type	icon	This option defines the type of view for this object. Possible values are: "icon" or "line". Before NagVis 1.4 you could change the view of an object by setting the line_type. Since NagVis 1.4 you need to set the view_type for changing icons to lines. (Current version is 1.5.6)
z	1	The z option defines the order of icons which are stacked on top of each other. The highest value will be displayed on top. The background image has the value of 0. So valid values should be above or equal 1. Note: To prevent conflicts with the header navigation you should keep this value below 100.

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
}

Value	Default	Description
host_name		Name of the host as defined in Nagios
service_description		Name of the service as defined in Nagios
x		X axis coordinate
y		Y axis coordinate
backend_id	inherited (global)	Backend-ID defined in Main Configuration file where NagVis should search for the object states. If this parameter is not given, the Backend which was set in global section of the map is taken.
context_menu	inherited (nagvis.ini.php)	Enable/Disable the context menu for this object.
context_template	inherited (nagvis.ini.php)	Context template for this object.
gadget_url		The value can be a gadget script in gadget path (/usr/local/groundwork/nagvis/gadgets) e.g. "std_speedometer.php" or a full URI to a gadget like script surrounded by brackets. This option is only recognized when view_type="gadget" is set.
gadget_scale	100	The scale of the gadget. Default scale is 100 (percent). The gadgets should be able to be resized by this parameter
gadget_opts		Optional gadget specific params. The contents can be freely defined for each gadget. The value is processed as GET param "opts". We recommend to use a var/val format like this: key1=val1,key2=val2. Then you can easily split this string to an array in the gadget.
hover_menu	inherited (nagvis.ini.php)	Enable/Disable the hover menu
hover_template	inherited (global)	Hover template for this object
hover_delay	inherited (nagvis.ini.php)	Delay of hover menu appearance in seconds
hover_url		URL which should be displayed in hover menu instead of standard information. There are some macros available: [host_name]: This macro stands for the object name. [service_description]: This macro stands for the service description and will only be replaced in service objects
hover_childs_show	inherited (nagvis.ini.php)	Enable/Disable displaying child objects
hover_childs_sort	inherited (nagvis.ini.php)	Sort method of child objects
hover_childs_order	inherited (nagvis.ini.php)	Order direction of child objects
hover_childs_limit	inherited (nagvis.ini.php)	Maximum number of children to be displayed. Set to -1 to disable the limit.
iconset	inherited (global)	Special iconset. Is inherited from global paragraph if not specified.
label_show	inherited (global)	Enable/Disable label for this object
label_text	[name] [service_description]	Text of the label. Available macros: [name], [alias], [service_description], [output]
label_x	inherited (global)	Label X-Position (with prefix + or - relative to the upper left corner of the icons, otherwise absolute position)
label_y	inherited (global)	Label Y-Position (with prefix + or - relative to the upper left corner of the icons, otherwise absolute position)
label_width	inherited (global)	Width of the label in px
label_background	inherited (global)	Background color of the label. The color should be given in hexcode. Can also be "transparent".
label_border	inherited (global)	Border color of the labels. The color should be given in hexcode. Can also be "transparent".
label_style	inherited (global)	Custom styling for the label text. To be given like HTML style attribute contents. E.g. font-family:sans;font-weight:bold;
line_type		Specifies the type of line when view_type=line. Valid values are: "11" for lines with one arrow at the end of a line. "10" for lines with two arrows pointing to each other in the middle of the line. "12" for plain lines without arrow.
line_width	3	This defines the width of the line when this object is being displayed as line.
only_hard_states	inherited (global)	Sets whether soft states should be ignored. Default setting is 0.
url		URL where the Icon should link to. Default link is to the Nagios CGIs. Available macros: [host_name], [service_description], [htmlcgi] and [htmlbase]. The value can be empty to disable the link
url_target	_self	Target of the Icon link, this option adapts <a target=""> (_self is same window). Available macros: [name], [service_description],
use		Comma separated list of object templates to use. For details see template objects
view_type	icon	This option defines the type of view for this object. Possible values are: "icon" or "line". Before NagVis 1.4 you could change the view of an object by setting the line_type. Since NagVis 1.4 you need to set the view_type for changing icons to lines. (Current version is 1.5.6)
z	1	The z option defines the order of icons which are stacked on top of each other. The highest value will be displayed on top. The background image has the value of 0. So valid values should be above or equal 1. Note: To prevent conflicts with the header navigation you should keep this value below 100.

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
}

Value	Default	Description
hostgroup_name		Name of the hostgroup as defined in Nagios
x		X axis coordinate
y		Y axis coordinate
backend_id	inherited (global)	Backend-ID defined in Main Configuration file where NagVis should search for the object states. If this parameter is not given, the Backend which was set in global section of the map is taken.
context_men	inherited (nagvis.ini.php)	Enable/Disable the context menu for this object.
context_template	inherited (nagvis.ini.php)	Context template for this object.
hover_menu	inherited (nagvis.ini.php)	Enable/Disable the hover menu
hover_delay	inherited (nagvis.ini.php)	Delay of hover menu appearance in seconds
hover_template	inherited (global)	Hover template for this object
hover_url		URL which should be displayed in hover menu instead of standard information. There are some macros available: [hostgroup_name]: This macro stands for the object name.
hover_childs_show	inherited (nagvis.ini.php)	Enable/Disable displaying child objects
hover_childs_sort	inherited (nagvis.ini.php)	Sort method of child objects
hover_childs_order	inherited (nagvis.ini.php)	Order direction of child objects
hover_childs_limit	inherited (nagvis.ini.php)	Maximum number of children to be displayed. Set to -1 to disable the limit.
iconset	inherited (global)	Special iconset. Is inherited from global paragraph if not specified.
label_show	inherited (global)	Enable/Disable label for this object
label_text	[name]	Text of the label. Available macros: [name], [alias], [output]
label_x	inherited (global)	Label X-Position (with prefix + or - relative to the upper left corner of the icons, otherwise absolute position)
label_y	inherited (global)	Label Y-Position (with prefix + or - relative to the upper left corner of the icons, otherwise absolute position)
label_width	inherited (global)	Width of the label in px
label_background	inherited (global)	Background color of the label. The color should be given in hexcode. Can also be "transparent".
label_border	inherited (global)	Border color of the labels. The color should be given in hexcode. Can also be "transparent".
label_style	inherited (global)	Custom styling for the label text. To be given like HTML style attribute contents. E.g. font-family:sans;font-weight:bold;
line_type		Specifies the type of line when view_type=line. Valid values are: "11" for lines with one arrow at the end of a line. "10" for lines with two arrows pointing to each other in the middle of the line. "12" for plain lines without arrow.
line_width	3	This defines the width of the line when this object is being displayed as line.
only_hard_states	inherited (global)	Sets whether soft states should be ignored. Default setting is 0.
recognize_services	inherited (global)	Defines if the services of the hosts affect the displayed state. If set to "1" a critical service on one of the host will result in a hostgroup state display as critical too. If set to "0" only the Nagios Host State (UP or DOWN) will be used and the services of the hosts will be ignored.
url		URL where the Icon should link to. Default link is to the Nagios CGIs. Available macros: [hostgroup_name], [htmlcgi] and [htmlbase]. The value can be empty to disable the link.
url_target	_self	Target of the Icon link, this option adapts <a target=""> (_self is same window). Available macros: [name]
use		Comma separated list of object templates to use. For details see template objects
view_type	icon	This option defines the type of view for this object. Possible values are: "icon" or "line". Before NagVis 1.4 you could change the view of an object by setting the line_type. Since NagVis 1.4 you need to set the view_type for changing icons to lines. (Current version is 1.5.6)
z	1	The z option defines the order of icons which are stacked on top of each other. The highest value will be displayed on top. The background image has the value of 0. So valid values should be above or equal 1. Note: To prevent conflicts with the header navigation you should keep this value below 100.

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
}

Value	Default	Description
servicegroup_name		Name of the servicegroup as defined in Nagios.
x		X axis coordinate
y		Y axis coordinate
backend_id	inherited (global)	Backend-ID defined in Main Configuration file where NagVis should search for the object states. If this parameter is not given, the Backend which was set in global section of the map is taken.
context_menu	inherited (nagvis.ini.php)	Enable/Disable the context menu for this object.
context_template	inherited (nagvis.ini.php)	Context template for this object.
hover_menu	inherited (nagvis.ini.php)	Enable/Disable the hover menu
hover_url		URL which should be displayed in hover menu instead of standard information. There are some macros available: [servicegroup_name]: This macro stands for the object name
hover_template	inherited (global)	Hover template for this object
hover_delay	inherited (nagvis.ini.php)	Delay of hover menu appearance in seconds
hover_childs_show	inherited (nagvis.ini.php)	Enable/Disable displaying child objects
hover_childs_sort	inherited (nagvis.ini.php)	Sort method of child objects
hover_childs_order	inherited (nagvis.ini.php)	Order direction of child objects
hover_childs_limit	inherited (nagvis.ini.php)	Number of maximum children to be displayed. Set to -1 to disable the limit.
iconset	inherited (global)	Special iconset. Is inherited from global paragraph if not specified.
label_show	inherited (global)	Enable/Disable label for this object
label_text	[name]	Text of the label. Available macros: [name], [alias], [output]
label_x	inherited (global)	Label X-Position (with prefix + or - relative to the upper left corner of the icons, otherwise absolute position)
label_y	inherited (global)	Label Y-Position (with prefix + or - relative to the upper left corner of the icons, otherwise absolute position)
label_width	inherited (global)	Width of the label in px
label_background	inherited (global)	Background color of the label. The color should be given in hexcode. Can also be "transparent".
label_border	inherited (global)	Border color of the labels. The color should be given in hexcode. Can also be "transparent".
label_style	inherited (global)	Custom styling for the label text. To be given like HTML style attribute contents. E.g. font-family:sans;font-weight:bold;
line_type		Specifies the type of line when view_type=line. Valid values are: "11" for lines with one arrow at the end of a line. "10" for lines with two arrows pointing to each other in the middle of the line. "12" for plain lines without arrow.
line_width	3	This defines the width of the line when this object is being displayed as line.
only_hard_states	inherited (global)	Sets whether soft states should be ignored. Default setting is 0.
url		URL where the Icon should link to. Default link is to the Nagios CGIs. Available macros: [servicegroup_name], [htmlcgi] and [htmlbase].The value can be empty to disable the link.
url_target	_self	Target of the Icon link, this option adapts <a target=""> (_self is same window). Available macros: [name]
use		Comma separated list of object templates to use. For details see template objects
view_type	icon	This option defines the type of view for this object. Possible values are: "icon" or "line". Before NagVis 1.4 you could change the view of an object by setting the line_type. Since NagVis 1.4 you need to set the view_type for changing icons to lines. (Current version is 1.5.6)
z	1	The z option defines the order of icons which are stacked on top of each other. The highest value will be displayed on top. The background image has the value of 0. So valid values should be above or equal 1. Note: To prevent conflicts with the header navigation you should keep this value below 100.

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
}

Value	Default	Description
map_name		Name of the NagVis map cfg file (without .cfg extension)
x		X axis coordinate
y		Y axis coordinate
context_menu	inherited (nagvis.ini.php)	Enable/Disable the context menu for this object.
context_template	inherited (nagvis.ini.php)	Context template for this object.
hover_menu	inherited (nagvis.ini.php)	Enable/Disable the hover menu
hover_url		URL which should be displayed in hover menu instead of standard information. There are some macros available: [map_name]: This macro stands for the object name.
hover_template	inherited (global)	Hover template for this object
hover_delay	inherited (nagvis.ini.php)	Delay of hover menu appearance in seconds
hover_childs_show	inherited (nagvis.ini.php)	Enable/Disable displaying child objects
hover_childs_sort	inherited (nagvis.ini.php)	Sort method of child objects
hover_childs_order	inherited (nagvis.ini.php)	Order direction of child objects
hover_childs_limit	inherited (nagvis.ini.php)	Number of maximum children to be displayed. Set to -1 to disable the limit.
iconset	inherited (global)	Special iconset. Is inherited from global paragraph if not specified.
label_show	inherited (global)	Enable/Disable label for this object
label_text	[name]	Text of the label. Available macros: [name], [alias], [output]
label_x	inherited (global)	Label X-Position (with prefix + or - relative to the upper left corner of the icons, otherwise absolute position)
label_y	inherited (global)	Label Y-Position (with prefix + or - relative to the upper left corner of the icons, otherwise absolute position)
label_width	inherited (global)	Width of the label in px
label_background	inherited (global)	Background color of the label. The color should be given in hexcode. Can also be "transparent".
label_border	inherited (global)	Border color of the labels. The color should be given in hexcode. Can also be "transparent".
label_style	inherited (global)	Custom styling for the label text. To be given like HTML style attribute contents. E.g. font-family:sans;font-weight:bold;
line_type		Specifies the type of line when view_type=line. Valid values are: "11" for lines with one arrow at the end of a line. "10" for lines with two arrows pointing to each other in the middle of the line. "12" for plain lines without arrow.
line_width	3	This defines the width of the line when this object is being displayed as line.
only_hard_states	inherited (global)	Sets whether soft states should be ignored. Default setting is 0.
url		URL where the Icon should link to. Default link is to the Nagios CGIs. Available macros: [map_name], [htmlcgi] and [htmlbase]. The value can be empty to disable the link.
url_target	_self	Target of the Icon link, this option adapts <a target=""> (_self is same window). Available macros: [name]
use		Comma separated list of object templates to use. For details see template objects
view_type	icon	This option defines the type of view for this object. Possible values are: "icon" or "line". Before NagVis 1.4 you could change the view of an object by setting the line_type. Since NagVis 1.4 you need to set the view_type for changing icons to lines. (Current version is 1.5.6)
z	1	The z option defines the order of icons which are stacked on top of each other. The highest value will be displayed on top. The background image has the value of 0. So valid values should be above or equal 1. Note: To prevent conflicts with the header navigation you should keep this value below 100.

Textbox
Example with all possible 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
w=200
}

Value	Default	Description
text		Your own text, HTML is possible. There are some macros: [refresh_counter]: Shows the time until the next reload/rotate dynamically [worker_last_run]: Shows the time of the last worker run
w		Width of the textbox in px (pixels). Set to "auto" for auto scaling.
x		X axis coordinate
y		Y axis coordinate
background_color	#C0C0C0	Background color of the textbox. The color should be given in hexcode. Can also be "transparent".
border_color	#000000	Background color of the textbox. The color should be given in hexcode. Can also be "transparent".
h	auto	Height of the textbox in px (pixels). Set to "auto" for auto scaling.
style		Custom styling for the text. To be given like HTML style attribute contents. E.g. font-family:sans;font-weight:bold;
use		Comma separated list of object templates to use. For details see Template
z	1	The z option defines the order of icons which are stacked on top of each other. The highest value will be displayed on top. The background image has the value of 0. So valid values should be above or equal 1. Note: To prevent conflicts with the header navigation you should keep this value below 100.

Shape - Basically 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
}

Value	Default	Description
icon	default: /usr/local/groundwork/nagvis/images/shapes	Filename of the shape. Shapes have to be located in the shape directory
x		X axis coordinate
y		Y axis coordinate
enable_refresh	0	This option activates the shape for regular updates in the frontend. This is only needed for dynamic shape images which change once in a while.
hover_menu	0	Enable/Disable the hover menu
hover_url		URL which should be displayed when hovering over the image. By default there is no action on hover.
hover_delay	inherited (nagvis.ini.php)	Delay of hover menu appearance in seconds
url		URL where the Icon should link to. By default there is no link. The value can be empty to disable the link.
url_target	_self	Target of the Icon link, this option adapts <a target=""> (_self is same window)
use		Comma separated list of object templates to use. For details see Template
z	1	The z option defines the order of icons which are stacked on top of each other. The highest value will be displayed on top. The background image has the value of 0. So valid values should be above or equal 1. Note: To prevent conflicts with the header navigation you should keep this value below 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
}

Value	Default	Description
line_type		Specifies the type of line when view_type=line. Valid values are: "11" for lines with one arrow at the end of a line. "10" for lines with two arrows pointing to each other in the middle of the line. "12" for plain lines without arrow.
x		X axis coordinate
y		Y axis coordinate
line_width	3	The width of the line in pixels.
line_color	#ffffff	The fill color of the line in hex form. Can also be "transparent".
line_color_border	#000000	The border color of the line in hex form. Can also be "transparent".
hover_menu	0	Enable/Disable the hover menu
hover_url		URL which should be displayed when hovering over the image. By default there is no action on hover.
hover_delay	inherited (nagvis.ini.php)	Delay of hover menu appearance in seconds
url		URL where the Icon should link to. By default there is no link. The value can be empty to disable the link.
url_target	_self	Target of the Icon link, this option adapts <a target=""> (_self is same window)
use		Comma separated list of object templates to use. For details see Template
z	1	The z option defines the order of icons which are stacked on top of each other. The highest value will be displayed on top. The background image has the value of 0. So valid values should be above or equal 1. Note: To prevent conflicts with the header navigation you should keep this value below 100.

Performance - Basically 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 performance {
perf=view_1234567890.xml
x=100
y=200
}

Value	Default	Description
perf		Filename of the GroundWork Performance View as found in: /usr/local/groundwork/core/performance/performance_views
x		X axis coordinate
y		Y axis coordinate
height	500	The height of the embedded object/popup window.
popup	0	Enable the popup window. When 0 performance graphs will be embedded into the map.
hover_menu	0	Enable/Disable the hover menu
hover_delay	inherited (nagvis.ini.php)	Delay of hover menu appearance in seconds
z	1	The z option defines the order of icons which are stacked on top of each other. The highest value will be displayed on top. The background image has the value of 0. So valid values should be above or equal 1. Note: To prevent conflicts with the header navigation you should keep this value below 100.

Template - In NagVis there is a new object type named 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.

At the moment the template objects have to be defined directly in the files, the WUI doesn't support it. Maybe it'll be added in following versions. Example with all values which have to be set:

define template {
name=generic-template
}

Value	Default	Description
name		Template name (simple string without space - has to be unique within the map)
...		All values which are available in the objects which inherit this template.

2.3 Automap Configuration

The NagVis automap configuration format equal to the map configuration format with small differences in the available parameters.

Object Types Descriptions

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
}

Value	Default	Description
alias	map_name	The alias is the label for each map. If it is defined it is shown everywhere in NagVis frontend and WUI.
backend_id	inherited (nagvis.ini.php)	Backend-ID defined in Main Configuration file where NagVis should search for the object states. If this parameter is not given, the Backend defined as "defaultbackend" at the Main Configuration file is used.
background_color	inherited (nagvis.ini.php)	Background color of this map. If this is not set backgroundcolor from Main Configuration file is taken.
context_menu	inherited (nagvis.ini.php)	Enable/Disable the context menu on your map objects.
context_template	inherited (nagvis.ini.php)	Default context template to be used on this map
default_params	inherited (nagvis.ini.php)	Default parameters to take when the different options are not given by url. Format is as in the URL e.g. &childLayers=2.
event_background	inherited (nagvis.ini.php)	Enable/Disable changing background color on state changes (Configured color is shown when summary state is PENDING, OK or UP).
event_highlight	inherited (nagvis.ini.php)	Enable/Disable highlighting of the state changing object by adding a flashing border.
event_highlight_duration	inherited (nagvis.ini.php)	Set the highlight duration in milliseconds
event_highlight_interval	inherited (nagvis.ini.php)	Set the highlight interval in milliseconds
event_log	inherited (nagvis.ini.php)	Enable/Disable the eventlog in the new javascript frontend. The eventlog keeps track of important actions and information.
event_log_level	inherited (nagvis.ini.php)	Loglevel of the eventlog (Available: debug, info, warning, critical).
event_log_height	inherited (nagvis.ini.php)	Height of the javascript eventlog in px
event_log_hidden	inherited (nagvis.ini.php)	Hide/Show the eventlog on map loading
event_scroll	inherited (nagvis.ini.php)	Enable/Disable scrolling to the icon which changed the state when the icon is out of the visible scope.
event_sound	inherited (nagvis.ini.php)	Enable/Disable sound signals on state changes.
header_menu	inherited (nagvis.ini.php)	Enable/Disable the header menu
header_template	inherited (nagvis.ini.php)	header template to be used on ths map
hover_menu	inherited (nagvis.ini.php)	Enable/Disable the hover menu
hover_delay	inherited (nagvis.ini.php)	Delay of hover menu appearance in seconds
hover_template	inherited (nagvis.ini.php)	Default hover template to be used on this map
hover_childs_show	inherited (nagvis.ini.php)	Enable/Disable displaying child objects
hover_childs_limit	inherited (nagvis.ini.php)	Number of maximum children to be displayed. Set to -1 to disable the limit.
hover_childs_order	inherited (nagvis.ini.php)	Order direction of child objects
hover_childs_sort	inherited (nagvis.ini.php)	Sort method of child objects
iconset	inherited (nagvis.ini.php)	Iconset to use as default for all objects placed on the map. Can be overwritten on a per object base. In the example "std_small" is used which means an OK state will be displayed using "std_small_ok.png", a CRITICAL state will be displayed by using "std_small_critical.png" and so on.
in_maintenance	0	Enable/Disable the maintenance mode of this map. If a map is in maintenance mode only a message gets displayed instead of the map.
label_show	0	Enable/Disable labels for the maps objects
label_x	-20	Default x-position of the labels in px (with prefix + or - relative to the upper left corner of the icons, otherwise absolute position)
label_y	+20	Default y-position of the labels in px (with prefix + or - relative to the upper left corner of the icons, otherwise absolute position)
label_width	auto	Default width of the labels in px
label_background	transparent	Default background color of the labels. The color should be given in hexcode. Can also be "transparent".
label_border	#000000	Default border color of the labels. The color should be given in hexcode. Can also be "transparent".
label_style		Custom styling for the label text. To be given like HTML style attribute contents. E.g. font-family:sans;font-weight:bold;
only_hard_states	inherited (nagvis.ini.php)	Sets whether soft states should be ignored. Default setting is 0.
recognize_services	inherited (nagvis.ini.php)	Sets whether the states of the services on hosts, hostgroup objects should be recognised. If this is not given in the config it's set to 1.
show_in_lists	inherited (nagvis.ini.php)	Show the maps in lists (dropdowns, index page, ...)
stylesheet	inherited (nagvis.ini.php)	Filename of the custom stylesheet to use on the maps (The file needs to be located in: /usr/local/groundwork/nagvis/share/userfiles/styles
url_target	_self	Target of the Icon link, this option adapts <a target=""> (_self is same window)

3.0 NagVis Authentication

Permission Management - NagVis contains a very detailed permission management. It is a role based concept where users can be assigned to one or several roles while the roles have permissions assigned. The permissions of the different roles of a user are summarized and control the actions the user is able to perform.
Roles
- Default Roles - The default roles are defined in using Groups > Organization > Users and groups management. Default roles should be sufficient in the beginning, however you may delete these users and roles but be aware NOT to delete the last administrative user and role.
- Customizing the Roles - It is possible to create new roles for customizing the permissions of users and groups of users. For example it is easy to create a role for all SAP administrators which then can only access the SAP related maps.

Permissions - The permissions are hard-coded in NagVis. A single permission consists of three elements:

Module: The related module (Map, Automap, Rotation, ...)
Action: The related action (view, edit, delete, ...)

Object: The related object (A particular user, map, ...)
Each of those three elements can be set by a dedicated name or alternatively by a wildcard "*" which then matches all modules, actions or objects. Here is a list of all available permissions in NagVis:

Module	Action	Object	Description
*	*	*	Grants full access to NagVis. No other permissions are needed.
Auth	logout	*	Allows a user to logout from NagVis.
AutoMap	add	*	Create a new automap.
AutoMap	delete	*	Delete all automaps.
AutoMap	edit	*	Edit all automaps.
AutoMap	view	*	View all automaps.
AutoMap	delete	<Name>	Delete a specific automap.
AutoMap	edit	<Name>	Edit a specific automap.
AutoMap	view	<Name>	View a specific automap.
ChangePassword	change	*	Allows a user to change one's own password.
General	*	*
MainCfg	edit	*
Map	add	*
Map	delete	*
Map	edit	*
Map	view	*
Map	delete	<Name>	Delete a specific map.
Map	edit	<Name>	Edit a specific map.
Map	view	<Name>	View a specific map.
Overview	view	*
RoleMgmt	manage	*
Rotation	view	*
Rotation	view	<Name>	View a specific rotation.
Search	view	*	Search objects on maps and automaps.
UserMgmt	manage	*

4.0 NagVis Advanced

Gadgets - Gadgets are small programs which generate images from information which is provided by NagVis.
- The main idea is to provide the performance data of Nagios to these programs for visualizing it as nice graphs or fancy speedometers, thermometers etc. The gadgets can be written in any language which can be interpreted by your webserver. Some options can be PHP, and Perl. Gadgets are only supported for service objects. An object can be turned into a gadget by setting view_type="gadget" and a valid gadget_url.
- NagVis 1.4 std_speedometer gadget on test map with enabled label:

Parameters - The gadgets get their information via a HTTP-Get call from NagVis. The following parameters are being passed to the gadgets:

Parameter	Example Value	Description
name1	localhost	The name of the host.
name2	Current Load	The service description of the object.
scale	100	The scale of the gadget.
state	OK	The string which represents the current state.
stateType	HARD	The type of the current state. Can be HARD or SOFT
perfdata	load1=0.960;5.000;10.000;0; load5=0.570;4.000;6.000;0; load15=0.540;3.000;4.000;0;	The current performance data information provided by Nagios. It's important to have valid performance data here.

A valid http get on the std_speedometer.php looks like this:

std_speedometer.php?name1=localhost&name2=Current%20Load&state=OK&stateType=HARD&perfdata=load1=0.450;5.000;10.000;0;%20load5=0.260;4.000;6.000;0;%20load15=0.750;3.000;4.000;0;

How to configure - Please check the parameters view_type and gadget_url on service object in the map configuration format description.

How to Create a Custom Gadget - Using the code shown included in gadgets_core.php two arrays are filled. $aPerfdata contains the performance data. $aOpts contains the options set in gadget_opts. The best thing is to take a look at the std_speedometer and adapt the core things from there. You should set a sample perfdata string in the gadget code by writing it to the variable $sDummyPerfdata. This makes it possible to show the gadget with dummy data in the WUI. It's much easier to design the maps in the WUI when the gadgets are shown there. Important: The variable needs to be set before the gadgets_core.php is included. A second example can be found in std_speedometer2.php. In contrast to std_speedometer.php it supports output produced by check_multi. Several options influence the behavior of the gadget:

Parameter	Example Value	Description
label	1	1 = Show host name / service description in the upper left corner of the graph; 0 = don't show the information (default).
current	1	1 = Show the current performance data value (default); 0 = don't show the information.
columns	5	Graphs can be arranged in columns. The number of rows is calculated based on the maximum number of performance data items. Default is 3.
string	pct	The performance data label has to contain the string to be displayed. In case of check_multi output only the last part is examined. Default is an empty string.

Gadget: groundwork_performance_graph
This gadget is developed by Super-Visions BVBA and allows you to show the service performance graph (like in the status view) instead of just a simple icon. In the optional parameter gadget_opts you can specify the start and end time of the graph. Example:
```
start=end-4hour
```
See also AT-STYLE TIME SPECIFICATION (RRD tool) section for a detailed explanation on ways to specify the start time.

Gadget: cacti_graph
This gadget allows you to display any Cacti graph as a visual representation for a service on a map. To specify which cacti graph you want to display, you need to fill the ID of the graph, together with other options, in the gadget_opts field. Example:

id:2,w:200,h:100,p:1d

You can find the Cacti GraphID under Advanced>Network Graphing>Graph Management, where you will see a column named ID. The options that you can specify include:

id	the graph ID. shows in cacti URL's as local_graph_id
w	width in pixels
h	height in pixels (note: this does NOT include the legend)
l	whether to show the legend or not
p	period, optional. Possible values are
hh	last half hour
lh	last hour
2h	last 2 hours
4h	last 4 hours
6h	last 6 hours
12h	last 12 hours
1d	last 24 hours = last day
2d	last 48 hours = last 2 days
4d	last 4 days
1w	last week
2w	last 2 weeks
1m	last month
2m	last 2 months
4m	last 4 months
6m	last 6 months
1y	last year
2y	last 2 years
The default URL for the cacti site has to be defined in a global variable
The id value is mandatory, all others are optional. Defaults are
w	250
h	150
l	off
p	1d
Width and Height must be a positive number between 50 and 2000, otherwise the defaults kick in.
Possible values for the "l" option are on, off, true, false, 0, 1
Any other options will be discarded/ignored

Context Templates

Context templates are html files with some macros in them. These files can be used as context menus (right click menus) for the objects on the maps. The templates are named like this:
```
<name>.context.html
```
It is possible to add a css file to the template, the name has to be:
```
<name>.context.css
```
There are some so called macros available in context menus of all object types and some which are only available for some special objects. All standard macros are listed below.

General - The following macros are available in hover menus of all object types:

Macro	Description
General
[obj_id]	ID of object in JavaScript. Needed to locate the object specific parts e.g. to schedule a manual update of the state information.
[name]	Name of the object (Hostname, Hostgroupname, Servicegroupname, Mapname,...)
[custom_1]	Represents the first custom macro which can be defined per backend. Might be useful to set backend individual URLs
[custom_2]	Second custom macro. Same as above.
[custom_3]	Third custom macro. Same as above.
Language Macros
[lang_refresh_status]	Label for refreshing the status of the object in frontend.
[lang_schedule_downtime]	Label for scheduling a downtime in Nagios.
[lang_reschedule_next_check]	Label for re-scheduling the next check of the object in Nagios.
[lang_connect_by_ssh]	Label for connecting a host by ssh.
Paths
[html_base]	Absolute URL to HTML-Base Default: /usr/local/groundwork/nagvis
[html_cgi]	Absolute URL to the Nagios CGIs. Using object specific value. Depends on the used backend. If no backend specific value set the default value will be used. Default: /usr/local/groundwork/nagvis/cgi-bin
[html_templates]	Path to context templates directory. Default: /usr/local/groundwork/nagvis/share/userfiles/templates
[html_template_images]	Path to context template images directory Default: /usr/local/groundwork/nagvis/share/userfiles/images/templates

Special Macros - There are macros for context templates of a specified type. These macros should be surrounded by section macros. The section macros define that the included code will be removed if the hover template is not parsed for this type. For example a section macro for host macros looks like this:
```
.+?
```
Host Objects -

Macro Description

[address] Address of the host configured in Nagios

[pnp_hostname] Hostname with replaced blanks for links to PNP
Service Objects

Macro Description

[service_description] Service description in Nagios

[pnp_service_description] Service description with replaced blanks for links to PNP

Header Templates

Header templates are html files with some macros in it. These files can be used as header menu in the maps. Relative to the NagVis root directory, the header templates are located in:
```
/usr/local/groundwork/nagvis/share/userfiles/templates/pages/*.header.html
```
The templates are named like this:
```
*.header.html
```

Macros - The following macros are available in the header templates:

Macro	Description
{$currentMap} (was [current_map])	Name of the current map (e.g. demo,demo2)
{$currentMapAlias} (was [current_map_alias])	Alias of the current map
{$currentLanguage} (was [current_language])	String representing the current language (For example en_US). This is needed for link to documentation.
{$currentUser}	Name of the current user
{$mod}	The current Module (Map, AutoMap, Overview, Welcome, ...)
{$act}	The current Action (view, edit, ...)
{$bRotation}	Is true when currently viewing a rotation. Otherwise it is False.
{$permittedOverview}	Is true when the user is permitted to access the overview page. Otherwise it is False.
{$permittedEdit}	Is true when the user is permitted to edit the current map. Otherwise it is False.
{$permittedEditAnyMap}	Is true when the user is allowed to edit at least one map. Otherwise it is False.
{$permittedChangePassword}	Is true when the user is permitted to change the own password. Otherwise it is False.
{$permittedUserMgmt}	Is true when the user is permitted to manage user accounts. Otherwise it is False.
{$permittedRoleMgmt}	Is true when the user is permitted to manage roles. Otherwise it is False.
{$permittedLogout}	Is true when the user is permitted to log out. Otherwise it is False.
{$supportedChangePassword}	Is true when the current auth module supports changing passwords. Otherwise it is False.
foreach $maps map{$map.mapName} /foreach Note: all instances of the foreach macro should be surrounded by left and right curly brackets	A list of all maps defined in NagVis. The code between foreach $maps map and /foreach is repeated for each map. For an example have a look at: /usr/local/groundwork/nagvis/share/userfiles/templates/pages/default.header.html Within the BEGIN/END-Tags the following macros are available: * {$map.mapName} (Was [map_name]): Name of the map * {$map.mapAlias} (Was [map_alias]): Alias of the map * {$map.urlParams}: Special parameters to hand over to the NagVis frontend like search strings. * {$map.permittedEdit}: Is the user permitted to edit this map?
foreach $langs lang {$lang.language} /foreach	A list of all languages available to the users in NagVis. The code between foreach $langs lang and /foreach is repeated for each language. For an example have a look at: /usr/local/groundwork/nagvis/share/userfiles/templates/pages/default.header.html Within the BEGIN/END-Tags the following macros are available: * {$lang.language}: Internal name of the language * {$lang.classUnderline}: Underline the language * {$lang.langLanguageLocated}: Located name of the language.
if $viewType == 'Map' \|\| $viewType == 'Automap' Note: this macro should be surrounded by left and right curly brackets	To be more flexible in the templates we added some sort of if statements. These can be used as in native PHP. For an example have a look at: /usr/local/groundwork/nagvis/share/userfiles/templates/pages/default.header.html
{$pathBase} (was [html_base])	URL to HTML-Base: /usr/local/groundwork/nagvis
{$pathImages} (was [html_images])	URL to HTML-Images: /usr/local/groundwork/nagvis/images
{$pathTemplates} (was [html_templates])	Path to header templates: /usr/local/groundwork/nagvis/share/userfiles/templates
{$pathTemplateImages} (was [html_template_images])	Path to header template images: /usr/local/groundwork/nagvis/share/userfiles/images/templates
{$langOpen} (was [lang_select_map])	Label for opening new views
{$langEditMap} (was [lang_edit_map])	Label for edit map link
{$langNeedHelp} (was [lang_need_help])	Label for help selection
{$langOnlineDoc} (was [lang_online_doc])	Label for link to online documentation
{$langForum} (was [lang_forum])	Label for link to NagVis forum
{$langSupportInfo} (was [lang_support_info])	Label for link to support information
{$langOverview} (was [lang_overview])	Label for overview string
{$langInstance} (was [lang_instance])	Label for the instance string
{$langRotationStart} (was [lang_rotation_start])	Label for starting the map rotation
{$langRotationStop} (was [lang_rotation_stop])	Label for stopping the map rotation
{$langSearch}	Label for searching an object on the map
{$langToggleGrid}	Label for enabling/disabling the grid
{$langActions}	Label for choosing the available actions
{$langWui}	Label for the WUI
{$langUser}	Label for the user
{$langLoggedIn}	Label for "Logged in as"
{$langChangePassword}	Label for changing the user's password
{$langUserMgmt}	Label for managing users
{$langManageRoles}	Label for managing user roles
{$langLogout}	Label for logging out
{$langChooseLanguage}	Label for choosing the user's language

Hover Templates

Hover templates are html files with some macros in it. These files can be used as hover menus for the objects on the maps. Relative to the NagVis root directory, the hover templates are located in:
```
share/userfiles/templates
```
The templates are named like this:
```
*.hover.html
```
There are macros which are available in hover menus of all object types and some which are only available for some special objects. All standard macros are listed below.

The following macros are available in hover menus of all object types:

Macro	Description
General
[obj_type]	Type of the object (host, service, hostgroup, ...)
[obj_name]	Name of the object (hostname, hostgroupname, servicegroupname, mapname,...)
[obj_alias]	Alias of the object (If no alias is defined it is equal to [obj_name])
[obj_display_name]	Display name of the object
[obj_state]	State of the object (OK, WARNING, CRITICAL,...)
[obj_summary_state]	Merged state of the object and all child objects (OK, WARNING, CRITICAL, ...)
[obj_acknowledged]	When the state is acknowledged the macro is replaced with "(Acknowledged)"
[obj_summary_acknowledged]	When the summary state is acknowledged the macro is replaced with "(Acknowledged)"
[obj_in_downtime]	When the object is currenty in a downtime this macro is replaced with "(In Downtime)"
[obj_summary_in_downtime]	When the object is currenty in a downtime this macro is replaced with "(In Downtime)"
[obj_output]	Output for this object
[obj_summary_output]	Summary output of the object
Language Macros
[lang_name]	Label for the object name
[lang_child_name]	Label for the child object names
[lang_alias]	Label for the object alias
[lang_address]	Label for the object address
[lang_state]	Label for the object state
[lang_obj_type]	Label for the object type
[lang_summary_state]	Label for the summary state
[lang_output]	Label for the output
[lang_summary_output]	Label for the summary output
[lang_overview]	Label for the overview
[lang_instance]	Label for the NDO instance
[lang_next_check]	Label for the next check of the object
[lang_last_check]	Label for the last check of the object
[lang_current_attempt]	Label for the current attempt
[lang_last_state_change]	Label for the last state change
[lang_state_duration]	Label for the state duration
[lang_service_description]	Label for the service description
[lang_notes]	Label for the object notes
Paths
[html_base]	Absolute URL to HTML-Base: /usr/local/groundwork/nagvis
[html_templates]	Path to hover templates directory: /usr/local/groundwork/nagvis/share/userfiles/templates
[html_template_images]	Path to hover template images directory: /usr/local/groundwork/nagvis/share/userfiles/images/templates

Special Macros - There are macros for hover templates of a specified type. These macros should be surrounded by section macros. The section macros define that the included code will be removed if the hover template is not parsed for this type. For example a section macro for host macros looks like this:
```
.+?
```
Below you can find a full list of the special macros.
All Exception Map Objects

Macro Description

[obj_backendid] The backend-id of the objects backend (backend_<*>)

[obj_backend_instancename] The NDO instance name of the objects backend

Host/Service Objects

Macro	Description
[obj_address]	The address of the host object
[obj_last_check]	The date and time of the last check of this object. The datetime is printed in the defined dateformat.
[obj_next_check]	The date and time of the next check of this object. The datetime is printed in the defined dateformat.
[obj_state_type]	The current state type (HARD/SOFT)
[obj_current_check_attempt]	The number of the current check attempt
[obj_max_check_attempts]	The number of the maximum check attempts
[obj_last_state_change]	The date and time of the last state change. The datetime is printed in the defined dateformat.
[obj_last_hard_state_change]	The date and time of the last hard state change. The datetime is printed in the defined dateformat.
[obj_state_duration]	The duration of the current state
[obj_notes]	The configured notes of the host or service objects

Service Objects

Macro	Description
[service_description]	Service description in Nagios
[pnp_hostname]	Hostname with replaced blanks for links to PNP images
[pnp_service_description]	Service description with replaced blanks for links to PNP images

Host Objects

Macro Description

[pnp_hostname] Hostname with replaced blanks for links to PNP images
Servicegroup Objects
There is a very special macro for the child services of a servicegroup, this is the selection macro:
```

```
Macro Description

[lang_child_name1] Label for the host name of the child service

[obj_name1] Hostname for the child service

Performance View Objects
- It is possible to show the GroundWork Performance View views directly on a NagVis Map, either as an icon with popup on click or embedded into the map itself.
- Performance view in WUI when configured as to be embedded in the map (popup = 0 )
- Performance view object defined as popup button with hover menu.
- Configuration -See the options in the Map Configuration section to configure a Performance view object. The requirement is that you must have at least one performance view defined in GroundWork Monitor.

5.0 NagVis Extending

Working with Icons - A complete iconset consists of 11 files, these files are png images:

Filename	Description
<set>_ack.png	Acknowledged problem
<set>_error.png	Error while fetching status
<set>_unknown.png	Unknown state
<set>_critical.png	Critical state
<set>_ok.png	Ok state
<set>_up.png	Up state (Host)
<set>_down.png	Down state (Host)
<set>_sack.png	Acknowledged problem (Service)
<set>_warning.png	Warning state

NagVis checks for the <set>_ok.png image to list the iconsets, meaning there has to be a <set>_ok.png image to have a complete iconset which can be chosen in WUI.

Almost every graphic art software has the ability to build PNG-files. In this example Photoshop is used to create a smaller version of the std_small iconset called std_mini.

Iconset	Icon Size	Icon Map
std_small	16×16 pixel
mini	9×9 pixel

To implement the set in your NagVis installation, copy all files to the iconset folder:
```
/usr/local/groundwork/nagvis/images/iconsets
```
To test, open one of your maps and add a new host-icon. You should now be able to select the iconset:
```
std_mini
```
To add your own shapes, you can add "stateless Icons" to your maps, we call them shapes. These icons are completely like the other icons, they just have no state.
- A shape is nothing else than a simple image. We recommend to use PNG as format for the shapes.
- Almost every graphic art software has the ability to build PNG-files.
- The shapes are placed in:
```
/usr/local/groundwork/nagvis/images/shapes
```
- Just copy them to this directory, then you can use them in your maps.
- To test open one of your maps and add a new shape-icon. You should now be able to select your own shapes.

Language File Format
- The GroundWork language settings are taken by default from your language settings in "My Preferences". The language format are gettext language files. For details about gettext see the official gettext page.
- The language files are stored in the language specific subdirectories:
```
/usr/local/groundwork/nagvis/share/frontend/nagvis-js/locale
```
- The english language file is:
```
en_US/LC_MESSAGES/nagvis.mo
```
- The files with .po extension are the sources which have to be compiled to .mo files.
- By default the following languages are supported in the current NagVis versions:
  - english
  - german
  - french
  - spanish
  - brazilian portugese
- Any other language setting outside the above will default to English.
- Your language is not supported by NagVis? No problem! You can easily build your own language file.
  - If you built a new language file or fixed sth. in existing language files you're welcome to submit the file to us so we can implement it in the next NagVis release or publish it on Nagvis.org.
Macros - There is support for replacing given strings with some other values.
- An example for a macro is the string [USER]. This string will be replaced before displaying in NagVis when the language entry supports it.
Default Macros - Default Macros are sth. like HTML-Tags which don't have to be defined by the user. At the moment the following default macros are supported:

Macro Replaced by

[i] <i>

[/i] </i>

[b] <b>

[/b] </b>
Special Chars - Special chars like ä,ö,ü,",',... have to be set as HTML-entities (e.g. )
Install Templates - You can add templates to customize the look of header- and hover-menus. You can get some of these templates at the NagVis template download page.
The directory structure changed between the NagVis version several times. So there may be compatibility problems between the versions.
- Unpack Template - Unpack the NagVis template in a path of your choice.
```
tar xvzf NagVis-Template-<name>-<version>.tar.gz
```
- Install NagVis-Template
  - Merge the NagVis-Template directory tree with your NagVis Folder:
    Default:
    /usr/local/groundwork/nagvis/share/userfiles/templates cp -r nagvis /usr/local/groundwork/nagvis/share/userfiles/templates
Configure - Now you should be able to use the new template in NagVis. You only have to configure the maps or objects to use the template.
- Header-Templates - You can set the header template in the main configuration of NagVis or in the global section of the map configuration. For details see Map Configuration.
- Hover-Templates - You can set the hover template in the main configuration for all your maps, in the global section of a map for all the objects on this map or in each object for having a custom hover menu for special objects. For details see Map Configuration.
Custom Context Menu Actions
- The context menus basically are right-click menus on the status icons. You can customize these menus by simply editing some template files. The template files are simple html files including some macros which are replaced during render time in NagVis.
- The context menus give you the ability to improve your administrative workflow with the monitoring information dramatically. Imagine you have a NagVis map as the primary user interface to gather status information about your systems and even as a base to control your systems. Imagine you can view status information from NagVis and simply connect to the problematic systems by ssh or via terminal session by just two clicks. It is also possible to store some default recover jobs in scripts or anything else.
- Take a look at this guide to get some ideas of the power of this new feature.
Quick How-To - This is a quick how-to to add a "connect by ssh" option to the NagVis hosts context menu. Most of the changes have to be made on the client browsers to get it handle ssh connections. In this guide I am using the firefox on Ubuntu. It is no problem to get this work on other systems like Windows.

Read basics about context templates

Create custom context template
Just copy the default context template:

cd /usr/local/groundwork/nagvis
cp share/userfiles/templates/default.context.html share/userfiles/templates/default-ssh.context.html

Now add a line to the host specific macro section like follows:

<li><a href="ssh://[address]">[lang_connect_by_ssh|lang_connect_by_ssh]</a></li>

The template is finished.

Configure host to use the new template
Set the option to use the new template called default-ssh:
```
context_menu=true
context_template=default-ssh
```
You can set this option in the global section of a map, in a host object or even a template which is used in a host object.
Configure your client to handle ssh:// uris
In this case I configure firefox on Ubuntu Linux. This may differ on your system. Open about:config in your firefox. Add some new options:
Name: network.protocol-handler.app.ssh
Type: String
Value: /usr/local/bin/ssh-connect-handler

Name: network.protocol-handler.expose.ssh
Type: Boolean
Value: true

Name: network.protocol-handler.external.ssh
Type: Boolean
Value: true

Name: network.protocol-handler.warn-external.ssh
Type: Boolean
Value: false
Create a handler script
Create the script at the given script path. In my case it is: /usr/local/bin/ssh-connect-handler
```
#!/bin/bash
xterm -e ssh ${1#ssh:\/\/*}
```
You need to make this script executable.
```
chmod +x /usr/local/bin/ssh-connect-handler
```
Test handler script:
Just enter ssh://<test-host> in your browser address bar and press enter. If an xterm with the ssh session opens everything is ok here.
Test context links:
Now open the map you configured the new context template usage. Then right-click the host you configured and hit the menu entry "Connect by ssh". A terminal window should open now.

Configuring NagVis