* [Register](https://exchange.icinga.org/authentication/register) an Icinga account.
* Create a new issue at the [Icinga 2 Development Tracker](https://dev.icinga.org/projects/i2).
-* When reporting a bug, please include the details described in the [Troubleshooting](12-troubleshooting.md#troubleshooting-information-required) chapter (version, configs, logs, etc).
+* When reporting a bug, please include the details described in the [Troubleshooting](13-troubleshooting.md#troubleshooting-information-required) chapter (version, configs, logs, etc).
## <a id="whats-new"></a> What's new
[PNP](http://www.pnp4nagios.org) must be configured using the
[bulk mode with npcd and npcdmod](http://docs.pnp4nagios.org/pnp-0.6/modes#bulk_mode_with_npcd_and_npcdmod)
-hence Icinga 2's [PerfdataWriter](3-monitoring-basics.md#performance-data) acts as npcdmod. NPCD will collect
+hence Icinga 2's [PerfdataWriter](4-advanced-topics.md#performance-data) acts as npcdmod. NPCD will collect
the rotated performance data files.
#### <a id="addons-graphing-ingraph"></a> inGraph
[inGraph](https://www.netways.org/projects/ingraph/wiki) requires the ingraph-collector addon
-to be configured to point at the perfdata files. Icinga 2's [PerfdataWriter](3-monitoring-basics.md#performance-data) will
+to be configured to point at the perfdata files. Icinga 2's [PerfdataWriter](4-advanced-topics.md#performance-data) will
write to the performance data spool directory.
#### <a id="addons-graphing-graphite"></a> Graphite
There are Graphite addons available for collecting the performance data files as well. But
-natively you can use the [GraphiteWriter](3-monitoring-basics.md#graphite-carbon-cache-writer) feature.
+natively you can use the [GraphiteWriter](4-advanced-topics.md#graphite-carbon-cache-writer) feature.
#### <a id="addons-reporting"></a> Icinga Reporting
As well as the Icinga supported web interfaces (Classic UI 1.x, Web 1.x, Web 2) there are a
number of community provided web interfaces too:
-* [Thruk](http://www.thruk.org) based on the [Livestatus](11-livestatus.md#setting-up-livestatus) feature
+* [Thruk](http://www.thruk.org) based on the [Livestatus](12-livestatus.md#setting-up-livestatus) feature
## <a id="plugins"></a> Plugins
* [Icinga Wiki](https://wiki.icinga.org)
The recommended way of setting up these plugins is to copy them to a common directory
-and create a new global constant, e.g. `CustomPluginDir` in your [constants.conf](4-configuring-icinga-2.md#constants-conf)
+and create a new global constant, e.g. `CustomPluginDir` in your [constants.conf](5-configuring-icinga-2.md#constants-conf)
configuration file:
# cp check_snmp_int.pl /opt/monitoring/plugins
Sometimes plugins contain hard-coded paths to other components. Instead of changing
the plugin it might be easier to create logical links which is (more) update-safe.
-Each plugin requires a [CheckCommand](5-object-types.md#objecttype-checkcommand) object in your
-configuration which can be used in the [Service](5-object-types.md#objecttype-service) or
-[Host](5-object-types.md#objecttype-host) object definition.
+Each plugin requires a [CheckCommand](6-object-types.md#objecttype-checkcommand) object in your
+configuration which can be used in the [Service](6-object-types.md#objecttype-service) or
+[Host](6-object-types.md#objecttype-host) object definition.
There are the following conventions to follow when adding a new command object definition:
* Define a unique `prefix` for the command's specific command arguments. That way you can safely
set them on host/service level and you'll always know which command they control.
* Use command argument default values, e.g. for thresholds
-* Use [advanced conditions](5-object-types.md#objecttype-checkcommand) like `set_if` definitions.
+* Use [advanced conditions](6-object-types.md#objecttype-checkcommand) like `set_if` definitions.
Example for a custom `my-snmp-int` check command:
vars.snmp_crit = "0,600"
}
-Icinga 2 has built-in check command definitions for the [Manubulon Plugin Checks](6-icinga-template-library.md#snmp-manubulon-plugin-check-commands).
+Icinga 2 has built-in check command definitions for the [Manubulon Plugin Checks](7-icinga-template-library.md#snmp-manubulon-plugin-check-commands).
For further information on your monitoring configuration read the
[Monitoring Basics](3-monitoring-basics.md#monitoring-basics) chapter.
> **Tip**
>
> Get to know the new configuration format and the advanced [apply](3-monitoring-basics.md#using-apply) rules and
-> use [syntax highlighting](9-addons-plugins.md#configuration-syntax-highlighting) in vim/nano.
+> use [syntax highlighting](10-addons-plugins.md#configuration-syntax-highlighting) in vim/nano.
If you're looking for puppet manifests, chef cookbooks, ansible recipes, etc - we're happy
to integrate them upstream, so please get in touch at [https://support.icinga.org](https://support.icinga.org).
## <a id="setting-up-icinga-classic-ui"></a> Setting up Icinga Classic UI 1.x
Icinga 2 can write `status.dat` and `objects.cache` files in the format that
-is supported by the Icinga 1.x Classic UI. [External commands](3-monitoring-basics.md#external-commands)
+is supported by the Icinga 1.x Classic UI. [External commands](4-advanced-topics.md#external-commands)
(a.k.a. the "command pipe") are also supported. It also supports writing Icinga 1.x
log files which are required for the reporting functionality in the Classic UI.
On all distributions other than Debian you may have to restart both your web
server as well as Icinga 2 after installing the Classic UI package.
-Icinga Classic UI requires the [StatusDataWriter](3-monitoring-basics.md#status-data), [CompatLogger](3-monitoring-basics.md#compat-logging)
-and [ExternalCommandListener](3-monitoring-basics.md#external-commands) features.
+Icinga Classic UI requires the [StatusDataWriter](4-advanced-topics.md#status-data), [CompatLogger](4-advanced-topics.md#compat-logging)
+and [ExternalCommandListener](4-advanced-topics.md#external-commands) features.
Enable these features and restart Icinga 2.
# icinga2 feature enable statusdata compatlog command
Icinga 2 can write to the same schema supplied by `Icinga IDOUtils 1.x` which
is an explicit requirement to run `Icinga Web` next to the external command pipe.
-Therefore you need to setup the [DB IDO feature](2-getting-started.md#configuring-db-ido) remarked in the previous sections.
+Therefore you need to setup the [DB IDO feature](#configuring-db-ido) remarked in the previous sections.
### <a id="installing-icinga-web"></a> Installing Icinga Web 1.x
# icinga-web-clearcache
-Additionally you need to enable the `command` feature for sending [external commands](3-monitoring-basics.md#external-commands):
+Additionally you need to enable the `command` feature for sending [external commands](4-advanced-topics.md#external-commands):
# icinga2 feature enable command
- `icinga-web-config-icinga2-ido-mysql`
- `icinga-web-config-icinga2-ido-pgsql`
-These packages take care of setting up the [DB IDO](2-getting-started.md#configuring-db-ido) configuration,
+These packages take care of setting up the [DB IDO](#configuring-db-ido) configuration,
enabling the external command pipe for Icinga Web and depend on
the corresponding packages of Icinga 2.
> **Note**
>
> If you are using an older version of Icinga Web, install it like this and adapt
-> the configuration manually as shown in [the RPM notes](10-alternative-frontends.md#icinga-web-rpm-notes):
+> the configuration manually as shown in [the RPM notes](11-alternative-frontends.md#icinga-web-rpm-notes):
>
> `apt-get install --no-install-recommends icinga-web`
>
> Only install the Livestatus feature if your web interface or addon requires
> you to do so (for example, [Icinga Web 2](2-getting-started.md#setting-up-icingaweb2)).
-> [Icinga Classic UI](10-alternative-frontends.md#setting-up-icinga-classic-ui) and [Icinga Web](10-alternative-frontends.md#setting-up-icinga-web)
+> [Icinga Classic UI](11-alternative-frontends.md#setting-up-icinga-classic-ui) and [Icinga Web](11-alternative-frontends.md#setting-up-icinga-web)
> do not use Livestatus as backend.
The Livestatus component that is distributed as part of Icinga 2 is a
Livestatus.
Details on the available tables and attributes with Icinga 2 can be found
-in the [Livestatus Schema](17-appendix.md#schema-livestatus) section.
+in the [Livestatus Schema](18-appendix.md#schema-livestatus) section.
You can enable Livestatus using icinga2 feature enable:
* Unix socket (default)
* TCP socket
-Details on the configuration can be found in the [LivestatusListener](5-object-types.md#objecttype-livestatuslistener)
+Details on the configuration can be found in the [LivestatusListener](6-object-types.md#objecttype-livestatuslistener)
object configuration.
### <a id="livestatus-get-queries"></a> Livestatus GET Queries
### <a id="livestatus-command-queries"></a> Livestatus COMMAND Queries
-A list of available external commands and their parameters can be found [here](17-appendix.md#external-commands-list-detail)
+A list of available external commands and their parameters can be found [here](18-appendix.md#external-commands-list-detail)
$ echo -e 'COMMAND <externalcommandstring>' | netcat 127.0.0.1 6558
downtimes | services | status attributes
timeperiods | | name and is inside flag
endpoints | | config and status attributes
- log | services, hosts, contacts, commands | parses [compatlog](5-object-types.md#objecttype-compatlogger) and shows log attributes
- statehist | hosts, services | parses [compatlog](5-object-types.md#objecttype-compatlogger) and aggregates state change attributes
+ log | services, hosts, contacts, commands | parses [compatlog](6-object-types.md#objecttype-compatlogger) and shows log attributes
+ statehist | hosts, services | parses [compatlog](6-object-types.md#objecttype-compatlogger) and aggregates state change attributes
The `commands` table is populated with `CheckCommand`, `EventCommand` and `NotificationCommand` objects.
-A detailed list on the available table attributes can be found in the [Livestatus Schema documentation](17-appendix.md#schema-livestatus).
+A detailed list on the available table attributes can be found in the [Livestatus Schema documentation](18-appendix.md#schema-livestatus).
* Provide complete configuration snippets explaining your problem in detail
* Provide complete logs targetting your problem
* If the check command failed - what's the output of your manual plugin tests?
-* In case of [debugging](12-troubleshooting.md#debug) Icinga 2, the full back traces and outputs
+* In case of [debugging](13-troubleshooting.md#debug) Icinga 2, the full back traces and outputs
## <a id="troubleshooting-enable-debug-output"></a> Enable Debug Output
The `icinga2 object list` CLI command can be used to list all configuration objects and their
attributes. The tool also shows where each of the attributes was modified.
-That way you can also identify which objects have been created from your [apply rules](15-language-reference.md#apply).
+That way you can also identify which objects have been created from your [apply rules](16-language-reference.md#apply).
# icinga2 object list
## <a id="check-command-definitions"></a> Where are the check command definitions?
-Icinga 2 features a number of built-in [check command definitions](6-icinga-template-library.md#plugin-check-commands) which are
+Icinga 2 features a number of built-in [check command definitions](7-icinga-template-library.md#plugin-check-commands) which are
included using
include <itl>
include <plugins>
-in the [icinga2.conf](4-configuring-icinga-2.md#icinga2-conf) configuration file. These files are not considered configuration files and will be overridden
+in the [icinga2.conf](5-configuring-icinga-2.md#icinga2-conf) configuration file. These files are not considered configuration files and will be overridden
on upgrade, so please send modifications as proposed patches upstream. The default include path is set to
`LocalStateDir + "/share/icinga2/includes"`.
* Check the debug log to see if the check command gets executed
* Verify that failed depedencies do not prevent command execution
* Make sure that the plugin is executable by the Icinga 2 user (run a manual test)
-* Make sure the [checker](7-cli-commands.md#features) feature is enabled.
+* Make sure the [checker](8-cli-commands.md#features) feature is enabled.
Examples:
* Do the notification attributes `states`, `types`, `period` match the notification conditions?
* Do the user attributes `states`, `types`, `period` match the notification conditions?
* Are there any notification `begin` and `end` times configured?
-* Make sure the [notification](7-cli-commands.md#features) feature is enabled.
+* Make sure the [notification](8-cli-commands.md#features) feature is enabled.
* Does the referenced NotificationCommand work when executed as Icinga user on the shell?
If notifications are to be sent via mail make sure that the mail program specified exists.
## <a id="feature-not-working"></a> Feature is not working
* Make sure that the feature configuration is enabled by symlinking from `features-available/`
-to `features-enabled` and that the latter is included in [icinga2.conf](4-configuring-icinga-2.md#icinga2-conf).
+to `features-enabled` and that the latter is included in [icinga2.conf](5-configuring-icinga-2.md#icinga2-conf).
* Are the feature attributes set correctly according to the documentation?
* Any errors on the logs?
## <a id="configuration-ignored"></a> Configuration is ignored
-* Make sure that the line(s) are not [commented out](15-language-reference.md#comments) (starting with `//` or `#`, or
+* Make sure that the line(s) are not [commented out](16-language-reference.md#comments) (starting with `//` or `#`, or
encapsulated by `/* ... */`).
-* Is the configuration file included in [icinga2.conf](4-configuring-icinga-2.md#icinga2-conf)?
+* Is the configuration file included in [icinga2.conf](5-configuring-icinga-2.md#icinga2-conf)?
## <a id="configuration-attribute-inheritance"></a> Configuration attributes are inherited from
-Icinga 2 allows you to import templates using the [import](15-language-reference.md#template-imports) keyword. If these templates
+Icinga 2 allows you to import templates using the [import](16-language-reference.md#template-imports) keyword. If these templates
contain additional attributes, your objects will automatically inherit them. You can override
or modify these attributes in the current object.
## <a id="troubleshooting-cluster"></a> Cluster Troubleshooting
-You should configure the [cluster health checks](8-monitoring-remote-systems.md#cluster-health-check) if you haven't
+You should configure the [cluster health checks](9-monitoring-remote-systems.md#cluster-health-check) if you haven't
done so already.
> **Note**
* Within a config master zone, only one configuration master is allowed to have its config in `/etc/icinga2/zones.d`.
** The master syncs the configuration to `/var/lib/icinga2/api/zones/` during startup and only syncs valid configuration to the other nodes
** The other nodes receive the configuration into `/var/lib/icinga2/api/zones/`
-* The `icinga2.log` log file will indicate whether this ApiListener [accepts config](8-monitoring-remote-systems.md#zone-config-sync-permissions), or not
+* The `icinga2.log` log file will indicate whether this ApiListener [accepts config](9-monitoring-remote-systems.md#zone-config-sync-permissions), or not
## <a id="debug"></a> Debug Icinga 2
For a long-term migration of your configuration you should consider re-creating
your configuration based on the proposed Icinga 2 configuration paradigm.
-Please read the [next chapter](14-migrating-from-icinga-1x.md#differences-1x-2) to find out more about the differences
+Please read the [next chapter](15-migrating-from-icinga-1x.md#differences-1x-2) to find out more about the differences
between 1.x and 2.
### <a id="manual-config-migration-hints"></a> Manual Config Migration Hints
The examples are taken from Icinga 1.x test and production environments and converted
straight into a possible Icinga 2 format. If you found a different strategy, send a patch!
-If you require in-depth explanations, please check the [next chapter](14-migrating-from-icinga-1x.md#differences-1x-2).
+If you require in-depth explanations, please check the [next chapter](15-migrating-from-icinga-1x.md#differences-1x-2).
#### <a id="manual-config-migration-hints-Intervals"></a> Manual Config Migration Hints for Intervals
hostgroup_members hg1
}
-This can be migrated to Icinga 2 and [using group assign](15-language-reference.md#group-assign). The additional nested hostgroup
+This can be migrated to Icinga 2 and [using group assign](16-language-reference.md#group-assign). The additional nested hostgroup
`hg1` is included into `hg2` with the `groups` attribute.
For the check command it is required to
* Escape all double quotes with an additional `\`.
-* Replace all [runtime macros](14-migrating-from-icinga-1x.md#manual-config-migration-hints-runtime-macros), e.g. `$HOSTADDRESS$` with `$address$`.
-* Replace [custom variable macros](14-migrating-from-icinga-1x.md#manual-config-migration-hints-runtime-custom-attributes) if any.
+* Replace all [runtime macros](15-migrating-from-icinga-1x.md#manual-config-migration-hints-runtime-macros), e.g. `$HOSTADDRESS$` with `$address$`.
+* Replace [custom variable macros](15-migrating-from-icinga-1x.md#manual-config-migration-hints-runtime-custom-attributes) if any.
* Keep `$ARGn$` macros.
The final check command looks like this in Icinga2:
#### <a id="manual-config-migration-hints-runtime-macros"></a> Manual Config Migration Hints for Runtime Macros
-Runtime macros have been renamed. A detailed comparison table can be found [here](14-migrating-from-icinga-1x.md#differences-1x-2-runtime-macros).
+Runtime macros have been renamed. A detailed comparison table can be found [here](15-migrating-from-icinga-1x.md#differences-1x-2-runtime-macros).
For example, accessing the service check output looks like the following in Icinga 1.x:
#### <a id="manual-config-migration-hints-contacts-users"></a> Manual Config Migration Hints for Contacts (Users)
Contacts in Icinga 1.x act as users in Icinga 2, but do not have any notification commands specified.
-This migration part is explained in the [next chapter](14-migrating-from-icinga-1x.md#manual-config-migration-hints-notifications).
+This migration part is explained in the [next chapter](15-migrating-from-icinga-1x.md#manual-config-migration-hints-notifications).
define contact{
contact_name testconfig-user
email icinga@localhost
}
-The `service_notification_options` can be [mapped](14-migrating-from-icinga-1x.md#manual-config-migration-hints-notification-filters)
+The `service_notification_options` can be [mapped](15-migrating-from-icinga-1x.md#manual-config-migration-hints-notification-filters)
into generic `state` and `type` filters, if additional notification filtering is required. `alias` gets
renamed to `display_name`.
Convert the `notification_options` attribute from Icinga 1.x to Icinga 2 `states` and `types`. Details
-[here](14-migrating-from-icinga-1x.md#manual-config-migration-hints-notification-filters). Add the notification period.
+[here](15-migrating-from-icinga-1x.md#manual-config-migration-hints-notification-filters). Add the notification period.
states = [ OK, Warning, Critical ]
types = [ Recovery, Problem, Custom ]
assign where "hg_svcdep2" in host.groups
}
-Host dependencies are explained in the [next chapter](14-migrating-from-icinga-1x.md#manual-config-migration-hints-host-parents).
+Host dependencies are explained in the [next chapter](15-migrating-from-icinga-1x.md#manual-config-migration-hints-host-parents).
* Icinga 2 does not support any 1.x NEB addons for check load distribution
* If your current setup consists of instances distributing the check load, you should consider
-building a [load distribution](8-monitoring-remote-systems.md#cluster-scenarios-load-distribution) setup with Icinga 2.
+building a [load distribution](9-monitoring-remote-systems.md#cluster-scenarios-load-distribution) setup with Icinga 2.
* If your current setup includes active/passive clustering with external tools like Pacemaker/DRBD
-consider the [High Availability](8-monitoring-remote-systems.md#cluster-scenarios-high-availability) setup.
+consider the [High Availability](9-monitoring-remote-systems.md#cluster-scenarios-high-availability) setup.
* If you have build your own custom configuration deployment and check result collecting mechanism
you should re-design your setup and re-evaluate your requirements, and how they may be fulfilled
using the Icinga 2 cluster capabilities.
### <a id="differences-1x-2-main-config"></a> Main Config File
In Icinga 1.x there are many global configuration settings available in `icinga.cfg`.
-Icinga 2 only uses a small set of [global constants](15-language-reference.md#constants) allowing
+Icinga 2 only uses a small set of [global constants](16-language-reference.md#constants) allowing
you to specify certain different setting such as the `NodeName` in a cluster scenario.
-Aside from that, the [icinga2.conf](4-configuring-icinga-2.md#icinga2-conf) should take care of including
-global constants, enabled [features](7-cli-commands.md#features) and the object configuration.
+Aside from that, the [icinga2.conf](5-configuring-icinga-2.md#icinga2-conf) should take care of including
+global constants, enabled [features](8-cli-commands.md#features) and the object configuration.
### <a id="differences-1x-2-include-files-dirs"></a> Include Files and Directories
const PluginDir = "/usr/lib/nagios/plugins"
-[Global macros](15-language-reference.md#constants) can only be defined once. Trying to modify a
+[Global macros](16-language-reference.md#constants) can only be defined once. Trying to modify a
global constant will result in an error.
### <a id="differences-1x-2-configuration-comments"></a> Configuration Comments
requiring some command timeouts to be extended.
Icinga 2 allows you to specify the command timeout directly on the command. So
-if your VMVware check plugin takes 15 minutes, [increase the timeout](5-object-types.md#objecttype-checkcommand)
+if your VMVware check plugin takes 15 minutes, [increase the timeout](6-object-types.md#objecttype-checkcommand)
accordingly.
For detailed examples on how to use the dependencies please check the [dependencies](3-monitoring-basics.md#dependencies)
chapter.
-Dependencies can be applied to hosts or services using the [apply rules](15-language-reference.md#apply).
+Dependencies can be applied to hosts or services using the [apply rules](16-language-reference.md#apply).
The `StatusDataWriter`, `IdoMysqlConnection` and `LivestatusListener` types
support the Icinga 1.x schema with dependencies and parent attributes for
* parent process continues with old configuration objects and the event scheduling
(doing checks, replicating cluster events, triggering alert notifications, etc.)
* validation NOT ok: child process terminates, parent process continues with old configuration state
-(this is ESSENTIAL for the [cluster config synchronisation](8-monitoring-remote-systems.md#cluster-zone-config-sync))
+(this is ESSENTIAL for the [cluster config synchronisation](9-monitoring-remote-systems.md#cluster-zone-config-sync))
* validation ok: child process signals parent process to terminate and save its current state
(all events until now) into the icinga2 state file
* parent process shuts down writing icinga2.state file
not synced between the master and slave nodes. There are addons available solving the check
and configuration distribution problems Icinga 1.x distributed monitoring currently suffers from.
-Icinga 2 implements a new built-in [distributed monitoring architecture](8-monitoring-remote-systems.md#distributed-monitoring-high-availability),
+Icinga 2 implements a new built-in [distributed monitoring architecture](9-monitoring-remote-systems.md#distributed-monitoring-high-availability),
including config and check distribution, IPv4/IPv6 support, SSL certificates and zone support for DMZ.
High Availability and load balancing are also part of the Icinga 2 Cluster setup.
check_interval = len(MyGroups) * 1m
}
-A list of available functions is available in the [Library Reference](16-library-reference.md#library-reference) chapter.
+A list of available functions is available in the [Library Reference](17-library-reference.md#library-reference) chapter.
## <a id="dictionary-operators"></a> Assignments
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 "ping"
-is created for each matching host. [Expression operators](15-language-reference.md#expression-operators)
+is created for each matching host. [Expression operators](16-language-reference.md#expression-operators)
may be used in `assign where` conditions.
The `to` keyword and the target type may be omitted if there is only one target
In this example the `assign where` condition is a boolean expression which is evaluated
for all objects of the type `Host`. Each matching host is added as member to the host group
with the name "linux-servers". Membership exclusion can be controlled using the `ignore where`
-condition. [Expression operators](15-language-reference.md#expression-operators) may be used in `assign where` and
+condition. [Expression operators](16-language-reference.md#expression-operators) may be used in `assign where` and
`ignore where` conditions.
Source Type | Variables
Non-empty dictionary | { key = "value" } | true
For a list of supported expression operators for `assign where` and `ignore where`
-statements, see [expression operators](15-language-reference.md#expression-operators).
+statements, see [expression operators](16-language-reference.md#expression-operators).
## <a id="comments"></a> Comments
config compiler to search the include search paths for the specified
file. By default $PREFIX/share/icinga2/include is included in the list of search
paths. Additional include search paths can be added using
-[command-line options](7-cli-commands.md#config-include-path).
+[command-line options](8-cli-commands.md#config-include-path).
Wildcards are not permitted when using angle brackets.
* `mainlog` for writing the `icinga2.log` file
You can verify that by calling `icinga2 feature list`
-[CLI command](7-cli-commands.md#cli-command-feature) to see which features are
+[CLI command](8-cli-commands.md#cli-command-feature) to see which features are
enabled and disabled.
# icinga2 feature list
OS X (MacPorts) | nagios-plugins | /opt/local/libexec
Depending on which directory your plugins are installed into you may need to
-update the global `PluginDir` constant in your [Icinga 2 configuration](4-configuring-icinga-2.md#constants-conf).
+update the global `PluginDir` constant in your [Icinga 2 configuration](5-configuring-icinga-2.md#constants-conf).
This constant is used by the check command definitions contained in the Icinga Template Library
to determine where to find the plugin binaries.
-Please refer to the [plugins](9-addons-plugins.md#plugins) chapter for details about how to integrate
+Please refer to the [plugins](10-addons-plugins.md#plugins) chapter for details about how to integrate
additional check plugins into your Icinga 2 setup.
## <a id="running-icinga2"></a> Running Icinga 2
Job for icinga2.service failed. See 'systemctl status icinga2.service' and 'journalctl -xn' for details.
If you're stuck with configuration errors, you can manually invoke the
-[configuration validation](7-cli-commands.md#config-validation).
+[configuration validation](8-cli-commands.md#config-validation).
## <a id="setting-up-the-user-interface"></a> Setting up Icinga Web 2
Icinga 2 can be used with Icinga Web 2 and a number of other web interfaces.
This chapter explains how to set up Icinga Web 2. The
-[Alternative Frontends](10-alternative-frontends.md#alternative-frontends)
+[Alternative Frontends](11-alternative-frontends.md#alternative-frontends)
chapter can be used as a starting point for installing some of the other web
interfaces which are also available.
update the database credentials in this file.
All available attributes are explained in the
-[IdoMysqlConnection object](5-object-types.md#objecttype-idomysqlconnection)
+[IdoMysqlConnection object](6-object-types.md#objecttype-idomysqlconnection)
chapter.
You can enable the `ido-mysql` feature configuration file using
the database credentials in this file.
All available attributes are explained in the
-[IdoPgsqlConnection object](5-object-types.md#objecttype-idopgsqlconnection)
+[IdoPgsqlConnection object](6-object-types.md#objecttype-idopgsqlconnection)
chapter.
You can enable the `ido-pgsql` feature configuration file using
A number of additional features are available in the form of addons. A list of
popular addons is available in the
-[Addons and Plugins](9-addons-plugins.md#addons-plugins) chapter.
+[Addons and Plugins](10-addons-plugins.md#addons-plugins) chapter.
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](12-troubleshooting.md#troubleshooting).
+Details on troubleshooting check problems can be found [here](13-troubleshooting.md#troubleshooting).
### <a id="host-states"></a> Host States
### <a id="host-service-checks"></a> Host and Service Checks
-Hosts and Services determine their state from a check result returned from a check
-execution to the Icinga 2 application. By default the `generic-host` example template
-will define `hostalive` as host check. If your host is unreachable for ping, you should
-consider using a different check command, for instance the `http` check command, or if
-there is no check available, the `dummy` check command.
+Hosts and services determine their state by running checks in a regular interval.
- object Host "uncheckable-host" {
- check_command = "dummy"
- vars.dummy_state = 1
- vars.dummy_text = "Pretending to be OK."
+ object Host "router" {
+ check_command = "hostalive"
+ address = "10.0.0.1"
}
-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](5-object-types.md#objecttype-service) object definition.
-
-## <a id="configuration-best-practice"></a> Configuration Best Practice
-
-The [Getting Started](2-getting-started.md#getting-started) chapter already introduced various aspects
-of the Icinga 2 configuration language. If you are ready to configure additional
-hosts, services, notifications, dependencies, etc, you should think about the
-requirements first and then decide for a possible strategy.
-
-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](9-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.
-
-In order to find the best strategy for your own configuration, ask yourself the following questions:
-
-* Do your hosts share a common group of services (for example linux hosts with disk, load, etc checks)?
-* Only a small set of users receives notifications and escalations for all hosts/services?
-
-If you can at least answer one of these questions with yes, look for the [apply rules](3-monitoring-basics.md#using-apply) logic
-instead of defining objects on a per host and service basis.
-
-* You are required to define specific configuration for each host/service?
-* Does your configuration generation tool already know about the host-service-relationship?
-
-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](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.
-* generated configuration with one file per host and a global configuration for groups, users, etc.
-* one big file generated from an external application (probably a bad idea for maintaining changes).
-* your own.
-
-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?
-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](3-monitoring-basics.md#object-inheritance-using-templates) chapter.
-* 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.
+The `hostalive` command is one of several built-in check commands. It sends ICMP
+echo requests to the IP address specified in the `address` attribute to determine
+whether a host is online.
-If you happen to have further questions, do not hesitate to join the [community support channels](https://support.icinga.org)
-and ask community members for their experience and best practices.
+A number of other [built-in check commands](#plugin-check-comamnds) are also
+available. In addition to these commands the next few chapters will explain in
+detail how to set up your own check commands.
-### <a id="object-inheritance-using-templates"></a> Object Inheritance Using Templates
+## <a id="object-inheritance-using-templates"></a> Templates
Templates may be used to apply a set of identical attributes to more than one
object:
enable_perfdata = true
}
- template Service "ipv6-service {
- notes = "IPv6 critical != IPv4 broken."
- }
-
apply Service "ping4" {
import "generic-service"
apply Service "ping6" {
import "generic-service"
- import "ipv6-service"
check_command = "ping6"
In this example the `ping4` and `ping6` services inherit properties from the
-template `generic-service`. The `ping6` service additionally imports the `ipv6-service`
-template with the `notes` attribute.
+template `generic-service`.
Objects as well as templates themselves can import an arbitrary number of
-templates. Attributes inherited from a template can be overridden in the
+other templates. Attributes inherited from a template can be overridden in the
object if necessary.
-You can import existing non-template objects into objects which
-requires you to use unique names for templates and objects sharing
-the same namespace.
-
-Example for importing objects:
-
- object CheckCommand "snmp-simple" {
- ...
- vars.snmp_defaults = ...
- }
+You can also import existing non-template objects. Note that templates
+and objects share the same namespace, i.e. you can't define a template
+that has the same name like an object.
- object CheckCommand "snmp-advanced" {
- import "snmp-simple"
- ...
- vars.snmp_advanced = ...
- }
-### <a id="using-apply"></a> Apply objects based on rules
+## <a id="using-apply"></a> Apply Rules
-Instead of assigning each object ([Service](5-object-types.md#objecttype-service),
-[Notification](5-object-types.md#objecttype-notification), [Dependency](5-object-types.md#objecttype-dependency),
-[ScheduledDowntime](5-object-types.md#objecttype-scheduleddowntime))
-based on attribute identifiers for example `host_name` objects can be [applied](15-language-reference.md#apply).
+Instead of assigning each object ([Service](6-object-types.md#objecttype-service),
+[Notification](6-object-types.md#objecttype-notification), [Dependency](6-object-types.md#objecttype-dependency),
+[ScheduledDowntime](6-object-types.md#objecttype-scheduleddowntime))
+based on attribute identifiers for example `host_name` objects can be [applied](16-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](15-language-reference.md#function-calls) on the host/service name?
- * [Multiple expressions combined](3-monitoring-basics.md#using-apply-expressions) with `&&` or `||` [operators](15-language-reference.md#expression-operators)
+ * A generic pattern [match](16-language-reference.md#function-calls) on the host/service name?
+ * [Multiple expressions combined](3-monitoring-basics.md#using-apply-expressions) with `&&` or `||` [operators](16-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](7-cli-commands.md#cli-command-object)
-> after successful [configuration validation](7-cli-commands.md#config-validation).
+> of the generated objects. Use the `object list` [CLI command](8-cli-commands.md#cli-command-object)
+> after successful [configuration validation](8-cli-commands.md#config-validation).
-###
# <a id="using-apply-expressions"></a> Apply Rules Expressions
+### <a id="using-apply-expressions"></a> Apply Rules Expressions
You can use simple or advanced combinations of apply rule expressions. Each
expression must evaluate into the boolean `true` value. An empty string
`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](15-language-reference.md#expression-operators) `2`.
+`OR` the `priority` custom attribute is [less than](16-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
+### <a id="using-apply-services"></a> Apply Services to Hosts
-The sample configuration already includes 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 sample configuration already includes a detailed example in [hosts.conf](5-configuring-icinga-2.md#hosts-conf)
+and [services.conf](5-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`.
Other detailed scenario examples are used in their respective chapters, for example
-[apply services with custom command arguments](3-monitoring-basics.md#using-apply-services-command-arguments).
+[apply services with custom command arguments](#using-apply-services-command-arguments).
-###
# <a id="using-apply-notifications"></a> Apply Notifications to Hosts and Services
+### <a id="using-apply-notifications"></a> Apply Notifications to Hosts and Services
Notifications are applied to specific targets (`Host` or `Service`) and work in a similar
manner:
`notification.mail` custom attribute defined. The notification command is set to `mail-service-notification`
and all members of the user group `noc` will get notified.
-###
# <a id="using-apply-dependencies"></a> Apply Dependencies to Hosts and Services
+### <a id="using-apply-dependencies"></a> Apply Dependencies to Hosts and Services
Detailed examples can be found in the [dependencies](3-monitoring-basics.md#dependencies) chapter.
-###
# <a id="using-apply-scheduledowntimes"></a> Apply Recurring Downtimes to Hosts and Services
+### <a id="using-apply-scheduledowntimes"></a> Apply Recurring Downtimes to Hosts and Services
-The sample confituration includes an example in [downtimes.conf](4-configuring-icinga-2.md#downtimes-conf).
+The sample confituration includes an example in [downtimes.conf](5-configuring-icinga-2.md#downtimes-conf).
-Detailed examples can be found in the [recurring downtimes](3-monitoring-basics.md#recurring-downtimes) chapter.
+Detailed examples can be found in the [recurring downtimes](4-advanced-topics.md#recurring-downtimes) chapter.
-###
# <a id="using-apply-for"></a> Using Apply For Rules
+### <a id="using-apply-for"></a> Using Apply For Rules
Next to the standard way of using apply rules there is the requirement of generating
apply rules objects based on set (array or dictionary). That way you'll save quite
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 includes 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 sample configuration already includes a detailed example in [hosts.conf](5-configuring-icinga-2.md#hosts-conf)
+and [services.conf](5-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()](15-language-reference.md#function-calls) function.
+This can be achieved by wrapping them into the [string()](16-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](7-cli-commands.md#cli-command-object)
-> after successful [configuration validation](7-cli-commands.md#config-validation).
+> of the generated objects. Use the `object list` [CLI command](8-cli-commands.md#cli-command-object)
+> after successful [configuration validation](8-cli-commands.md#config-validation).
-###
# <a id="using-apply-object attributes"></a> Use Object Attributes in Apply Rules
+### <a id="using-apply-object attributes"></a> Use Object Attributes in Apply Rules
Since apply rules are evaluated after the generic objects, you
can reference existing host and/or service object attributes as
action_url = "http://snmp.checker.company.com/" + host.name + "/" + vars.customer_id
}
-##
# <a id="groups"></a> Groups
+## <a id="groups"></a> Groups
-Groups are used for combining hosts, services, and users into
-accessible configuration attributes and views in external (web)
-interfaces.
+A group is a collection of similar objects. Groups are primarily used as a
+visualization aid in web interfaces.
Group membership is defined at the respective object itself. If
you have a hostgroup name `windows` for example, and want to assign
specific hosts to this group for later viewing the group on your
-alert dashboard, first create the hostgroup:
+alert dashboard, first create a HostGroup object:
object HostGroup "windows" {
display_name = "Windows Servers"
}
-Then add your hosts to this hostgroup
+Then add your hosts to this group:
template Host "windows-server" {
groups += [ "windows" ]
vars.mssql_port = 1433
}
-This can be done for service and user groups the same way. Additionally
-the user groups are associated as attributes in `Notification` objects.
+This can be done for service and user groups the same way:
object UserGroup "windows-mssql-admins" {
display_name = "Windows MSSQL Admins"
email = "ops@example.com"
}
-###
# <a id="group-assign-intro"></a> Group Membership Assign
+### <a id="group-assign-intro"></a> Group Membership Assign
-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](15-language-reference.md#apply)
+Instead of manually assigning each object to a group you can also assign objects
+to a group based on their attributes:
object HostGroup "prod-mssql" {
display_name = "Production MSSQL Servers"
+
assign where host.vars.mssql_port && host.vars.prod_mysql_db
ignore where host.vars.test_server == true
ignore where match("*internal", host.name)
}
-In this inherited example from above all hosts with the `vars` attribute `mssql_port`
-set will be added as members to the host group `mssql`. All `*internal`
-hosts or with the `test_server` attribute set to `true` will be ignored.
+In this example all hosts with the `vars` attribute `mssql_port`
+will be added as members to the host group `mssql`. However, all `*internal`
+hosts or with the `test_server` attribute set to `true` are not added to this
+group.
+
+Details on the `assign where` syntax can be found in the
+[Language Reference](16-language-reference.md#apply)
## <a id="notifications"></a> Notifications
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](12-troubleshooting.md#troubleshooting).
+Details on troubleshooting notification problems can be found [here](13-troubleshooting.md#troubleshooting).
> **Note**
>
-> Make sure that the [notification](7-cli-commands.md#features) feature is enabled on your master instance
+> Make sure that the [notification](8-cli-commands.md#features) feature is enabled
> in order to execute notification commands.
You should choose which information you (and your notified users) are interested in
You can filter for acknowledgements and custom notifications too.s and custom notifications too.
-## <a id="timeperiods"></a> Time Periods
-
-Time Periods define time ranges in Icinga where event actions are
-triggered, for example whether a service check is executed or not within
-the `check_period` attribute. Or a notification should be sent to
-users or not, filtered by the `period` and `notification_period`
-configuration attributes for `Notification` and `User` objects.
-
-> **Note**
->
-> If you are familar with Icinga 1.x - these time period definitions
-> are called `legacy timeperiods` in Icinga 2.
->
-> An Icinga 2 legacy timeperiod requires the `ITL` provided template
->`legacy-timeperiod`.
-
-The `TimePeriod` attribute `ranges` may contain multiple directives,
-including weekdays, days of the month, and calendar dates.
-These types may overlap/override other types in your ranges dictionary.
-
-The descending order of precedence is as follows:
-
-* Calendar date (2008-01-01)
-* Specific month date (January 1st)
-* Generic month date (Day 15)
-* Offset weekday of specific month (2nd Tuesday in December)
-* Offset weekday (3rd Monday)
-* Normal weekday (Tuesday)
-
-If you don't set any `check_period` or `notification_period` attribute
-on your configuration objects Icinga 2 assumes `24x7` as time period
-as shown below.
-
- object TimePeriod "24x7" {
- import "legacy-timeperiod"
-
- display_name = "Icinga 2 24x7 TimePeriod"
- ranges = {
- "monday" = "00:00-24:00"
- "tuesday" = "00:00-24:00"
- "wednesday" = "00:00-24:00"
- "thursday" = "00:00-24:00"
- "friday" = "00:00-24:00"
- "saturday" = "00:00-24:00"
- "sunday" = "00:00-24:00"
- }
- }
-
-If your operation staff should only be notified during workhours
-create a new timeperiod named `workhours` defining a work day from
-09:00 to 17:00.
-
- object TimePeriod "workhours" {
- import "legacy-timeperiod"
-
- display_name = "Icinga 2 8x5 TimePeriod"
- ranges = {
- "monday" = "09:00-17:00"
- "tuesday" = "09:00-17:00"
- "wednesday" = "09:00-17:00"
- "thursday" = "09:00-17:00"
- "friday" = "09:00-17:00"
- }
- }
-
-Use the `period` attribute to assign time periods to
-`Notification` and `Dependency` objects:
-
- object Notification "mail" {
- import "generic-notification"
-
- host_name = "localhost"
-
- command = "mail-notification"
- users = [ "icingaadmin" ]
- period = "workhours"
- }
-
-
## <a id="commands"></a> Commands
Icinga 2 uses three different command object types to specify how
checks should be performed, notifications should be sent, and
events should be handled.
-### <a id="command-environment-variables"></a> Environment Variables for Commands
-
-Please check [Runtime Custom Attributes as Environment Variables](3-monitoring-basics.md#runtime-custom-attribute-env-vars).
-
-
### <a id="check-commands"></a> Check Commands
-[CheckCommand](5-object-types.md#objecttype-checkcommand) objects define the command line how
+[CheckCommand](6-object-types.md#objecttype-checkcommand) objects define the command line how
a check is called.
-[CheckCommand](5-object-types.md#objecttype-checkcommand) objects are referenced by
-[Host](5-object-types.md#objecttype-host) and [Service](5-object-types.md#objecttype-service) objects
+[CheckCommand](6-object-types.md#objecttype-checkcommand) objects are referenced by
+[Host](6-object-types.md#objecttype-host) and [Service](6-object-types.md#objecttype-service) objects
using the `check_command` attribute.
> **Note**
>
-> Make sure that the [checker](7-cli-commands.md#features) feature is enabled in order to
+> Make sure that the [checker](8-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](5-object-types.md#objecttype-checkcommand) objects require the [ITL template](6-icinga-template-library.md#itl-plugin-check-command)
+[CheckCommand](6-object-types.md#objecttype-checkcommand) objects require the [ITL template](7-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](4-configuring-icinga-2.md#constants-conf) directory. The following example uses the
+into the [PluginDir](5-configuring-icinga-2.md#constants-conf) directory. The following example uses the
`check_disk` plugin contained in 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](5-object-types.md#objecttype-checkcommand)
+a host or service object, and add a [CheckCommand](6-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](6-icinga-template-library.md#plugin-check-command-disk).
+> ready to use with the [plugin check commands](7-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](5-object-types.md#objecttype-checkcommand).
-
-### <a id="using-apply-services-command-arguments"></a> Apply Services with Custom Command Arguments
-
-Imagine the following scenario: The `my-host1` host is reachable using the default port 22, while
-the `my-host2` host requires a different port on 2222. Both hosts are in the hostgroup `my-linux-servers`.
-
- object HostGroup "my-linux-servers" {
- display_name = "Linux Servers"
- assign where host.vars.os == "Linux"
- }
-
- /* this one has port 22 opened */
- object Host "my-host1" {
- import "generic-host"
- address = "129.168.1.50"
- vars.os = "Linux"
- }
-
- /* this one listens on a different ssh port */
- object Host "my-host2" {
- import "generic-host"
- address = "129.168.2.50"
- vars.os = "Linux"
- vars.custom_ssh_port = 2222
- }
-
-All hosts in the `my-linux-servers` hostgroup should get the `my-ssh` service applied based on an
-[apply rule](15-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
-(`-1` is smaller than the other defaults).
-
- object CheckCommand "my-ssh" {
- import "plugin-check-command"
-
- command = [ PluginDir + "/check_ssh" ]
-
- arguments = {
- "-p" = "$ssh_port$"
- "host" = {
- value = "$ssh_address$"
- skip_key = true
- order = -1
- }
- }
-
- vars.ssh_address = "$address$"
- }
-
- /* apply ssh service */
- apply Service "my-ssh" {
- import "generic-service"
- check_command = "my-ssh"
-
- //set the command argument for ssh port with a custom host attribute, if set
- vars.ssh_port = "$host.vars.custom_ssh_port$"
-
- assign where "my-linux-servers" in host.groups
- }
-
-The `my-host1` will get the `my-ssh` service checking on the default port:
-
- [2014-05-26 21:52:23 +0200] notice/Process: Running command '/usr/lib/nagios/plugins/check_ssh', '129.168.1.50': PID 27281
-
-The `my-host2` will inherit the `custom_ssh_port` variable to the service and execute a different command:
-
- [2014-05-26 21:51:32 +0200] notice/Process: Running command '/usr/lib/nagios/plugins/check_ssh', '-p', '2222', '129.168.2.50': PID 26956
+[CheckCommand object definition](6-object-types.md#objecttype-checkcommand).
### <a id="notification-commands"></a> Notification Commands
-[NotificationCommand](5-object-types.md#objecttype-notificationcommand) objects define how notifications are delivered to external
+[NotificationCommand](6-object-types.md#objecttype-notificationcommand) objects define how notifications are delivered to external
interfaces (E-Mail, XMPP, IRC, Twitter, etc).
-[NotificationCommand](5-object-types.md#objecttype-notificationcommand) objects are referenced by
-[Notification](5-object-types.md#objecttype-notification) objects using the `command` attribute.
+[NotificationCommand](6-object-types.md#objecttype-notificationcommand) objects are referenced by
+[Notification](6-object-types.md#objecttype-notification) objects using the `command` attribute.
-`NotificationCommand` objects require the [ITL template](6-icinga-template-library.md#itl-plugin-notification-command)
+`NotificationCommand` objects require the [ITL template](7-icinga-template-library.md#itl-plugin-notification-command)
`plugin-notification-command` to support native plugin-based notifications.
> **Note**
>
-> Make sure that the [notification](7-cli-commands.md#features) feature is enabled on your master instance
+> Make sure that the [notification](8-cli-commands.md#features) feature is enabled
> 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](5-object-types.md#objecttype-eventcommand) objects are referenced by
-[Host](5-object-types.md#objecttype-host) and [Service](5-object-types.md#objecttype-service) objects
+[EventCommand](6-object-types.md#objecttype-eventcommand) objects are referenced by
+[Host](6-object-types.md#objecttype-host) and [Service](6-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](5-object-types.md#objecttype-eventcommand) object `event_by_ssh`
+Define a generic [EventCommand](6-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 */
Apache2 is running (pid 24908).
-
-
## <a id="dependencies"></a> Dependencies
-Icinga 2 uses host and service [Dependency](5-object-types.md#objecttype-dependency) objects
+Icinga 2 uses host and service [Dependency](6-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](17-appendix.md#schema-db-ido-extensions).
+in for example [DB IDO](18-appendix.md#schema-db-ido-extensions).
### <a id="dependencies-implicit-host-service"></a> Implicit Dependencies for Services on Host
but not the `nrpe-health` service itself.
-## <a id="downtimes"></a> Downtimes
-
-Downtimes can be scheduled for planned server maintenance or
-any other targetted service outage you are aware of in advance.
-
-Downtimes will suppress any notifications, and may trigger other
-downtimes too. If the downtime was set by accident, or the duration
-exceeds the maintenance, you can manually cancel the downtime.
-Planned downtimes will also be taken into account for SLA reporting
-tools calculating the SLAs based on the state and downtime history.
-
-Multiple downtimes for a single object may overlap. This is useful
-when you want to extend your maintenance window taking longer than expected.
-If there are multiple downtimes triggered for one object, the overall downtime depth
-will be greater than `1`.
-
-
-If the downtime was scheduled after the problem changed to a critical hard
-state triggering a problem notification, and the service recovers during
-the downtime window, the recovery notification won't be suppressed.
-
-### <a id="fixed-flexible-downtimes"></a> Fixed and Flexible Downtimes
-
-A `fixed` downtime will be activated at the defined start time, and
-removed at the end time. During this time window the service state
-will change to `NOT-OK` and then actually trigger the downtime.
-Notifications are suppressed and the downtime depth is incremented.
-
-Common scenarios are a planned distribution upgrade on your linux
-servers, or database updates in your warehouse. The customer knows
-about a fixed downtime window between 23:00 and 24:00. After 24:00
-all problems should be alerted again. Solution is simple -
-schedule a `fixed` downtime starting at 23:00 and ending at 24:00.
-
-Unlike a `fixed` downtime, a `flexible` downtime will be triggered
-by the state change in the time span defined by start and end time,
-and then last for the specified duration in minutes.
-
-Imagine the following scenario: Your service is frequently polled
-by users trying to grab free deleted domains for immediate registration.
-Between 07:30 and 08:00 the impact will hit for 15 minutes and generate
-a network outage visible to the monitoring. The service is still alive,
-but answering too slow to Icinga 2 service checks.
-For that reason, you may want to schedule a downtime between 07:30 and
-08:00 with a duration of 15 minutes. The downtime will then last from
-its trigger time until the duration is over. After that, the downtime
-is removed (may happen before or after the actual end time!).
-
-### <a id="scheduling-downtime"></a> Scheduling a downtime
-
-This can either happen through a web interface or by sending an [external command](3-monitoring-basics.md#external-commands)
-to the external command pipe provided by the `ExternalCommandListener` configuration.
-
-Fixed downtimes require a start and end time (a duration will be ignored).
-Flexible downtimes need a start and end time for the time span, and a duration
-independent from that time span.
-
-### <a id="triggered-downtimes"></a> Triggered Downtimes
-
-This is optional when scheduling a downtime. If there is already a downtime
-scheduled for a future maintenance, the current downtime can be triggered by
-that downtime. This renders useful if you have scheduled a host downtime and
-are now scheduling a child host's downtime getting triggered by the parent
-downtime on NOT-OK state change.
-
-### <a id="recurring-downtimes"></a> Recurring Downtimes
-
-[ScheduledDowntime objects](5-object-types.md#objecttype-scheduleddowntime) can be used to set up
-recurring downtimes for services.
-
-Example:
-
- apply ScheduledDowntime "backup-downtime" to Service {
- author = "icingaadmin"
- comment = "Scheduled downtime for backup"
-
- ranges = {
- monday = "02:00-03:00"
- tuesday = "02:00-03:00"
- wednesday = "02:00-03:00"
- thursday = "02:00-03:00"
- friday = "02:00-03:00"
- saturday = "02:00-03:00"
- sunday = "02:00-03:00"
- }
-
- assign where "backup" in service.groups
- }
-
-
-## <a id="comments-intro"></a> Comments
-
-Comments can be added at runtime and are persistent over restarts. You can
-add useful information for others on repeating incidents (for example
-"last time syslog at 100% cpu on 17.10.2013 due to stale nfs mount") which
-is primarly accessible using web interfaces.
-
-Adding and deleting comment actions are possible through the external command pipe
-provided with the `ExternalCommandListener` configuration. The caller must
-pass the comment id in case of manipulating an existing comment.
-
-
-## <a id="acknowledgements"></a> Acknowledgements
-
-If a problem is alerted and notified you may signal the other notification
-recipients that you are aware of the problem and will handle it.
-
-By sending an acknowledgement to Icinga 2 (using the external command pipe
-provided with `ExternalCommandListener` configuration) all future notifications
-are suppressed, a new comment is added with the provided description and
-a notification with the type `NotificationFilterAcknowledgement` is sent
-to all notified users.
-
-### <a id="expiring-acknowledgements"></a> Expiring Acknowledgements
-
-Once a problem is acknowledged it may disappear from your `handled problems`
-dashboard and no-one ever looks at it again since it will suppress
-notifications too.
-
-This `fire-and-forget` action is quite common. If you're sure that a
-current problem should be resolved in the future at a defined time,
-you can define an expiration time when acknowledging the problem.
-
-Icinga 2 will clear the acknowledgement when expired and start to
-re-notify if the problem persists.
-
-
## <a id="custom-attributes"></a> Custom Attributes
There are several ways of using custom attributes with [apply rules](3-monitoring-basics.md#using-apply):
-* As simple attribute literal ([number](15-language-reference.md#numeric-literals), [string](15-language-reference.md#string-literals),
-[boolean](15-language-reference.md#boolean-literals)) for expression conditions (`assign where`, `ignore where`)
-* As [array](15-language-reference.md#array) or [dictionary](15-language-reference.md#dictionary) attribute with nested values
+* As simple attribute literal ([number](16-language-reference.md#numeric-literals), [string](16-language-reference.md#string-literals),
+[boolean](16-language-reference.md#boolean-literals)) for expression conditions (`assign where`, `ignore where`)
+* As [array](16-language-reference.md#array) or [dictionary](16-language-reference.md#dictionary) attribute with nested values
(e.g. dictionaries in dictionaries) in [apply for](3-monitoring-basics.md#using-apply-for) rules.
-* As a [function object](#functions)
+* As a [function object](16-language-reference.md#functions)
-Features like [DB IDO](3-monitoring-basics.md#db-ido), Livestatus(#setting-up-livestatus) or StatusData(#status-data)
+Features like [DB IDO](4-advanced-topics.md#db-ido), [Livestatus](12-livestatus.md#setting-up-livestatus) or [StatusData](4-advanced-topics.md#status-data)
dump this column as encoded JSON string, and set `is_json` resp. `cv_is_json` to `1`.
If arrays are used in runtime macros (for example `$host.groups$`) all entries
Custom attributes may be used in command definitions to dynamically change how the command
is executed.
-Additionally there are Icinga 2 features such as the [PerfDataWriter](3-monitoring-basics.md#performance-data) feature
+Additionally there are Icinga 2 features such as the [PerfDataWriter](4-advanced-topics.md#performance-data) feature
which use custom runtime attributes to format their output.
> **Tip**
>
> Custom attributes are identified by the `vars` dictionary attribute as short name.
-> Accessing the different attribute keys is possible using the [index accessor](15-language-reference.md#indexer) `.`.
+> Accessing the different attribute keys is possible using the [index accessor](16-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](6-icinga-template-library.md#plugin-check-command-disk)
-* [check_nrpe -a](6-icinga-template-library.md#plugin-check-command-nrpe)
-* [check_nscp -l](6-icinga-template-library.md#plugin-check-command-nscp)
-* [check_dns -a](6-icinga-template-library.md#plugin-check-command-dns)
+* [check_disk -p](7-icinga-template-library.md#plugin-check-command-disk)
+* [check_nrpe -a](7-icinga-template-library.md#plugin-check-command-nrpe)
+* [check_nscp -l](7-icinga-template-library.md#plugin-check-command-nscp)
+* [check_dns -a](7-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](5-object-types.md#objecttype-checkcommand-arguments).
+found in [this section](6-object-types.md#objecttype-checkcommand-arguments).
> **Note**
>
icinga.num_hosts_acknowledged | Current number of acknowledged host problems.
-## <a id="check-result-freshness"></a> Check Result Freshness
-
-In Icinga 2 active check freshness is enabled by default. It is determined by the
-`check_interval` attribute and no incoming check results in that period of time.
-
- threshold = last check execution time + check interval
-
-Passive check freshness is calculated from the `check_interval` attribute if set.
-
- threshold = last check result time + check interval
-
-If the freshness checks are invalid, a new check is executed defined by the
-`check_command` attribute.
-
-
-## <a id="check-flapping"></a> Check Flapping
-
-The flapping algorithm used in Icinga 2 does not store the past states but
-calculcates the flapping threshold from a single value based on counters and
-half-life values. Icinga 2 compares the value with a single flapping threshold
-configuration attribute named `flapping_threshold`.
-
-Flapping detection can be enabled or disabled using the `enable_flapping` attribute.
-
-## <a id="volatile-services"></a> Volatile Services
-
-By default all services remain in a non-volatile state. When a problem
-occurs, the `SOFT` state applies and once `max_check_attempts` attribute
-is reached with the check counter, a `HARD` state transition happens.
-Notifications are only triggered by `HARD` state changes and are then
-re-sent defined by the `interval` attribute.
-
-It may be reasonable to have a volatile service which stays in a `HARD`
-state type if the service stays in a `NOT-OK` state. That way each
-service recheck will automatically trigger a notification unless the
-service is acknowledged or in a scheduled downtime.
-
-
-## <a id="external-commands"></a> External Commands
-
-Icinga 2 provides an external command pipe for processing commands
-triggering specific actions (for example rescheduling a service check
-through the web interface).
-
-In order to enable the `ExternalCommandListener` configuration use the
-following command and restart Icinga 2 afterwards:
-
- # icinga2 feature enable command
-
-Icinga 2 creates the command pipe file as `/var/run/icinga2/cmd/icinga2.cmd`
-using the default configuration.
-
-Web interfaces and other Icinga addons are able to send commands to
-Icinga 2 through the external command pipe, for example for rescheduling
-a forced service check:
-
- # /bin/echo "[`date +%s`] SCHEDULE_FORCED_SVC_CHECK;localhost;ping4;`date +%s`" >> /var/run/icinga2/cmd/icinga2.cmd
-
- # tail -f /var/log/messages
-
- Oct 17 15:01:25 icinga-server icinga2: Executing external command: [1382014885] SCHEDULE_FORCED_SVC_CHECK;localhost;ping4;1382014885
- Oct 17 15:01:25 icinga-server icinga2: Rescheduling next check for service 'ping4'
-
-
-### <a id="external-command-list"></a> External Command List
-
-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).
-
-## <a id="logging"></a> Logging
-
-Icinga 2 supports three different types of logging:
-
-* File logging
-* Syslog (on *NIX-based operating systems)
-* Console logging (`STDOUT` on tty)
-
-You can enable additional loggers using the `icinga2 feature enable`
-and `icinga2 feature disable` commands to configure loggers:
-
-Feature | Description
----------|------------
-debuglog | Debug log (path: `/var/log/icinga2/debug.log`, severity: `debug` or higher)
-mainlog | Main log (path: `/var/log/icinga2/icinga2.log`, severity: `information` or higher)
-syslog | Syslog (severity: `warning` or higher)
-
-By default file the `mainlog` feature is enabled. When running Icinga 2
-on a terminal log messages with severity `information` or higher are
-written to the console.
-
-
-## <a id="performance-data"></a> Performance Data
-
-When a host or service check is executed plugins should provide so-called
-`performance data`. Next to that additional check performance data
-can be fetched using Icinga 2 runtime macros such as the check latency
-or the current service state (or additional custom attributes).
-
-The performance data can be passed to external applications which aggregate and
-store them in their backends. These tools usually generate graphs for historical
-reporting and trending.
-
-Well-known addons processing Icinga performance data are PNP4Nagios,
-inGraph and Graphite.
-
-### <a id="writing-performance-data-files"></a> Writing Performance Data Files
-
-PNP4Nagios, inGraph and Graphios use performance data collector daemons to fetch
-the current performance files for their backend updates.
-
-Therefore the Icinga 2 `PerfdataWriter` object allows you to define
-the output template format for host and services backed with Icinga 2
-runtime vars.
-
- host_format_template = "DATATYPE::HOSTPERFDATA\tTIMET::$icinga.timet$\tHOSTNAME::$host.name$\tHOSTPERFDATA::$host.perfdata$\tHOSTCHECKCOMMAND::$host.checkcommand$\tHOSTSTATE::$host.state$\tHOSTSTATETYPE::$host.statetype$"
- service_format_template = "DATATYPE::SERVICEPERFDATA\tTIMET::$icinga.timet$\tHOSTNAME::$host.name$\tSERVICEDESC::$service.name$\tSERVICEPERFDATA::$service.perfdata$\tSERVICECHECKCOMMAND::$service.checkcommand$\tHOSTSTATE::$host.state$\tHOSTSTATETYPE::$host.statetype$\tSERVICESTATE::$service.state$\tSERVICESTATETYPE::$service.statetype$"
-
-The default templates are already provided with the Icinga 2 feature configuration
-which can be enabled using
-
- # icinga2 feature enable perfdata
-
-By default all performance data files are rotated in a 15 seconds interval into
-the `/var/spool/icinga2/perfdata/` directory as `host-perfdata.<timestamp>` and
-`service-perfdata.<timestamp>`.
-External collectors need to parse the rotated performance data files and then
-remove the processed files.
-
-### <a id="graphite-carbon-cache-writer"></a> Graphite Carbon Cache Writer
-
-While there are some Graphite collector scripts and daemons like Graphios available for
-Icinga 1.x it's more reasonable to directly process the check and plugin performance
-in memory in Icinga 2. Once there are new metrics available, Icinga 2 will directly
-write them to the defined Graphite Carbon daemon tcp socket.
-
-You can enable the feature using
-
- # icinga2 feature enable graphite
-
-By default the `GraphiteWriter` object expects the Graphite Carbon Cache to listen at
-`127.0.0.1` on TCP port `2003`.
-
-The current naming schema is
-
- icinga.<hostname>.<metricname>
- icinga.<hostname>.<servicename>.<metricname>
-
-You can customize the metric prefix name by using the `host_name_template` and
-`service_name_template` configuration attributes.
-
-The example below uses [runtime macros](3-monitoring-basics.md#runtime-macros) and a
-[global constant](15-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"
-
- object GraphiteWriter "graphite" {
- host_name_template = GraphiteEnv + ".$host.name$"
- service_name_template = GraphiteEnv + ".$host.name$.$service.name$"
- }
-
-To make sure Icinga 2 writes a valid label into Graphite some characters are replaced
-with `_` in the target name:
-
- \/.- (and space)
-
-The resulting name in Graphite might look like:
-
- www-01 / http-cert / response time
- icinga.www_01.http_cert.response_time
-
-In addition to the performance data retrieved from the check plugin, Icinga 2 sends
-internal check statistic data to Graphite:
-
- metric | description
- -------------------|------------------------------------------
- current_attempt | current check attempt
- max_check_attempts | maximum check attempts until the hard state is reached
- reachable | checked object is reachable
- downtime_depth | number of downtimes this object is in
- execution_time | check execution time
- latency | check latency
- state | current state of the checked object
- state_type | 0=SOFT, 1=HARD state
-
-The following example illustrates how to configure the storage-schemas for Graphite Carbon
-Cache. Please make sure that the order is correct because the first match wins.
-
- [icinga_internals]
- pattern = ^icinga\..*\.(max_check_attempts|reachable|current_attempt|execution_time|latency|state|state_type)
- retentions = 5m:7d
-
- [icinga_default]
- # intervals like PNP4Nagios uses them per default
- pattern = ^icinga\.
- retentions = 1m:2d,5m:10d,30m:90d,360m:4y
-
-### <a id="gelfwriter"></a> GELF Writer
-
-The `Graylog Extended Log Format` (short: [GELF](http://www.graylog2.org/resources/gelf))
-can be used to send application logs directly to a TCP socket.
-
-While it has been specified by the [graylog2](http://www.graylog2.org/) project as their
-[input resource standard](http://www.graylog2.org/resources/gelf), other tools such as
-[Logstash](http://www.logstash.net) also support `GELF` as
-[input type](http://logstash.net/docs/latest/inputs/gelf).
-
-You can enable the feature using
-
- # icinga2 feature enable gelf
-
-By default the `GelfWriter` object expects the GELF receiver to listen at `127.0.0.1` on TCP port `12201`.
-The default `source` attribute is set to `icinga2`. You can customize that for your needs if required.
-
-Currently these events are processed:
-* Check results
-* State changes
-* Notifications
-
-### <a id="opentsdb-writer"></a> OpenTSDB Writer
-
-While there are some OpenTSDB collector scripts and daemons like tcollector available for
-Icinga 1.x it's more reasonable to directly process the check and plugin performance
-in memory in Icinga 2. Once there are new metrics available, Icinga 2 will directly
-write them to the defined TSDB TCP socket.
-
-You can enable the feature using
-
- # icinga2 feature enable opentsdb
-
-By default the `OpenTsdbWriter` object expects the TSD to listen at
-`127.0.0.1` on port `4242`.
-
-The current naming schema is
-
- icinga.host.<metricname>
- icinga.service.<servicename>.<metricname>
-
-for host and service checks. The tag host is always applied.
-
-To make sure Icinga 2 writes a valid metric into OpenTSDB some characters are replaced
-with `_` in the target name:
-
- \ (and space)
-
-The resulting name in OpenTSDB might look like:
-
- www-01 / http-cert / response time
- icinga.http_cert.response_time
-
-In addition to the performance data retrieved from the check plugin, Icinga 2 sends
-internal check statistic data to OpenTSDB:
-
- metric | description
- -------------------|------------------------------------------
- current_attempt | current check attempt
- max_check_attempts | maximum check attempts until the hard state is reached
- reachable | checked object is reachable
- downtime_depth | number of downtimes this object is in
- execution_time | check execution time
- latency | check latency
- state | current state of the checked object
- state_type | 0=SOFT, 1=HARD state
-
-While reachable, state and state_type are metrics for the host or service the
-other metrics follow the current naming schema
-
- icinga.check.<metricname>
-
-with the following tags
-
- tag | description
- --------|------------------------------------------
- type | the check type, one of [host, service]
- host | hostname, the check ran on
- service | the service name (if type=service)
-
-> **Note**
->
-> You might want to set the tsd.core.auto_create_metrics setting to `true`
-> in your opentsdb.conf configuration file.
-
-
-## <a id="status-data"></a> Status Data
-
-Icinga 1.x writes object configuration data and status data in a cyclic
-interval to its `objects.cache` and `status.dat` files. Icinga 2 provides
-the `StatusDataWriter` object which dumps all configuration objects and
-status updates in a regular interval.
-
- # icinga2 feature enable statusdata
-
-Icinga 1.x Classic UI requires this data set as part of its backend.
-
-> **Note**
->
-> If you are not using any web interface or addon which uses these files
-> you can safely disable this feature.
-
-
-## <a id="compat-logging"></a> Compat Logging
-
-The Icinga 1.x log format is considered being the `Compat Log`
-in Icinga 2 provided with the `CompatLogger` object.
-
-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](11-livestatus.md#setting-up-livestatus) feature uses these logs for answering queries to
-historical tables.
-
-The `CompatLogger` object can be enabled with
-
- # icinga2 feature enable compatlog
-
-By default, the Icinga 1.x log file called `icinga.log` is located
-in `/var/log/icinga2/compat`. Rotated log files are moved into
-`var/log/icinga2/compat/archives`.
-
-The format cannot be changed without breaking compatibility to
-existing log parsers.
-
- # tail -f /var/log/icinga2/compat/icinga.log
-
- [1382115688] LOG ROTATION: HOURLY
- [1382115688] LOG VERSION: 2.0
- [1382115688] HOST STATE: CURRENT;localhost;UP;HARD;1;
- [1382115688] SERVICE STATE: CURRENT;localhost;disk;WARNING;HARD;1;
- [1382115688] SERVICE STATE: CURRENT;localhost;http;OK;HARD;1;
- [1382115688] SERVICE STATE: CURRENT;localhost;load;OK;HARD;1;
- [1382115688] SERVICE STATE: CURRENT;localhost;ping4;OK;HARD;1;
- [1382115688] SERVICE STATE: CURRENT;localhost;ping6;OK;HARD;1;
- [1382115688] SERVICE STATE: CURRENT;localhost;processes;WARNING;HARD;1;
- [1382115688] SERVICE STATE: CURRENT;localhost;ssh;OK;HARD;1;
- [1382115688] SERVICE STATE: CURRENT;localhost;users;OK;HARD;1;
- [1382115706] EXTERNAL COMMAND: SCHEDULE_FORCED_SVC_CHECK;localhost;disk;1382115705
- [1382115706] EXTERNAL COMMAND: SCHEDULE_FORCED_SVC_CHECK;localhost;http;1382115705
- [1382115706] EXTERNAL COMMAND: SCHEDULE_FORCED_SVC_CHECK;localhost;load;1382115705
- [1382115706] EXTERNAL COMMAND: SCHEDULE_FORCED_SVC_CHECK;localhost;ping4;1382115705
- [1382115706] EXTERNAL COMMAND: SCHEDULE_FORCED_SVC_CHECK;localhost;ping6;1382115705
- [1382115706] EXTERNAL COMMAND: SCHEDULE_FORCED_SVC_CHECK;localhost;processes;1382115705
- [1382115706] EXTERNAL COMMAND: SCHEDULE_FORCED_SVC_CHECK;localhost;ssh;1382115705
- [1382115706] EXTERNAL COMMAND: SCHEDULE_FORCED_SVC_CHECK;localhost;users;1382115705
- [1382115731] EXTERNAL COMMAND: PROCESS_SERVICE_CHECK_RESULT;localhost;ping6;2;critical test|
- [1382115731] SERVICE ALERT: localhost;ping6;CRITICAL;SOFT;2;critical test
-
-
-
-
-## <a id="db-ido"></a> DB IDO
-
-The IDO (Icinga Data Output) modules for Icinga 2 take care of exporting all
-configuration and status information into a database. The IDO database is used
-by a number of projects including Icinga Web 1.x and 2.
-
-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](5-object-types.md#objecttype-idomysqlconnection) and
-[IdoPgsqlConnection](5-object-types.md#objecttype-idopgsqlconnection)
-object configuration documentation.
-The DB IDO feature supports [High Availability](8-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
-writing its current status to the DB IDO backend table `icinga_programstatus`
-every 10 seconds. By default it checks 60 seconds into the past which is a reasonable
-amount of time - adjust it for your requirements. If the condition is not met,
-the query returns an empty result.
-
-> **Tip**
->
-> Use [check plugins](9-addons-plugins.md#plugins) to monitor the backend.
-
-Replace the `default` string with your instance name, if different.
-
-Example for MySQL:
-
- # mysql -u root -p icinga -e "SELECT status_update_time FROM icinga_programstatus ps
- JOIN icinga_instances i ON ps.instance_id=i.instance_id
- WHERE (UNIX_TIMESTAMP(ps.status_update_time) > UNIX_TIMESTAMP(NOW())-60)
- AND i.instance_name='default';"
-
- +---------------------+
- | status_update_time |
- +---------------------+
- | 2014-05-29 14:29:56 |
- +---------------------+
-
-
-Example for PostgreSQL:
-
- # export PGPASSWORD=icinga; psql -U icinga -d icinga -c "SELECT ps.status_update_time FROM icinga_programstatus AS ps
- JOIN icinga_instances AS i ON ps.instance_id=i.instance_id
- WHERE ((SELECT extract(epoch from status_update_time) FROM icinga_programstatus) > (SELECT extract(epoch from now())-60))
- AND i.instance_name='default'";
-
- status_update_time
- ------------------------
- 2014-05-29 15:11:38+02
- (1 Zeile)
-
-
-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
-
-Icinga 1.x writes its check result files to a temporary spool directory
-where they are processed in a regular interval.
-While this is extremely inefficient in performance regards it has been
-rendered useful for passing passive check results directly into Icinga 1.x
-skipping the external command pipe.
-
-Several clustered/distributed environments and check-aggregation addons
-use that method. In order to support step-by-step migration of these
-environments, Icinga 2 supports the `CheckResultReader` object.
-
-There is no feature configuration available, but it must be defined
-on-demand in your Icinga 2 objects configuration.
-
- object CheckResultReader "reader" {
- spool_dir = "/data/check-results"
- }
when installing the Icinga 2 packages.
If you're interested in a detailed explanation of each language feature used in those
-configuration files you can find more information in the [Language Reference](15-language-reference.md#language-reference)
+configuration files you can find more information in the [Language Reference](16-language-reference.md#language-reference)
chapter.
## <a id="icinga2-conf"></a> icinga2.conf
* to the documentation that is distributed as part of Icinga 2.
*/
-Icinga 2 supports [C/C++-style comments](15-language-reference.md#comments).
+Icinga 2 supports [C/C++-style comments](16-language-reference.md#comments).
/**
* The constants.conf defines global constants.
This `include` directive takes care of including the configuration files for all
the features which have been enabled with `icinga2 feature enable`. See
-[Enabling/Disabling Features](7-cli-commands.md#features) for more details.
+[Enabling/Disabling Features](8-cli-commands.md#features) for more details.
/**
* The repository.d directory contains all configuration objects
This `include_recursive` directive is used for discovery of services on remote clients
and their generated configuration described in
-[this chapter](8-monitoring-remote-systems.md#icinga2-remote-monitoring-master-discovery-generate-config).
+[this chapter](9-monitoring-remote-systems.md#icinga2-remote-monitoring-master-discovery-generate-config).
/**
*/
include_recursive "conf.d"
-You can put your own configuration files in the [conf.d](4-configuring-icinga-2.md#conf-d) directory. This
+You can put your own configuration files in the [conf.d](5-configuring-icinga-2.md#conf-d) directory. This
directive makes sure that all of your own configuration files are included.
## <a id="constants-conf"></a> constants.conf
* The `PluginDir` constant must be set to the path where the [Monitoring Project plugins](2-getting-started.md#setting-up-check-plugins) are installed.
This constant is used by a number of
-[built-in check command definitions](6-icinga-template-library.md#plugin-check-commands).
+[built-in check command definitions](7-icinga-template-library.md#plugin-check-commands).
* The `NodeName` constant defines your local node name. Should be set to FQDN which is the default
if not set. This constant is required for local host configuration, monitoring remote clients and
cluster setup.
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](4-configuring-icinga-2.md#icinga2-conf) configuration file by default.
+[icinga2.conf](5-configuring-icinga-2.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](4-configuring-icinga-2.md#icinga2-conf) file.
+[icinga2.conf](5-configuring-icinga-2.md#icinga2-conf) file.
You are certainly not bound to it. Remove it, 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](3-monitoring-basics.md#configuration-best-practice).
+own strategy is described in [this chapter](#configuration-best-practice).
Available configuration files which are installed by default:
-* [hosts.conf](4-configuring-icinga-2.md#hosts-conf)
-* [services.conf](4-configuring-icinga-2.md#services-conf)
-* [users.conf](4-configuring-icinga-2.md#users-conf)
-* [notifications.conf](4-configuring-icinga-2.md#notifications-conf)
-* [commands.conf](4-configuring-icinga-2.md#commands-conf)
-* [groups.conf](4-configuring-icinga-2.md#groups-conf)
-* [templates.conf](4-configuring-icinga-2.md#templates-conf)
-* [downtimes.conf](4-configuring-icinga-2.md#downtimes-conf)
-* [timeperiods.conf](4-configuring-icinga-2.md#timeperiods-conf)
-* [satellite.conf](4-configuring-icinga-2.md#satellite-conf)
+* [hosts.conf](5-configuring-icinga-2.md#hosts-conf)
+* [services.conf](5-configuring-icinga-2.md#services-conf)
+* [users.conf](5-configuring-icinga-2.md#users-conf)
+* [notifications.conf](5-configuring-icinga-2.md#notifications-conf)
+* [commands.conf](5-configuring-icinga-2.md#commands-conf)
+* [groups.conf](5-configuring-icinga-2.md#groups-conf)
+* [templates.conf](5-configuring-icinga-2.md#templates-conf)
+* [downtimes.conf](5-configuring-icinga-2.md#downtimes-conf)
+* [timeperiods.conf](5-configuring-icinga-2.md#timeperiods-conf)
+* [satellite.conf](5-configuring-icinga-2.md#satellite-conf)
### <a id="hosts-conf"></a> hosts.conf
The `hosts.conf` file contains an example host based on your
-`NodeName` setting in [constants.conf](4-configuring-icinga-2.md#constants-conf). You
+`NodeName` setting in [constants.conf](5-configuring-icinga-2.md#constants-conf). You
can use global constants for your object names instead of string
values.
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
-for check and notification commands. Most of the [Plugin Check Commands](6-icinga-template-library.md#plugin-check-commands)
+for check and notification commands. Most of the [Plugin Check Commands](7-icinga-template-library.md#plugin-check-commands)
in the Icinga Template Library require an `address` attribute.
The custom attribute `os` is evaluated by the `linux-servers` group in
-[groups.conf](4-configuring-icinga-2.md#groups-conf) making the local host a member.
+[groups.conf](5-configuring-icinga-2.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](4-configuring-icinga-2.md#services-conf).
+in [services.conf](5-configuring-icinga-2.md#services-conf).
* define disks (all, specific `/`) and their attributes for the `disk`
-service apply rule defined in [services.conf](4-configuring-icinga-2.md#services-conf).
+service apply rule defined in [services.conf](5-configuring-icinga-2.md#services-conf).
* define notification types (`mail`) and set the groups attribute. This
will be used by notification apply rules in [notifications.conf](notifications-conf).
If you've installed [Icinga Web 2](2-getting-started.md#setting-up-icingaweb2) you can
uncomment the http vhost attributes and relaod Icinga 2. The apply
-rules in [services.conf](4-configuring-icinga-2.md#services-conf) will automatically
+rules in [services.conf](5-configuring-icinga-2.md#services-conf) will automatically
generate a new service checking the `/icingaweb2` URI using the `http`
check.
}
This is only the host object definition. Now we'll need to make sure that this
-host and your additional hosts are getting [services](4-configuring-icinga-2.md#services-conf) applied.
+host and your additional hosts are getting [services](5-configuring-icinga-2.md#services-conf) applied.
> **Tip**
>
-> If you don't understand all the attributes and how to use [apply rules](15-language-reference.md#apply)
+> If you don't understand all the attributes and how to use [apply rules](16-language-reference.md#apply)
> don't worry - the [monitoring basics](3-monitoring-basics.md#monitoring-basics) chapter will explain
> that in detail.
### <a id="services-conf"></a> services.conf
-These service [apply rules](15-language-reference.md#apply) will show you how to monitor
+These service [apply rules](16-language-reference.md#apply) will show you how to monitor
the local host, but also allow you to re-use or modify them for
your own requirements.
The Debian packages also include an additional `apt` service check applied to the local host.
The command object `icinga` for the embedded health check is provided by the
-[Icinga Template Library (ITL)](6-icinga-template-library.md#icinga-template-library) while `http_ip`, `ssh`, `load`, `processes`,
-`users` and `disk` are all provided by the [Plugin Check Commands](6-icinga-template-library.md#plugin-check-commands)
+[Icinga Template Library (ITL)](7-icinga-template-library.md#icinga-template-library) while `http_ip`, `ssh`, `load`, `processes`,
+`users` and `disk` are all provided by the [Plugin Check Commands](7-icinga-template-library.md#plugin-check-commands)
which we enabled earlier by including the `itl` and `plugins` configuration file.
The custom attribe `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](4-configuring-icinga-2.md#downtimes-conf).
+these services in [downtimes.conf](5-configuring-icinga-2.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"
-is created for each matching host. [Expression operators](15-language-reference.md#expression-operators)
+is created for each matching host. [Expression operators](16-language-reference.md#expression-operators)
may be used in `assign where` conditions.
Multiple `assign where` condition can be combined with `AND` using the `&&` operator
attribute defined `AND` having the custom attribute `os` set to the string
`Linux`.
You can modify this condition to match multiple expressions by combinding `AND`
-and `OR` using `&&` and `||` [operators](15-language-reference.md#expression-operators), for example
+and `OR` using `&&` and `||` [operators](16-language-reference.md#expression-operators), for example
`assign where host.address && (vars.os == "Linux" || vars.os == "Windows")`.
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](4-configuring-icinga-2.md#hosts-conf) defines the
+The idea is simple: Your host in [hosts.conf](5-configuring-icinga-2.md#hosts-conf) defines the
`disks` dictionary as custom attribute in `vars`.
-Remember the example from [hosts.conf](4-configuring-icinga-2.md#hosts-conf):
+Remember the example from [hosts.conf](5-configuring-icinga-2.md#hosts-conf):
...
* loop through all entries in the `host.vars.disks` dictionary. That's `disk` and `disk /` as keys.
* call `apply` on each, and set the service object name from the provided key
* inside apply, the `generic-service` template is imported
-* defining the [disk](6-icinga-template-library.md#plugin-check-command-disk) check command requiring command arguments like `disk_partition`
+* defining the [disk](7-icinga-template-library.md#plugin-check-command-disk) check command requiring command arguments like `disk_partition`
* adding the `config` dictionary items to `vars`. Simply said, there's now `vars.disk_partition` defined for the
generated service
host the information provider for all apply rules. Define them once, and only
manage your hosts.
-Look into [notifications.conf](4-configuring-icinga-2.md#notifications-conf) how this technique is used
+Look into [notifications.conf](5-configuring-icinga-2.md#notifications-conf) how this technique is used
for applying notifications to hosts and services using their type and user
attributes.
### <a id="users-conf"></a> users.conf
Defines the `icingaadmin` User and the `icingaadmins` UserGroup. The latter is used in
-[hosts.conf](4-configuring-icinga-2.md#hosts-conf) for defining a custom host attribute later used in
-[notifications.conf](4-configuring-icinga-2.md#notifications-conf) for notification apply rules.
+[hosts.conf](5-configuring-icinga-2.md#hosts-conf) for defining a custom host attribute later used in
+[notifications.conf](5-configuring-icinga-2.md#notifications-conf) for notification apply rules.
object User "icingaadmin" {
import "generic-user"
Please note that the `to` keyword is important in [notification apply rules](3-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](4-configuring-icinga-2.md#templates-conf).
+The `import` keyword imports the specific mail templates defined in [templates.conf](5-configuring-icinga-2.md#templates-conf).
-The `interval` attribute is not explicitly set - it [defaults to 30 minutes](5-object-types.md#objecttype-notification).
+The `interval` attribute is not explicitly set - it [defaults to 30 minutes](6-object-types.md#objecttype-notification).
By setting the `user_groups` to the value provided by the
-respective [host.vars.notification.mail](4-configuring-icinga-2.md#hosts-conf) attribute we'll
-implicitely use the`icingaadmins` UserGroup defined in [users.conf](4-configuring-icinga-2.md#users-conf).
+respective [host.vars.notification.mail](5-configuring-icinga-2.md#hosts-conf) attribute we'll
+implicitely use the`icingaadmins` UserGroup defined in [users.conf](5-configuring-icinga-2.md#users-conf).
apply Notification "mail-icingaadmin" to Host {
import "mail-host-notification"
### <a id="commands-conf"></a> commands.conf
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](4-configuring-icinga-2.md#templates-conf).
+only the notification commands used by the notification templates defined in [templates.conf](5-configuring-icinga-2.md#templates-conf).
You can freely customize these notification commands, and adapt them for your needs.
Read more on that topic [here](3-monitoring-basics.md#notification-commands).
custom attribute `os` set to `Linux` and is therefore automatically
a member of the host group `linux-servers`.
-This is done by using the [group assign](15-language-reference.md#group-assign) expressions similar
+This is done by using the [group assign](16-language-reference.md#group-assign) expressions similar
to previously seen [apply rules](3-monitoring-basics.md#using-apply).
object HostGroup "linux-servers" {
}
Service groups can be grouped together by similar pattern matches.
-The [match() function](15-language-reference.md#function-calls) expects a wildcard match string
+The [match() function](16-language-reference.md#function-calls) expects a wildcard match string
and the attribute string to match with.
object ServiceGroup "ping" {
}
The `hostalive` check command is part of the
-[Plugin Check Commands](6-icinga-template-library.md#plugin-check-commands).
+[Plugin Check Commands](7-icinga-template-library.md#plugin-check-commands).
template Notification "mail-host-notification" {
period = "24x7"
}
-More details on `Notification` object attributes can be found [here](5-object-types.md#objecttype-notification).
+More details on `Notification` object attributes can be found [here](6-object-types.md#objecttype-notification).
### <a id="downtimes-conf"></a> downtimes.conf
-The `load` service apply rule defined in [services.conf](4-configuring-icinga-2.md#services-conf) defines
+The `load` service apply rule defined in [services.conf](5-configuring-icinga-2.md#services-conf) defines
the `backup_downtime` custom attribute.
-The [ScheduledDowntime](5-object-types.md#objecttype-scheduleddowntime) apply rule uses this attribute
+The [ScheduledDowntime](6-object-types.md#objecttype-scheduleddowntime) apply rule uses this attribute
to define the default value for the time ranges required for recurring downtime slots.
apply ScheduledDowntime "backup-downtime" to Service {
### <a id="satellite-conf"></a> satellite.conf
-Includes default templates and dependencies for [monitoring remote clients](8-monitoring-remote-systems.md#icinga2-remote-client-monitoring)
-using service discovery and [config generation](8-monitoring-remote-systems.md#icinga2-remote-monitoring-master-discovery-generate-config)
+Includes default templates and dependencies for [monitoring remote clients](9-monitoring-remote-systems.md#icinga2-remote-client-monitoring)
+using service discovery and [config generation](9-monitoring-remote-systems.md#icinga2-remote-monitoring-master-discovery-generate-config)
on the master. Can be ignored/removed on setups not using this features.
> **Best Practice**
>
-> Assign host group members using the [group assign](15-language-reference.md#group-assign) rules.
+> Assign host group members using the [group assign](16-language-reference.md#group-assign) rules.
Example:
> **Best Practice**
>
-> Assign service group members using the [group assign](15-language-reference.md#group-assign) rules.
+> Assign service group members using the [group assign](16-language-reference.md#group-assign) rules.
Example:
> **Best Practice**
>
-> Assign user group members using the [group assign](15-language-reference.md#group-assign) rules.
+> Assign user group members using the [group assign](16-language-reference.md#group-assign) rules.
Example:
zone |**Optional.** The zone this object is a member of.
arguments |**Optional.** A dictionary of command arguments.
-Command arguments can be used the same way as for [CheckCommand objects](5-object-types.md#objecttype-checkcommand-arguments).
+Command arguments can be used the same way as for [CheckCommand objects](6-object-types.md#objecttype-checkcommand-arguments).
## <a id="objecttype-eventcommand"></a> EventCommand
timeout |**Optional.** The command timeout in seconds. Defaults to 60 seconds.
arguments |**Optional.** A dictionary of command arguments.
-Command arguments can be used the same way as for [CheckCommand objects](5-object-types.md#objecttype-checkcommand-arguments).
+Command arguments can be used the same way as for [CheckCommand objects](6-object-types.md#objecttype-checkcommand-arguments).
## <a id="objecttype-notification"></a> Notification
> to just create a `ScheduledDowntime` template and use the `apply` keyword to assign the
> scheduled downtime to a number of hosts or services. Use the `to` keyword to set the specific target
> type for `Host` or `Service`.
-> Check the [recurring downtimes](3-monitoring-basics.md#recurring-downtimes) example for details.
+> Check the [recurring downtimes](4-advanced-topics.md#recurring-downtimes) example for details.
Example:
Metric prefix names can be modified using [runtime macros](3-monitoring-basics.md#runtime-macros).
-Example with your custom [global constant](15-language-reference.md#constants) `GraphiteEnv`:
+Example with your custom [global constant](16-language-reference.md#constants) `GraphiteEnv`:
const GraphiteEnv = "icinga.env1"
table\_prefix |**Optional.** MySQL database table prefix. Defaults to "icinga\_".
instance\_name |**Optional.** Unique identifier for the local Icinga 2 instance. Defaults to "default".
instance\_description|**Optional.** Description for the Icinga 2 instance.
- enable_ha |**Optional.** Enable the high availability functionality. Only valid in a [cluster setup](8-monitoring-remote-systems.md#high-availability-db-ido). Defaults to "true".
- failover_timeout | **Optional.** Set the failover timeout in a [HA cluster](8-monitoring-remote-systems.md#high-availability-db-ido). Must not be lower than 60s. Defaults to "60s".
+ enable_ha |**Optional.** Enable the high availability functionality. Only valid in a [cluster setup](9-monitoring-remote-systems.md#high-availability-db-ido). Defaults to "true".
+ failover_timeout | **Optional.** Set the failover timeout in a [HA cluster](9-monitoring-remote-systems.md#high-availability-db-ido). Must not be lower than 60s. Defaults to "60s".
cleanup |**Optional.** Dictionary with items for historical table cleanup.
categories |**Optional.** The types of information that should be written to the database.
table\_prefix |**Optional.** PostgreSQL database table prefix. Defaults to "icinga\_".
instance\_name |**Optional.** Unique identifier for the local Icinga 2 instance. Defaults to "default".
instance\_description|**Optional.** Description for the Icinga 2 instance.
- enable_ha |**Optional.** Enable the high availability functionality. Only valid in a [cluster setup](8-monitoring-remote-systems.md#high-availability-db-ido). Defaults to "true".
- failover_timeout | **Optional.** Set the failover timeout in a [HA cluster](8-monitoring-remote-systems.md#high-availability-db-ido). Must not be lower than 60s. Defaults to "60s".
+ enable_ha |**Optional.** Enable the high availability functionality. Only valid in a [cluster setup](9-monitoring-remote-systems.md#high-availability-db-ido). Defaults to "true".
+ failover_timeout | **Optional.** Set the failover timeout in a [HA cluster](9-monitoring-remote-systems.md#high-availability-db-ido). Must not be lower than 60s. Defaults to "60s".
cleanup |**Optional.** Dictionary with items for historical table cleanup.
categories |**Optional.** The types of information that should be written to the database.
ApiListener objects are used for distributed monitoring setups
specifying the certificate files used for ssl authorization.
-The `NodeName` constant must be defined in [constants.conf](4-configuring-icinga-2.md#constants-conf).
+The `NodeName` constant must be defined in [constants.conf](5-configuring-icinga-2.md#constants-conf).
Example:
is set to the path where the Manubublon SNMP plugins are installed.
You can enable these plugin check commands by adding the following the include directive in your
-configuration [icinga2.conf](4-configuring-icinga-2.md#icinga2-conf) file:
+configuration [icinga2.conf](5-configuring-icinga-2.md#icinga2-conf) file:
include <manubulon>
#### Libraries
-Instead of loading libraries using the [`library` config directive](15-language-reference.md#library)
+Instead of loading libraries using the [`library` config directive](16-language-reference.md#library)
you can also use the `--library` command-line option.
#### Constants
-[Global constants](15-language-reference.md#constants) can be set using the `--define` command-line option.
+[Global constants](16-language-reference.md#constants) can be set using the `--define` command-line option.
#### <a id="config-include-path"></a> Config Include Path
### <a id="cli-command-daemon"></a> CLI command: Daemon
The CLI command `daemon` provides the functionality to start/stop Icinga 2.
-Furthermore it provides the [configuration validation](7-cli-commands.md#config-validation).
+Furthermore it provides the [configuration validation](8-cli-commands.md#config-validation).
# icinga2 daemon --help
icinga2 - The Icinga 2 network monitoring daemon (version: v2.1.1-299-gf695275)
The `--validate` option can be used to check if your configuration files
contain errors. If any errors are found the exit status is 1, otherwise 0
-is returned. More details in the [configuration validation](7-cli-commands.md#config-validation) chapter.
+is returned. More details in the [configuration validation](8-cli-commands.md#config-validation) chapter.
### <a id="cli-command-feature"></a> CLI command: Feature
### <a id="cli-command-node"></a> CLI command: Node
Provides the functionality to install and manage master and client
-nodes in a [remote monitoring ](8-monitoring-remote-systems.md#icinga2-remote-client-monitoring) or
-[distributed cluster](8-monitoring-remote-systems.md#distributed-monitoring-high-availability) scenario.
+nodes in a [remote monitoring ](9-monitoring-remote-systems.md#icinga2-remote-client-monitoring) or
+[distributed cluster](9-monitoring-remote-systems.md#distributed-monitoring-high-availability) scenario.
# icinga2 node --help
The `object` CLI command can be used to list all configuration objects and their
attributes. The command also shows where each of the attributes was modified.
-That way you can also identify which objects have been created from your [apply rules](15-language-reference.md#apply).
+That way you can also identify which objects have been created from your [apply rules](16-language-reference.md#apply).
-More information can be found in the [troubleshooting](12-troubleshooting.md#list-configuration-objects) section.
+More information can be found in the [troubleshooting](13-troubleshooting.md#list-configuration-objects) section.
# icinga2 object --help
icinga2 - The Icinga 2 network monitoring daemon (version: v2.1.1-299-gf695275)
* request a signed certificate from the master
* generate a new ticket for the client setup
-This functionality is used by the [node setup/wizard](7-cli-commands.md#cli-command-pki) CLI commands too.
+This functionality is used by the [node setup/wizard](8-cli-commands.md#cli-command-pki) CLI commands too.
# icinga2 pki --help
icinga2 - The Icinga 2 network monitoring daemon (version: v2.1.1-299-gf695275)
### <a id="cli-command-variable"></a> CLI command: Variable
-Lists all configured variables (constants) in a similar fasion like [object list](7-cli-commands.md#cli-command-object).
+Lists all configured variables (constants) in a similar fasion like [object list](8-cli-commands.md#cli-command-object).
# icinga2 variable --help
icinga2 - The Icinga 2 network monitoring daemon (version: v2.1.1-299-gf695275)
Icinga 2 provides configuration files for some commonly used features. These
are installed in the `/etc/icinga2/features-available` directory and can be
enabled and disabled using the `icinga2 feature enable` and `icinga2 feature disable`
-[CLI commands](7-cli-commands.md#cli-command-feature), respectively.
+[CLI commands](8-cli-commands.md#cli-command-feature), respectively.
The `icinga2 feature enable` CLI command creates symlinks in the
`/etc/icinga2/features-enabled` directory which is included by default
> `# icinga2 daemon -C`
If you encouter errors during configuration validation, please make sure
-to read the [troubleshooting](12-troubleshooting.md#troubleshooting) chapter.
+to read the [troubleshooting](13-troubleshooting.md#troubleshooting) chapter.
-You can also use the [CLI command](7-cli-commands.md#cli-command-object) `icinga2 object list`
+You can also use the [CLI command](8-cli-commands.md#cli-command-object) `icinga2 object list`
after validation passes to analyze object attributes, inheritance or created
objects by apply rules.
-Find more on troubleshooting with `object list` in [this chapter](12-troubleshooting.md#list-configuration-objects).
+Find more on troubleshooting with `object list` in [this chapter](13-troubleshooting.md#list-configuration-objects).
Example filtered by `Service` objects with the name `ping*`:
## <a id="config-change-reload"></a> Reload on Configuration Changes
Everytime you have changed your configuration you should first tell Icinga 2
-to [validate](7-cli-commands.md#config-validation). If there are no validation errors you can
+to [validate](8-cli-commands.md#config-validation). If there are no validation errors you can
safely reload the Icinga 2 daemon.
# /etc/init.d/icinga2 reload
> which will validate the configuration in a separate process and not stop
> the other events like check execution, notifications, etc.
>
-> Details can be found [here](14-migrating-from-icinga-1x.md#differences-1x-2-real-reload).
+> Details can be found [here](15-migrating-from-icinga-1x.md#differences-1x-2-real-reload).
# <a id="monitoring-remote-systems"></a> Monitoring Remote Systems
-There are multiple ways you can monitor remote clients. Be it using [agent-less](8-monitoring-remote-systems.md#agent-less-checks)
+There are multiple ways you can monitor remote clients. Be it using [agent-less](9-monitoring-remote-systems.md#agent-less-checks)
or [agent-based](agent-based-checks-addons) using additional addons & tools.
Icinga 2 uses its own unique and secure communitication protol amongst instances.
Be it an High-Availability cluster setup, distributed load-balanced setup or just a single
-agent [monitoring a remote client](8-monitoring-remote-systems.md#icinga2-remote-client-monitoring).
+agent [monitoring a remote client](9-monitoring-remote-systems.md#icinga2-remote-client-monitoring).
All communication is secured by TLS with certificates, and fully supports IPv4 and IPv6.
If you are planning to use the native Icinga 2 cluster feature for distributed
monitoring and high-availability, please continue reading in
-[this chapter](8-monitoring-remote-systems.md#distributed-monitoring-high-availability).
+[this chapter](9-monitoring-remote-systems.md#distributed-monitoring-high-availability).
> **Tip**
>
If the remote service is available using a network protocol and port,
and a [check plugin](2-getting-started.md#setting-up-check-plugins) is available, you don't
necessarily need a local client installed. Rather choose a plugin and
-configure all parameters and thresholds. The [Icinga 2 Template Library](6-icinga-template-library.md#icinga-template-library)
+configure all parameters and thresholds. The [Icinga 2 Template Library](7-icinga-template-library.md#icinga-template-library)
already ships various examples like
-* [ping4](6-icinga-template-library.md#plugin-check-command-ping4), [ping6](6-icinga-template-library.md#plugin-check-command-ping6),
-[fping4](6-icinga-template-library.md#plugin-check-command-fping4), [fping6](6-icinga-template-library.md#plugin-check-command-fping6), [hostalive](6-icinga-template-library.md#plugin-check-command-hostalive)
-* [tcp](6-icinga-template-library.md#plugin-check-command-tcp), [udp](6-icinga-template-library.md#plugin-check-command-udp), [ssl](6-icinga-template-library.md#plugin-check-command-ssl)
-* [http](6-icinga-template-library.md#plugin-check-command-http), [ftp](6-icinga-template-library.md#plugin-check-command-ftp)
-* [smtp](6-icinga-template-library.md#plugin-check-command-smtp), [ssmtp](6-icinga-template-library.md#plugin-check-command-ssmtp),
-[imap](6-icinga-template-library.md#plugin-check-command-imap), [simap](6-icinga-template-library.md#plugin-check-command-simap),
-[pop](6-icinga-template-library.md#plugin-check-command-pop), [spop](6-icinga-template-library.md#plugin-check-command-spop)
-* [ntp_time](6-icinga-template-library.md#plugin-check-command-ntp-time)
-* [ssh](6-icinga-template-library.md#plugin-check-command-ssh)
-* [dns](6-icinga-template-library.md#plugin-check-command-dns), [dig](6-icinga-template-library.md#plugin-check-command-dig), [dhcp](6-icinga-template-library.md#plugin-check-command-dhcp)
+* [ping4](7-icinga-template-library.md#plugin-check-command-ping4), [ping6](7-icinga-template-library.md#plugin-check-command-ping6),
+[fping4](7-icinga-template-library.md#plugin-check-command-fping4), [fping6](7-icinga-template-library.md#plugin-check-command-fping6), [hostalive](7-icinga-template-library.md#plugin-check-command-hostalive)
+* [tcp](7-icinga-template-library.md#plugin-check-command-tcp), [udp](7-icinga-template-library.md#plugin-check-command-udp), [ssl](7-icinga-template-library.md#plugin-check-command-ssl)
+* [http](7-icinga-template-library.md#plugin-check-command-http), [ftp](7-icinga-template-library.md#plugin-check-command-ftp)
+* [smtp](7-icinga-template-library.md#plugin-check-command-smtp), [ssmtp](7-icinga-template-library.md#plugin-check-command-ssmtp),
+[imap](7-icinga-template-library.md#plugin-check-command-imap), [simap](7-icinga-template-library.md#plugin-check-command-simap),
+[pop](7-icinga-template-library.md#plugin-check-command-pop), [spop](7-icinga-template-library.md#plugin-check-command-spop)
+* [ntp_time](7-icinga-template-library.md#plugin-check-command-ntp-time)
+* [ssh](7-icinga-template-library.md#plugin-check-command-ssh)
+* [dns](7-icinga-template-library.md#plugin-check-command-dns), [dig](7-icinga-template-library.md#plugin-check-command-dig), [dhcp](7-icinga-template-library.md#plugin-check-command-dhcp)
There are numerous check plugins contributed by community members available
on the internet. If you found one for your requirements, [integrate them into Icinga 2](3-monitoring-basics.md#command-plugin-integration).
* [Icinga Wiki](https://wiki.icinga.org)
An example is provided in the sample configuration in the getting started
-section shipped with Icinga 2 ([hosts.conf](4-configuring-icinga-2.md#hosts-conf), [services.conf](4-configuring-icinga-2.md#services-conf)).
+section shipped with Icinga 2 ([hosts.conf](5-configuring-icinga-2.md#hosts-conf), [services.conf](5-configuring-icinga-2.md#services-conf)).
## <a id="icinga2-remote-client-monitoring"></a> Monitoring Icinga 2 Remote Clients
* a remote command execution client (similar to NRPE, NSClient++, etc)
Later on, you will be asked again and told how to proceed with these
-different [roles](8-monitoring-remote-systems.md#icinga2-remote-monitoring-client-roles).
+different [roles](9-monitoring-remote-systems.md#icinga2-remote-monitoring-client-roles).
> **Note**
>
> If you are planning to build an Icinga 2 distributed setup using the cluster feature, please skip
> the following instructions and jump directly to the
-> [cluster setup instructions](8-monitoring-remote-systems.md#distributed-monitoring-high-availability).
+> [cluster setup instructions](9-monitoring-remote-systems.md#distributed-monitoring-high-availability).
> **Note**
>
## <a id="icinga2-remote-monitoring-master"></a> Master Setup for Remote Monitoring
-If you are planning to use the [remote Icinga 2 clients](8-monitoring-remote-systems.md#icinga2-remote-monitoring-client)
+If you are planning to use the [remote Icinga 2 clients](9-monitoring-remote-systems.md#icinga2-remote-monitoring-client)
you'll first need to update your master setup.
Your master setup requires the following
* Enabled API feature, and a local Endpoint and Zone object configuration
* Firewall ACLs for the communication port (default 5665)
-You can use the [CLI command](7-cli-commands.md#cli-command-node) `node wizard` for setting up a new node
+You can use the [CLI command](8-cli-commands.md#cli-command-node) `node wizard` for setting up a new node
on the master. The command must be run as root, all Icinga 2 specific files
will be updated to the icinga user the daemon is running as (certificate files
for example).
* Generate a new CSR, sign it with the local CA and copying it into `/etc/icinga2/pki`
* Generate a local zone and endpoint configuration for this master based on FQDN
* Enabling the API feature, and setting optional `bind_host` and `bind_port`
-* Setting the `NodeName` and `TicketSalt` constants in [constants.conf](4-configuring-icinga-2.md#constants-conf)
+* Setting the `NodeName` and `TicketSalt` constants in [constants.conf](5-configuring-icinga-2.md#constants-conf)
The setup wizard does not automatically restart Icinga 2.
## <a id="icinga2-remote-monitoring-client"></a> Client Setup for Remote Monitoring
Icinga 2 can be installed on Linux/Unix and Windows. While
-[Linux/Unix](8-monitoring-remote-systems.md#icinga2-remote-monitoring-client-linux) will be using the [CLI command](7-cli-commands.md#cli-command-node)
+[Linux/Unix](9-monitoring-remote-systems.md#icinga2-remote-monitoring-client-linux) will be using the [CLI command](8-cli-commands.md#cli-command-node)
`node wizard` for a guided setup, you will need to use the
graphical installer for Windows based client setup.
Your client setup requires the following
-* A ready configured and installed [master node](8-monitoring-remote-systems.md#icinga2-remote-monitoring-master)
+* A ready configured and installed [master node](9-monitoring-remote-systems.md#icinga2-remote-monitoring-master)
* SSL signed certificate for communication with the master (Use [CSR auto-signing](certifiates-csr-autosigning)).
* Enabled API feature, and a local Endpoint and Zone object configuration
* Firewall ACLs for the communication port (default 5665)
If your remote clients are capable of connecting to the central master, Icinga 2
supports CSR auto-signing.
-First you'll need to define a secure ticket salt in the [constants.conf](4-configuring-icinga-2.md#constants-conf).
-The [setup wizard for the master setup](8-monitoring-remote-systems.md#icinga2-remote-monitoring-master) will create
+First you'll need to define a secure ticket salt in the [constants.conf](5-configuring-icinga-2.md#constants-conf).
+The [setup wizard for the master setup](9-monitoring-remote-systems.md#icinga2-remote-monitoring-master) will create
one for you already.
# grep TicketSalt /etc/icinga2/constants.conf
> **Note**
>
> You can omit the `--salt` parameter using the `TicketSalt` constant from
-> [constants.conf](4-configuring-icinga-2.md#constants-conf) if already defined and Icinga 2 was
+> [constants.conf](5-configuring-icinga-2.md#constants-conf) if already defined and Icinga 2 was
> reloaded after the master setup.
#### <a id="certificates-manual-creation"></a> Manual SSL Certificate Generation
-This is described separately in the [cluster setup chapter](8-monitoring-remote-systems.md#manual-certificate-generation).
+This is described separately in the [cluster setup chapter](9-monitoring-remote-systems.md#manual-certificate-generation).
> **Note**
>
-> If you're using [CSR Auto-Signing](8-monitoring-remote-systems.md#csr-autosigning-requirements), skip this step.
+> If you're using [CSR Auto-Signing](9-monitoring-remote-systems.md#csr-autosigning-requirements), skip this step.
#### <a id="icinga2-remote-monitoring-client-linux-setup"></a> Linux Client Setup Wizard for Remote Monitoring
Install Icinga 2 from your distribution's package repository as described in the
general [installation instructions](2-getting-started.md#setting-up-icinga2).
-Please make sure that either [CSR Auto-Signing](8-monitoring-remote-systems.md#csr-autosigning-requirements) requirements
-are fulfilled, or that you're using [manual SSL certificate generation](8-monitoring-remote-systems.md#manual-certificate-generation).
+Please make sure that either [CSR Auto-Signing](9-monitoring-remote-systems.md#csr-autosigning-requirements) requirements
+are fulfilled, or that you're using [manual SSL certificate generation](9-monitoring-remote-systems.md#manual-certificate-generation).
> **Note**
>
* The client's local zone name. Defaults to FQDN.
* The master endpoint name. Look into your master setup `zones.conf` file for the proper name.
* The master endpoint connection information. Your master's IP address and port (defaults to 5665)
-* The [request ticket number](8-monitoring-remote-systems.md#csr-autosigning-requirements) generated on your master
+* The [request ticket number](9-monitoring-remote-systems.md#csr-autosigning-requirements) generated on your master
for CSR Auto-Signing
* Bind host/port for the Api feature (optional)
(based on FQDN)
* Disabling the notification feature for this client
* Enabling the API feature, and setting optional `bind_host` and `bind_port`
-* Setting the `NodeName` constant in [constants.conf](4-configuring-icinga-2.md#constants-conf)
+* Setting the `NodeName` constant in [constants.conf](5-configuring-icinga-2.md#constants-conf)
The setup wizard does not automatically restart Icinga 2.
* The client's local zone name. Defaults to FQDN.
* The master endpoint name. Look into your master setup `zones.conf` file for the proper name.
* The master endpoint connection information. Your master's IP address and port (defaults to 5665)
-* The [request ticket number](8-monitoring-remote-systems.md#csr-autosigning-requirements) generated on your master
+* The [request ticket number](9-monitoring-remote-systems.md#csr-autosigning-requirements) generated on your master
for CSR Auto-Signing
* Bind host/port for the Api feature (optional)
your Icinga 2 master or satellite, and only send commands remotely.
Requirements:
-* Exact same [CheckCommand](5-object-types.md#objecttype-checkcommand) (and
-[EventCommand](5-object-types.md#objecttype-eventcommand)) configuration objects
+* Exact same [CheckCommand](6-object-types.md#objecttype-checkcommand) (and
+[EventCommand](6-object-types.md#objecttype-eventcommand)) configuration objects
on the master and the remote client(s).
* Installed plugin scripts on the remote client (`PluginDir` constant can be locally modified)
* `Zone` and `Endpoint` configuration for the client on the master
endpoint
`CheckCommand` objects are already shipped with the Icinga 2 ITL
-as [plugin check commands](6-icinga-template-library.md#plugin-check-commands). If you are
+as [plugin check commands](7-icinga-template-library.md#plugin-check-commands). If you are
using your own configuration definitions for example in
-[commands.conf](4-configuring-icinga-2.md#commands-conf) make sure to copy/sync it
+[commands.conf](5-configuring-icinga-2.md#commands-conf) make sure to copy/sync it
on your remote client.
#### <a id="icinga2-remote-monitoring-client-command-execution-client"></a> Client Configuration Remote Client for Command Execution
}
More details here:
-* [configure endpoints](8-monitoring-remote-systems.md#configure-cluster-endpoints)
-* [configure zones](8-monitoring-remote-systems.md#configure-cluster-zones)
+* [configure endpoints](9-monitoring-remote-systems.md#configure-cluster-endpoints)
+* [configure zones](9-monitoring-remote-systems.md#configure-cluster-zones)
Configuration example for host and service objects running commands on the remote endpoint `remote-client1`:
> clients. There are no local configured objects available.
>
> If you require this, please install a full-featured
-> [local client](8-monitoring-remote-systems.md#icinga2-remote-monitoring-client-local-config).
+> [local client](9-monitoring-remote-systems.md#icinga2-remote-monitoring-client-local-config).
### <a id="icinga2-remote-monitoring-client-local-config"></a> Remote Client with Local Configuration
> **Note**
>
-> Better use [blacklists and/or whitelists](8-monitoring-remote-systems.md#icinga2-remote-monitoring-master-discovery-blacklist-whitelist)
+> Better use [blacklists and/or whitelists](9-monitoring-remote-systems.md#icinga2-remote-monitoring-master-discovery-blacklist-whitelist)
> to control which clients and hosts/services are integrated into your master configuration repository.
### <a id="icinga2-remote-monitoring-master-discovery-generate-config"></a> Generate Icinga 2 Configuration for Client Services on the Master
### <a id="icinga2-remote-monitoring-master-manual-add-endpoint-zone"></a> Manually add Client Endpoint and Zone Objects on the Master
-Define a [Zone](5-object-types.md#objecttype-zone) with a new [Endpoint](5-object-types.md#objecttype-endpoint) similar to the cluster setup.
+Define a [Zone](6-object-types.md#objecttype-zone) with a new [Endpoint](6-object-types.md#objecttype-endpoint) similar to the cluster setup.
-* [configure the node name](8-monitoring-remote-systems.md#configure-nodename)
-* [configure the ApiListener object](8-monitoring-remote-systems.md#configure-apilistener-object)
-* [configure cluster endpoints](8-monitoring-remote-systems.md#configure-cluster-endpoints)
-* [configure cluster zones](8-monitoring-remote-systems.md#configure-cluster-zones)
+* [configure the node name](9-monitoring-remote-systems.md#configure-nodename)
+* [configure the ApiListener object](9-monitoring-remote-systems.md#configure-apilistener-object)
+* [configure cluster endpoints](9-monitoring-remote-systems.md#configure-cluster-endpoints)
+* [configure cluster zones](9-monitoring-remote-systems.md#configure-cluster-zones)
on a per remote client basis. If you prefer to synchronize the configuration to remote
-clients, you can also use the cluster provided [configuration sync](8-monitoring-remote-systems.md#cluster-zone-config-sync)
+clients, you can also use the cluster provided [configuration sync](9-monitoring-remote-systems.md#cluster-zone-config-sync)
in `zones.d`.
The SNMP daemon runs on the remote system and answers SNMP queries by plugin
binaries. The [Monitoring Plugins package](2-getting-started.md#setting-up-check-plugins) ships
-the `check_snmp` plugin binary, but there are plenty of [existing plugins](9-addons-plugins.md#plugins)
+the `check_snmp` plugin binary, but there are plenty of [existing plugins](10-addons-plugins.md#plugins)
for specific use cases already around, for example monitoring Cisco routers.
-The following example uses the [SNMP ITL](6-icinga-template-library.md#plugin-check-command-snmp) `CheckCommand` and just
+The following example uses the [SNMP ITL](7-icinga-template-library.md#plugin-check-command-snmp) `CheckCommand` and just
overrides the `snmp_oid` custom attribute. A service is created for all hosts which
have the `snmp-community` custom attribute.
assign where host.vars.snmp_community != ""
}
-Additional SNMP plugins are available using the [Manubulon SNMP Plugins](6-icinga-template-library.md#snmp-manubulon-plugin-check-commands).
+Additional SNMP plugins are available using the [Manubulon SNMP Plugins](7-icinga-template-library.md#snmp-manubulon-plugin-check-commands).
### <a id="agent-based-checks-ssh"></a> SSH
> The NRPE protocol is considered insecure and has multiple flaws in its
> design. Upstream is not willing to fix these issues.
>
-> In order to stay safe, please use the native [Icinga 2 client](8-monitoring-remote-systems.md#icinga2-remote-monitoring-master)
+> In order to stay safe, please use the native [Icinga 2 client](9-monitoring-remote-systems.md#icinga2-remote-monitoring-master)
> instead.
The NRPE daemon uses its own configuration format in nrpe.cfg while `check_nrpe`
can be embedded into the Icinga 2 `CheckCommand` configuration syntax.
You can use the `check_nrpe` plugin from the NRPE project to query the NRPE daemon.
-Icinga 2 provides the [nrpe check command](6-icinga-template-library.md#plugin-check-command-nrpe) for this:
+Icinga 2 provides the [nrpe check command](7-icinga-template-library.md#plugin-check-command-nrpe) for this:
Example:
/usr/local/icinga/libexec/check_disk -w 20% -c 10% -p /
-You can pass arguments in a similar manner to [NSClient++](8-monitoring-remote-systems.md#agent-based-checks-nsclient)
+You can pass arguments in a similar manner to [NSClient++](9-monitoring-remote-systems.md#agent-based-checks-nsclient)
when using its NRPE supported check method.
### <a id="agent-based-checks-nsclient"></a> NSClient++
the required output and performance counters.
You can use the `check_nt` plugin from the Monitoring Plugins project to query NSClient++.
-Icinga 2 provides the [nscp check command](6-icinga-template-library.md#plugin-check-command-nscp) for this:
+Icinga 2 provides the [nscp check command](7-icinga-template-library.md#plugin-check-command-nscp) for this:
Example:
and specific trap handlers passing the check results to Icinga 2.
Following the SNMPTT [Format](http://snmptt.sourceforge.net/docs/snmptt.shtml#SNMPTT.CONF-FORMAT)
-documentation and the Icinga external command syntax found [here](17-appendix.md#external-commands-list-detail)
+documentation and the Icinga external command syntax found [here](18-appendix.md#external-commands-list-detail)
we can create generic services that can accommodate any number of hosts for a given scenario.
#### <a id="simple-traps"></a> Simple SNMP Traps
Building distributed environments with high availability included is fairly easy with Icinga 2.
The cluster feature is built-in and allows you to build many scenarios based on your requirements:
-* [High Availability](8-monitoring-remote-systems.md#cluster-scenarios-high-availability). All instances in the `Zone` elect one active master and run as Active/Active cluster.
-* [Distributed Zones](8-monitoring-remote-systems.md#cluster-scenarios-distributed-zones). A master zone and one or more satellites in their zones.
-* [Load Distribution](8-monitoring-remote-systems.md#cluster-scenarios-load-distribution). A configuration master and multiple checker satellites.
+* [High Availability](9-monitoring-remote-systems.md#cluster-scenarios-high-availability). All instances in the `Zone` elect one active master and run as Active/Active cluster.
+* [Distributed Zones](9-monitoring-remote-systems.md#cluster-scenarios-distributed-zones). A master zone and one or more satellites in their zones.
+* [Load Distribution](9-monitoring-remote-systems.md#cluster-scenarios-load-distribution). A configuration master and multiple checker satellites.
You can combine these scenarios into a global setup fitting your requirements.
* cluster zones can be built in a Top-Down-design where the child trusts the parent
* communication between zones happens bi-directional which means that a DMZ-located node can still reach the master node, or vice versa
* Update firewall rules and ACLs
-* Decide whether to use the built-in [configuration syncronization](8-monitoring-remote-systems.md#cluster-zone-config-sync) or use an external tool (Puppet, Ansible, Chef, Salt, etc) to manage the configuration deployment
+* Decide whether to use the built-in [configuration syncronization](9-monitoring-remote-systems.md#cluster-zone-config-sync) or use an external tool (Puppet, Ansible, Chef, Salt, etc) to manage the configuration deployment
> **Tip**
>
> If you're looking for troubleshooting cluster problems, check the general
-> [troubleshooting](12-troubleshooting.md#troubleshooting-cluster) section.
+> [troubleshooting](13-troubleshooting.md#troubleshooting-cluster) section.
### <a id="manual-certificate-generation"></a> Manual SSL Certificate Generation
-Icinga 2 ships [CLI commands](7-cli-commands.md#cli-command-pki) assisting with CA and node certificate creation
+Icinga 2 ships [CLI commands](8-cli-commands.md#cli-command-pki) assisting with CA and node certificate creation
for your Icinga 2 distributed setup.
> **Note**
#### <a id="cluster-naming-convention"></a> Cluster Naming Convention
-The SSL certificate common name (CN) will be used by the [ApiListener](5-object-types.md#objecttype-apilistener)
-object to determine the local authority. This name must match the local [Endpoint](5-object-types.md#objecttype-endpoint)
+The SSL certificate common name (CN) will be used by the [ApiListener](6-object-types.md#objecttype-apilistener)
+object to determine the local authority. This name must match the local [Endpoint](6-object-types.md#objecttype-endpoint)
object name.
Example:
host = "icinga2a.icinga.org"
}
-The [Endpoint](5-object-types.md#objecttype-endpoint) name is further referenced as `endpoints` attribute on the
-[Zone](5-object-types.md#objecttype-zone) object.
+The [Endpoint](6-object-types.md#objecttype-endpoint) name is further referenced as `endpoints` attribute on the
+[Zone](6-object-types.md#objecttype-zone) object.
object Endpoint "icinga2b" {
host = "icinga2b.icinga.org"
endpoints = [ "icinga2a", "icinga2b" ]
}
-Specifying the local node name using the [NodeName](8-monitoring-remote-systems.md#configure-nodename) variable requires
+Specifying the local node name using the [NodeName](9-monitoring-remote-systems.md#configure-nodename) variable requires
the same name as used for the endpoint name and common name above. If not set, the FQDN is used.
const NodeName = "icinga2a"
The following section describe which configuration must be updated/created
in order to get your cluster running with basic functionality.
-* [configure the node name](8-monitoring-remote-systems.md#configure-nodename)
-* [configure the ApiListener object](8-monitoring-remote-systems.md#configure-apilistener-object)
-* [configure cluster endpoints](8-monitoring-remote-systems.md#configure-cluster-endpoints)
-* [configure cluster zones](8-monitoring-remote-systems.md#configure-cluster-zones)
+* [configure the node name](9-monitoring-remote-systems.md#configure-nodename)
+* [configure the ApiListener object](9-monitoring-remote-systems.md#configure-apilistener-object)
+* [configure cluster endpoints](9-monitoring-remote-systems.md#configure-cluster-endpoints)
+* [configure cluster zones](9-monitoring-remote-systems.md#configure-cluster-zones)
Once you're finished with the basic setup the following section will
-describe how to use [zone configuration synchronisation](8-monitoring-remote-systems.md#cluster-zone-config-sync)
-and configure [cluster scenarios](8-monitoring-remote-systems.md#cluster-scenarios).
+describe how to use [zone configuration synchronisation](9-monitoring-remote-systems.md#cluster-zone-config-sync)
+and configure [cluster scenarios](9-monitoring-remote-systems.md#cluster-scenarios).
#### <a id="configure-nodename"></a> Configure the Icinga Node Name
Instead of using the default FQDN as node name you can optionally set
-that value using the [NodeName](15-language-reference.md#constants) constant.
+that value using the [NodeName](16-language-reference.md#constants) constant.
> ** Note **
>
> in `/etc/icinga2/constants.conf`.
This setting must be unique for each node, and must also match
-the name of the local [Endpoint](5-object-types.md#objecttype-endpoint) object and the
+the name of the local [Endpoint](6-object-types.md#objecttype-endpoint) object and the
SSL certificate common name as described in the
-[cluster naming convention](8-monitoring-remote-systems.md#cluster-naming-convention).
+[cluster naming convention](9-monitoring-remote-systems.md#cluster-naming-convention).
vim /etc/icinga2/constants.conf
const NodeName = "icinga2a"
-Read further about additional [naming conventions](8-monitoring-remote-systems.md#cluster-naming-convention).
+Read further about additional [naming conventions](9-monitoring-remote-systems.md#cluster-naming-convention).
Not specifying the node name will make Icinga 2 using the FQDN. Make sure that all
configured endpoint names and common names are in sync.
#### <a id="configure-apilistener-object"></a> Configure the ApiListener Object
-The [ApiListener](5-object-types.md#objecttype-apilistener) object needs to be configured on
+The [ApiListener](6-object-types.md#objecttype-apilistener) object needs to be configured on
every node in the cluster with the following settings:
A sample config looks like:
`Zone` objects specify the endpoints located in a zone. That way your distributed setup can be
seen as zones connected together instead of multiple instances in that specific zone.
-Zones can be used for [high availability](8-monitoring-remote-systems.md#cluster-scenarios-high-availability),
-[distributed setups](8-monitoring-remote-systems.md#cluster-scenarios-distributed-zones) and
-[load distribution](8-monitoring-remote-systems.md#cluster-scenarios-load-distribution).
+Zones can be used for [high availability](9-monitoring-remote-systems.md#cluster-scenarios-high-availability),
+[distributed setups](9-monitoring-remote-systems.md#cluster-scenarios-distributed-zones) and
+[load distribution](9-monitoring-remote-systems.md#cluster-scenarios-load-distribution).
Each Icinga 2 `Endpoint` must be put into its respective `Zone`. In this example, you will
define the zone `config-ha-master` where the `icinga2a` and `icinga2b` endpoints
Your child zones and endpoint members **must not** have their config copied to `zones.d`.
The built-in configuration synchronisation takes care of that if your nodes accept
configuration from the parent zone. You can define that in the
-[ApiListener](8-monitoring-remote-systems.md#configure-apilistener-object) object by configuring the `accept_config`
+[ApiListener](9-monitoring-remote-systems.md#configure-apilistener-object) object by configuring the `accept_config`
attribute accordingly.
You should remove the sample config included in `conf.d` by commenting the `recursive_include`
-statement in [icinga2.conf](4-configuring-icinga-2.md#icinga2-conf):
+statement in [icinga2.conf](5-configuring-icinga-2.md#icinga2-conf):
//include_recursive "conf.d"
Better use a dedicated directory name like `cluster` or similar, and include that
one if your nodes require local configuration not being synced to other nodes. That's
-useful for local [health checks](8-monitoring-remote-systems.md#cluster-health-check) for example.
+useful for local [health checks](9-monitoring-remote-systems.md#cluster-health-check) for example.
> **Note**
>
-> In a [high availability](8-monitoring-remote-systems.md#cluster-scenarios-high-availability)
+> In a [high availability](9-monitoring-remote-systems.md#cluster-scenarios-high-availability)
> setup only one assigned node can act as configuration master. All other zone
> member nodes **must not** have the `/etc/icinga2/zones.d` directory populated.
Each configured zone must exist with the same directory name. The parent zone
syncs the configuration to the child zones, if allowed using the `accept_config`
-attribute of the [ApiListener](8-monitoring-remote-systems.md#configure-apilistener-object) object.
+attribute of the [ApiListener](9-monitoring-remote-systems.md#configure-apilistener-object) object.
Config on node `icinga2a`:
> **Note**
>
-> `zones.d` must not be included in [icinga2.conf](4-configuring-icinga-2.md#icinga2-conf). Icinga 2 automatically
+> `zones.d` must not be included in [icinga2.conf](5-configuring-icinga-2.md#icinga2-conf). Icinga 2 automatically
> determines the required include directory. This can be overridden using the
-> [global constant](15-language-reference.md#constants) `ZonesDir`.
+> [global constant](16-language-reference.md#constants) `ZonesDir`.
#### <a id="zone-global-config-templates"></a> Global Configuration Zone for Templates
#### <a id="zone-config-sync-permissions"></a> Zone Configuration Synchronisation Permissions
-Each [ApiListener](5-object-types.md#objecttype-apilistener) object must have the `accept_config` attribute
+Each [ApiListener](6-object-types.md#objecttype-apilistener) object must have the `accept_config` attribute
set to `true` to receive configuration from the parent `Zone` members. Default value is `false`.
object ApiListener "api" {
> ** Tip **
>
-> Look into the [troubleshooting guides](12-troubleshooting.md#troubleshooting-cluster-config-sync) for debugging
+> Look into the [troubleshooting guides](13-troubleshooting.md#troubleshooting-cluster-config-sync) for debugging
> problems with the configuration synchronisation.
### <a id="cluster-health-check"></a> Cluster Health Check
-The Icinga 2 [ITL](6-icinga-template-library.md#icinga-template-library) ships an internal check command checking all configured
+The Icinga 2 [ITL](7-icinga-template-library.md#icinga-template-library) ships an internal check command checking all configured
`EndPoints` in the cluster setup. The check result will become critical if
one or more configured nodes are not connected.
* Child zones only receive event updates (check results, commands, etc) for their configured updates.
* Zones cannot influence/interfere other zones. Each checked object is assigned to only one zone.
* All nodes in a zone trust each other.
-* [Configuration sync](8-monitoring-remote-systems.md#zone-config-sync-permissions) is disabled by default.
+* [Configuration sync](9-monitoring-remote-systems.md#zone-config-sync-permissions) is disabled by default.
#### <a id="cluster-scenarios-features"></a> Features in Cluster Zones
actual slave checker node.
DB IDO on the left, graphite on the right side - works (if you disable
-[DB IDO HA](8-monitoring-remote-systems.md#high-availability-db-ido)).
+[DB IDO HA](9-monitoring-remote-systems.md#high-availability-db-ido)).
Icinga Web 2 on the left, checker and notifications on the right side - works too.
Everything on the left and on the right side - make sure to deal with
-[load-balanced notifications and checks](8-monitoring-remote-systems.md#high-availability-features) in a
-[HA zone](8-monitoring-remote-systems.md#cluster-scenarios-high-availability).
+[load-balanced notifications and checks](9-monitoring-remote-systems.md#high-availability-features) in a
+[HA zone](9-monitoring-remote-systems.md#cluster-scenarios-high-availability).
configure-cluster-zones
#### <a id="cluster-scenarios-distributed-zones"></a> Distributed Zones
Imagine the following example with a master node in Nuremberg, and two remote DMZ
based instances in Berlin and Vienna. Additonally you'll specify
-[global templates](8-monitoring-remote-systems.md#zone-global-config-templates) available in all zones.
+[global templates](9-monitoring-remote-systems.md#zone-global-config-templates) available in all zones.
The configuration tree on the master instance `nuremberg` could look like this:
> The child zones `berlin` and `vienna` will get their configuration synchronised
> from the configuration master 'nuremberg'. The endpoints in the child
> zones **must not** have their `zones.d` directory populated if this endpoint
-> [accepts synced configuration](8-monitoring-remote-systems.md#zone-config-sync-permissions).
+> [accepts synced configuration](9-monitoring-remote-systems.md#zone-config-sync-permissions).
#### <a id="cluster-scenarios-load-distribution"></a> Load Distribution
> The child zones `checker` will get its configuration synchronised
> from the configuration master 'master'. The endpoints in the child
> zone **must not** have their `zones.d` directory populated if this endpoint
-> [accepts synced configuration](8-monitoring-remote-systems.md#zone-config-sync-permissions).
+> [accepts synced configuration](9-monitoring-remote-systems.md#zone-config-sync-permissions).
#### <a id="cluster-scenarios-high-availability"></a> Cluster High Availability
High availability with Icinga 2 is possible by putting multiple nodes into
-a dedicated [zone](8-monitoring-remote-systems.md#configure-cluster-zones). All nodes will elect one
+a dedicated [zone](9-monitoring-remote-systems.md#configure-cluster-zones). All nodes will elect one
active master, and retry an election once the current active master is down.
-Selected features provide advanced [HA functionality](8-monitoring-remote-systems.md#high-availability-features).
+Selected features provide advanced [HA functionality](9-monitoring-remote-systems.md#high-availability-features).
Checks and notifications are load-balanced between nodes in the high availability
zone.
endpoints = [ "icinga2a", "icinga2b", "icinga2c" ]
}
-Two or more nodes in a high availability setup require an [initial cluster sync](8-monitoring-remote-systems.md#initial-cluster-sync).
+Two or more nodes in a high availability setup require an [initial cluster sync](9-monitoring-remote-systems.md#initial-cluster-sync).
> **Note**
>
> Keep in mind that **only one node acts as configuration master** having the
> configuration files in the `zones.d` directory. All other nodes **must not**
> have that directory populated. Instead they are required to
-> [accept synced configuration](8-monitoring-remote-systems.md#zone-config-sync-permissions).
-> Details in the [Configuration Sync Chapter](8-monitoring-remote-systems.md#cluster-zone-config-sync).
+> [accept synced configuration](9-monitoring-remote-systems.md#zone-config-sync-permissions).
+> Details in the [Configuration Sync Chapter](9-monitoring-remote-systems.md#cluster-zone-config-sync).
#### <a id="cluster-scenarios-multiple-hierarchies"></a> Multiple Hierarchies
By default the following features provide advanced HA functionality:
-* [Checks](8-monitoring-remote-systems.md#high-availability-checks) (load balanced, automated failover)
-* [Notifications](8-monitoring-remote-systems.md#high-availability-notifications) (load balanced, automated failover)
-* [DB IDO](8-monitoring-remote-systems.md#high-availability-db-ido) (Run-Once, automated failover)
+* [Checks](9-monitoring-remote-systems.md#high-availability-checks) (load balanced, automated failover)
+* [Notifications](9-monitoring-remote-systems.md#high-availability-notifications) (load balanced, automated failover)
+* [DB IDO](9-monitoring-remote-systems.md#high-availability-db-ido) (Run-Once, automated failover)
#### <a id="high-availability-checks"></a> High Availability with Checks
is enabled.
If your nodes should notify independent from any other nodes (this will cause
duplicated notifications if not properly handled!), you can set `enable_ha = false`
-in the [NotificationComponent](5-object-types.md#objecttype-notificationcomponent) feature.
+in the [NotificationComponent](6-object-types.md#objecttype-notificationcomponent) feature.
#### <a id="high-availability-db-ido"></a> High Availability with DB IDO
> **Note**
>
> The DB IDO HA feature can be disabled by setting the `enable_ha` attribute to `false`
-> for the [IdoMysqlConnection](5-object-types.md#objecttype-idomysqlconnection) or
-> [IdoPgsqlConnection](5-object-types.md#objecttype-idopgsqlconnection) object on all nodes in the
+> for the [IdoMysqlConnection](6-object-types.md#objecttype-idomysqlconnection) or
+> [IdoPgsqlConnection](6-object-types.md#objecttype-idopgsqlconnection) object on all nodes in the
> same zone.
>
> All endpoints will enable the DB IDO feature then, connect to the configured
* generate a new [SSL client certificate](#certificate-authority-certificates)
* identify its location in the zones
-* update the `zones.conf` file on each involved node ([endpoint](8-monitoring-remote-systems.md#configure-cluster-endpoints), [zones](8-monitoring-remote-systems.md#configure-cluster-zones))
+* update the `zones.conf` file on each involved node ([endpoint](9-monitoring-remote-systems.md#configure-cluster-endpoints), [zones](9-monitoring-remote-systems.md#configure-cluster-zones))
* a new slave zone node requires updates for the master and slave zones
- * verify if this endpoints requires [configuration synchronisation](8-monitoring-remote-systems.md#cluster-zone-config-sync) enabled
-* if the node requires the existing zone history: [initial cluster sync](8-monitoring-remote-systems.md#initial-cluster-sync)
-* add a [cluster health check](8-monitoring-remote-systems.md#cluster-health-check)
+ * verify if this endpoints requires [configuration synchronisation](9-monitoring-remote-systems.md#cluster-zone-config-sync) enabled
+* if the node requires the existing zone history: [initial cluster sync](9-monitoring-remote-systems.md#initial-cluster-sync)
+* add a [cluster health check](9-monitoring-remote-systems.md#cluster-health-check)
#### <a id="initial-cluster-sync"></a> Initial Cluster Sync
By default Icinga 2 and its features will place their runtime data below the prefix
`LocalStateDir`. By default packages will set that path to `/var`.
You can either set that variable as constant configuration
-definition in [icinga2.conf](4-configuring-icinga-2.md#icinga2-conf) or pass it as runtime variable to
+definition in [icinga2.conf](5-configuring-icinga-2.md#icinga2-conf) or pass it as runtime variable to
the Icinga 2 daemon.
# icinga2 -c /etc/icinga2/node1/icinga2.conf -DLocalStateDir=/opt/node1/var
- [1-about.md, About Icinga 2]
- [2-getting-started.md, Getting Started]
- [3-monitoring-basics.md, Monitoring Basics]
-- [4-configuring-icinga-2.md, Configuring Icinga 2]
-- [5-object-types.md, Object Types]
-- [6-icinga-template-library.md, Icinga Template Library]
-- [7-cli-commands.md, CLI Commands]
-- [8-monitoring-remote-systems.md, Monitoring Remote Systems]
-- [9-addons-plugins.md, Addons and Plugins]
-- [10-alternative-frontends.md, Alternative Frontends]
-- [11-livestatus.md, Livestatus]
-- [12-troubleshooting.md, Troubleshooting]
-- [13-upgrading-icinga-2.md, Upgrading Icinga 2]
-- [14-migrating-from-icinga-1x.md, Migrating from Icinga 1.x]
-- [15-language-reference.md, Language Reference]
-- [16-library-reference.md, Library Reference]
-- [17-appendix.md, Appendix]
+- [4-advanced-topics.md, Advanced Topics]
+- [5-configuring-icinga-2.md, Configuring Icinga 2]
+- [6-object-types.md, Object Types]
+- [7-icinga-template-library.md, Icinga Template Library]
+- [8-cli-commands.md, CLI Commands]
+- [9-monitoring-remote-systems.md, Monitoring Remote Systems]
+- [10-addons-plugins.md, Addons and Plugins]
+- [11-alternative-frontends.md, Alternative Frontends]
+- [12-livestatus.md, Livestatus]
+- [13-troubleshooting.md, Troubleshooting]
+- [14-upgrading-icinga-2.md, Upgrading Icinga 2]
+- [15-migrating-from-icinga-1x.md, Migrating from Icinga 1.x]
+- [16-language-reference.md, Language Reference]
+- [17-library-reference.md, Library Reference]
+- [18-appendix.md, Appendix]
theme: readthedocs
markdown_extensions: [smarty]
extra_javascript: [scroll.js]
projects / icinga2 / commitdiff