Session Cookie Lifetime

instance: Only 'instance' is allowed as a subelement, this node maps an instance name determined by the attribute "name" to a host (see later), determined by the value of this tag:

 <instance name="%icinga instance name%">%host name%</instance>

defaultHost: Defines the host that will be used for actions, if no host is defined. At this time (v1.6), this is only important for some modules and doesn't affect icinga-web's basic featureset.

 <defaultHost>localhost</defaultHost>

The host must be defined in the hosts section

access: Icinga-Web (and modules, if written correctly) don't access non architecture-level system resources directly, but via a console-interface, which handles security. In the access section you define, which system resources may be accessed by this handler and where they are located. Also you give system resources a resource name. For example, the console handler only accesses the icinga pipe through the 'icinga_pipe' symbol name.

The access section allows four sub-elements: 'readwrite', 'read', 'write', 'execute', which define the access level to resources located underneath. Resources themselves are defined under the 'folders' or 'files' tags and encapsulated by 'resource': The following example allows r/w access to Icinga's objects folder and the icinga.cfg file. Write, read, and execute follow the same scheme so the 'readwrite' tag is to be replaced with the appropriate tag.

host: Defines a single host and gives him a name which can be used to reference this host (like in the instances section).

 <!-- Example for ssh connection with user/password auth -->
 <host name="vm_host1">
    <type>ssh</type>
    <ssh-config>
       <host>localhost</host>
       <port>22</port>
       <auth>
          <type>password</type>
          <user>john_doe</user>
          <password>foobar</password>
       </auth>
    </ssh-config>

    <access useDefaults="true" />
 </host>

The 'host' tag has a bunch of subelements:

type: Either local or ssh. Defines if commands will be executed directly on the machine icinga-web is running on or via ssh.

access: See the access section above. Additionally, 'useDefaults' can be set in order to tell the CommandInterface that all default access definitions may be applied (if they are not overwritten in this section)

ssh-config: (Only if type:ssh) This defines how the host will be accessed over ssh. There are three authentication methods for ssh: 'none', 'password' or 'key', which will be explained in the next session. No matter which method you choose, the 'host' and 'port' entries must be set on every host.

Auth type: none

This tells the Console-connection to only use a username for authentication:

 <ssh-config>
    <host>localhost</host>
    <port>22</port>
    <auth>
       <type>none</type>
       <user>john_doe</user>
    </auth>
 </ssh-config>

In this example, only the username 'john_doe' will be provided for authentication. This can be useful if your machines use automatic key authentication.

Auth type: password

This tells the console-connection to use a username and a password for authentication:

 <ssh-config>
    <host>localhost</host>
    <port>22</port>
    <auth>
       <type>password</type>
       <user>john_doe</user>
       <password>foobar</password>
    </auth>
 </ssh-config>

In this example, only username 'john_doe' and the password 'foobar' will be provided for authentication.

Auth type: key

	Important
	Experimental! Try it out and open a ticket if you encounter any issues!

This tells the Console-connection to use a key file for authentication, optionally secured with a password:

 <ssh-config>
    <host>localhost</host>
    <port>22</port>
    <auth>
       <type>key</type>
       <user>testuser</user>
       <private-key>/usr/local/icinga-web/app/modules/Api/lib/.ssh/host1_rsa</private-key>
       <password>secret123</password>
    </auth>
 </ssh-config>

Here the private key defined in the 'private-key' tag will be used. You shouldn't and needn't to define this path in the hosts-access section!

Database identifier

<db:database name="%Database name%" class="%Handler%">
   ...
</db:database>

With the db:database tag you let Icinga Web know about a database, this tag must have two attributes:

dsn (Data Source Name):

Defines the credentials, type and location of the database:

For MySQL, PostgreSQL, and Oracle:

<db:database ...>
    ...
    <ae:parameter name="dsn">%driver%://%username%:%password%@%host%:%port%/%database name%</ae:parameter>
    ...
</db:database>

For sqlite3:

<db:database ...>
    ...
    <ae:parameter name="dsn">sqlite:///%path to your db file%</ae:parameter>
    ...
</db:database>

	Note
	SQLite database files must be read and writeable for the webserver's user, as well as the folder that contains the file.

charset

<db:database ...>
    ...
    <ae:parameter name="charset">utf8</ae:parameter>
    ...
</db:database>

In general, your database charset should be utf8.

manager_attributes, load_models, models_directory

<db:database ...>
    ...
    <ae:parameter name="manager_attributes">
        <ae:parameter name="Doctrine_Core::ATTR_MODEL_LOADING">CONSERVATIVE</ae:parameter>
    </ae:parameter>
    ...
</db:database>

You can safely ignore this section and just copy it, this only handles doctrine specific settings (in particular, how database models will be loaded and where they are located. If you want to know more, look at the doctrine documentation).

date_formate

This is required to properly access oracle databases and sets the date format to use for this database.

<db:database ...>
    ...
    <ae:parameter name="date_format"><![CDATA[YYYY-MM-DD HH24:MI:SS]]></ae:parameter>
    ...
</db:database>

Caching

<db:database ...>
    ...
    <ae:parameter name="caching">
        <ae:parameter name="enabled">false</ae:parameter>
        <ae:parameter name="driver">apc</ae:parameter>
        <ae:parameter name="use_query_cache">true</ae:parameter>
        <ae:parameter name="use_result_cache">true</ae:parameter>
        <ae:parameter name="result_cache_lifespan">60</ae:parameter>
    </ae:parameter>
<db:database>

If you use apc or memcache, you can cache either database queries or results. While query caching almost never is a bad thing (if you're not developing), result cache is a rather specific case - as you might get outdated data from your database. So never use it for your Icinga database!

Database identifier

The icinga database identifier must use IcingaDoctrineDatabase as the 'class' attribute and 'icinga' as the database name, see:

<db:database name="icinga" class="IcingaDoctrineDatabase">
...
</db:database>

dsn

You can use the same credentials as in ido2db.cfg but for security reasons, it's highly advised to create a read only user especially for icinga-web. Below is an example which values from ido2db.cfg fit.

    <ae:parameter name="dsn">mysql://db_user:db_pass@db_host:db_port/db_name</ae:parameter>

prefix

Defines the prefix like defined in Icinga's ido2db.cfg

<db:database name="icinga" class="IcingaDoctrineDatabase">
...
    <ae:parameter name="prefix">icinga_</ae:parameter>
...
</db:database>

For Oracle, add a blank value.

<db:database name="icinga" class="IcingaDoctrineDatabase">
...
    <ae:parameter name="prefix"></ae:parameter>
...
</db:database>

use_retained

Whether to use retained or original data dumps (see the value in idomod.cfg)

<db:database name="icinga" class="IcingaDoctrineDatabase">
...
     <ae:parameter name="use_retained">true</ae:parameter>
</db:database>