# Main configuration format description

## General Information

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 have to ensure to have uncommented the section too. Semicolons (`;`) are used to mark comments. Sections and variables with a leading semicolon are commented out and won't be recognised by NagVis.

In a fresh NagVis installation there is no 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 overview

- global
  General options which affect the whole NagVis installation
- paths
  Path definitions
- defaults
  Default values which are inherited to the maps and its objects
- index
  Options to configure the Overview page of NagVis
- automap
  Options for the Automap
- wui
  Options for the WUI
- worker
  Options for the Worker
- backend_*
  Backend definitions
- rotation_*
  Rotation pool definitions
- states (New in 1.5)
  Options which affect the handling and appearance of the different states

## Description of the sections in detail

### global

All values which are used througout 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. (New in 1.5)
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. (New in 1.5)
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. (New in 1.5)
dateformat | Y-m-d H:i:s | The format of date and time shown in NagVis. Available options like in date function of php
displayheader | 1 | Show header menu in maps. (Deprecated in 1.4. Moved as option "headermenu" to default and index section.)

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. (New in 1.5)

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 behaviour 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. (New in 1.5)

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. (New in 1.5)
logonenvvar | REMOTE_USER | Defines the environment variable to be used for fetching the authenticated user from the webservers environment. This option is only used with the logon modules LogonEnv and LogonMixed. (New in 1.5)
logonenvcreateuser | 1 | Tells the LogonEnv/LogonMixed module to create a user account for each unknown user which opens the NagVis pages. This option is only used with the logon modules LogonEnv and LogonMixed. (New in 1.5)
logonenvcreaterole | Guests | Tells the LogonEnv/LogonMixed module to create the user accounts with the given role associated. This option is only used with the logon modules LogonEnv and LogonMixed. (New in 1.5)
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. (New in 1.5)
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. (New in 1.5)
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. (New in 1.5)
startmodule | overview | The default module to show when none is given by the user (New in 1.5)
startaction | view | The default action to do when none is given by the user (New in 1.5)
startshow |  | The startshow parameter is only used by some views at the moment. It is used by the Map and the AutoMap modules. (New in 1.5.2)

### paths

In this section all necessary path variables are defined.

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

### defaults

Default values which are applied to the maps you use. 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
headerfade | 1 | Enable/Disable the fade effect of the submenus in the header menu (When the used header menu supports that option). (New in 1.5.2)
hovermenu | 1 | Enable/Disable the hover menu
hovertemplate | default | Default hover template
hovertimeout | 5 | Default hover menu ajax request timeout in seconds (Deprecated in 1.4)
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 |  | Filename of the custom stylesheet to use on the maps (The file needs to be located in the share/nagvis/styles directory) (New in 1.5)
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 (New in 1.5)
showmaps | 1 | Enable/Disable the listing of maps (New in 1.5)
showmapthumbs | 1 | Enable/Disable the listing of map thumbnails (New in 1.5)
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
--- | --- | ---
allowedforconfig | EVERYONE | <trike>Users who are allowed to change the NagVis configuration (comma separated list) or EVERYONE (Deprecated in 1.5)
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. (New in 1.5)
grid_color | #F7F7F7 | The color of the grid lines. (New in 1.5)
grid_steps | 32 | Scale of the grid in px. (New in 1.5)
headermenu | 1 | Enable/Disable the header menu in the WUI. (New in 1.5)
headertemplate | default | Default header template to use in the WUI (New in 1.5).
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 maxium 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 `[backend_<backend-id>]`. 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.

    [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

statushost

The status host can be used to prevent annoying timeouts when a backend is not reachable. This is only useful in multi backend setups.

It works as follows: The assumption is that there is a "local" backend which monitors the host of the "remote" backend. When the remote backend host is reported as UP the backend is queried as normal.

When the remote backend host is reported as "DOWN" or "UNREACHABLE" NagVis won't try to connect to the backend anymore until the backend host gets available again.

The statushost needs to be given in the following format: "<backend_id>:<hostname>" -> e.g. "live_2:nagios"

The host needs to be in another backend than the current one to work correctly.

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 (New in 1.5).
custom_2 |  | Second custom variable. Same as above.
custom_3 |  | Third custom variable. Same as above.

For the backendtype specific options see the backends documentation.

### 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= 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.

New in 1.5: 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 (New in 1.5)

Options which affect the handling and appearance of the different states in the NagVis installation.

These settings define the state handling behaviour. 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

This settings define the behaviour 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 |