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.