tyler.durden
/
icinga2
mirror of https://github.com/Icinga/icinga2.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Update documentation

This commit is contained in:
Gunnar Beutner 2015-02-11 11:51:58 +01:00
parent 14938778dc
commit a15b79f0df
18 changed files with 373 additions and 1148 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
doc/1-about.md
View File

@ -47,7 +47,7 @@ More details in the [Icinga FAQ](https://www.icinga.org/icinga/faq/).
* [Register](https://exchange.icinga.org/authentication/register) an Icinga account. * [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). * 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 ## <a id="whats-new"></a> What's new

22
doc/9-addons-plugins.md → doc/10-addons-plugins.md
View File

@ -8,19 +8,19 @@
[PNP](http://www.pnp4nagios.org) must be configured using the [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) [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. the rotated performance data files.
#### <a id="addons-graphing-ingraph"></a> inGraph #### <a id="addons-graphing-ingraph"></a> inGraph
[inGraph](https://www.netways.org/projects/ingraph/wiki) requires the ingraph-collector addon [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. write to the performance data spool directory.
#### <a id="addons-graphing-graphite"></a> Graphite #### <a id="addons-graphing-graphite"></a> Graphite
There are Graphite addons available for collecting the performance data files as well. But 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 #### <a id="addons-reporting"></a> Icinga Reporting
@ -39,7 +39,7 @@ based on your monitoring configuration and status data using [NagVis](http://www
As well as the Icinga supported web interfaces (Classic UI 1.x, Web 1.x, Web 2) there are a 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: 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 ## <a id="plugins"></a> Plugins
@ -54,7 +54,7 @@ list of popular community sites which host check plugins:
* [Icinga Wiki](https://wiki.icinga.org) * [Icinga Wiki](https://wiki.icinga.org)
The recommended way of setting up these plugins is to copy them to a common directory 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: configuration file:
# cp check_snmp_int.pl /opt/monitoring/plugins # cp check_snmp_int.pl /opt/monitoring/plugins
@ -81,9 +81,9 @@ documentation and/or plugin provided README for installation instructions.
Sometimes plugins contain hard-coded paths to other components. Instead of changing 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. 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 Each plugin requires a [CheckCommand](6-object-types.md#objecttype-checkcommand) object in your
configuration which can be used in the [Service](5-object-types.md#objecttype-service) or configuration which can be used in the [Service](6-object-types.md#objecttype-service) or
[Host](5-object-types.md#objecttype-host) object definition. [Host](6-object-types.md#objecttype-host) object definition.
There are the following conventions to follow when adding a new command object definition: There are the following conventions to follow when adding a new command object definition:
@ -93,7 +93,7 @@ in `[ ... ]` then for shell escaping.
* Define a unique `prefix` for the command's specific command arguments. That way you can safely * 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. 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 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: Example for a custom `my-snmp-int` check command:
@ -123,7 +123,7 @@ Example for a custom `my-snmp-int` check command:
vars.snmp_crit = "0,600" 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 For further information on your monitoring configuration read the
[Monitoring Basics](3-monitoring-basics.md#monitoring-basics) chapter. [Monitoring Basics](3-monitoring-basics.md#monitoring-basics) chapter.
@ -151,7 +151,7 @@ or similar.
> **Tip** > **Tip**
> >
> Get to know the new configuration format and the advanced [apply](3-monitoring-basics.md#using-apply) rules and > 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 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). to integrate them upstream, so please get in touch at [https://support.icinga.org](https://support.icinga.org).

14
doc/10-alternative-frontends.md → doc/11-alternative-frontends.md
View File

@ -3,7 +3,7 @@
## <a id="setting-up-icinga-classic-ui"></a> Setting up Icinga Classic UI 1.x ## <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 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 (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. log files which are required for the reporting functionality in the Classic UI.
@ -32,8 +32,8 @@ to satisfy this dependency:
On all distributions other than Debian you may have to restart both your web 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. 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) Icinga Classic UI requires the [StatusDataWriter](4-advanced-topics.md#status-data), [CompatLogger](4-advanced-topics.md#compat-logging)
and [ExternalCommandListener](3-monitoring-basics.md#external-commands) features. and [ExternalCommandListener](4-advanced-topics.md#external-commands) features.
Enable these features and restart Icinga 2. Enable these features and restart Icinga 2.
# icinga2 feature enable statusdata compatlog command # icinga2 feature enable statusdata compatlog command
@ -57,7 +57,7 @@ please check the official [Icinga 1.x user interface documentation](http://docs.
Icinga 2 can write to the same schema supplied by `Icinga IDOUtils 1.x` which 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. 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 ### <a id="installing-icinga-web"></a> Installing Icinga Web 1.x
@ -104,7 +104,7 @@ found in the [Icinga Web documentation](http://docs.icinga.org/latest/en/icinga-
# icinga-web-clearcache # 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 # icinga2 feature enable command
@ -140,7 +140,7 @@ use one of the config packages:
- `icinga-web-config-icinga2-ido-mysql` - `icinga-web-config-icinga2-ido-mysql`
- `icinga-web-config-icinga2-ido-pgsql` - `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 enabling the external command pipe for Icinga Web and depend on
the corresponding packages of Icinga 2. the corresponding packages of Icinga 2.
@ -157,7 +157,7 @@ When changing Icinga Web configuration files make sure to clear the config cache
> **Note** > **Note**
> >
> If you are using an older version of Icinga Web, install it like this and adapt > 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` > `apt-get install --no-install-recommends icinga-web`

14
doc/11-livestatus.md → doc/12-livestatus.md
View File

@ -8,7 +8,7 @@ status information. It can also be used to send commands.
> >
> Only install the Livestatus feature if your web interface or addon requires > 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)). > 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. > do not use Livestatus as backend.
The Livestatus component that is distributed as part of Icinga 2 is a The Livestatus component that is distributed as part of Icinga 2 is a
@ -16,7 +16,7 @@ re-implementation of the Livestatus protocol which is compatible with MK
Livestatus. Livestatus.
Details on the available tables and attributes with Icinga 2 can be found 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: You can enable Livestatus using icinga2 feature enable:
@ -59,7 +59,7 @@ Other to the Icinga 1.x Addon, Icinga 2 supports two socket types
* Unix socket (default) * Unix socket (default)
* TCP socket * 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. object configuration.
### <a id="livestatus-get-queries"></a> Livestatus GET Queries ### <a id="livestatus-get-queries"></a> Livestatus GET Queries
@ -92,7 +92,7 @@ Example using the tcp socket listening on port `6558`:
### <a id="livestatus-command-queries"></a> Livestatus COMMAND 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 $ echo -e 'COMMAND <externalcommandstring>' | netcat 127.0.0.1 6558
@ -185,10 +185,10 @@ Default separators.
downtimes | services | status attributes downtimes | services | status attributes
timeperiods | &nbsp; | name and is inside flag timeperiods | &nbsp; | name and is inside flag
endpoints | &nbsp; | config and status attributes endpoints | &nbsp; | config and status attributes
log | services, hosts, contacts, commands | parses [compatlog](5-object-types.md#objecttype-compatlogger) and shows log attributes log | services, hosts, contacts, commands | parses [compatlog](6-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 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. 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).

24
doc/12-troubleshooting.md → doc/13-troubleshooting.md
View File

@ -8,7 +8,7 @@
* Provide complete configuration snippets explaining your problem in detail * Provide complete configuration snippets explaining your problem in detail
* Provide complete logs targetting your problem * Provide complete logs targetting your problem
* If the check command failed - what's the output of your manual plugin tests? * 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 ## <a id="troubleshooting-enable-debug-output"></a> Enable Debug Output
@ -32,7 +32,7 @@ You can find the debug log file in `/var/log/icinga2/debug.log`.
The `icinga2 object list` CLI command can be used to list all configuration objects and their 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. 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 # icinga2 object list
@ -91,13 +91,13 @@ You can also filter by name and type:
## <a id="check-command-definitions"></a> Where are the check command definitions? ## <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 included using
include <itl> include <itl>
include <plugins> 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 on upgrade, so please send modifications as proposed patches upstream. The default include path is set to
`LocalStateDir + "/share/icinga2/includes"`. `LocalStateDir + "/share/icinga2/includes"`.
@ -109,7 +109,7 @@ or similar.
* Check the debug log to see if the check command gets executed * Check the debug log to see if the check command gets executed
* Verify that failed depedencies do not prevent command execution * 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 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: Examples:
@ -131,7 +131,7 @@ Verify the following configuration
* Do the notification attributes `states`, `types`, `period` match the notification conditions? * Do the notification attributes `states`, `types`, `period` match the notification conditions?
* Do the user 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? * 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? * 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. If notifications are to be sent via mail make sure that the mail program specified exists.
@ -146,25 +146,25 @@ Examples:
## <a id="feature-not-working"></a> Feature is not working ## <a id="feature-not-working"></a> Feature is not working
* Make sure that the feature configuration is enabled by symlinking from `features-available/` * 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? * Are the feature attributes set correctly according to the documentation?
* Any errors on the logs? * Any errors on the logs?
## <a id="configuration-ignored"></a> Configuration is ignored ## <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 `/* ... */`). 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 ## <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 contain additional attributes, your objects will automatically inherit them. You can override
or modify these attributes in the current object. or modify these attributes in the current object.
## <a id="troubleshooting-cluster"></a> Cluster Troubleshooting ## <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. done so already.
> **Note** > **Note**
@ -218,7 +218,7 @@ If the cluster zones do not sync their configuration, make sure to check the fol
* Within a config master zone, only one configuration master is allowed to have its config in `/etc/icinga2/zones.d`. * 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 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 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 ## <a id="debug"></a> Debug Icinga 2

0
doc/13-upgrading-icinga-2.md → doc/14-upgrading-icinga-2.md
View File

40
doc/14-migrating-from-icinga-1x.md → doc/15-migrating-from-icinga-1x.md
View File

@ -27,7 +27,7 @@ If you encounter a bug, please open an issue at https://dev.icinga.org.
For a long-term migration of your configuration you should consider re-creating For a long-term migration of your configuration you should consider re-creating
your configuration based on the proposed Icinga 2 configuration paradigm. 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. between 1.x and 2.
### <a id="manual-config-migration-hints"></a> Manual Config Migration Hints ### <a id="manual-config-migration-hints"></a> Manual Config Migration Hints
@ -39,7 +39,7 @@ Icinga 1.x configuration.
The examples are taken from Icinga 1.x test and production environments and converted 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! 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 #### <a id="manual-config-migration-hints-Intervals"></a> Manual Config Migration Hints for Intervals
@ -127,7 +127,7 @@ a member and includes all members of the `hg1` hostgroup.
hostgroup_members hg1 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. `hg1` is included into `hg2` with the `groups` attribute.
@ -217,8 +217,8 @@ directory - one major problem solved.
For the check command it is required to For the check command it is required to
* Escape all double quotes with an additional `\`. * 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 all [runtime macros](15-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 [custom variable macros](15-migrating-from-icinga-1x.md#manual-config-migration-hints-runtime-custom-attributes) if any.
* Keep `$ARGn$` macros. * Keep `$ARGn$` macros.
The final check command looks like this in Icinga2: The final check command looks like this in Icinga2:
@ -257,7 +257,7 @@ That way the old command arguments fashion can be applied for Icinga 2, although
#### <a id="manual-config-migration-hints-runtime-macros"></a> Manual Config Migration Hints for Runtime Macros #### <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: For example, accessing the service check output looks like the following in Icinga 1.x:
@ -318,7 +318,7 @@ while the service check command resolves its value to the service attribute attr
#### <a id="manual-config-migration-hints-contacts-users"></a> Manual Config Migration Hints for Contacts (Users) #### <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. 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{ define contact{
contact_name testconfig-user contact_name testconfig-user
@ -328,7 +328,7 @@ This migration part is explained in the [next chapter](14-migrating-from-icinga-
email icinga@localhost 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 into generic `state` and `type` filters, if additional notification filtering is required. `alias` gets
renamed to `display_name`. renamed to `display_name`.
@ -380,7 +380,7 @@ Assign it to the host or service and set the newly generated notification comman
Convert the `notification_options` attribute from Icinga 1.x to Icinga 2 `states` and `types`. Details 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 ] states = [ OK, Warning, Critical ]
types = [ Recovery, Problem, Custom ] types = [ Recovery, Problem, Custom ]
@ -617,7 +617,7 @@ enabled.
assign where "hg_svcdep2" in host.groups 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).
@ -721,9 +721,9 @@ daemon for passing check results between instances.
* Icinga 2 does not support any 1.x NEB addons for check load distribution * 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 * 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 * 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 * 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 you should re-design your setup and re-evaluate your requirements, and how they may be fulfilled
using the Icinga 2 cluster capabilities. using the Icinga 2 cluster capabilities.
@ -773,11 +773,11 @@ included in `icinga2.conf` by default.
### <a id="differences-1x-2-main-config"></a> Main Config File ### <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`. 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. 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 Aside from that, the [icinga2.conf](5-configuring-icinga-2.md#icinga2-conf) should take care of including
global constants, enabled [features](7-cli-commands.md#features) and the object configuration. 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 ### <a id="differences-1x-2-include-files-dirs"></a> Include Files and Directories
@ -826,7 +826,7 @@ set in the `constants.conf` configuration file:
const PluginDir = "/usr/lib/nagios/plugins" 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. global constant will result in an error.
### <a id="differences-1x-2-configuration-comments"></a> Configuration Comments ### <a id="differences-1x-2-configuration-comments"></a> Configuration Comments
@ -1253,7 +1253,7 @@ timeout. This was essentially bad when there only was a couple of check plugins
requiring some command timeouts to be extended. requiring some command timeouts to be extended.
Icinga 2 allows you to specify the command timeout directly on the command. So 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. accordingly.
@ -1388,7 +1388,7 @@ child attributes may be omitted.
For detailed examples on how to use the dependencies please check the [dependencies](3-monitoring-basics.md#dependencies) For detailed examples on how to use the dependencies please check the [dependencies](3-monitoring-basics.md#dependencies)
chapter. 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 The `StatusDataWriter`, `IdoMysqlConnection` and `LivestatusListener` types
support the Icinga 1.x schema with dependencies and parent attributes for support the Icinga 1.x schema with dependencies and parent attributes for
@ -1438,7 +1438,7 @@ Unlike Icinga 1.x the Icinga 2 daemon reload happens asynchronously.
* parent process continues with old configuration objects and the event scheduling * parent process continues with old configuration objects and the event scheduling
(doing checks, replicating cluster events, triggering alert notifications, etc.) (doing checks, replicating cluster events, triggering alert notifications, etc.)
* validation NOT ok: child process terminates, parent process continues with old configuration state * 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 * validation ok: child process signals parent process to terminate and save its current state
(all events until now) into the icinga2 state file (all events until now) into the icinga2 state file
* parent process shuts down writing icinga2.state file * parent process shuts down writing icinga2.state file
@ -1493,6 +1493,6 @@ distribution out-of-the-box. Furthermore comments, downtimes, and other stateful
not synced between the master and slave nodes. There are addons available solving the check 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. 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. 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. High Availability and load balancing are also part of the Icinga 2 Cluster setup.

10
doc/15-language-reference.md → doc/16-language-reference.md
View File

@ -199,7 +199,7 @@ Functions can be called using the `()` operator:
check_interval = len(MyGroups) * 1m 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 ## <a id="dictionary-operators"></a> Assignments
@ -394,7 +394,7 @@ another group of objects.
In this example the `assign where` condition is a boolean expression which is 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" 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. may be used in `assign where` conditions.
The `to` keyword and the target type may be omitted if there is only one target The `to` keyword and the target type may be omitted if there is only one target
@ -431,7 +431,7 @@ and `ignore where` conditions.
In this example the `assign where` condition is a boolean expression which is evaluated 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 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` 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. `ignore where` conditions.
Source Type | Variables Source Type | Variables
@ -460,7 +460,7 @@ Empty dictionary | {} | false
Non-empty dictionary | { key = "value" } | true Non-empty dictionary | { key = "value" } | true
For a list of supported expression operators for `assign where` and `ignore where` 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 ## <a id="comments"></a> Comments
@ -498,7 +498,7 @@ Note the use of angle brackets instead of double quotes. This causes the
config compiler to search the include search paths for the specified 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 file. By default $PREFIX/share/icinga2/include is included in the list of search
paths. Additional include search paths can be added using 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. Wildcards are not permitted when using angle brackets.

0
doc/16-library-reference.md → doc/17-library-reference.md
View File

0
doc/17-appendix.md → doc/18-appendix.md
View File

16
doc/2-getting-started.md
View File

@ -107,7 +107,7 @@ Icinga 2 installation:
* `mainlog` for writing the `icinga2.log` file * `mainlog` for writing the `icinga2.log` file
You can verify that by calling `icinga2 feature list` 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. enabled and disabled.
# icinga2 feature list # icinga2 feature list
@ -154,11 +154,11 @@ FreeBSD | nagios-plugins | /usr/local/libexec/nagios
OS X (MacPorts) | nagios-plugins | /opt/local/libexec OS X (MacPorts) | nagios-plugins | /opt/local/libexec
Depending on which directory your plugins are installed into you may need to 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 This constant is used by the check command definitions contained in the Icinga Template Library
to determine where to find the plugin binaries. 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. additional check plugins into your Icinga 2 setup.
## <a id="running-icinga2"></a> Running Icinga 2 ## <a id="running-icinga2"></a> Running Icinga 2
@ -231,13 +231,13 @@ Examples:
Job for icinga2.service failed. See 'systemctl status icinga2.service' and 'journalctl -xn' for details. 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 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 ## <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. 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 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 chapter can be used as a starting point for installing some of the other web
interfaces which are also available. interfaces which are also available.
@ -324,7 +324,7 @@ The package provides a new configuration file that is installed in
update the database credentials in this file. update the database credentials in this file.
All available attributes are explained in the All available attributes are explained in the
[IdoMysqlConnection object](5-object-types.md#objecttype-idomysqlconnection) [IdoMysqlConnection object](6-object-types.md#objecttype-idomysqlconnection)
chapter. chapter.
You can enable the `ido-mysql` feature configuration file using You can enable the `ido-mysql` feature configuration file using
@ -441,7 +441,7 @@ The package provides a new configuration file that is installed in
the database credentials in this file. the database credentials in this file.
All available attributes are explained in the All available attributes are explained in the
[IdoPgsqlConnection object](5-object-types.md#objecttype-idopgsqlconnection) [IdoPgsqlConnection object](6-object-types.md#objecttype-idopgsqlconnection)
chapter. chapter.
You can enable the `ido-pgsql` feature configuration file using You can enable the `ido-pgsql` feature configuration file using
@ -548,5 +548,5 @@ for further instructions on how to install Icinga Web 2.
A number of additional features are available in the form of addons. A list of A number of additional features are available in the form of addons. A list of
popular addons is available in the 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.

964
doc/3-monitoring-basics.md
View File

File diff suppressed because it is too large Load Diff

104
doc/4-configuring-icinga-2.md → doc/5-configuring-icinga-2.md
View File

@ -4,7 +4,7 @@ This chapter prodides an introduction to the configuration files which are autom
when installing the Icinga 2 packages. when installing the Icinga 2 packages.
If you're interested in a detailed explanation of each language feature used in those 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. chapter.
## <a id="icinga2-conf"></a> icinga2.conf ## <a id="icinga2-conf"></a> icinga2.conf
@ -22,7 +22,7 @@ Here's a brief description of the example configuration:
* to the documentation that is distributed as part of Icinga 2. * 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. * The constants.conf defines global constants.
@ -56,7 +56,7 @@ The `include` directive can be used to include other files.
This `include` directive takes care of including the configuration files for all This `include` directive takes care of including the configuration files for all
the features which have been enabled with `icinga2 feature enable`. See 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 * The repository.d directory contains all configuration objects
@ -66,7 +66,7 @@ the features which have been enabled with `icinga2 feature enable`. See
This `include_recursive` directive is used for discovery of services on remote clients This `include_recursive` directive is used for discovery of services on remote clients
and their generated configuration described in 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).
/** /**
@ -76,7 +76,7 @@ and their generated configuration described in
*/ */
include_recursive "conf.d" 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. directive makes sure that all of your own configuration files are included.
## <a id="constants-conf"></a> constants.conf ## <a id="constants-conf"></a> constants.conf
@ -87,7 +87,7 @@ By default, you need to make sure to set these constants:
* The `PluginDir` constant must be set to the path where the [Monitoring Project plugins](2-getting-started.md#setting-up-check-plugins) are installed. * 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 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 * 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 if not set. This constant is required for local host configuration, monitoring remote clients and
cluster setup. cluster setup.
@ -121,35 +121,35 @@ and distributed setups only.
This directory contains example configuration which should help you get started This directory contains example configuration which should help you get started
with monitoring the local host and its services. It is included in the 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. It can be used as reference example for your own configuration strategy.
Just keep in mind to include the main directories in the 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 You are certainly not bound to it. Remove it, if you prefer your own
way of deploying Icinga 2 configuration. way of deploying Icinga 2 configuration.
Further details on configuration best practice and how to build your 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: Available configuration files which are installed by default:
* [hosts.conf](4-configuring-icinga-2.md#hosts-conf) * [hosts.conf](5-configuring-icinga-2.md#hosts-conf)
* [services.conf](4-configuring-icinga-2.md#services-conf) * [services.conf](5-configuring-icinga-2.md#services-conf)
* [users.conf](4-configuring-icinga-2.md#users-conf) * [users.conf](5-configuring-icinga-2.md#users-conf)
* [notifications.conf](4-configuring-icinga-2.md#notifications-conf) * [notifications.conf](5-configuring-icinga-2.md#notifications-conf)
* [commands.conf](4-configuring-icinga-2.md#commands-conf) * [commands.conf](5-configuring-icinga-2.md#commands-conf)
* [groups.conf](4-configuring-icinga-2.md#groups-conf) * [groups.conf](5-configuring-icinga-2.md#groups-conf)
* [templates.conf](4-configuring-icinga-2.md#templates-conf) * [templates.conf](5-configuring-icinga-2.md#templates-conf)
* [downtimes.conf](4-configuring-icinga-2.md#downtimes-conf) * [downtimes.conf](5-configuring-icinga-2.md#downtimes-conf)
* [timeperiods.conf](4-configuring-icinga-2.md#timeperiods-conf) * [timeperiods.conf](5-configuring-icinga-2.md#timeperiods-conf)
* [satellite.conf](4-configuring-icinga-2.md#satellite-conf) * [satellite.conf](5-configuring-icinga-2.md#satellite-conf)
### <a id="hosts-conf"></a> hosts.conf ### <a id="hosts-conf"></a> hosts.conf
The `hosts.conf` file contains an example host based on your 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 can use global constants for your object names instead of string
values. values.
@ -158,24 +158,24 @@ takes care of setting up the host check command to `hostalive`. If you
require a different check command, you can override it in the object definition. require a different check command, you can override it in the object definition.
The `vars` attribute can be used to define custom attributes which are available The `vars` attribute can be used to define custom 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. in the Icinga Template Library require an `address` attribute.
The custom attribute `os` is evaluated by the `linux-servers` group in 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 The example host will show you how to
* define http vhost attributes for the `http` service apply rule defined * 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` * 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 * define notification types (`mail`) and set the groups attribute. This
will be used by notification apply rules in [notifications.conf](notifications-conf). 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 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 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` generate a new service checking the `/icingaweb2` URI using the `http`
check. check.
@ -232,17 +232,17 @@ check.
} }
This is only the host object definition. Now we'll need to make sure that this This is only the host object definition. Now we'll need to make sure that this
host and your additional hosts are getting [services](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** > **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 > don't worry - the [monitoring basics](3-monitoring-basics.md#monitoring-basics) chapter will explain
> that in detail. > that in detail.
### <a id="services-conf"></a> services.conf ### <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 the local host, but also allow you to re-use or modify them for
your own requirements. your own requirements.
@ -262,8 +262,8 @@ Service(s) | Applied on host(s)
The Debian packages also include an additional `apt` service check applied to the local host. The Debian packages also include an additional `apt` service check applied to the local host.
The command object `icinga` for the embedded health check is provided by the 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`, [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](6-icinga-template-library.md#plugin-check-commands) `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. which we enabled earlier by including the `itl` and `plugins` configuration file.
@ -286,11 +286,11 @@ attributes.
The custom attribe `backup_downtime` is defined to a specific timerange string. The custom attribe `backup_downtime` is defined to a specific timerange string.
This variable value will be used for applying a `ScheduledDowntime` object to This variable value will be used for applying a `ScheduledDowntime` object to
these services in [downtimes.conf](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 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" 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. may be used in `assign where` conditions.
Multiple `assign where` condition can be combined with `AND` using the `&&` operator Multiple `assign where` condition can be combined with `AND` using the `&&` operator
@ -308,7 +308,7 @@ In this example, the service `ssh` is applied to all hosts having the `address`
attribute defined `AND` having the custom attribute `os` set to the string attribute defined `AND` having the custom attribute `os` set to the string
`Linux`. `Linux`.
You can modify this condition to match multiple expressions by combinding `AND` 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")`. `assign where host.address && (vars.os == "Linux" || vars.os == "Windows")`.
@ -317,10 +317,10 @@ rules. While one `apply` rule for `ssh` will only create a service for matching
hosts, you can go one step further: Generate apply rules based on array items hosts, you can go one step further: Generate apply rules based on array items
or dictionary key-value pairs. 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`. `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):
... ...
@ -354,7 +354,7 @@ Once defined like this, the `apply` rule defined below will do the following:
* loop through all entries in the `host.vars.disks` dictionary. That's `disk` and `disk /` as keys. * 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 * call `apply` on each, and set the service object name from the provided key
* inside apply, the `generic-service` template is imported * 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 * adding the `config` dictionary items to `vars`. Simply said, there's now `vars.disk_partition` defined for the
generated service generated service
@ -372,7 +372,7 @@ A similar example is used for the `http` services. That way you can make your
host the information provider for all apply rules. Define them once, and only host the information provider for all apply rules. Define them once, and only
manage your hosts. 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 for applying notifications to hosts and services using their type and user
attributes. attributes.
@ -385,8 +385,8 @@ Further details on the monitoring configuration can be found in the
### <a id="users-conf"></a> users.conf ### <a id="users-conf"></a> users.conf
Defines the `icingaadmin` User and the `icingaadmins` UserGroup. The latter is used in 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 [hosts.conf](5-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. [notifications.conf](5-configuring-icinga-2.md#notifications-conf) for notification apply rules.
object User "icingaadmin" { object User "icingaadmin" {
import "generic-user" import "generic-user"
@ -413,13 +413,13 @@ nested dictionary attribute `notification.mail` is set.
Please note that the `to` keyword is important in [notification apply rules](3-monitoring-basics.md#using-apply-notifications) 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. 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 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 respective [host.vars.notification.mail](5-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). implicitely use the`icingaadmins` UserGroup defined in [users.conf](5-configuring-icinga-2.md#users-conf).
apply Notification "mail-icingaadmin" to Host { apply Notification "mail-icingaadmin" to Host {
import "mail-host-notification" import "mail-host-notification"
@ -443,7 +443,7 @@ filters can be read in [this chapter](3-monitoring-basics.md#notifications).
### <a id="commands-conf"></a> commands.conf ### <a id="commands-conf"></a> commands.conf
This is the place where your own command configuration can be defined. By default 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. 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). Read more on that topic [here](3-monitoring-basics.md#notification-commands).
@ -454,7 +454,7 @@ The example host defined in [hosts.conf](hosts-conf) already has the
custom attribute `os` set to `Linux` and is therefore automatically custom attribute `os` set to `Linux` and is therefore automatically
a member of the host group `linux-servers`. 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). to previously seen [apply rules](3-monitoring-basics.md#using-apply).
object HostGroup "linux-servers" { object HostGroup "linux-servers" {
@ -470,7 +470,7 @@ to previously seen [apply rules](3-monitoring-basics.md#using-apply).
} }
Service groups can be grouped together by similar pattern matches. 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. and the attribute string to match with.
object ServiceGroup "ping" { object ServiceGroup "ping" {
@ -512,7 +512,7 @@ default:
} }
The `hostalive` check command is part of the 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" { template Notification "mail-host-notification" {
@ -537,15 +537,15 @@ The `hostalive` check command is part of the
period = "24x7" 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 ### <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 `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. to define the default value for the time ranges required for recurring downtime slots.
apply ScheduledDowntime "backup-downtime" to Service { apply ScheduledDowntime "backup-downtime" to Service {
@ -575,8 +575,8 @@ objects such as hosts, services or notifications.
### <a id="satellite-conf"></a> satellite.conf ### <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) Includes default templates and dependencies for [monitoring remote clients](9-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) 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. on the master. Can be ignored/removed on setups not using this features.

24
doc/5-object-types.md → doc/6-object-types.md
View File

@ -82,7 +82,7 @@ A group of hosts.
> **Best Practice** > **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: Example:
@ -189,7 +189,7 @@ A group of services.
> **Best Practice** > **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: Example:
@ -273,7 +273,7 @@ A user group.
> **Best Practice** > **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: Example:
@ -447,7 +447,7 @@ Configuration Attributes:
zone |**Optional.** The zone this object is a member of. zone |**Optional.** The zone this object is a member of.
arguments |**Optional.** A dictionary of command arguments. 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 ## <a id="objecttype-eventcommand"></a> EventCommand
@ -474,7 +474,7 @@ Configuration Attributes:
timeout |**Optional.** The command timeout in seconds. Defaults to 60 seconds. timeout |**Optional.** The command timeout in seconds. Defaults to 60 seconds.
arguments |**Optional.** A dictionary of command arguments. 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 ## <a id="objecttype-notification"></a> Notification
@ -597,7 +597,7 @@ ScheduledDowntime objects can be used to set up recurring downtimes for hosts/se
> to just create a `ScheduledDowntime` template and use the `apply` keyword to assign the > 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 > scheduled downtime to a number of hosts or services. Use the `to` keyword to set the specific target
> type for `Host` or `Service`. > 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: Example:
@ -794,7 +794,7 @@ Configuration Attributes:
Metric prefix names can be modified using [runtime macros](3-monitoring-basics.md#runtime-macros). 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" const GraphiteEnv = "icinga.env1"
@ -883,8 +883,8 @@ Configuration Attributes:
table\_prefix |**Optional.** MySQL database table prefix. Defaults to "icinga\_". 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\_name |**Optional.** Unique identifier for the local Icinga 2 instance. Defaults to "default".
instance\_description|**Optional.** Description for the Icinga 2 instance. 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". 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](8-monitoring-remote-systems.md#high-availability-db-ido). Must not be lower than 60s. Defaults to "60s". 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. cleanup |**Optional.** Dictionary with items for historical table cleanup.
categories |**Optional.** The types of information that should be written to the database. categories |**Optional.** The types of information that should be written to the database.
@ -972,8 +972,8 @@ Configuration Attributes:
table\_prefix |**Optional.** PostgreSQL database table prefix. Defaults to "icinga\_". 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\_name |**Optional.** Unique identifier for the local Icinga 2 instance. Defaults to "default".
instance\_description|**Optional.** Description for the Icinga 2 instance. 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". 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](8-monitoring-remote-systems.md#high-availability-db-ido). Must not be lower than 60s. Defaults to "60s". 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. cleanup |**Optional.** Dictionary with items for historical table cleanup.
categories |**Optional.** The types of information that should be written to the database. categories |**Optional.** The types of information that should be written to the database.
@ -1232,7 +1232,7 @@ Configuration Attributes:
ApiListener objects are used for distributed monitoring setups ApiListener objects are used for distributed monitoring setups
specifying the certificate files used for ssl authorization. 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: Example:

2
doc/6-icinga-template-library.md → doc/7-icinga-template-library.md
View File

@ -696,7 +696,7 @@ The SNMP manubulon plugin check commands assume that the global constant named `
is set to the path where the Manubublon SNMP plugins are installed. 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 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> include <manubulon>

32
doc/7-cli-commands.md → doc/8-cli-commands.md
View File

@ -105,12 +105,12 @@ Debian/Ubuntu:
#### Libraries #### 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. you can also use the `--library` command-line option.
#### Constants #### 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="config-include-path"></a> Config Include Path
@ -151,7 +151,7 @@ use the `rlwrap` program if you require those features:
### <a id="cli-command-daemon"></a> CLI command: Daemon ### <a id="cli-command-daemon"></a> CLI command: Daemon
The CLI command `daemon` provides the functionality to start/stop Icinga 2. 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 daemon --help
icinga2 - The Icinga 2 network monitoring daemon (version: v2.1.1-299-gf695275) icinga2 - The Icinga 2 network monitoring daemon (version: v2.1.1-299-gf695275)
@ -195,7 +195,7 @@ Icinga 2 automatically falls back to using the configuration file
The `--validate` option can be used to check if your configuration files 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 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-feature"></a> CLI command: Feature
@ -219,8 +219,8 @@ The `feature list` command shows which features are currently enabled:
### <a id="cli-command-node"></a> CLI command: Node ### <a id="cli-command-node"></a> CLI command: Node
Provides the functionality to install and manage master and client 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 nodes in a [remote monitoring ](9-monitoring-remote-systems.md#icinga2-remote-client-monitoring) or
[distributed cluster](8-monitoring-remote-systems.md#distributed-monitoring-high-availability) scenario. [distributed cluster](9-monitoring-remote-systems.md#distributed-monitoring-high-availability) scenario.
# icinga2 node --help # icinga2 node --help
@ -264,9 +264,9 @@ nodes in a [remote monitoring ](8-monitoring-remote-systems.md#icinga2-remote-cl
The `object` CLI command can be used to list all configuration objects and their 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. 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 object --help
icinga2 - The Icinga 2 network monitoring daemon (version: v2.1.1-299-gf695275) icinga2 - The Icinga 2 network monitoring daemon (version: v2.1.1-299-gf695275)
@ -305,7 +305,7 @@ Provides the CLI commands to
* request a signed certificate from the master * request a signed certificate from the master
* generate a new ticket for the client setup * 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 pki --help
icinga2 - The Icinga 2 network monitoring daemon (version: v2.1.1-299-gf695275) icinga2 - The Icinga 2 network monitoring daemon (version: v2.1.1-299-gf695275)
@ -394,7 +394,7 @@ cleared after review.
### <a id="cli-command-variable"></a> CLI command: Variable ### <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 variable --help
icinga2 - The Icinga 2 network monitoring daemon (version: v2.1.1-299-gf695275) icinga2 - The Icinga 2 network monitoring daemon (version: v2.1.1-299-gf695275)
@ -430,7 +430,7 @@ Lists all configured variables (constants) in a similar fasion like [object list
Icinga 2 provides configuration files for some commonly used features. These Icinga 2 provides configuration files for some commonly used features. These
are installed in the `/etc/icinga2/features-available` directory and can be are installed in the `/etc/icinga2/features-available` directory and can be
enabled and disabled using the `icinga2 feature enable` and `icinga2 feature disable` 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 The `icinga2 feature enable` CLI command creates symlinks in the
`/etc/icinga2/features-enabled` directory which is included by default `/etc/icinga2/features-enabled` directory which is included by default
@ -508,12 +508,12 @@ Or manually passing the `-C` argument:
> `# icinga2 daemon -C` > `# icinga2 daemon -C`
If you encouter errors during configuration validation, please make sure 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 after validation passes to analyze object attributes, inheritance or created
objects by apply rules. 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*`: Example filtered by `Service` objects with the name `ping*`:
@ -546,7 +546,7 @@ Example filtered by `Service` objects with the name `ping*`:
## <a id="config-change-reload"></a> Reload on Configuration Changes ## <a id="config-change-reload"></a> Reload on Configuration Changes
Everytime you have changed your configuration you should first tell Icinga 2 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. safely reload the Icinga 2 daemon.
# /etc/init.d/icinga2 reload # /etc/init.d/icinga2 reload
@ -557,5 +557,5 @@ safely reload the Icinga 2 daemon.
> which will validate the configuration in a separate process and not stop > which will validate the configuration in a separate process and not stop
> the other events like check execution, notifications, etc. > 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).

224
doc/8-monitoring-remote-systems.md → doc/9-monitoring-remote-systems.md
View File

@ -1,17 +1,17 @@
# <a id="monitoring-remote-systems"></a> Monitoring Remote Systems # <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. or [agent-based](agent-based-checks-addons) using additional addons & tools.
Icinga 2 uses its own unique and secure communitication protol amongst instances. 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 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. 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 If you are planning to use the native Icinga 2 cluster feature for distributed
monitoring and high-availability, please continue reading in 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** > **Tip**
> >
@ -24,19 +24,19 @@ monitoring and high-availability, please continue reading in
If the remote service is available using a network protocol and port, 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 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 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 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), * [ping4](7-icinga-template-library.md#plugin-check-command-ping4), [ping6](7-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) [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](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) * [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](6-icinga-template-library.md#plugin-check-command-http), [ftp](6-icinga-template-library.md#plugin-check-command-ftp) * [http](7-icinga-template-library.md#plugin-check-command-http), [ftp](7-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), * [smtp](7-icinga-template-library.md#plugin-check-command-smtp), [ssmtp](7-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), [imap](7-icinga-template-library.md#plugin-check-command-imap), [simap](7-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) [pop](7-icinga-template-library.md#plugin-check-command-pop), [spop](7-icinga-template-library.md#plugin-check-command-spop)
* [ntp_time](6-icinga-template-library.md#plugin-check-command-ntp-time) * [ntp_time](7-icinga-template-library.md#plugin-check-command-ntp-time)
* [ssh](6-icinga-template-library.md#plugin-check-command-ssh) * [ssh](7-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) * [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 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). on the internet. If you found one for your requirements, [integrate them into Icinga 2](3-monitoring-basics.md#command-plugin-integration).
@ -47,7 +47,7 @@ Start your search at
* [Icinga Wiki](https://wiki.icinga.org) * [Icinga Wiki](https://wiki.icinga.org)
An example is provided in the sample configuration in the getting started 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 id="icinga2-remote-client-monitoring"></a> Monitoring Icinga 2 Remote Clients
@ -58,13 +58,13 @@ First, you should decide which role the remote client has:
* a remote command execution client (similar to NRPE, NSClient++, etc) * a remote command execution client (similar to NRPE, NSClient++, etc)
Later on, you will be asked again and told how to proceed with these 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** > **Note**
> >
> If you are planning to build an Icinga 2 distributed setup using the cluster feature, please skip > 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 > 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** > **Note**
> >
@ -73,7 +73,7 @@ different [roles](8-monitoring-remote-systems.md#icinga2-remote-monitoring-clien
## <a id="icinga2-remote-monitoring-master"></a> Master Setup for Remote Monitoring ## <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. you'll first need to update your master setup.
Your master setup requires the following Your master setup requires the following
@ -82,7 +82,7 @@ Your master setup requires the following
* Enabled API feature, and a local Endpoint and Zone object configuration * Enabled API feature, and a local Endpoint and Zone object configuration
* Firewall ACLs for the communication port (default 5665) * 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 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 will be updated to the icinga user the daemon is running as (certificate files
for example). for example).
@ -133,7 +133,7 @@ The setup wizard will do the following:
* Generate a new CSR, sign it with the local CA and copying it into `/etc/icinga2/pki` * 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 * 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` * 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. The setup wizard does not automatically restart Icinga 2.
@ -148,13 +148,13 @@ The setup wizard does not automatically restart Icinga 2.
## <a id="icinga2-remote-monitoring-client"></a> Client Setup for Remote Monitoring ## <a id="icinga2-remote-monitoring-client"></a> Client Setup for Remote Monitoring
Icinga 2 can be installed on Linux/Unix and Windows. While 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 `node wizard` for a guided setup, you will need to use the
graphical installer for Windows based client setup. graphical installer for Windows based client setup.
Your client setup requires the following 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)). * 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 * Enabled API feature, and a local Endpoint and Zone object configuration
* Firewall ACLs for the communication port (default 5665) * Firewall ACLs for the communication port (default 5665)
@ -168,8 +168,8 @@ Your client setup requires the following
If your remote clients are capable of connecting to the central master, Icinga 2 If your remote clients are capable of connecting to the central master, Icinga 2
supports CSR auto-signing. 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). 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](8-monitoring-remote-systems.md#icinga2-remote-monitoring-master) will create The [setup wizard for the master setup](9-monitoring-remote-systems.md#icinga2-remote-monitoring-master) will create
one for you already. one for you already.
# grep TicketSalt /etc/icinga2/constants.conf # grep TicketSalt /etc/icinga2/constants.conf
@ -188,16 +188,16 @@ Example for a client notebook:
> **Note** > **Note**
> >
> You can omit the `--salt` parameter using the `TicketSalt` constant from > 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. > reloaded after the master setup.
#### <a id="certificates-manual-creation"></a> Manual SSL Certificate Generation #### <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** > **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 #### <a id="icinga2-remote-monitoring-client-linux-setup"></a> Linux Client Setup Wizard for Remote Monitoring
@ -205,8 +205,8 @@ This is described separately in the [cluster setup chapter](8-monitoring-remote-
Install Icinga 2 from your distribution's package repository as described in the Install Icinga 2 from your distribution's package repository as described in the
general [installation instructions](2-getting-started.md#setting-up-icinga2). 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 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](8-monitoring-remote-systems.md#manual-certificate-generation). are fulfilled, or that you're using [manual SSL certificate generation](9-monitoring-remote-systems.md#manual-certificate-generation).
> **Note** > **Note**
> >
@ -222,7 +222,7 @@ You'll need the following configuration details:
* The client's local zone name. Defaults to FQDN. * 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 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 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 for CSR Auto-Signing
* Bind host/port for the Api feature (optional) * Bind host/port for the Api feature (optional)
@ -299,7 +299,7 @@ The setup wizard will do the following:
(based on FQDN) (based on FQDN)
* Disabling the notification feature for this client * Disabling the notification feature for this client
* Enabling the API feature, and setting optional `bind_host` and `bind_port` * 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 setup wizard does not automatically restart Icinga 2.
@ -325,7 +325,7 @@ You'll need the following configuration details:
* The client's local zone name. Defaults to FQDN. * 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 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 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 for CSR Auto-Signing
* Bind host/port for the Api feature (optional) * Bind host/port for the Api feature (optional)
@ -348,8 +348,8 @@ This scenario allows you to configure the checkable objects (hosts, services) on
your Icinga 2 master or satellite, and only send commands remotely. your Icinga 2 master or satellite, and only send commands remotely.
Requirements: Requirements:
* Exact same [CheckCommand](5-object-types.md#objecttype-checkcommand) (and * Exact same [CheckCommand](6-object-types.md#objecttype-checkcommand) (and
[EventCommand](5-object-types.md#objecttype-eventcommand)) configuration objects [EventCommand](6-object-types.md#objecttype-eventcommand)) configuration objects
on the master and the remote client(s). on the master and the remote client(s).
* Installed plugin scripts on the remote client (`PluginDir` constant can be locally modified) * Installed plugin scripts on the remote client (`PluginDir` constant can be locally modified)
* `Zone` and `Endpoint` configuration for the client on the master * `Zone` and `Endpoint` configuration for the client on the master
@ -357,9 +357,9 @@ on the master and the remote client(s).
endpoint endpoint
`CheckCommand` objects are already shipped with the Icinga 2 ITL `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 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. on your remote client.
#### <a id="icinga2-remote-monitoring-client-command-execution-client"></a> Client Configuration Remote Client for Command Execution #### <a id="icinga2-remote-monitoring-client-command-execution-client"></a> Client Configuration Remote Client for Command Execution
@ -395,8 +395,8 @@ in [zones.conf](#zones-conf) and define a trusted master zone as `parent`.
} }
More details here: More details here:
* [configure endpoints](8-monitoring-remote-systems.md#configure-cluster-endpoints) * [configure endpoints](9-monitoring-remote-systems.md#configure-cluster-endpoints)
* [configure zones](8-monitoring-remote-systems.md#configure-cluster-zones) * [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`: Configuration example for host and service objects running commands on the remote endpoint `remote-client1`:
@ -447,7 +447,7 @@ schedule client updates in your management tool (e.g. Puppet).
> clients. There are no local configured objects available. > clients. There are no local configured objects available.
> >
> If you require this, please install a full-featured > 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 ### <a id="icinga2-remote-monitoring-client-local-config"></a> Remote Client with Local Configuration
@ -519,7 +519,7 @@ using the following CLI command:
> **Note** > **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. > 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-discovery-generate-config"></a> Generate Icinga 2 Configuration for Client Services on the Master
@ -600,15 +600,15 @@ You can `list` and `remove` existing blacklists:
### <a id="icinga2-remote-monitoring-master-manual-add-endpoint-zone"></a> Manually add Client Endpoint and Zone Objects 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 node name](9-monitoring-remote-systems.md#configure-nodename)
* [configure the ApiListener object](8-monitoring-remote-systems.md#configure-apilistener-object) * [configure the ApiListener object](9-monitoring-remote-systems.md#configure-apilistener-object)
* [configure cluster endpoints](8-monitoring-remote-systems.md#configure-cluster-endpoints) * [configure cluster endpoints](9-monitoring-remote-systems.md#configure-cluster-endpoints)
* [configure cluster zones](8-monitoring-remote-systems.md#configure-cluster-zones) * [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 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`. in `zones.d`.
@ -622,10 +622,10 @@ become handy.
The SNMP daemon runs on the remote system and answers SNMP queries by plugin 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 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. 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 overrides the `snmp_oid` custom attribute. A service is created for all hosts which
have the `snmp-community` custom attribute. have the `snmp-community` custom attribute.
@ -638,7 +638,7 @@ have the `snmp-community` custom attribute.
assign where host.vars.snmp_community != "" 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 ### <a id="agent-based-checks-ssh"></a> SSH
@ -676,14 +676,14 @@ remote client.
> The NRPE protocol is considered insecure and has multiple flaws in its > The NRPE protocol is considered insecure and has multiple flaws in its
> design. Upstream is not willing to fix these issues. > 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. > instead.
The NRPE daemon uses its own configuration format in nrpe.cfg while `check_nrpe` The NRPE daemon uses its own configuration format in nrpe.cfg while `check_nrpe`
can be embedded into the Icinga 2 `CheckCommand` configuration syntax. 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. 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: Example:
@ -742,7 +742,7 @@ executed by the NRPE daemon looks similar to that:
/usr/local/icinga/libexec/check_disk -w 20% -c 10% -p / /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. when using its NRPE supported check method.
### <a id="agent-based-checks-nsclient"></a> NSClient++ ### <a id="agent-based-checks-nsclient"></a> NSClient++
@ -753,7 +753,7 @@ but using `NSClient++` will allow you to run local scripts similar to check plug
the required output and performance counters. the required output and performance counters.
You can use the `check_nt` plugin from the Monitoring Plugins project to query NSClient++. 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: Example:
@ -789,7 +789,7 @@ SNMP Traps can be received and filtered by using [SNMPTT](http://snmptt.sourcefo
and specific trap handlers passing the check results to Icinga 2. 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) 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. we can create generic services that can accommodate any number of hosts for a given scenario.
#### <a id="simple-traps"></a> Simple SNMP Traps #### <a id="simple-traps"></a> Simple SNMP Traps
@ -973,9 +973,9 @@ passive update with the state and text from the second and third varbind:
Building distributed environments with high availability included is fairly easy with Icinga 2. 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: 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. * [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](8-monitoring-remote-systems.md#cluster-scenarios-distributed-zones). A master zone and one or more satellites in their zones. * [Distributed Zones](9-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. * [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. You can combine these scenarios into a global setup fitting your requirements.
@ -999,18 +999,18 @@ Before you start deploying, keep the following things in mind:
* cluster zones can be built in a Top-Down-design where the child trusts the parent * 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 * 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 * 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** > **Tip**
> >
> If you're looking for troubleshooting cluster problems, check the general > 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 ### <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. for your Icinga 2 distributed setup.
> **Note** > **Note**
@ -1053,8 +1053,8 @@ the host's FQDN):
#### <a id="cluster-naming-convention"></a> Cluster Naming Convention #### <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) 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](5-object-types.md#objecttype-endpoint) object to determine the local authority. This name must match the local [Endpoint](6-object-types.md#objecttype-endpoint)
object name. object name.
Example: Example:
@ -1068,8 +1068,8 @@ Example:
host = "icinga2a.icinga.org" host = "icinga2a.icinga.org"
} }
The [Endpoint](5-object-types.md#objecttype-endpoint) name is further referenced as `endpoints` attribute on the The [Endpoint](6-object-types.md#objecttype-endpoint) name is further referenced as `endpoints` attribute on the
[Zone](5-object-types.md#objecttype-zone) object. [Zone](6-object-types.md#objecttype-zone) object.
object Endpoint "icinga2b" { object Endpoint "icinga2b" {
host = "icinga2b.icinga.org" host = "icinga2b.icinga.org"
@ -1079,7 +1079,7 @@ The [Endpoint](5-object-types.md#objecttype-endpoint) name is further referenced
endpoints = [ "icinga2a", "icinga2b" ] 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. the same name as used for the endpoint name and common name above. If not set, the FQDN is used.
const NodeName = "icinga2a" const NodeName = "icinga2a"
@ -1090,19 +1090,19 @@ the same name as used for the endpoint name and common name above. If not set, t
The following section describe which configuration must be updated/created The following section describe which configuration must be updated/created
in order to get your cluster running with basic functionality. in order to get your cluster running with basic functionality.
* [configure the node name](8-monitoring-remote-systems.md#configure-nodename) * [configure the node name](9-monitoring-remote-systems.md#configure-nodename)
* [configure the ApiListener object](8-monitoring-remote-systems.md#configure-apilistener-object) * [configure the ApiListener object](9-monitoring-remote-systems.md#configure-apilistener-object)
* [configure cluster endpoints](8-monitoring-remote-systems.md#configure-cluster-endpoints) * [configure cluster endpoints](9-monitoring-remote-systems.md#configure-cluster-endpoints)
* [configure cluster zones](8-monitoring-remote-systems.md#configure-cluster-zones) * [configure cluster zones](9-monitoring-remote-systems.md#configure-cluster-zones)
Once you're finished with the basic setup the following section will 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) describe how to use [zone configuration synchronisation](9-monitoring-remote-systems.md#cluster-zone-config-sync)
and configure [cluster scenarios](8-monitoring-remote-systems.md#cluster-scenarios). and configure [cluster scenarios](9-monitoring-remote-systems.md#cluster-scenarios).
#### <a id="configure-nodename"></a> Configure the Icinga Node Name #### <a id="configure-nodename"></a> Configure the Icinga Node Name
Instead of using the default FQDN as node name you can optionally set 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 ** > ** Note **
> >
@ -1110,9 +1110,9 @@ that value using the [NodeName](15-language-reference.md#constants) constant.
> in `/etc/icinga2/constants.conf`. > in `/etc/icinga2/constants.conf`.
This setting must be unique for each node, and must also match 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 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 vim /etc/icinga2/constants.conf
@ -1122,14 +1122,14 @@ SSL certificate common name as described in the
const NodeName = "icinga2a" 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 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. configured endpoint names and common names are in sync.
#### <a id="configure-apilistener-object"></a> Configure the ApiListener Object #### <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: every node in the cluster with the following settings:
A sample config looks like: A sample config looks like:
@ -1177,9 +1177,9 @@ If this endpoint object is reachable on a different port, you must configure the
`Zone` objects specify the endpoints located in a zone. That way your distributed setup can be `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. 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), Zones can be used for [high availability](9-monitoring-remote-systems.md#cluster-scenarios-high-availability),
[distributed setups](8-monitoring-remote-systems.md#cluster-scenarios-distributed-zones) and [distributed setups](9-monitoring-remote-systems.md#cluster-scenarios-distributed-zones) and
[load distribution](8-monitoring-remote-systems.md#cluster-scenarios-load-distribution). [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 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 define the zone `config-ha-master` where the `icinga2a` and `icinga2b` endpoints
@ -1214,21 +1214,21 @@ on the configuration master.
Your child zones and endpoint members **must not** have their config copied to `zones.d`. 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 The built-in configuration synchronisation takes care of that if your nodes accept
configuration from the parent zone. You can define that in the 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. attribute accordingly.
You should remove the sample config included in `conf.d` by commenting the `recursive_include` 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" //include_recursive "conf.d"
Better use a dedicated directory name like `cluster` or similar, and include that 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 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** > **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 > 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. > member nodes **must not** have the `/etc/icinga2/zones.d` directory populated.
@ -1237,7 +1237,7 @@ to their respective target zone instances.
Each configured zone must exist with the same directory name. The parent zone 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` 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`: Config on node `icinga2a`:
@ -1276,9 +1276,9 @@ process.
> **Note** > **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 > 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-global-config-templates"></a> Global Configuration Zone for Templates
@ -1325,7 +1325,7 @@ If you don't require any global configuration, skip this setting.
#### <a id="zone-config-sync-permissions"></a> Zone Configuration Synchronisation Permissions #### <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`. set to `true` to receive configuration from the parent `Zone` members. Default value is `false`.
object ApiListener "api" { object ApiListener "api" {
@ -1340,13 +1340,13 @@ master instances anymore.
> ** Tip ** > ** 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. > problems with the configuration synchronisation.
### <a id="cluster-health-check"></a> Cluster Health Check ### <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 `EndPoints` in the cluster setup. The check result will become critical if
one or more configured nodes are not connected. one or more configured nodes are not connected.
@ -1395,7 +1395,7 @@ additional security itself:
* Child zones only receive event updates (check results, commands, etc) for their configured updates. * 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. * Zones cannot influence/interfere other zones. Each checked object is assigned to only one zone.
* All nodes in a zone trust each other. * 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 #### <a id="cluster-scenarios-features"></a> Features in Cluster Zones
@ -1406,11 +1406,11 @@ re-schedule a check or acknowledge a problem on the master, and it gets replicat
actual slave checker node. actual slave checker node.
DB IDO on the left, graphite on the right side - works (if you disable 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. 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 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 [load-balanced notifications and checks](9-monitoring-remote-systems.md#high-availability-features) in a
[HA zone](8-monitoring-remote-systems.md#cluster-scenarios-high-availability). [HA zone](9-monitoring-remote-systems.md#cluster-scenarios-high-availability).
configure-cluster-zones configure-cluster-zones
#### <a id="cluster-scenarios-distributed-zones"></a> Distributed Zones #### <a id="cluster-scenarios-distributed-zones"></a> Distributed Zones
@ -1425,7 +1425,7 @@ graphing, etc. in their own specified zone.
Imagine the following example with a master node in Nuremberg, and two remote DMZ Imagine the following example with a master node in Nuremberg, and two remote DMZ
based instances in Berlin and Vienna. Additonally you'll specify 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 configuration tree on the master instance `nuremberg` could look like this:
@ -1489,7 +1489,7 @@ check results from the satellite nodes in the zones `berlin` and `vienna`.
> The child zones `berlin` and `vienna` will get their configuration synchronised > The child zones `berlin` and `vienna` will get their configuration synchronised
> from the configuration master 'nuremberg'. The endpoints in the child > from the configuration master 'nuremberg'. The endpoints in the child
> zones **must not** have their `zones.d` directory populated if this endpoint > 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 #### <a id="cluster-scenarios-load-distribution"></a> Load Distribution
@ -1548,15 +1548,15 @@ Zones:
> The child zones `checker` will get its configuration synchronised > The child zones `checker` will get its configuration synchronised
> from the configuration master 'master'. The endpoints in the child > from the configuration master 'master'. The endpoints in the child
> zone **must not** have their `zones.d` directory populated if this endpoint > 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 #### <a id="cluster-scenarios-high-availability"></a> Cluster High Availability
High availability with Icinga 2 is possible by putting multiple nodes into 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. 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 Checks and notifications are load-balanced between nodes in the high availability
zone. zone.
@ -1568,15 +1568,15 @@ commands, etc.
endpoints = [ "icinga2a", "icinga2b", "icinga2c" ] 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** > **Note**
> >
> Keep in mind that **only one node acts as configuration master** having the > 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** > configuration files in the `zones.d` directory. All other nodes **must not**
> have that directory populated. Instead they are required to > have that directory populated. Instead they are required to
> [accept synced configuration](8-monitoring-remote-systems.md#zone-config-sync-permissions). > [accept synced configuration](9-monitoring-remote-systems.md#zone-config-sync-permissions).
> Details in the [Configuration Sync Chapter](8-monitoring-remote-systems.md#cluster-zone-config-sync). > Details in the [Configuration Sync Chapter](9-monitoring-remote-systems.md#cluster-zone-config-sync).
#### <a id="cluster-scenarios-multiple-hierarchies"></a> Multiple Hierarchies #### <a id="cluster-scenarios-multiple-hierarchies"></a> Multiple Hierarchies
@ -1610,9 +1610,9 @@ amongst them.
By default the following features provide advanced HA functionality: By default the following features provide advanced HA functionality:
* [Checks](8-monitoring-remote-systems.md#high-availability-checks) (load balanced, automated failover) * [Checks](9-monitoring-remote-systems.md#high-availability-checks) (load balanced, automated failover)
* [Notifications](8-monitoring-remote-systems.md#high-availability-notifications) (load balanced, automated failover) * [Notifications](9-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) * [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 #### <a id="high-availability-checks"></a> High Availability with Checks
@ -1633,7 +1633,7 @@ Notifications are load balanced amongst all nodes in a zone. By default this fun
is enabled. is enabled.
If your nodes should notify independent from any other nodes (this will cause 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` 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 #### <a id="high-availability-db-ido"></a> High Availability with DB IDO
@ -1651,8 +1651,8 @@ nodes disable the active IDO database connection at runtime.
> **Note** > **Note**
> >
> The DB IDO HA feature can be disabled by setting the `enable_ha` attribute to `false` > 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 > for the [IdoMysqlConnection](6-object-types.md#objecttype-idomysqlconnection) or
> [IdoPgsqlConnection](5-object-types.md#objecttype-idopgsqlconnection) object on all nodes in the > [IdoPgsqlConnection](6-object-types.md#objecttype-idopgsqlconnection) object on all nodes in the
> same zone. > same zone.
> >
> All endpoints will enable the DB IDO feature then, connect to the configured > All endpoints will enable the DB IDO feature then, connect to the configured
@ -1682,11 +1682,11 @@ These steps are required for integrating a new cluster endpoint:
* generate a new [SSL client certificate](#certificate-authority-certificates) * generate a new [SSL client certificate](#certificate-authority-certificates)
* identify its location in the zones * 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 * 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 * 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](8-monitoring-remote-systems.md#initial-cluster-sync) * if the node requires the existing zone history: [initial cluster sync](9-monitoring-remote-systems.md#initial-cluster-sync)
* add a [cluster health check](8-monitoring-remote-systems.md#cluster-health-check) * add a [cluster health check](9-monitoring-remote-systems.md#cluster-health-check)
#### <a id="initial-cluster-sync"></a> Initial Cluster Sync #### <a id="initial-cluster-sync"></a> Initial Cluster Sync
@ -1705,7 +1705,7 @@ Special scenarios might require multiple cluster nodes running on a single host.
By default Icinga 2 and its features will place their runtime data below the prefix 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`. `LocalStateDir`. By default packages will set that path to `/var`.
You can either set that variable as constant configuration 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. the Icinga 2 daemon.
# icinga2 -c /etc/icinga2/node1/icinga2.conf -DLocalStateDir=/opt/node1/var # icinga2 -c /etc/icinga2/node1/icinga2.conf -DLocalStateDir=/opt/node1/var

29
mkdocs.yml
View File

@ -5,20 +5,21 @@ pages:
- [1-about.md, About Icinga 2] - [1-about.md, About Icinga 2]
- [2-getting-started.md, Getting Started] - [2-getting-started.md, Getting Started]
- [3-monitoring-basics.md, Monitoring Basics] - [3-monitoring-basics.md, Monitoring Basics]
- [4-configuring-icinga-2.md, Configuring Icinga 2] - [4-advanced-topics.md, Advanced Topics]
- [5-object-types.md, Object Types] - [5-configuring-icinga-2.md, Configuring Icinga 2]
- [6-icinga-template-library.md, Icinga Template Library] - [6-object-types.md, Object Types]
- [7-cli-commands.md, CLI Commands] - [7-icinga-template-library.md, Icinga Template Library]
- [8-monitoring-remote-systems.md, Monitoring Remote Systems] - [8-cli-commands.md, CLI Commands]
- [9-addons-plugins.md, Addons and Plugins] - [9-monitoring-remote-systems.md, Monitoring Remote Systems]
- [10-alternative-frontends.md, Alternative Frontends] - [10-addons-plugins.md, Addons and Plugins]
- [11-livestatus.md, Livestatus] - [11-alternative-frontends.md, Alternative Frontends]
- [12-troubleshooting.md, Troubleshooting] - [12-livestatus.md, Livestatus]
- [13-upgrading-icinga-2.md, Upgrading Icinga 2] - [13-troubleshooting.md, Troubleshooting]
- [14-migrating-from-icinga-1x.md, Migrating from Icinga 1.x] - [14-upgrading-icinga-2.md, Upgrading Icinga 2]
- [15-language-reference.md, Language Reference] - [15-migrating-from-icinga-1x.md, Migrating from Icinga 1.x]
- [16-library-reference.md, Library Reference] - [16-language-reference.md, Language Reference]
- [17-appendix.md, Appendix] - [17-library-reference.md, Library Reference]
- [18-appendix.md, Appendix]
theme: readthedocs theme: readthedocs
markdown_extensions: [smarty] markdown_extensions: [smarty]
extra_javascript: [scroll.js] extra_javascript: [scroll.js]