The `address` attribute is used by check commands to determine which network
address is associated with the host object.
-Details on troubleshooting check problems can be found [here](8-troubleshooting.md#troubleshooting).
+Details on troubleshooting check problems can be found [here](10-troubleshooting.md#troubleshooting).
### <a id="host-states"></a> Host States
Service checks could also use a `dummy` check, but the common strategy is to
[integrate an existing plugin](3-monitoring-basics.md#command-plugin-integration) as
[check command](3-monitoring-basics.md#check-commands) and [reference](3-monitoring-basics.md#command-passing-parameters)
-that in your [Service](12-object-types.md#objecttype-service) object definition.
+that in your [Service](15-object-types.md#objecttype-service) object definition.
## <a id="configuration-best-practice"></a> Configuration Best Practice
There are many ways of creating Icinga 2 configuration objects:
* Manually with your preferred editor, for example vi(m), nano, notepad, etc.
-* Generated by a [configuration management too](2-getting-started.md#configuration-tools) such as Puppet, Chef, Ansible, etc.
+* Generated by a [configuration management too](7-addons-plugins.md#configuration-tools) such as Puppet, Chef, Ansible, etc.
* A configuration addon for Icinga 2
* A custom exporter script from your CMDB or inventory tool
* your own.
Then you should look for the object specific configuration setting `host_name` etc accordingly.
Finding the best files and directory tree for your configuration is up to you. Make sure that
-the [icinga2.conf](2-getting-started.md#icinga2-conf) configuration file includes them, and then think about:
+the [icinga2.conf](4-configuring-icinga-2.md#icinga2-conf) configuration file includes them, and then think about:
* tree-based on locations, hostgroups, specific host attributes with sub levels of directories.
* flat `hosts.conf`, `services.conf`, etc files for rule based configuration.
* 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](3-monitoring-basics.md#object-inheritance-using-templates) chapter.
-* Apply rules may overlap. Keep a central place (for example, [services.conf](2-getting-started.md#services-conf) or [notifications.conf](2-getting-started.md#notifications-conf)) storing
+* Apply rules may overlap. Keep a central place (for example, [services.conf](4-configuring-icinga-2.md#services-conf) or [notifications.conf](4-configuring-icinga-2.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](3-monitoring-basics.md#check-commands) chapter.
### <a id="using-apply"></a> Apply objects based on rules
-Instead of assigning each object ([Service](12-object-types.md#objecttype-service),
-[Notification](12-object-types.md#objecttype-notification), [Dependency](12-object-types.md#objecttype-dependency),
-[ScheduledDowntime](12-object-types.md#objecttype-scheduleddowntime))
-based on attribute identifiers for example `host_name` objects can be [applied](10-language-reference.md#apply).
+Instead of assigning each object ([Service](15-object-types.md#objecttype-service),
+[Notification](15-object-types.md#objecttype-notification), [Dependency](15-object-types.md#objecttype-dependency),
+[ScheduledDowntime](15-object-types.md#objecttype-scheduleddowntime))
+based on attribute identifiers for example `host_name` objects can be [applied](13-language-reference.md#apply).
Before you start using the apply rules keep the following in mind:
* Define the best match.
* A set of unique [custom attributes](3-monitoring-basics.md#custom-attributes-apply) for these hosts/services?
* Or [group](3-monitoring-basics.md#groups) memberships, e.g. a host being a member of a hostgroup, applying services to it?
- * A generic pattern [match](10-language-reference.md#function-calls) on the host/service name?
- * [Multiple expressions combined](3-monitoring-basics.md#using-apply-expressions) with `&&` or `||` [operators](10-language-reference.md#expression-operators)
+ * A generic pattern [match](13-language-reference.md#function-calls) on the host/service name?
+ * [Multiple expressions combined](3-monitoring-basics.md#using-apply-expressions) with `&&` or `||` [operators](13-language-reference.md#expression-operators)
* All expressions must return a boolean value (an empty string is equal to `false` e.g.)
> **Note**
> **Tip**
>
> Building configuration in that dynamic way requires detailed information
-> of the generated objects. Use the `object list` [CLI command](5-cli-commands.md#cli-command-object)
-> after successful [configuration validation](5-cli-commands.md#config-validation).
+> of the generated objects. Use the `object list` [CLI command](6-cli-commands.md#cli-command-object)
+> after successful [configuration validation](6-cli-commands.md#config-validation).
#### <a id="using-apply-expressions"></a> Apply Rules Expressions
`OR` the host custom attribute `always_notify` is set to `true`.
The notification is ignored for services whose host name ends with `*internal`
-`OR` the `priority` custom attribute is [less than](10-language-reference.md#expression-operators) `2`.
+`OR` the `priority` custom attribute is [less than](13-language-reference.md#expression-operators) `2`.
template Notification "cust-xy-notification" {
users = [ "noc-xy", "mgmt-xy" ]
#### <a id="using-apply-services"></a> Apply Services to Hosts
-The sample configuration already ships a detailed example in [hosts.conf](2-getting-started.md#hosts-conf)
-and [services.conf](2-getting-started.md#services-conf) for this use case.
+The sample configuration already ships a detailed example in [hosts.conf](4-configuring-icinga-2.md#hosts-conf)
+and [services.conf](4-configuring-icinga-2.md#services-conf) for this use case.
The example for `ssh` applies a service object to all hosts with the `address`
attribute being defined and the custom attribute `os` set to the string `Linux` in `vars`.
#### <a id="using-apply-scheduledowntimes"></a> Apply Recurring Downtimes to Hosts and Services
-The sample confituration ships an example in [downtimes.conf](2-getting-started.md#downtimes-conf).
+The sample confituration ships an example in [downtimes.conf](4-configuring-icinga-2.md#downtimes-conf).
Detailed examples can be found in the [recurring downtimes](3-monitoring-basics.md#recurring-downtimes) chapter.
of a lot of duplicated apply rules by combining them into one generic generating
the object name with or without a prefix.
-The sample configuration already ships a detailed example in [hosts.conf](2-getting-started.md#hosts-conf)
-and [services.conf](2-getting-started.md#services-conf) for this use case.
+The sample configuration already ships a detailed example in [hosts.conf](4-configuring-icinga-2.md#hosts-conf)
+and [services.conf](4-configuring-icinga-2.md#services-conf) for this use case.
Imagine a different example: You are monitoring your switch (hosts) with many
interfaces (services). The following requirements/problems apply:
}
Note that numbers must be explicitely casted to string when adding to strings.
-This can be achieved by wrapping them into the [string()](10-language-reference.md#function-calls) function.
+This can be achieved by wrapping them into the [string()](13-language-reference.md#function-calls) function.
> **Tip**
>
> Building configuration in that dynamic way requires detailed information
-> of the generated objects. Use the `object list` [CLI command](5-cli-commands.md#cli-command-object)
-> after successful [configuration validation](5-cli-commands.md#config-validation).
+> of the generated objects. Use the `object list` [CLI command](6-cli-commands.md#cli-command-object)
+> after successful [configuration validation](6-cli-commands.md#config-validation).
#### <a id="using-apply-object attributes"></a> Use Object Attributes in Apply Rules
If there is a certain number of hosts, services, or users matching a pattern
it's reasonable to assign the group object to these members.
-Details on the `assign where` syntax can be found [here](10-language-reference.md#apply)
+Details on the `assign where` syntax can be found [here](13-language-reference.md#apply)
object HostGroup "prod-mssql" {
display_name = "Production MSSQL Servers"
If you don't set the `states` and `types` configuration attributes for the `User`
object, notifications for all states and types will be sent.
-Details on troubleshooting notification problems can be found [here](8-troubleshooting.md#troubleshooting).
+Details on troubleshooting notification problems can be found [here](10-troubleshooting.md#troubleshooting).
> **Note**
>
-> Make sure that the [notification](5-cli-commands.md#features) feature is enabled on your master instance
+> Make sure that the [notification](6-cli-commands.md#features) feature is enabled on your master instance
> in order to execute notification commands.
You should choose which information you (and your notified users) are interested in
### <a id="check-commands"></a> Check Commands
-[CheckCommand](12-object-types.md#objecttype-checkcommand) objects define the command line how
+[CheckCommand](15-object-types.md#objecttype-checkcommand) objects define the command line how
a check is called.
-[CheckCommand](12-object-types.md#objecttype-checkcommand) objects are referenced by
-[Host](12-object-types.md#objecttype-host) and [Service](12-object-types.md#objecttype-service) objects
+[CheckCommand](15-object-types.md#objecttype-checkcommand) objects are referenced by
+[Host](15-object-types.md#objecttype-host) and [Service](15-object-types.md#objecttype-service) objects
using the `check_command` attribute.
> **Note**
>
-> Make sure that the [checker](5-cli-commands.md#features) feature is enabled in order to
+> Make sure that the [checker](6-cli-commands.md#features) feature is enabled in order to
> execute checks.
#### <a id="command-plugin-integration"></a> Integrate the Plugin with a CheckCommand Definition
-[CheckCommand](12-object-types.md#objecttype-checkcommand) objects require the [ITL template](13-icinga-template-library.md#itl-plugin-check-command)
+[CheckCommand](15-object-types.md#objecttype-checkcommand) objects require the [ITL template](16-icinga-template-library.md#itl-plugin-check-command)
`plugin-check-command` to support native plugin based check methods.
Unless you have done so already, download your check plugin and put it
-into the [PluginDir](2-getting-started.md#constants-conf) directory. The following example uses the
+into the [PluginDir](4-configuring-icinga-2.md#constants-conf) directory. The following example uses the
`check_disk` plugin shipped with the Monitoring Plugins package.
The plugin path and all command arguments are made a list of
> Don't execute plugins as `root` and always use the absolute path to the plugin! Trust us.
Next step is to understand how command parameters are being passed from
-a host or service object, and add a [CheckCommand](12-object-types.md#objecttype-checkcommand)
+a host or service object, and add a [CheckCommand](15-object-types.md#objecttype-checkcommand)
definition based on these required parameters and/or default values.
#### <a id="command-passing-parameters"></a> Passing Check Command Parameters from Host or Service
> **Note**
>
> A proper example for the `check_disk` plugin is already shipped with Icinga 2
-> ready to use with the [plugin check commands](13-icinga-template-library.md#plugin-check-command-disk).
+> ready to use with the [plugin check commands](16-icinga-template-library.md#plugin-check-command-disk).
The host `localhost` with the applied service `basic-partitions` checks a basic set of disk partitions
with modified custom attributes (warning thresholds at `10%`, critical thresholds at `5%`
without SSL enabled checks saving you duplicated command definitions.
Details on all available options can be found in the
-[CheckCommand object definition](12-object-types.md#objecttype-checkcommand).
+[CheckCommand object definition](15-object-types.md#objecttype-checkcommand).
### <a id="using-apply-services-command-arguments"></a> Apply Services with Custom Command Arguments
}
All hosts in the `my-linux-servers` hostgroup should get the `my-ssh` service applied based on an
-[apply rule](10-language-reference.md#apply). The optional `ssh_port` command argument should be inherited from the host
+[apply rule](13-language-reference.md#apply). The optional `ssh_port` command argument should be inherited from the host
the service is applied to. If not set, the check command `my-ssh` will omit the argument.
The `host` argument is special: `skip_key` tells Icinga 2 to ignore the key, and directly put the
value onto the command line. The `order` attribute specifies that this argument is the first one
### <a id="notification-commands"></a> Notification Commands
-[NotificationCommand](12-object-types.md#objecttype-notificationcommand) objects define how notifications are delivered to external
+[NotificationCommand](15-object-types.md#objecttype-notificationcommand) objects define how notifications are delivered to external
interfaces (E-Mail, XMPP, IRC, Twitter, etc).
-[NotificationCommand](12-object-types.md#objecttype-notificationcommand) objects are referenced by
-[Notification](12-object-types.md#objecttype-notification) objects using the `command` attribute.
+[NotificationCommand](15-object-types.md#objecttype-notificationcommand) objects are referenced by
+[Notification](15-object-types.md#objecttype-notification) objects using the `command` attribute.
-`NotificationCommand` objects require the [ITL template](13-icinga-template-library.md#itl-plugin-notification-command)
+`NotificationCommand` objects require the [ITL template](16-icinga-template-library.md#itl-plugin-notification-command)
`plugin-notification-command` to support native plugin-based notifications.
> **Note**
>
-> Make sure that the [notification](5-cli-commands.md#features) feature is enabled on your master instance
+> Make sure that the [notification](6-cli-commands.md#features) feature is enabled on your master instance
> in order to execute notification commands.
Below is an example using runtime macros from Icinga 2 (such as `$service.output$` for
* The host/service state changes into a [hard state](3-monitoring-basics.md#hard-soft-states)
* The host/service state recovers from a [soft or hard state](3-monitoring-basics.md#hard-soft-states) to [OK](3-monitoring-basics.md#service-states)/[Up](3-monitoring-basics.md#host-states)
-[EventCommand](12-object-types.md#objecttype-eventcommand) objects are referenced by
-[Host](12-object-types.md#objecttype-host) and [Service](12-object-types.md#objecttype-service) objects
+[EventCommand](15-object-types.md#objecttype-eventcommand) objects are referenced by
+[Host](15-object-types.md#objecttype-host) and [Service](15-object-types.md#objecttype-service) objects
using the `event_command` attribute.
Therefore the `EventCommand` object should define a command line
icinga ALL=(ALL) NOPASSWD: /etc/init.d/apache2 restart
-Define a generic [EventCommand](12-object-types.md#objecttype-eventcommand) object `event_by_ssh`
+Define a generic [EventCommand](15-object-types.md#objecttype-eventcommand) object `event_by_ssh`
which can be used for all event commands triggered using ssh:
/* pass event commands through ssh */
## <a id="dependencies"></a> Dependencies
-Icinga 2 uses host and service [Dependency](12-object-types.md#objecttype-dependency) objects
+Icinga 2 uses host and service [Dependency](15-object-types.md#objecttype-dependency) objects
for determing their network reachability.
A service can depend on a host, and vice versa. A service has an implicit
dependency will fail and render all child objects (hosts or services) unreachable.
You can determine the child's reachability by querying the `is_reachable` attribute
-in for example [DB IDO](14-appendix.md#schema-db-ido-extensions).
+in for example [DB IDO](17-appendix.md#schema-db-ido-extensions).
### <a id="dependencies-implicit-host-service"></a> Implicit Dependencies for Services on Host
### <a id="recurring-downtimes"></a> Recurring Downtimes
-[ScheduledDowntime objects](12-object-types.md#objecttype-scheduleddowntime) can be used to set up
+[ScheduledDowntime objects](15-object-types.md#objecttype-scheduleddowntime) can be used to set up
recurring downtimes for services.
Example:
There are several ways of using custom attributes with [apply rules](3-monitoring-basics.md#using-apply):
-* As simple attribute literal ([number](10-language-reference.md#numeric-literals), [string](10-language-reference.md#string-literals),
-[boolean](10-language-reference.md#boolean-literals)) for expression conditions (`assign where`, `ignore where`)
-* As [array](10-language-reference.md#array) or [dictionary](10-language-reference.md#dictionary) attribute with nested values
+* As simple attribute literal ([number](13-language-reference.md#numeric-literals), [string](13-language-reference.md#string-literals),
+[boolean](13-language-reference.md#boolean-literals)) for expression conditions (`assign where`, `ignore where`)
+* As [array](13-language-reference.md#array) or [dictionary](13-language-reference.md#dictionary) attribute with nested values
(e.g. dictionaries in dictionaries) in [apply for](3-monitoring-basics.md#using-apply-for) rules.
Features like [DB IDO](3-monitoring-basics.md#db-ido), Livestatus(#setting-up-livestatus) or StatusData(#status-data)
> **Tip**
>
> Custom attributes are identified by the `vars` dictionary attribute as short name.
-> Accessing the different attribute keys is possible using the [index accessor](10-language-reference.md#indexer) `.`.
+> Accessing the different attribute keys is possible using the [index accessor](13-language-reference.md#indexer) `.`.
Custom attributes in command definitions or performance data templates are evaluated at
runtime when executing a command. These custom attributes cannot be used somewhere else
This helps passing multiple parameters to check plugins requiring them. Prominent
plugin examples are:
-* [check_disk -p](13-icinga-template-library.md#plugin-check-command-disk)
-* [check_nrpe -a](13-icinga-template-library.md#plugin-check-command-nrpe)
-* [check_nscp -l](13-icinga-template-library.md#plugin-check-command-nscp)
-* [check_dns -a](13-icinga-template-library.md#plugin-check-command-dns)
+* [check_disk -p](16-icinga-template-library.md#plugin-check-command-disk)
+* [check_nrpe -a](16-icinga-template-library.md#plugin-check-command-nrpe)
+* [check_nscp -l](16-icinga-template-library.md#plugin-check-command-nscp)
+* [check_dns -a](16-icinga-template-library.md#plugin-check-command-dns)
More details on how to use `repeat_key` and other command argument options can be
-found in [this section](12-object-types.md#objecttype-checkcommand-arguments).
+found in [this section](15-object-types.md#objecttype-checkcommand-arguments).
> **Note**
>
### <a id="external-command-list"></a> External Command List
-A list of currently supported external commands can be found [here](14-appendix.md#external-commands-list-detail).
+A list of currently supported external commands can be found [here](17-appendix.md#external-commands-list-detail).
Detailed information on the commands and their required parameters can be found
on the [Icinga 1.x documentation](http://docs.icinga.org/latest/en/extcommands2.html).
`service_name_template` configuration attributes.
The example below uses [runtime macros](3-monitoring-basics.md#runtime-macros) and a
-[global constant](10-language-reference.md#constants) named `GraphiteEnv`. The constant name
-is freely definable and should be put in the [constants.conf](2-getting-started.md#constants-conf) file.
+[global constant](13-language-reference.md#constants) named `GraphiteEnv`. The constant name
+is freely definable and should be put in the [constants.conf](4-configuring-icinga-2.md#constants-conf) file.
const GraphiteEnv = "icinga.env1"
These logs are not only used for informational representation in
external web interfaces parsing the logs, but also to generate
SLA reports and trends in Icinga 1.x Classic UI. Furthermore the
-[Livestatus](7-livestatus.md#setting-up-livestatus) feature uses these logs for answering queries to
+[Livestatus](9-livestatus.md#setting-up-livestatus) feature uses these logs for answering queries to
historical tables.
The `CompatLogger` object can be enabled with
Details on the installation can be found in the [Configuring DB IDO](2-getting-started.md#configuring-db-ido)
chapter. Details on the configuration can be found in the
-[IdoMysqlConnection](12-object-types.md#objecttype-idomysqlconnection) and
-[IdoPgsqlConnection](12-object-types.md#objecttype-idopgsqlconnection)
+[IdoMysqlConnection](15-object-types.md#objecttype-idomysqlconnection) and
+[IdoPgsqlConnection](15-object-types.md#objecttype-idopgsqlconnection)
object configuration documentation.
-The DB IDO feature supports [High Availability](4-monitoring-remote-systems.md#high-availability-db-ido) in
+The DB IDO feature supports [High Availability](5-monitoring-remote-systems.md#high-availability-db-ido) in
the Icinga 2 cluster.
The following example query checks the health of the current Icinga 2 instance
> **Tip**
>
-> Use [check plugins](6-addons-plugins.md#plugins) to monitor the backend.
+> Use [check plugins](7-addons-plugins.md#plugins) to monitor the backend.
Replace the `default` string with your instance name, if different.
(1 Zeile)
-A detailed list on the available table attributes can be found in the [DB IDO Schema documentation](14-appendix.md#schema-db-ido).
+A detailed list on the available table attributes can be found in the [DB IDO Schema documentation](17-appendix.md#schema-db-ido).
## <a id="check-result-files"></a> Check Result Files
projects / icinga2 / blobdiff