Icinga

Configuration Overview of Icinga-Web

Where are my config files?

We're trying to reduce global configuration files. Icinga operates in modules, every module has its own configuration. This is also done with the libraries. If you need information about the cronk library, take a look into app/modules/Cronks/lib (for js things app/modules/Cronks/lib/js).

A sample module looks like this:

tree -d -L 1 app/modules/AppKit/
app/modules/AppKit/
|-- actions
|-- config
|-- lib
|-- models
|-- templates
|-- validate
|-- views

Index

Global Configuration Section

app/config

Here you find the global configuration files for e.g. the Web session, the Icinga web path and the database information.

The main interesting files:

Session Cookie Lifetime

Example: change the session_cookie_lifetime

The Session Lifetime is the time in seconds until the Icinga Web session expires. It can be configured on global level in the file app/config/factories.xml.

#> vi app/config/factories.xml
<ae:parameter name="session_cookie_lifetime">3600</ae:parameter>

Please make your customised settings in factories.site.xml.

Change Icinga-Web timezone

Example: Change the default timezone for Icinga-Web

If the time(zone) in Icinga-Web differs from your system time(zone), please check the date.timezone entry in app/modules/AppKit/config/module.xml (e.g. 'Europe/Berlin')

#> vi app/modules/AppKit/config/module.xml
<ae:parameter name="date.timezone">GMT</ae:parameter>

Module Configuration

app/modules/AppKit

Here lives the framework spun around: Authentication, Menus and so on.

Authentication

Example: LDAP authentication

Look into app/modules/AppKit/config/auth.xml.

There is a provider like this:

 <ae:parameter name="msad-ldap1">
            <ae:parameter name="auth_module">AppKit</ae:parameter>
            <ae:parameter name="auth_provider">Auth.Provider.LDAP</ae:parameter>
            <ae:parameter name="auth_enable">true</ae:parameter>
            <ae:parameter name="auth_authoritative">true</ae:parameter>
            <ae:parameter name="auth_create">true</ae:parameter>
            <ae:parameter name="auth_update">true</ae:parameter>

            <ae:parameter name="auth_map">
                <ae:parameter name="user_firstname">givenName</ae:parameter>
                <ae:parameter name="user_lastname">sn</ae:parameter>
                <ae:parameter name="user_email">mail</ae:parameter> 
            </ae:parameter>

            <ae:parameter name="ldap_dsn">ldap://ad.icinga.org</ae:parameter>
            <ae:parameter name="ldap_basedn">DC=ad,DC=icinga,DC=org</ae:parameter>
            <ae:parameter name="ldap_binddn">ldap@AD.ICINGA.ORG</ae:parameter>
            <ae:parameter name="ldap_bindpw"><![CDATA[XXXXXXXXX]]></ae:parameter>
            <ae:parameter name="ldap_userattr">uid</ae:parameter>
            <ae:parameter name="ldap_filter_user"><![CDATA[(&(sAmAccountName=__USERNAME__))]]></ae:parameter>
        </ae:parameter>

The auth.xml holds the documentation for the global config. The LDAP authentication should be done with some basic LDAP knowledge.

You can also duplicate the provider to provide more authentication bases. You can split the auth into authentication and authorising parts if you want. If you have new providers, please share them and let the auth database grow!

Please store your custom authentication configuration in auth.site.xml !

app/modules/Cronks

All the cronks are implemented there: Grids, iframes. All of them are simple html sites which hold ExtJS component codes. If you need to add a new cronk, this module is your friend.

If you want to develop a new cronk take a look at HowToDevelopCronks

To change the configuration, go to the Cronks module.

#> ls app/modules/Cronks/config
autoload.xml  config_handlers.xml  cronks.xml  module.xml  validators.xml

app/modules/Web

Or better: Icinga. This module holds all Icinga related stuff, IcingaAPI2Json, status information. Also the IcingaAPI connection is configured here.

Icinga-API connection settings

Example: Change the IcingaApi connection settings

Take a look at app/modules/Web/config/icinga-io.xml, here you'll find the default settings for the IcingaApi connection.

#> vi app/modules/Web/config/icinga-io.xml

          <setting name="api.interfaces.data">
                                        <!-- IcingaApi connection interface -->
                                        <ae:parameter name="api_type">IcingaApi::CONNECTION_IDO</ae:parameter>

                                        <!-- Suits for all interfaes -->
                                        <ae:parameter name="config_type">mysql</ae:parameter>
                                        <ae:parameter name="config_host">localhost</ae:parameter>
                                        <ae:parameter name="config_port">3306</ae:parameter>

                                        <!-- ###BEGIN_CONNECTION_IDO### -->
                                        <!-- Database specific (IcingaApi::CONNECTION_IDO) -->
                                        <ae:parameter name="config_database">icinga</ae:parameter>
                                        <ae:parameter name="config_user">icinga</ae:parameter>
                                        <ae:parameter name="config_password">icinga</ae:parameter>
                                        <ae:parameter name="config_table_prefix">icinga_</ae:parameter>
                                        <!-- ###END_CONNECTION_IDO### -->

If you want to change these settings to your needs, please edit app/modules/Web/config/icinga-io.site.xml.

Customised Configuration

Notes

When creating and/or editing configuration files, keep the following in mind:

  1. Lines that start with a <!-- and end with --> character are taken to be comments and are not processed

  2. Variable names are case-sensitive

  3. Your specific Icinga-Web configuration settings like api, authentication and database settings can be set in app/modules/Appkit(/Cronks/Web)/config/*.site.xml files and will be used in the first place. They won't get overwritten during the next upgrade process.

    These files already exist and you're free to use them for your specific settings:

    app/modules/Cronks/config/cronks.site.xml

    app/modules/Web/config/icinga-io.site.xml

    app/modules/AppKit/config/auth.site.xml

    app/config/icinga.site.xml

    app/config/databases.site.xml

    app/config/settings.site.xml

    app/config/translation.site.xml

    app/config/factories.site.xml

    The templates for Grids and TO's (tactical overview) are allowed to copy to *.site.xml in their location:

    The Grids:

    app/modules/Cronks/data/xml/grid/icinga-hostgroup-summary-template.xml

    app/modules/Cronks/data/xml/grid/icinga-host-history-template.xml

    app/modules/Cronks/data/xml/grid/icinga-host-template.xml

    ...

    and the TO's:

    app/modules/Cronks/data/xml/to/icinga-tactical-overview-groupstat.xml

    app/modules/Cronks/data/xml/to/icinga-tactical-overview-presets.xml

    app/modules/Cronks/data/xml/to/icinga-tactical-overview-template-charts.xml

    ...

    Please edit app/modules/Cronks/config/cronks.xml and add your created *.site.xml to make the new cronks accessible.

[Note] Note

After changing those configs you need to clear the config cache!

 #> rm -rf app/cache/config/*.php

or

 #> /usr/local/icinga-web/bin/clearcache.sh

You need more information? Please have a look at our Development Wiki.