#### <a id="hosts-conf"></a> 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
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.
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.
#### <a id="installing-ido-mysql"></a> Installing the IDO MySQL module
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.
#### <a id="installing-ido-postgresql"></a> Installing the IDO PostgreSQL module
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)
* `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"
-}
+#### <a id="icinga2-remote-monitoring-client-command-execution-client"></a> 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.
+
+Edit the `api` feature configuration in `/etc/icinga2/features-enabled/api.conf`
+and set `accept_commands` to `true`.
+
+ 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
+ }
+
+#### <a id="icinga2-remote-monitoring-client-command-execution-master"></a> Master Configuration Remote Client for Command Execution
+
+Add an `Endpoint` and `Zone` configuration object for the remote client
+in [zones.conf](#zones-conf) and define a trusted master zone as `parent`.
+
+ object Endpoint "remote-client1" {
+ host = "192.168.33.20"
+ }
-Example for host and service object configuration running commands on the remote endpoint:
+ object Zone "remote-client1" {
+ endpoints = [ "remote-client1" ]
+ parent = "master"
+ }
-object Host "host-remote" {
- import "generic-host"
+More details here:
+* [configure endpoints](#configure-cluster-endpoints)
+* [configure zones](#configure-cluster-zones)
- address = "127.0.0.1"
- address6 = "::1"
- vars.os = "Linux"
+Configuration example for host and service objects running commands on the remote endpoint `remote-client1`:
- vars.remote_client = "remote-client1"
+ object Host "host-remote" {
+ import "generic-host"
- /* host specific check arguments */
- vars.users_wgreater = 10
- vars.users_wgreater = 20
-}
+ address = "127.0.0.1"
+ address6 = "::1"
-apply Service "users-remote" {
- import "generic-service"
+ vars.os = "Linux"
- check_command = "users"
- command_endpoint = host.vars.remote_client
+ vars.remote_client = "remote-client1"
- /* override (remote) command arguments with host settings */
- vars.users_wgreater = host.vars.users_wgreater
- vars.users_cgreater = host.vars.users_cgreater
+ /* host specific check arguments */
+ vars.users_wgreater = 10
+ vars.users_wgreater = 20
+ }
- /* assign where a remote client is set */
- assign where host.vars.remote_client
-}
+ 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).
### <a id="icinga2-remote-monitoring-client-local-config"></a> Remote Client with Local Configuration
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**
>
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
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`.
### <a id="objecttype-endpoint"></a> Endpoint
projects / icinga2 / commitdiff