1 # <a id="icinga2-client"></a> Icinga 2 Client
3 ## <a id="icinga2-client-introduction"></a> Introduction
5 Icinga 2 uses its own unique and secure communitication protol amongst instances.
6 Be it an High-Availability cluster setup, distributed load-balanced setup or just a single
7 agent [monitoring a remote client](11-icinga2-client.md#icinga2-client).
9 All communication is secured by TLS with certificates, and fully supports IPv4 and IPv6.
11 If you are planning to use the native Icinga 2 cluster feature for distributed
12 monitoring and high-availability, please continue reading in
13 [this chapter](distributed-monitoring-high-availability).
17 > Don't panic - there are CLI commands available, including setup wizards for easy installation
18 > with SSL certificates.
19 > If you prefer to use your own CA (for example Puppet) you can do that as well.
22 ## <a id="icinga2-client-scenarios"></a> Client Scenarios
24 * Clients with [local configuration](11-icinga2-client.md#icinga2-client-configuration-local), sending their inventory to the master
25 * Clients as [command execution bridge](11-icinga2-client.md#icinga2-client-configuration-command-bridge) without local configuration
26 * Clients receive their configuration from the master ([Cluster config sync](11-icinga2-client.md#icinga2-client-configuration-master-config-sync))
28 Keep the [naming convention](13-distributed-monitoring-ha.md#cluster-naming-convention) for nodes in mind.
32 > If you're looking for troubleshooting clients problems, check the general
33 > [cluster troubleshooting](16-troubleshooting.md#troubleshooting-cluster) section.
35 ### <a id="icinga2-client-configuration-combined-scenarios"></a> Combined Client Scenarios
37 If your setup consists of remote clients with local configuration but also command execution bridges
38 and probably syncing global templates through the cluster config sync, you should take a deep
39 breath and take pen and paper to draw your design before starting over.
41 Keep the following hints in mind:
43 * You can blacklist remote nodes entirely. They are then ignored on `node update-config`
45 * Your remote instance can have local configuration **and** act as remote command execution bridge.
46 * You can use the `global` cluster zones to sync check commands, templates, etc to your remote clients.
47 Be it just for command execution or for helping the local configuration.
48 * If your remote clients shouldn't have local configuration, remove `conf.d` inclusion from `icinga2`
49 and simply use the cluster configuration sync.
50 * `accept_config` and `accept_commands` are disabled by default in the `api` feature
52 If you are planning to use the Icinga 2 client inside a distributed setup, refer to
53 [this chapter](13-distributed-monitoring-ha.md#cluster-scenarios-master-satellite-clients) with detailed instructions.
56 ## <a id="icinga2-client-installation"></a> Installation
58 ### <a id="icinga2-client-installation-firewall"></a> Configure the Firewall
60 Icinga 2 master, satellite and client instances communicate using the default tcp
63 Communication between zones requires one of these connection directions:
65 * The parent zone nodes are able to connect to the child zone nodes (`parent => child`).
66 * The child zone nodes are able to connect to the parent zone nodes (`parent <= child`).
67 * Both connnection directions work.
69 If you are going to use CSR-Autosigning, you must (temporarly) allow the client
70 connecting to the master instance and open the firewall port. Once the client install is done,
71 you can close the port and use a different communication direction (master-to-client).
73 In case of a [multiple hierarchy setup](13-distributed-monitoring-ha.md#cluster-scenarios-master-satellite-clients)
74 (master, satellite, client) you will need to manually deploy your [client certificates](11-icinga2-client.md#certificates-manual-creation)
75 and zone configuration.
77 ### <a id="icinga2-client-installation-master-setup"></a> Setup the Master for Remote Clients
79 If you are planning to use the [remote Icinga 2 clients](11-icinga2-client.md#icinga2-client)
80 you'll first need to update your master setup.
82 Your master setup requires the following
84 * SSL CA and signed certificate for the master
85 * Enabled API feature, and a local Endpoint and Zone object configuration
86 * Firewall ACLs for the communication port (default 5665)
88 You can use the [CLI command](8-cli-commands.md#cli-command-node) `node wizard` for setting up a new node
89 on the master. The command must be run as root, all Icinga 2 specific files
90 will be updated to the icinga user the daemon is running as (certificate files
93 Make sure to answer the first question with `n` (no).
95 nbmif /etc/icinga2 # icinga2 node wizard
96 Welcome to the Icinga 2 Setup Wizard!
98 We'll guide you through all required configuration details.
100 Please specify if this is a satellite setup ('n' installs a master setup) [Y/n]: n
101 Starting the Master setup routine...
102 Please specifiy the common name (CN) [icinga2-node1.localdomain]:
103 Checking the 'api' feature...
104 'api' feature not enabled, running 'api setup' now.
105 information/cli: Generating new CA.
107 information/base: Writing private key to '/var/lib/icinga2/ca/ca.key'.
108 information/base: Writing X509 certificate to '/var/lib/icinga2/ca/ca.crt'.
109 information/cli: Initializing serial file in '/var/lib/icinga2/ca/serial.txt'.
110 information/cli: Generating new CSR in '/etc/icinga2/pki/icinga2-node1.localdomain.csr'.
112 information/base: Writing private key to '/etc/icinga2/pki/icinga2-node1.localdomain.key'.
113 information/base: Writing certificate signing request to '/etc/icinga2/pki/icinga2-node1.localdomain.csr'.
114 information/cli: Signing CSR with CA and writing certificate to '/etc/icinga2/pki/icinga2-node1.localdomain.crt'.
116 information/cli: Copying CA certificate to '/etc/icinga2/pki/ca.crt'.
118 information/cli: Adding new ApiUser 'root' in '/etc/icinga2/conf.d/api-users.conf'.
120 information/cli: Enabling the ApiListener feature.
122 Enabling feature api. Make sure to restart Icinga 2 for these changes to take effect.
123 information/cli: Dumping config items to file '/etc/icinga2/zones.conf'.
124 Please specify the API bind host/port (optional):
127 information/cli: Updating constants.conf.
128 information/cli: Updating constants file '/etc/icinga2/constants.conf'.
129 information/cli: Updating constants file '/etc/icinga2/constants.conf'.
132 Now restart your Icinga 2 daemon to finish the installation!
135 The setup wizard will do the following:
137 * Check if the `api` feature is already enabled, and if not:
138 * Generate a local CA in `/var/lib/icinga2/ca` or use the existing one
139 * Generate a new CSR, sign it with the local CA and copying it into `/etc/icinga2/pki`
140 * Enabling the API feature, and setting optional `bind_host` and `bind_port`
141 * Generate a local zone and endpoint configuration for this master based on FQDN
142 * Setting the `NodeName` and `TicketSalt` constants in [constants.conf](4-configuring-icinga-2.md#constants-conf)
144 The setup wizard does not automatically restart Icinga 2.
146 Verify the modified configuration:
148 # egrep 'NodeName|TicketSalt' /etc/icinga2/constants.conf
150 # cat /etc/icinga2/zones.conf
152 * Generated by Icinga 2 node setup commands
153 * on 2015-02-09 15:21:49 +0100
156 object Endpoint "icinga2-node1.localdomain" {
159 object Zone "master" {
160 //this is the local node master named = "master"
161 endpoints = [ "icinga2-node1.localdomain" ]
164 Validate the configuration and restart Icinga 2.
169 > This setup wizard will install a standalone master, HA cluster scenarios are currently
170 > not supported and require manual modifications afterwards.
172 ## <a id="icinga2-client-setup"></a> Client Setup for Remote Monitoring
174 Icinga 2 can be installed on Linux/Unix and Windows. While
175 [Linux/Unix](11-icinga2-client.md#icinga2-client-installation-client-setup-linux) will be using the [CLI command](8-cli-commands.md#cli-command-node)
176 `node wizard` for a guided setup, you will need to use the
177 graphical installer for Windows based client setup.
179 Your client setup requires the following
181 * A ready configured and installed [master node](11-icinga2-client.md#icinga2-client-installation-master-setup)
182 * SSL signed certificate for communication with the master (Use [CSR auto-signing](11-icinga2-client.md#csr-autosigning-requirements)).
183 * Enabled API feature, and a local Endpoint and Zone object configuration
184 * Firewall ACLs for the communication port (default 5665)
188 ### <a id="csr-autosigning-requirements"></a> Requirements for CSR Auto-Signing
190 If your remote clients are capable of connecting to the central master, Icinga 2
191 supports CSR auto-signing.
193 First you'll need to define a secure ticket salt in the [constants.conf](4-configuring-icinga-2.md#constants-conf).
194 The [setup wizard for the master setup](11-icinga2-client.md#icinga2-client-installation-master-setup) will create
199 > **Never** expose the ticket salt to your clients. This is the master's private key
200 > and must remain on the master providing the CSR Auto-Signing functionality for security reasons.
202 The client setup wizard will ask you to generate a valid ticket number using its CN.
203 If you already know your remote client's Common Names (CNs) - usually the FQDN - you
204 can generate all ticket numbers on-demand.
206 This is also reasonable if you are not capable of installing the remote client, but
207 a colleague of yours, or a customer.
209 Example for a client:
211 # icinga2 pki ticket --cn icinga2-node2.localdomain
214 ### <a id="certificates-manual-creation"></a> Manual SSL Certificate Generation
216 This is described separately in the [cluster setup chapter](13-distributed-monitoring-ha.md#manual-certificate-generation).
220 > If you're using [CSR Auto-Signing](11-icinga2-client.md#csr-autosigning-requirements), skip this step.
223 ### <a id="icinga2-client-installation-client-setup-linux"></a> Setup the Client on Linux
225 There is no extra client binary or package required. Install Icinga 2 from your distribution's package
226 repository as described in the general [installation instructions](2-getting-started.md#setting-up-icinga2).
228 Please make sure that either [CSR Auto-Signing](11-icinga2-client.md#csr-autosigning-requirements) requirements
229 are fulfilled, or that you're using [manual SSL certificate generation](13-distributed-monitoring-ha.md#manual-certificate-generation).
233 > You don't need any features (DB IDO, Livestatus) or user interfaces on the remote client.
234 > Install them only if you're planning to use them.
236 Once the package installation succeeded, use the `node wizard` CLI command to install
237 a new Icinga 2 node as client setup.
239 You'll need the following configuration details:
241 * The client common name (CN). Defaults to FQDN.
242 * The client's local zone name. Defaults to FQDN.
243 * The master endpoint name. Look into your master setup `zones.conf` file for the proper name.
244 * The master endpoint connection information. Your master's IP address and port (port defaults to 5665)
245 * The [request ticket number](11-icinga2-client.md#csr-autosigning-requirements) generated on your master
247 * Bind host/port for the Api feature (optional)
249 The command must be run as root, all Icinga 2 specific files will be updated to the icinga
250 user the daemon is running as (certificate files for example). The wizard creates backups
251 of configuration and certificate files if already existing.
253 Capitalized options in square brackets (e.g. `[Y/n]`) signal the default value and
254 allow you to continue pressing `Enter` instead of entering a value.
256 # icinga2 node wizard
257 Welcome to the Icinga 2 Setup Wizard!
258 We'll guide you through all required configuration details.
260 Please specify if this is a satellite setup ('n' installs a master setup) [Y/n]:
261 Starting the Node setup routine...
262 Please specifiy the common name (CN) [icinga2-node2.localdomain]:
263 Please specifiy the local zone name [icinga2-node2.localdomain]:
264 Please specify the master endpoint(s) this node should connect to:
265 Master Common Name (CN from your master setup): icinga2-node1.localdomain
266 Please fill out the master connection information:
267 Master endpoint host (optional, your master's IP address or FQDN): 192.168.56.101
268 Master endpoint port (optional) []:
269 Add more master endpoints? [y/N]
270 Please specify the master connection for CSR auto-signing (defaults to master endpoint host):
271 Host [192.168.56.101]:
273 information/base: Writing private key to '/etc/icinga2/pki/icinga2-node2.localdomain.key'.
274 information/base: Writing X509 certificate to '/etc/icinga2/pki/icinga2-node2.localdomain.crt'.
275 information/cli: Generating self-signed certifiate:
276 information/cli: Fetching public certificate from master (192.168.56.101, 5665):
278 information/cli: Writing trusted certificate to file '/etc/icinga2/pki/trusted-master.crt'.
279 information/cli: Stored trusted master certificate in '/etc/icinga2/pki/trusted-master.crt'.
281 Please specify the request ticket generated on your Icinga 2 master.
282 (Hint: # icinga2 pki ticket --cn 'icinga2-node2.localdomain'): ead2d570e18c78abf285d6b85524970a0f69c22d
283 information/cli: Processing self-signed certificate request. Ticket 'ead2d570e18c78abf285d6b85524970a0f69c22d'.
285 information/cli: Writing signed certificate to file '/etc/icinga2/pki/icinga2-node2.localdomain.crt'.
286 information/cli: Writing CA certificate to file '/etc/icinga2/pki/ca.crt'.
287 Please specify the API bind host/port (optional):
290 information/cli: Disabling the Notification feature.
291 Disabling feature notification. Make sure to restart Icinga 2 for these changes to take effect.
292 information/cli: Enabling the Apilistener feature.
293 Enabling feature api. Make sure to restart Icinga 2 for these changes to take effect.
294 information/cli: Created backup file '/etc/icinga2/features-available/api.conf.orig'.
295 information/cli: Generating local zones.conf.
296 information/cli: Dumping config items to file '/etc/icinga2/zones.conf'.
297 information/cli: Created backup file '/etc/icinga2/zones.conf.orig'.
298 information/cli: Updating constants.conf.
299 information/cli: Created backup file '/etc/icinga2/constants.conf.orig'.
300 information/cli: Updating constants file '/etc/icinga2/constants.conf'.
301 information/cli: Updating constants file '/etc/icinga2/constants.conf'.
304 Now restart your Icinga 2 daemon to finish the installation!
307 The setup wizard will do the following:
309 * Generate a new self-signed certificate and copy it into `/etc/icinga2/pki`
310 * Store the master's certificate as trusted certificate for requesting a new signed certificate
311 (manual step when using `node setup`).
312 * Request a new signed certificate from the master and store updated certificate and master CA in `/etc/icinga2/pki`
313 * Generate a local zone and endpoint configuration for this client and the provided master information
315 * Disabling the `notification` feature for this client
316 * Enabling the `api` feature, and setting optional `bind_host` and `bind_port`
317 * Setting the `NodeName` constant in [constants.conf](4-configuring-icinga-2.md#constants-conf)
319 The setup wizard does not automatically restart Icinga 2.
321 Verify the modified configuration:
323 # grep 'NodeName' /etc/icinga2/constants.conf
325 # cat /etc/icinga2/zones.conf
327 * Generated by Icinga 2 node setup commands
328 * on 2015-02-09 16:56:10 +0100
331 object Endpoint "icinga2-node1.localdomain" {
332 host = "192.168.56.101"
335 object Zone "master" {
336 endpoints = [ "icinga2-node1.localdomain" ]
339 object Endpoint "icinga2-node2.localdomain" {
342 object Zone "icinga2-node2.localdomain" {
343 //this is the local node = "icinga2-node2.localdomain"
344 endpoints = [ "icinga2-node2.localdomain" ]
348 Validate the configuration and restart Icinga 2.
350 If you are getting an error when requesting the ticket number, please check the following:
352 * Can your client connect to the master instance?
353 * Is the CN the same (from pki ticket on the master and setup node on the client)?
354 * Is the ticket expired?
358 #### <a id="icinga2-client-installation-client-setup-linux-manual"></a> Manual Setup without Wizard
360 Instead of using the `node wizard` cli command, there is an alternative `node setup`
361 cli command available which has some pre-requisites. Make sure that the
362 `/etc/icinga2/pki` exists and is owned by the `icinga` user (or the user Icinga 2 is
365 `icinga2-node1.localdomain` is the already installed master instance while
366 `icinga2-node2.localdomain` is the instance where the installation cli commands
369 Required information:
371 * The client common name (CN). Use the FQDN, e.g. `icinga2-node2.localdomain`.
372 * The master host and zone name. Pass that to `pki save-cert` as `--host` parameter for example.
373 * The client ticket number generated on the master (`icinga2 pki ticket --cn icinga2-node2.localdomain`)
375 Generate a new local self-signed certificate.
377 # icinga2 pki new-cert --cn icinga2-node2.localdomain \
378 --key /etc/icinga2/pki/icinga2-node2.localdomain.key \
379 --cert /etc/icinga2/pki/icinga2-node2.localdomain.crt
381 Request the master certificate from the master host (`icinga2-node1.localdomain`)
382 and store it as `trusted-master.crt`. Review it and continue.
384 # icinga2 pki save-cert --key /etc/icinga2/pki/icinga2-node2.localdomain.key \
385 --cert /etc/icinga2/pki/icinga2-node2.localdomain.crt \
386 --trustedcert /etc/icinga2/pki/trusted-master.crt \
387 --host icinga2-node1.localdomain
389 Send the self-signed certificate to the master host using the ticket number and
390 receive a CA signed certificate and the master's `ca.crt` certificate.
391 Specify the path to the previously stored trusted master certificate.
393 # icinga2 pki request --host icinga2-node1.localdomain \
395 --ticket ead2d570e18c78abf285d6b85524970a0f69c22d \
396 --key /etc/icinga2/pki/icinga2-node2.localdomain.key \
397 --cert /etc/icinga2/pki/icinga2-node2.localdomain.crt \
398 --trustedcert /etc/icinga2/pki/trusted-master.crt \
399 --ca /etc/icinga2/pki/ca.crt
401 Continue with the additional node setup steps. Specify a local endpoint and zone name (`icinga2-node2.localdomain`)
402 and set the master host (`icinga2-node1.localdomain`) as parent zone configuration. Specify the path to
403 the previously stored trusted master certificate.
405 # icinga2 node setup --ticket ead2d570e18c78abf285d6b85524970a0f69c22d \
406 --endpoint icinga2-node1.localdomain \
407 --zone icinga2-node2.localdomain \
408 --master_host icinga2-node1.localdomain \
409 --trustedcert /etc/icinga2/pki/trusted-master.crt
411 Restart Icinga 2 once complete.
413 # service icinga2 restart
416 ### <a id="icinga2-client-installation-client-setup-windows"></a> Setup the Client on Windows
418 Download the MSI-Installer package from [http://packages.icinga.org/windows/](http://packages.icinga.org/windows/).
421 * Windows Vista/Server 2008 or higher
422 * [Microsoft .NET Framework 2.0](http://www.microsoft.com/de-de/download/details.aspx?id=1639) if not already installed.
424 The installer package includes the [NSClient++](http://www.nsclient.org/) so Icinga 2 can
425 use its built-in plugins. You can use [predefined commands from the ITL](7-icinga-template-library.md#nscp-plugin-check-commands) for these plugins.
427 If you want to install the client silently / unattended use the `/qn` modifier. The
428 installation should not trigger a restart but if you want to be completly sure, you can use the `/norestart` modifier.
430 C:> msiexec /i C:\Icinga2-v2.4.5-x86.msi /qn /norestart
432 After the installation you can run Icinga 2 from the Start menu. (The graphical installer will
433 offer to run Icinga 2 right after the installation) On the first start Icinga 2 will show you
434 the setup wizard which will help you with SSL certificate generation,
435 CSR-Autosigning and configuration setup.
437 You'll need the following configuration details:
439 * The client common name (CN). Defaults to FQDN.
440 * The client's local zone name. Defaults to FQDN.
441 * The master endpoint name. Look into your master setup `zones.conf` file for the proper name.
442 * The master endpoint connection information. Your master's IP address and port (defaults to 5665)
443 * The [request ticket number](11-icinga2-client.md#csr-autosigning-requirements) generated on your master
445 * Bind host/port for the Api feature (optional)
447 Besides the configuration changes, the setup wizard offers you to install the included NSClient++ package.
449 Once install and configuration is done, Icinga 2 is automatically started as a Windows service.
450 Running Icinga 2 again from the Start menu will allow you to change the settings from the the first
451 setup wizard run. Please keep in mind that you can change all those settings within the configuration
452 file and on the commandline.
454 The Icinga 2 configuration is located inside the installation path and can be edited with
455 your favorite editor.
457 Configuration validation is done similar to the linux pendant on the Windows shell:
459 C:> icinga2.exe daemon -C
463 > You have to run this command in a shell with `administrator` permissions.
466 ## <a id="icinga2-client-configuration-modes"></a> Client Configuration Modes
468 * Clients with [local configuration](11-icinga2-client.md#icinga2-client-configuration-local), sending their inventory to the master
469 * Clients as [command execution bridge](11-icinga2-client.md#icinga2-client-configuration-command-bridge) without local configuration
470 * Clients receive their configuration from the master ([Cluster config sync](11-icinga2-client.md#icinga2-client-configuration-master-config-sync))
472 ### <a id="icinga2-client-configuration-local"></a> Clients with Local Configuration
474 This is considered as independant satellite using a local scheduler, configuration
475 and the possibility to add Icinga 2 features on demand.
477 There is no difference in the configuration syntax on clients to any other Icinga 2 installation.
478 You can also use additional features like notifications directly on the remote client, if you are
479 required to. Basically everything a single Icinga 2 instance provides by default.
481 The following convention applies to remote clients:
483 * The hostname in the default host object should be the same as the Common Name (CN) used for SSL setup
484 * Add new services and check commands locally
486 Local configured checks are transferred to the central master. There are additional `node`
487 cli commands available which allow you to list/add/remove/blacklist remote clients and
488 generate the configuration on the master.
491 #### <a id="icinga2-remote-monitoring-master-discovery"></a> Discover Client Services on the Master
493 Icinga 2 clients will sync their locally defined objects to the defined master node. That way you can
494 list, add, filter and remove nodes based on their `node`, `zone`, `host` or `service` name.
496 List all discovered nodes (satellites, agents) and their hosts/services:
499 Node 'icinga2-node2.localdomain' (last seen: Mon Feb 9 16:58:21 2015)
500 * Host 'icinga2-node2.localdomain'
513 Listing the node and its host(s) and service(s) does not modify the master configuration yet. You
514 need to generate the configuration in the next step.
517 ### <a id="icinga2-client-master-discovery-generate-config"></a> Generate Configuration for Client Services on the Master
519 There is a dedicated Icinga 2 CLI command for updating the client services on the master,
520 generating all required configuration.
522 # icinga2 node update-config
524 The generated configuration of all nodes is stored in the `repository.d/` directory.
526 By default, the following additional configuration is generated:
527 * add `Endpoint` and `Zone` objects for the newly added node
528 * add `cluster-zone` health check for the master host for reachability and dependencies
529 * use the default templates `satellite-host` and `satellite-service` defined in `/etc/icinga2/conf.d/satellite.conf`
530 * apply a dependency for all other hosts on the remote satellite prevening failure checks/notifications
532 If hosts or services disappeared from the client discovery, it will remove the existing configuration objects
533 from the config repository. If there are existing hosts/services defined or modified, the CLI command will not
534 overwrite these (modified) configuration files.
536 After updating the configuration repository, make sure to reload Icinga 2.
538 # service icinga2 reload
541 # systemctl reload icinga2
544 The `update-config` CLI command will fail, if there are uncommitted changes for the
545 configuration repository or if your master is part of a HA setup (see https://dev.icinga.org/issues/8292 for details).
546 Please review these changes manually, or clear the commit and try again. This is a
547 safety hook to prevent unwanted manual changes to be committed by a updating the
548 client discovered objects only.
550 # icinga2 repository commit --simulate
551 # icinga2 repository clear-changes
552 # icinga2 repository commit
555 ### <a id="icinga2-client-configuration-command-bridge"></a> Clients as Command Execution Bridge
557 Similar to other addons (NRPE, NSClient++, etc) the remote Icinga 2 client will only
558 execute commands the master instance is sending. There are no local host or service
559 objects configured, only the check command definitions must be configured.
563 > Remote clients must explicitely accept commands in a similar
564 > fashion as cluster nodes [accept configuration](13-distributed-monitoring-ha.md#cluster-zone-config-sync).
565 > This is due to security reasons.
567 Edit the `api` feature configuration in `/etc/icinga2/features-enabled/api.conf` on your client
568 and set `accept_commands` to `true`.
570 object ApiListener "api" {
571 cert_path = SysconfDir + "/icinga2/pki/" + NodeName + ".crt"
572 key_path = SysconfDir + "/icinga2/pki/" + NodeName + ".key"
573 ca_path = SysconfDir + "/icinga2/pki/ca.crt"
574 accept_commands = true
577 Icinga 2 on the remote client does not schedule checks locally, or keep checking
578 hosts/services on connection loss. This mode also does not allow to use features
579 for backend data writing (DB IDO, Perfdata, etc.) as the client does not have
580 local objects configured.
582 Icinga 2 already provides a variety of `CheckCommand` definitions using the Plugin
583 Check Commands, but you should also modify the local configuration inside `commands.conf`
586 If you're wondering why you need to keep the same command configuration on the master and
587 remote client: Icinga 2 calculates all required runtime macros used as command arguments on
588 the master and sends that information to the client.
589 In case you want to limit command arguments or handles values in a different manner, you
590 can modify the check command configuration on the remote client only. See [this issue](https://dev.icinga.org/issues/8221#note-3)
593 ### <a id="icinga2-client-configuration-command-bridge-master-config"></a> Master Configuration for Clients as Command Execution Bridge
595 This step involves little knowledge about the way the Icinga 2 nodes communication and trust
596 each other. Each client is configured as `Endpoint` object providing connection information.
597 As a matter of trust the client `Endpoint` is a member of its own `Zone` object which gets
598 the master zone configured as parent. That way the master knows how to connect to the client
599 and where to execute the check commands.
601 Add an `Endpoint` and `Zone` configuration object for the remote client
602 in `/etc/icinga2/zones.conf` and define a trusted master zone as `parent`.
604 object Endpoint "icinga2-node2.localdomain" {
605 host = "192.168.56.102"
608 object Zone "icinga2-node2.localdomain" {
610 endpoints = [ "icinga2-node2.localdomain" ]
614 * [configure endpoints](13-distributed-monitoring-ha.md#configure-cluster-endpoints)
615 * [configure zones](13-distributed-monitoring-ha.md#configure-cluster-zones)
618 Once you have configured the required `Endpoint` and `Zone` object definition, you can start
619 configuring your host and service objects. The configuration is simple: If the `command_endpoint`
620 attribute is set, Icinga 2 calculcates all required runtime macros and sends that over to the
621 defined endpoint. The check result is then received asynchronously through the cluster protocol.
623 object Host "host-remote" {
624 import "generic-host"
626 address = "127.0.0.1"
632 apply Service "users-remote" {
633 import "generic-service"
635 check_command = "users"
636 command_endpoint = "icinga2-node2.localdomain"
638 vars.users_wgreater = 10
639 vars.users_cgreater = 20
641 /* assign where a remote client pattern is matched */
642 assign where match("*-remote", host.name)
646 If there is a failure on execution (for example, the local check command configuration or the plugin
647 is missing), the check will return `UNKNOWN` and populate the check output with the error message.
648 This will happen in a similar fashion if you forgot to enable the `accept_commands` attribute
649 inside the `api` feature.
651 If you don't want to define the endpoint name inside the service apply rule everytime, you can
652 also easily inherit this from a host's custom attribute like shown in the example below.
654 object Host "host-remote" {
655 import "generic-host"
657 address = "127.0.0.1"
662 vars.remote_client = "icinga2-node2.localdomain"
664 /* host specific check arguments */
665 vars.users_wgreater = 10
666 vars.users_cgreater = 20
669 apply Service "users-remote" {
670 import "generic-service"
672 check_command = "users"
673 command_endpoint = host.vars.remote_client
675 /* override (remote) command arguments with host settings */
676 vars.users_wgreater = host.vars.users_wgreater
677 vars.users_cgreater = host.vars.users_cgreater
679 /* assign where a remote client is set */
680 assign where host.vars.remote_client
683 That way your generated host object is the information provider and the service apply
684 rules must only be configured once.
688 > [Event commands](3-monitoring-basics.md#event-commands) are executed on the
689 > remote command endpoint as well. You do not need
690 > an additional transport layer such as SSH or similar.
693 ### <a id="icinga2-client-configuration-master-config-sync"></a> Clients with Master Config Sync
695 This is an advanced configuration mode which requires knowledge about the Icinga 2
696 cluster configuration and its object relation (Zones, Endpoints, etc) and the way you
697 will be able to sync the configuration from the master to the remote satellite or client.
699 Please continue reading in the [distributed monitoring chapter](13-distributed-monitoring-ha.md#distributed-monitoring-high-availability),
700 especially the [configuration synchronisation](13-distributed-monitoring-ha.md#cluster-zone-config-sync)
701 and [best practices](13-distributed-monitoring-ha.md#zone-config-sync-best-practice).
706 ### <a id="icinga2-client-cli-node"></a> Advanced Node Cli Actions
708 #### <a id="icinga2-remote-monitoring-master-discovery-blacklist-whitelist"></a> Blacklist/Whitelist for Clients on the Master
710 It's sometimes necessary to `blacklist` an entire remote client, or specific hosts or services
711 provided by this client. While it's reasonable for the local admin to configure for example an
712 additional ping check, you're not interested in that on the master sending out notifications
713 and presenting the dashboard to your support team.
715 Blacklisting an entire set might not be sufficient for excluding several objects, be it a
716 specific remote client with one ping servie you're interested in. Therefore you can `whitelist`
717 clients, hosts, services in a similar manner
719 Example for blacklisting all `ping*` services, but allowing only `probe` host with `ping4`:
721 # icinga2 node blacklist add --zone "*" --host "*" --service "ping*"
722 # icinga2 node whitelist add --zone "*" --host "probe" --service "ping*"
724 You can `list` and `remove` existing blacklists:
726 # icinga2 node blacklist list
727 Listing all blacklist entries:
728 blacklist filter for Node: '*' Host: '*' Service: 'ping*'.
730 # icinga2 node whitelist list
731 Listing all whitelist entries:
732 whitelist filter for Node: '*' Host: 'probe' Service: 'ping*'.
737 > The blacklist feature only prevents future updates from creating and removing objects, but it does not remove already existing objects.
738 > The `--zone` and `--host` arguments are required. A zone is always where the remote client is in.
739 > If you are unsure about it, set a wildcard (`*`) for them and filter only by host/services.
743 #### <a id="icinga2-client-master-discovery-manual"></a> Manually Discover Clients on the Master
745 Add a to-be-discovered client to the master:
747 # icinga2 node add my-remote-client
749 Set the connection details, and the Icinga 2 master will attempt to connect to this node and sync its
752 # icinga2 node set my-remote-client --host 192.168.33.101 --port 5665
754 You can control that by calling the `node list` command:
757 Node 'my-remote-client' (host: 192.168.33.101, port: 5665, log duration: 1 day, last seen: Sun Nov 2 17:46:29 2014)
759 #### <a id="icinga2-remote-monitoring-master-discovery-remove"></a> Remove Discovered Clients
761 If you don't require a connected agent, you can manually remove it and its discovered hosts and services
762 using the following CLI command:
764 # icinga2 node remove my-discovered-agent
768 > Better use [blacklists and/or whitelists](11-icinga2-client.md#icinga2-remote-monitoring-master-discovery-blacklist-whitelist)
769 > to control which clients and hosts/services are integrated into your master configuration repository.