diff --git a/doc/2-getting-started.md b/doc/2-getting-started.md
index 6878f8cee..5319b2456 100644
--- a/doc/2-getting-started.md
+++ b/doc/2-getting-started.md
@@ -436,8 +436,10 @@ Available configuration files shipped by default:
#### hosts.conf
-The `conf.d/hosts.conf` file contains an example host based on your
-`NodeName` setting in [constants.conf](#constants-conf).
+The `hosts.conf` file contains an example host based on your
+`NodeName` setting in [constants.conf](#constants-conf). You
+can use global constants for your object names instead of string
+values.
The `import` keyword is used to import the `generic-host` template which
takes care of setting up the host check command to `hostalive`. If you
@@ -885,7 +887,12 @@ Further details on the monitoring configuration can be found in the
The DB IDO (Database Icinga Data Output) modules for Icinga 2 take care of exporting
all configuration and status information into a database. The IDO database is used
-by a number of projects including Icinga Web 1.x, Reporting or Icinga Web 2.
+by a number of projects including [Icinga Web 2](#setting-up-icingaweb2),
+Icinga Reporting or Icinga Web 1.x.
+
+Icinga 2 does not read configuration or status data from the database backend
+so this interface is fully optional, if not required by your user interfaces
+or addons.
There is a separate module for each database back-end. At present support for
both MySQL and PostgreSQL is implemented.
@@ -1024,13 +1031,14 @@ The Icinga 2 DB IDO module will check for the required database schema version o
and generate an error message if not satisfied.
-**Example:** You are upgrading Icinga 2 from version `2.0.2` to `2.1.0`. Look into
+**Example:** You are upgrading Icinga 2 from version `2.0.2` to `2.2.0`. Look into
the *upgrade* directory:
$ ls /usr/share/icinga2-ido-mysql/schema/upgrade/
- 2.0.2.sql 2.1.0.sql
+ 2.0.2.sql 2.1.0.sql 2.2.0.sql
-There is a new upgrade file called `2.1.0.sql` which must be applied to your IDO database.
+There are two new upgrade files called `2.1.0.sql` and `2.2.0.sql`
+which must be applied incrementially to your IDO database.
#### Installing the IDO MySQL module
@@ -1141,9 +1149,10 @@ and generate an error message if not satisfied.
the *upgrade* directory:
$ ls /usr/share/icinga2-ido-pgsql/schema/upgrade/
- 2.0.2.sql 2.1.0.sql
+ 2.0.2.sql 2.1.0.sql 2.2.0.sql
-There is a new upgrade file called `2.1.0.sql` which must be applied to your IDO database.
+There are two new upgrade files called `2.1.0.sql` and `2.2.0.sql`
+which must be applied incrementially to your IDO database.
#### Installing the IDO PostgreSQL module
diff --git a/doc/5-monitoring-remote-systems.md b/doc/5-monitoring-remote-systems.md
index 28f44e538..db2276e1b 100644
--- a/doc/5-monitoring-remote-systems.md
+++ b/doc/5-monitoring-remote-systems.md
@@ -154,6 +154,7 @@ graphical installer for Windows based client setup.
Your client setup requires the following
+* A ready configured and installed [master node](#icinga2-remote-monitoring-master)
* SSL signed certificate for communication with the master (Use [CSR auto-signing](certifiates-csr-autosigning)).
* Enabled API feature, and a local Endpoint and Zone object configuration
* Firewall ACLs for the communication port (default 5665)
@@ -357,54 +358,98 @@ on the master and the remote client(s).
* `command_endpoint` attribute configured for host/service objects pointing to the configured
endpoint
-Example for communication configuration:
+`CheckCommand` objects are already shipped with the Icinga 2 ITL
+as [plugin check commands](#plugin-check-commands). If you are
+using your own configuration definitions for example in
+[commands.conf](#commands-conf) make sure to copy/sync it
+on your remote client.
-object Endpoint "remote-client1" {
- host = "192.168.33.20"
-}
+#### Client Configuration Remote Client for Command Execution
-object Zone "remote-client1" {
- endpoints = [ "remote-client1" ]
- parent = "master"
-}
+> **Note**
+>
+> Remote clients must explicitely accept commands in a similar
+> fashion as cluster nodes [accept configuration]#i(cluster-zone-config-sync).
+> This is due to security reasons.
-Example for host and service object configuration running commands on the remote endpoint:
+Edit the `api` feature configuration in `/etc/icinga2/features-enabled/api.conf`
+and set `accept_commands` to `true`.
-object Host "host-remote" {
- import "generic-host"
+ object ApiListener "api" {
+ cert_path = SysconfDir + "/icinga2/pki/" + NodeName + ".crt"
+ key_path = SysconfDir + "/icinga2/pki/" + NodeName + ".key"
+ ca_path = SysconfDir + "/icinga2/pki/ca.crt"
+ accept_commands = true
+ }
- address = "127.0.0.1"
- address6 = "::1"
+#### Master Configuration Remote Client for Command Execution
- vars.os = "Linux"
+Add an `Endpoint` and `Zone` configuration object for the remote client
+in [zones.conf](#zones-conf) and define a trusted master zone as `parent`.
- vars.remote_client = "remote-client1"
+ object Endpoint "remote-client1" {
+ host = "192.168.33.20"
+ }
- /* host specific check arguments */
- vars.users_wgreater = 10
- vars.users_wgreater = 20
-}
+ object Zone "remote-client1" {
+ endpoints = [ "remote-client1" ]
+ parent = "master"
+ }
-apply Service "users-remote" {
- import "generic-service"
+More details here:
+* [configure endpoints](#configure-cluster-endpoints)
+* [configure zones](#configure-cluster-zones)
- check_command = "users"
- command_endpoint = host.vars.remote_client
- /* override (remote) command arguments with host settings */
- vars.users_wgreater = host.vars.users_wgreater
- vars.users_cgreater = host.vars.users_cgreater
+Configuration example for host and service objects running commands on the remote endpoint `remote-client1`:
- /* assign where a remote client is set */
- assign where host.vars.remote_client
-}
+ object Host "host-remote" {
+ import "generic-host"
+
+ address = "127.0.0.1"
+ address6 = "::1"
+
+ vars.os = "Linux"
+
+ vars.remote_client = "remote-client1"
+
+ /* host specific check arguments */
+ vars.users_wgreater = 10
+ vars.users_wgreater = 20
+ }
+
+ apply Service "users-remote" {
+ import "generic-service"
+
+ check_command = "users"
+ command_endpoint = host.vars.remote_client
+
+ /* override (remote) command arguments with host settings */
+ vars.users_wgreater = host.vars.users_wgreater
+ vars.users_cgreater = host.vars.users_cgreater
+
+ /* assign where a remote client is set */
+ assign where host.vars.remote_client
+ }
That way you can also execute the `icinga` check remotely
-verifying the health of your remote client(s). As a bonus
+thus verifying the health of your remote client(s). As a bonus
you'll also get the running Icinga 2 version and may
schedule client updates in your management tool (e.g. Puppet).
+> **Tip**
+>
+> [Event commands](#event-commands) are executed on the
+> remote command endpoint as well. You do not need
+> an additional transport layer such as SSH or similar.
+
+> **Note**
+> You cannot add any Icinga 2 features like DB IDO on the remote
+> clients. There are no local configured objects available.
+>
+> If you require this, please install a full-featured
+> [local client](#icinga2-remote-monitoring-client-local-config).
### Remote Client with Local Configuration
diff --git a/doc/7-configuring-icinga-2.md b/doc/7-configuring-icinga-2.md
index 0b23d2933..cb10fc3bc 100644
--- a/doc/7-configuring-icinga-2.md
+++ b/doc/7-configuring-icinga-2.md
@@ -649,11 +649,12 @@ Attributes:
flapping\_threshold|**Optional.** The flapping threshold in percent when a host is considered to be flapping.
volatile |**Optional.** The volatile setting enables always `HARD` state types if `NOT-OK` state changes occur.
zone |**Optional.** The zone this object is a member of.
+ command\_endpoint|**Optional.** The endpoint where commands are executed on.
notes |**Optional.** Notes for the host.
- notes_url |**Optional.** Url for notes for the host (for example, in notification commands).
- action_url |**Optional.** Url for actions for the host (for example, an external graphing tool).
- icon_image |**Optional.** Icon image for the host. Used by external interfaces only.
- icon_image_alt |**Optional.** Icon image description for the host. Used by external interface only.
+ notes\_url |**Optional.** Url for notes for the host (for example, in notification commands).
+ action\_url |**Optional.** Url for actions for the host (for example, an external graphing tool).
+ icon\_image |**Optional.** Icon image for the host. Used by external interfaces only.
+ icon\_image\_alt|**Optional.** Icon image description for the host. Used by external interface only.
> **Best Practice**
>
@@ -736,11 +737,12 @@ Attributes:
flapping\_threshold|**Optional.** The flapping threshold in percent when a service is considered to be flapping.
volatile |**Optional.** The volatile setting enables always `HARD` state types if `NOT-OK` state changes occur.
zone |**Optional.** The zone this object is a member of.
+ command\_endpoint|**Optional.** The endpoint where commands are executed on.
notes |**Optional.** Notes for the service.
- notes_url |**Optional.** Url for notes for the service (for example, in notification commands).
+ notes\_url |**Optional.** Url for notes for the service (for example, in notification commands).
action_url |**Optional.** Url for actions for the service (for example, an external graphing tool).
- icon_image |**Optional.** Icon image for the service. Used by external interfaces only.
- icon_image_alt |**Optional.** Icon image description for the service. Used by external interface only.
+ icon\_image |**Optional.** Icon image for the service. Used by external interfaces only.
+ icon\_image\_alt|**Optional.** Icon image description for the service. Used by external interface only.
Service objects have composite names, i.e. their names are based on the host_name attribute and the name you specified. This means
@@ -1775,6 +1777,7 @@ Attributes:
bind\_host |**Optional.** The IP address the api listener should be bound to. Defaults to `0.0.0.0`.
bind\_port |**Optional.** The port the api listener should be bound to. Defaults to `5665`.
accept\_config |**Optional.** Accept zone configuration. Defaults to `false`.
+ accept\_commands |**Optional.** Accept remote commands. Defaults to `false`.
### Endpoint