-# Configuring Icinga 2: First Steps <a id="configuring-icinga2-first-steps"></a>
+# Configuration: First Steps <a id="configuration-first-steps"></a>
This chapter provides an introduction into best practices for your Icinga 2 configuration.
The configuration files which are automatically created when installing the Icinga 2 packages
Then you should look for the object specific configuration setting `host_name` etc. accordingly.
You decide on the "best" layout for configuration files and directories. Ensure that
-the [icinga2.conf](04-configuring-icinga-2.md#icinga2-conf) configuration file includes them.
+the [icinga2.conf](04-configuration.md#icinga2-conf) configuration file includes them.
Consider these ideas:
In either way of choosing the right strategy you should additionally check the following:
-* Are there any specific attributes describing the host/service you could set as `vars` custom attributes?
+* Are there any specific attributes describing the host/service you could set as `vars` custom variables?
You can later use them for applying assign/ignore rules, or export them into external interfaces.
* Put hosts into hostgroups, services into servicegroups and use these attributes for your apply rules.
* Use templates to store generic attributes for your objects and apply rules making your configuration more readable.
Details can be found in the [using templates](03-monitoring-basics.md#object-inheritance-using-templates) chapter.
-* Apply rules may overlap. Keep a central place (for example, [services.conf](04-configuring-icinga-2.md#services-conf) or [notifications.conf](04-configuring-icinga-2.md#notifications-conf)) storing
+* Apply rules may overlap. Keep a central place (for example, [services.conf](04-configuration.md#services-conf) or [notifications.conf](04-configuration.md#notifications-conf)) storing
the configuration instead of defining apply rules deep in your configuration tree.
* Every plugin used as check, notification or event command requires a `Command` definition.
Further details can be looked up in the [check commands](03-monitoring-basics.md#check-commands) chapter.
include_recursive "conf.d"
```
-You can put your own configuration files in the [conf.d](04-configuring-icinga-2.md#conf-d) directory. This
+You can put your own configuration files in the [conf.d](04-configuration.md#conf-d) directory. This
directive makes sure that all of your own configuration files are included.
### constants.conf <a id="constants-conf"></a>
By default, you need to make sure to set these constants:
-* The `PluginDir` constant must be set to the path where the [Monitoring Project plugins](02-getting-started.md#setting-up-check-plugins) are installed.
+* The `PluginDir` constant must be set to the path where the [Monitoring Project plugins](02-installation.md#setting-up-check-plugins) are installed.
This constant is used by a number of
[built-in check command definitions](10-icinga-template-library.md#icinga-template-library).
* The `NodeName` constant defines your local node name. Should be set to FQDN which is the default
and [Endpoint](09-object-types.md#objecttype-endpoint) configuration object for
[distributed monitoring](06-distributed-monitoring.md#distributed-monitoring).
-By default the `NodeName` and `ZoneName` [constants](04-configuring-icinga-2.md#constants-conf) will be used.
+By default the `NodeName` and `ZoneName` [constants](04-configuration.md#constants-conf) will be used.
It also contains several [global zones](06-distributed-monitoring.md#distributed-monitoring-global-zone-config-sync)
for distributed monitoring environments.
This directory contains **example configuration** which should help you get started
with monitoring the local host and its services. It is included in the
-[icinga2.conf](04-configuring-icinga-2.md#icinga2-conf) configuration file by default.
+[icinga2.conf](04-configuration.md#icinga2-conf) configuration file by default.
It can be used as reference example for your own configuration strategy.
Just keep in mind to include the main directories in the
-[icinga2.conf](04-configuring-icinga-2.md#icinga2-conf) file.
+[icinga2.conf](04-configuration.md#icinga2-conf) file.
> **Note**
>
-> You can remove the include directive in [icinga2.conf](04-configuring-icinga-2.md#icinga2-conf)
+> You can remove the include directive in [icinga2.conf](04-configuration.md#icinga2-conf)
> if you prefer your own way of deploying Icinga 2 configuration.
Further details on configuration best practice and how to build your
-own strategy is described in [this chapter](04-configuring-icinga-2.md#configuration-best-practice).
+own strategy is described in [this chapter](04-configuration.md#configuration-best-practice).
Available configuration files which are installed by default:
-* [hosts.conf](04-configuring-icinga-2.md#hosts-conf)
-* [services.conf](04-configuring-icinga-2.md#services-conf)
-* [users.conf](04-configuring-icinga-2.md#users-conf)
-* [notifications.conf](04-configuring-icinga-2.md#notifications-conf)
-* [commands.conf](04-configuring-icinga-2.md#commands-conf)
-* [groups.conf](04-configuring-icinga-2.md#groups-conf)
-* [templates.conf](04-configuring-icinga-2.md#templates-conf)
-* [downtimes.conf](04-configuring-icinga-2.md#downtimes-conf)
-* [timeperiods.conf](04-configuring-icinga-2.md#timeperiods-conf)
-* [api-users.conf](04-configuring-icinga-2.md#api-users-conf)
-* [app.conf](04-configuring-icinga-2.md#app-conf)
+* [hosts.conf](04-configuration.md#hosts-conf)
+* [services.conf](04-configuration.md#services-conf)
+* [users.conf](04-configuration.md#users-conf)
+* [notifications.conf](04-configuration.md#notifications-conf)
+* [commands.conf](04-configuration.md#commands-conf)
+* [groups.conf](04-configuration.md#groups-conf)
+* [templates.conf](04-configuration.md#templates-conf)
+* [downtimes.conf](04-configuration.md#downtimes-conf)
+* [timeperiods.conf](04-configuration.md#timeperiods-conf)
+* [api-users.conf](04-configuration.md#api-users-conf)
+* [app.conf](04-configuration.md#app-conf)
#### hosts.conf <a id="hosts-conf"></a>
The `hosts.conf` file contains an example host based on your
-`NodeName` setting in [constants.conf](04-configuring-icinga-2.md#constants-conf). You
+`NodeName` setting in [constants.conf](04-configuration.md#constants-conf). You
can use global constants for your object names instead of string
values.
takes care of setting up the host check command to `hostalive`. If you
require a different check command, you can override it in the object definition.
-The `vars` attribute can be used to define custom attributes which are available
+The `vars` attribute can be used to define custom variables which are available
for check and notification commands. Most of the [Plugin Check Commands](10-icinga-template-library.md#icinga-template-library)
in the Icinga Template Library require an `address` attribute.
-The custom attribute `os` is evaluated by the `linux-servers` group in
-[groups.conf](04-configuring-icinga-2.md#groups-conf) making the local host a member.
+The custom variable `os` is evaluated by the `linux-servers` group in
+[groups.conf](04-configuration.md#groups-conf) making the local host a member.
The example host will show you how to:
* define http vhost attributes for the `http` service apply rule defined
-in [services.conf](04-configuring-icinga-2.md#services-conf).
+in [services.conf](04-configuration.md#services-conf).
* define disks (all, specific `/`) and their attributes for the `disk`
-service apply rule defined in [services.conf](04-configuring-icinga-2.md#services-conf).
+service apply rule defined in [services.conf](04-configuration.md#services-conf).
* define notification types (`mail`) and set the groups attribute. This
-will be used by notification apply rules in [notifications.conf](04-configuring-icinga-2.md#notifications-conf).
+will be used by notification apply rules in [notifications.conf](04-configuration.md#notifications-conf).
-If you've installed [Icinga Web 2](02-getting-started.md#setting-up-icingaweb2), you can
+If you've installed [Icinga Web 2](02-installation.md#setting-up-icingaweb2), you can
uncomment the http vhost attributes and reload Icinga 2. The apply
-rules in [services.conf](04-configuring-icinga-2.md#services-conf) will automatically
+rules in [services.conf](04-configuration.md#services-conf) will automatically
generate a new service checking the `/icingaweb2` URI using the `http`
check.
address = "127.0.0.1"
address6 = "::1"
- /* Set custom attribute `os` for hostgroup assignment in `groups.conf`. */
+ /* Set custom variable `os` for hostgroup assignment in `groups.conf`. */
vars.os = "Linux"
/* Define http vhost attributes for service apply rules in `services.conf`. */
```
This is only the host object definition. Now we'll need to make sure that this
-host and your additional hosts are getting [services](04-configuring-icinga-2.md#services-conf) applied.
+host and your additional hosts are getting [services](04-configuration.md#services-conf) applied.
> **Tip**
>
`load`, `procs`, `swap`, `users`, `icinga` | The `NodeName` host only.
`ping4`, `ping6` | All hosts with `address` resp. `address6` attribute.
`ssh` | All hosts with `address` and `vars.os` set to `Linux`
-`http`, optional: `Icinga Web 2` | All hosts with custom attribute `http_vhosts` defined as dictionary.
-`disk`, `disk /` | All hosts with custom attribute `disks` defined as dictionary.
+`http`, optional: `Icinga Web 2` | All hosts with custom variable `http_vhosts` defined as dictionary.
+`disk`, `disk /` | All hosts with custom variable `disks` defined as dictionary.
The Debian packages also include an additional `apt` service check applied to the local host.
another group of objects. You can `import` existing templates, define (custom)
attributes.
-The custom attribute `backup_downtime` is defined to a specific timerange string.
+The custom variable `backup_downtime` is defined to a specific timerange string.
This variable value will be used for applying a `ScheduledDowntime` object to
-these services in [downtimes.conf](04-configuring-icinga-2.md#downtimes-conf).
+these services in [downtimes.conf](04-configuration.md#downtimes-conf).
In this example the `assign where` condition is a boolean expression which is
evaluated for all objects of type `Host` and a new service with name "load"
```
In this example, the service `ssh` is applied to all hosts having the `address`
-attribute defined `AND` having the custom attribute `os` set to the string
+attribute defined `AND` having the custom variable `os` set to the string
`Linux`.
You can modify this condition to match multiple expressions by combining `AND`
and `OR` using `&&` and `||` [operators](17-language-reference.md#expression-operators), for example
hosts, you can go one step further: Generate apply rules based on array items
or dictionary key-value pairs.
-The idea is simple: Your host in [hosts.conf](04-configuring-icinga-2.md#hosts-conf) defines the
-`disks` dictionary as custom attribute in `vars`.
+The idea is simple: Your host in [hosts.conf](04-configuration.md#hosts-conf) defines the
+`disks` dictionary as custom variable in `vars`.
-Remember the example from [hosts.conf](04-configuring-icinga-2.md#hosts-conf):
+Remember the example from [hosts.conf](04-configuration.md#hosts-conf):
```
...
host the information provider for all apply rules. Define them once, and only
manage your hosts.
-Look into [notifications.conf](04-configuring-icinga-2.md#notifications-conf) how this technique is used
+Look into [notifications.conf](04-configuration.md#notifications-conf) how this technique is used
for applying notifications to hosts and services using their type and user
attributes.
-Don't forget to install the [check plugins](02-getting-started.md#setting-up-check-plugins) required by
+Don't forget to install the [check plugins](02-installation.md#setting-up-check-plugins) required by
the hosts and services and their check commands.
Further details on the monitoring configuration can be found in the
#### users.conf <a id="users-conf"></a>
Defines the `icingaadmin` User and the `icingaadmins` UserGroup. The latter is used in
-[hosts.conf](04-configuring-icinga-2.md#hosts-conf) for defining a custom host attribute later used in
-[notifications.conf](04-configuring-icinga-2.md#notifications-conf) for notification apply rules.
+[hosts.conf](04-configuration.md#hosts-conf) for defining a custom host attribute later used in
+[notifications.conf](04-configuration.md#notifications-conf) for notification apply rules.
```
object User "icingaadmin" {
Please note that the `to` keyword is important in [notification apply rules](03-monitoring-basics.md#using-apply-notifications)
defining whether these notifications are applies to hosts or services.
-The `import` keyword imports the specific mail templates defined in [templates.conf](04-configuring-icinga-2.md#templates-conf).
+The `import` keyword imports the specific mail templates defined in [templates.conf](04-configuration.md#templates-conf).
The `interval` attribute is not explicitly set -- it [defaults to 30 minutes](09-object-types.md#objecttype-notification).
By setting the `user_groups` to the value provided by the
-respective [host.vars.notification.mail](04-configuring-icinga-2.md#hosts-conf) attribute we'll
-implicitely use the `icingaadmins` UserGroup defined in [users.conf](04-configuring-icinga-2.md#users-conf).
+respective [host.vars.notification.mail](04-configuration.md#hosts-conf) attribute we'll
+implicitely use the `icingaadmins` UserGroup defined in [users.conf](04-configuration.md#users-conf).
```
apply Notification "mail-icingaadmin" to Host {
#### commands.conf <a id="commands-conf"></a>
This is the place where your own command configuration can be defined. By default
-only the notification commands used by the notification templates defined in [templates.conf](04-configuring-icinga-2.md#templates-conf).
+only the notification commands used by the notification templates defined in [templates.conf](04-configuration.md#templates-conf).
You can freely customize these notification commands, and adapt them for your needs.
Read more on that topic [here](03-monitoring-basics.md#notification-commands).
#### groups.conf <a id="groups-conf"></a>
The example host defined in [hosts.conf](hosts-conf) already has the
-custom attribute `os` set to `Linux` and is therefore automatically
+custom variable `os` set to `Linux` and is therefore automatically
a member of the host group `linux-servers`.
This is done by using the [group assign](17-language-reference.md#group-assign) expressions similar
#### downtimes.conf <a id="downtimes-conf"></a>
-The `load` service apply rule defined in [services.conf](04-configuring-icinga-2.md#services-conf) defines
-the `backup_downtime` custom attribute.
+The `load` service apply rule defined in [services.conf](04-configuration.md#services-conf) defines
+the `backup_downtime` custom variable.
The ScheduledDowntime apply rule uses this attribute to define the default value
for the time ranges required for recurring downtime slots.
projects / icinga2 / blobdiff