Docs: Rename 'custom attribute' to 'custom variable'

[icinga2] / doc / 04-configuration.md

diff --git a/doc/04-configuration.md b/doc/04-configuration.md
index 434b8c9b8c53b964fc1e0bba5bc9cf194bbfc87c..690c80ca2e6b7c73e339da4a192db460404807df 100644 (file)
--- a/doc/04-configuration.md
+++ b/doc/04-configuration.md
@@ -1,4 +1,4 @@
-# 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
 
 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


@@ -36,7 +36,7 @@ host and service basis.
 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
 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:
 
 
 Consider these ideas:
 


@@ -48,12 +48,12 @@ Consider these ideas:
 
 In either way of choosing the right strategy you should additionally check the following:
 
 
 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.
 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.
 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.


@@ -176,7 +176,7 @@ the features which have been enabled with `icinga2 feature enable`. See
 include_recursive "conf.d"
 ```
 
 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>
 directive makes sure that all of your own configuration files are included.
 
 ### constants.conf <a id="constants-conf"></a>


@@ -185,7 +185,7 @@ The `constants.conf` configuration file can be used to define global constants.
 
 By default, you need to make sure to set these constants:
 
 
 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
 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


@@ -224,7 +224,7 @@ This file can be used to specify the required [Zone](09-object-types.md#objectty
 and [Endpoint](09-object-types.md#objecttype-endpoint) configuration object for
 [distributed monitoring](06-distributed-monitoring.md#distributed-monitoring).
 
 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.
 
 It also contains several [global zones](06-distributed-monitoring.md#distributed-monitoring-global-zone-config-sync)
 for distributed monitoring environments.


@@ -237,38 +237,38 @@ for your `Zone` and `Endpoint` object names.
 
 This directory contains **example configuration** which should help you get started
 with monitoring the local host and its services. It is included in the
 
 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
 
 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**
 >
 
 > **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
 > 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:
 
 
 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
 
 #### 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.
 
 can use global constants for your object names instead of string
 values.
 


@@ -276,25 +276,25 @@ The `import` keyword is used to import the `generic-host` template which
 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.
 
 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.
 
 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
 
 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`
 * 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
 * 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
 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.
 
 generate a new service checking the `/icingaweb2` URI using the `http`
 check.
 


@@ -324,7 +324,7 @@ object Host NodeName {
   address = "127.0.0.1"
   address6 = "::1"
 
   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`. */
   vars.os = "Linux"
 
   /* Define http vhost attributes for service apply rules in `services.conf`. */


@@ -353,7 +353,7 @@ object Host NodeName {
 ```
 
 This is only the host object definition. Now we'll need to make sure that this
 ```
 
 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**
 >
 
 > **Tip**
 >


@@ -377,8 +377,8 @@ Service(s)                                  | Applied on host(s)
 `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`
 `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.
 
 
 The Debian packages also include an additional `apt` service check applied to the local host.
 


@@ -407,9 +407,9 @@ The `apply` keyword can be used to create new objects which are associated with
 another group of objects. You can `import` existing templates, define (custom)
 attributes.
 
 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
 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 `assign where` condition is a boolean expression which is
 evaluated for all objects of type `Host` and a new service with name "load"


@@ -430,7 +430,7 @@ apply Service "ssh" {
 ```
 
 In this example, the service `ssh` is applied to all hosts having the `address`
 ```
 
 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
 `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


@@ -442,10 +442,10 @@ rules. While one `apply` rule for `ssh` will only create a service for matching
 hosts, you can go one step further: Generate apply rules based on array items
 or dictionary key-value pairs.
 
 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):

 
 ```
 ...
 
 ```
 ...


@@ -499,11 +499,11 @@ A similar example is used for the `http` services. That way you can make your
 host the information provider for all apply rules. Define them once, and only
 manage your hosts.
 
 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.
 
 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
 the hosts and services and their check commands.
 
 Further details on the monitoring configuration can be found in the


@@ -512,8 +512,8 @@ 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
 #### 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" {
 
 ```
 object User "icingaadmin" {


@@ -541,13 +541,13 @@ nested dictionary attribute `notification.mail` is set.
 
 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.
 
 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
 
 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 {
 
 ```
 apply Notification "mail-icingaadmin" to Host {


@@ -575,7 +575,7 @@ filters can be read in [this chapter](03-monitoring-basics.md#alert-notification
 #### commands.conf <a id="commands-conf"></a>
 
 This is the place where your own command configuration can be defined. By default
 #### 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).
 
 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).


@@ -583,7 +583,7 @@ 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
 #### 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
 a member of the host group `linux-servers`.
 
 This is done by using the [group assign](17-language-reference.md#group-assign) expressions similar


@@ -680,8 +680,8 @@ More details on `Notification` object attributes can be found [here](09-object-t
 
 #### downtimes.conf <a id="downtimes-conf"></a>
 
 
 #### 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.
 
 The ScheduledDowntime apply rule uses this attribute to define the default value
 for the time ranges required for recurring downtime slots.