diff --git a/doc/5-monitoring-remote-systems.md b/doc/5-monitoring-remote-systems.md
index 64ca91764..28f44e538 100644
--- a/doc/5-monitoring-remote-systems.md
+++ b/doc/5-monitoring-remote-systems.md
@@ -45,14 +45,20 @@ Start your search at
* [Icinga Exchange](https://exchange.icinga.org)
* [Icinga Wiki](https://wiki.icinga.org)
-*
+
+An example is provided in the sample configuration in the getting started
+section shipped with Icinga 2 ([hosts.conf](#hosts-conf), [services.conf](#services-conf)).
## Monitoring Icinga 2 Remote Clients
First, you should decide which role the remote client has:
-* a single host with local checks
+* a single host with local checks and configuration
* a remote satellite checking other hosts (for example in your DMZ)
+* a remote command execution client (similar to NRPE, NSClient++, etc)
+
+Later on, you will be asked again and told how to proceed with these
+different [roles](#icinga2-remote-monitoring-client-roles).
> **Note**
>
@@ -286,8 +292,7 @@ Make sure to answer the first question with `n` (no).
The setup wizard will do the following:
-* Generate a local CA in `/var/lib/icinga2/ca` or use the existing one
-* Generate a new CSR, sign it with the local CA and copying it into `/etc/icinga2/pki`
+* Generate a new self-signed certificate and copy it into `/etc/icinga2/pki`
* Store the master's certificate as trusted certificate for requesting a new signed certificate
(manual step when using `node setup`).
* Request a new signed certificate from the master and store updated certificate and master CA in `/etc/icinga2/pki`
@@ -327,10 +332,92 @@ for CSR Auto-Signing
Once install is done, Icinga 2 is automatically started as a Windows service.
+### Remote Monitoring Client Roles
+
+Icinga 2 allows you to use two separate ways of defining a client (or: `agent`) role:
+
+* execute commands remotely, but host/service configuration happens on the master.
+* schedule remote checks on remote satellites with their local configuration.
+
+Depending on your scenario, either one or both combined with a cluster setup
+could be build and put together.
+### Remote Client for Command Execution
-### Client Configuration for Remote Monitoring
+This scenario allows you to configure the checkable objects (hosts, services) on
+your Icinga 2 master or satellite, and only send commands remotely.
+
+Requirements:
+* Exact same [CheckCommand](#objecttype-checkcommand) (and
+[EventCommand](#objecttype-eventcommand)) configuration objects
+on the master and the remote client(s).
+* Installed plugin scripts on the remote client (`PluginDir` constant can be locally modified)
+* `Zone` and `Endpoint` configuration for the client on the master
+* `command_endpoint` attribute configured for host/service objects pointing to the configured
+endpoint
+
+Example for communication configuration:
+
+object Endpoint "remote-client1" {
+ host = "192.168.33.20"
+}
+
+object Zone "remote-client1" {
+ endpoints = [ "remote-client1" ]
+ parent = "master"
+}
+
+Example for host and service object configuration running commands on the remote endpoint:
+
+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
+you'll also get the running Icinga 2 version and may
+schedule client updates in your management tool (e.g. Puppet).
+
+
+### Remote Client with Local Configuration
+
+This is considered as independant satellite using a local scheduler, configuration
+and the possibility to add Icinga 2 features on demand.
+
+Local configured checks are transferred to the central master and helped
+with discovery cli commands.
+
+Please follow the instructions closely in order to deploy your fully featured
+client, or `agent` as others might call it.
+
+#### Client Configuration for Remote Monitoring
There is no difference in the configuration syntax on clients to any other Icinga 2 installation.
@@ -354,7 +441,7 @@ You can also use additional features like notifications directly on the remote c
required to. Basically everything a single Icinga 2 instance provides by default.
-### Discover Client Services on the Master
+#### Discover Client Services on the Master
Icinga 2 clients will sync their locally defined objects to the defined master node. That way you can
list, add, filter and remove nodes based on their `node`, `zone`, `host` or `service` name.
@@ -542,6 +629,14 @@ the required plugins and command definitions.
Icinga 2 calls the `check_nrpe` plugin binary in order to query the configured command on the
remote client.
+> **Note**
+>
+> The NRPE protocol is considered insecure and has multiple flaws in its
+> design. Upstream is not willing to fix these issues.
+>
+> In order to stay safe, please use the native [Icinga 2 client](#icinga2-remote-monitoring-master)
+> instead.
+
The NRPE daemon uses its own configuration format in nrpe.cfg while `check_nrpe`
can be embedded into the Icinga 2 `CheckCommand` configuration syntax.