]> granicus.if.org Git - icinga2/blob - doc/10-icinga2-client.md
Documentation: Enhance cluster troubleshooting; add HA command_endpoint
[icinga2] / doc / 10-icinga2-client.md
1 # <a id="icinga2-client"></a> Icinga 2 Client
2
3 ## <a id="icinga2-client-introduction"></a> Introduction
4
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](10-icinga2-client.md#icinga2-client).
8
9 All communication is secured by TLS with certificates, and fully supports IPv4 and IPv6.
10
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).
14
15 > **Tip**
16 >
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.
20
21
22 ## <a id="icinga2-client-scenarios"></a> Client Scenarios
23
24 * Clients with [local configuration](10-icinga2-client.md#icinga2-client-configuration-local), sending their inventory to the master
25 * Clients as [command execution bridge](10-icinga2-client.md#icinga2-client-configuration-command-bridge) without local configuration
26 * Clients receive their configuration from the master ([Cluster config sync](10-icinga2-client.md#icinga2-client-configuration-master-config-sync))
27
28 ### <a id="icinga2-client-configuration-combined-scenarios"></a> Combined Client Scenarios
29
30 If your setup consists of remote clients with local configuration but also command execution bridges
31 and probably syncing global templates through the cluster config sync, you should take a deep
32 breath and take pen and paper to draw your design before starting over.
33
34 Keep the following hints in mind:
35
36 * You can blacklist remote nodes entirely. They are then ignored on `node update-config`
37 on the master.
38 * Your remote instance can have local configuration **and** act as remote command execution bridge.
39 * You can use the `global` cluster zones to sync check commands, templates, etc to your remote clients.
40 Be it just for command execution or for helping the local configuration.
41 * If your remote clients shouldn't have local configuration, remove `conf.d` inclusion from `icinga2`
42 and simply use the cluster configuration sync.
43 * `accept_config` and `accept_commands` are disabled by default in the `api` feature
44
45 If you are planning to use the Icinga 2 client inside a distributed setup, refer to
46 [this chapter](12-distributed-monitoring-ha.md#cluster-scenarios-master-satellite-clients) with detailed instructions.
47
48
49 ## <a id="icinga2-client-installation"></a> Installation
50
51 ### <a id="icinga2-client-installation-firewall"></a> Configure the Firewall
52
53 Icinga 2 master, satellite and client instances communicate using the default tcp
54 port `5665`. The communication is bi-directional and the first node opening the
55 connection "wins" if there are both connection ways enabled in your firewall policies.
56
57 If you are going to use CSR-Autosigning, you must (temporarly) allow the client
58 connecting to the master instance and open the firewall port. Once the client install is done,
59 you can close the port and use a different communication direction (master-to-client).
60
61 ### <a id="icinga2-client-installation-master-setup"></a> Setup the Master for Remote Clients
62
63 If you are planning to use the [remote Icinga 2 clients](10-icinga2-client.md#icinga2-client)
64 you'll first need to update your master setup.
65
66 Your master setup requires the following
67
68 * SSL CA and signed certificate for the master
69 * Enabled API feature, and a local Endpoint and Zone object configuration
70 * Firewall ACLs for the communication port (default 5665)
71
72 You can use the [CLI command](8-cli-commands.md#cli-command-node) `node wizard` for setting up a new node
73 on the master. The command must be run as root, all Icinga 2 specific files
74 will be updated to the icinga user the daemon is running as (certificate files
75 for example).
76
77 Make sure to answer the first question with `n` (no).
78
79     # icinga2 node wizard
80     Welcome to the Icinga 2 Setup Wizard!
81
82     We'll guide you through all required configuration details.
83
84     Please specify if this is a satellite setup ('n' installs a master setup) [Y/n]: n
85     Starting the Master setup routine...
86     Please specifiy the common name (CN) [icinga2-node1.localdomain]:
87     information/base: Writing private key to '/var/lib/icinga2/ca/ca.key'.
88     information/base: Writing X509 certificate to '/var/lib/icinga2/ca/ca.crt'.
89     information/cli: Initializing serial file in '/var/lib/icinga2/ca/serial.txt'.
90     information/cli: Generating new CSR in '/etc/icinga2/pki/icinga2-node1.localdomain.csr'.
91     information/base: Writing private key to '/etc/icinga2/pki/icinga2-node1.localdomain.key'.
92     information/base: Writing certificate signing request to '/etc/icinga2/pki/icinga2-node1.localdomain.csr'.
93     information/cli: Signing CSR with CA and writing certificate to '/etc/icinga2/pki/icinga2-node1.localdomain.crt'.
94     information/cli: Copying CA certificate to '/etc/icinga2/pki/ca.crt'.
95     information/cli: Dumping config items to file '/etc/icinga2/zones.conf'.
96     information/cli: Created backup file '/etc/icinga2/zones.conf.orig'.
97     Please specify the API bind host/port (optional):
98     Bind Host []:
99     Bind Port []:
100     information/cli: Enabling the APIlistener feature.
101     Enabling feature api. Make sure to restart Icinga 2 for these changes to take effect.
102     information/cli: Created backup file '/etc/icinga2/features-available/api.conf.orig'.
103     information/cli: Updating constants.conf.
104     information/cli: Created backup file '/etc/icinga2/constants.conf.orig'.
105     information/cli: Updating constants file '/etc/icinga2/constants.conf'.
106     information/cli: Updating constants file '/etc/icinga2/constants.conf'.
107     Done.
108
109     Now restart your Icinga 2 daemon to finish the installation!
110
111
112 The setup wizard will do the following:
113
114 * Generate a local CA in `/var/lib/icinga2/ca` or use the existing one
115 * Generate a new CSR, sign it with the local CA and copying it into `/etc/icinga2/pki`
116 * Generate a local zone and endpoint configuration for this master based on FQDN
117 * Enabling the API feature, and setting optional `bind_host` and `bind_port`
118 * Setting the `NodeName` and `TicketSalt` constants in [constants.conf](5-configuring-icinga-2.md#constants-conf)
119
120 The setup wizard does not automatically restart Icinga 2.
121
122 Verify the modified configuration:
123
124     # egrep 'NodeName|TicketSalt' /etc/icinga2/constants.conf
125
126     # cat /etc/icinga2/zones.conf
127     /*
128      * Generated by Icinga 2 node setup commands
129      * on 2015-02-09 15:21:49 +0100
130      */
131
132     object Endpoint "icinga2-node1.localdomain" {
133     }
134
135     object Zone "master" {
136         //this is the local node master named  = "master"
137         endpoints = [ "icinga2-node1.localdomain" ]
138     }
139
140 Validate the configuration and restart Icinga 2.
141
142
143 > **Note**
144 >
145 > This setup wizard will install a standalone master, HA cluster scenarios are currently
146 > not supported and require manual modifications afterwards.
147
148 ## <a id="icinga2-client-setup"></a> Client Setup for Remote Monitoring
149
150 Icinga 2 can be installed on Linux/Unix and Windows. While
151 [Linux/Unix](10-icinga2-client.md#icinga2-client-installation-client-setup-linux) will be using the [CLI command](8-cli-commands.md#cli-command-node)
152 `node wizard` for a guided setup, you will need to use the
153 graphical installer for Windows based client setup.
154
155 Your client setup requires the following
156
157 * A ready configured and installed [master node](10-icinga2-client.md#icinga2-client-installation-master-setup)
158 * SSL signed certificate for communication with the master (Use [CSR auto-signing](10-icinga2-client.md#csr-autosigning-requirements)).
159 * Enabled API feature, and a local Endpoint and Zone object configuration
160 * Firewall ACLs for the communication port (default 5665)
161
162
163
164 ### <a id="csr-autosigning-requirements"></a> Requirements for CSR Auto-Signing
165
166 If your remote clients are capable of connecting to the central master, Icinga 2
167 supports CSR auto-signing.
168
169 First you'll need to define a secure ticket salt in the [constants.conf](5-configuring-icinga-2.md#constants-conf).
170 The [setup wizard for the master setup](10-icinga2-client.md#icinga2-client-installation-master-setup) will create
171 one for you already.
172
173     # grep TicketSalt /etc/icinga2/constants.conf
174
175 The client setup wizard will ask you to generate a valid ticket number using its CN.
176 If you already know your remote client's Common Names (CNs) - usually the FQDN - you
177 can generate all ticket numbers on-demand.
178
179 This is also reasonable if you are not capable of installing the remote client, but
180 a colleague of yours, or a customer.
181
182 Example for a client:
183
184     # icinga2 pki ticket --cn icinga2-node2.localdomain
185
186
187 > **Note**
188 >
189 > You can omit the `--salt` parameter using the `TicketSalt` constant from
190 > [constants.conf](5-configuring-icinga-2.md#constants-conf) if already defined and Icinga 2 was
191 > reloaded after the master setup.
192
193 ### <a id="certificates-manual-creation"></a> Manual SSL Certificate Generation
194
195 This is described separately in the [cluster setup chapter](12-distributed-monitoring-ha.md#manual-certificate-generation).
196
197 > **Note**
198 >
199 > If you're using [CSR Auto-Signing](10-icinga2-client.md#csr-autosigning-requirements), skip this step.
200
201
202 ### <a id="icinga2-client-installation-client-setup-linux"></a> Setup the Client on Linux
203
204 There is no extra client binary or package required. Install Icinga 2 from your distribution's package
205 repository as described in the general [installation instructions](2-getting-started.md#setting-up-icinga2).
206
207 Please make sure that either [CSR Auto-Signing](10-icinga2-client.md#csr-autosigning-requirements) requirements
208 are fulfilled, or that you're using [manual SSL certificate generation](12-distributed-monitoring-ha.md#manual-certificate-generation).
209
210 > **Note**
211 >
212 > You don't need any features (DB IDO, Livestatus) or user interfaces on the remote client.
213 > Install them only if you're planning to use them.
214
215 Once the package installation succeeded, use the `node wizard` CLI command to install
216 a new Icinga 2 node as client setup.
217
218 You'll need the following configuration details:
219
220 * The client common name (CN). Defaults to FQDN.
221 * The client's local zone name. Defaults to FQDN.
222 * The master endpoint name. Look into your master setup `zones.conf` file for the proper name.
223 * The master endpoint connection information. Your master's IP address and port (port defaults to 5665)
224 * The [request ticket number](10-icinga2-client.md#csr-autosigning-requirements) generated on your master
225 for CSR Auto-Signing
226 * Bind host/port for the Api feature (optional)
227
228 The command must be run as root, all Icinga 2 specific files will be updated to the icinga
229 user the daemon is running as (certificate files for example). The wizard creates backups
230 of configuration and certificate files if already existing.
231
232 Capitalized options in square brackets (e.g. `[Y/n]`) signal the default value and
233 allow you to continue pressing `Enter` instead of entering a value.
234
235     # icinga2 node wizard
236     Welcome to the Icinga 2 Setup Wizard!
237     We'll guide you through all required configuration details.
238
239     Please specify if this is a satellite setup ('n' installs a master setup) [Y/n]:
240     Starting the Node setup routine...
241     Please specifiy the common name (CN) [icinga2-node2.localdomain]:
242     Please specifiy the local zone name [icinga2-node2.localdomain]:
243     Please specify the master endpoint(s) this node should connect to:
244     Master Common Name (CN from your master setup): icinga2-node1.localdomain
245     Please fill out the master connection information:
246     Master endpoint host (optional, your master's IP address or FQDN): 192.168.56.101
247     Master endpoint port (optional) []:
248     Add more master endpoints? [y/N]
249     Please specify the master connection for CSR auto-signing (defaults to master endpoint host):
250     Host [192.168.56.101]:
251     Port [5665]:
252     information/base: Writing private key to '/etc/icinga2/pki/icinga2-node2.localdomain.key'.
253     information/base: Writing X509 certificate to '/etc/icinga2/pki/icinga2-node2.localdomain.crt'.
254     information/cli: Generating self-signed certifiate:
255     information/cli: Fetching public certificate from master (192.168.56.101, 5665):
256
257     information/cli: Writing trusted certificate to file '/etc/icinga2/pki/trusted-master.crt'.
258     information/cli: Stored trusted master certificate in '/etc/icinga2/pki/trusted-master.crt'.
259
260     Please specify the request ticket generated on your Icinga 2 master.
261      (Hint: # icinga2 pki ticket --cn 'icinga2-node2.localdomain'): ead2d570e18c78abf285d6b85524970a0f69c22d
262     information/cli: Processing self-signed certificate request. Ticket 'ead2d570e18c78abf285d6b85524970a0f69c22d'.
263
264     information/cli: Writing signed certificate to file '/etc/icinga2/pki/icinga2-node2.localdomain.crt'.
265     information/cli: Writing CA certificate to file '/etc/icinga2/pki/ca.crt'.
266     Please specify the API bind host/port (optional):
267     Bind Host []:
268     Bind Port []:
269     information/cli: Disabling the Notification feature.
270     Disabling feature notification. Make sure to restart Icinga 2 for these changes to take effect.
271     information/cli: Enabling the Apilistener feature.
272     Enabling feature api. Make sure to restart Icinga 2 for these changes to take effect.
273     information/cli: Created backup file '/etc/icinga2/features-available/api.conf.orig'.
274     information/cli: Generating local zones.conf.
275     information/cli: Dumping config items to file '/etc/icinga2/zones.conf'.
276     information/cli: Created backup file '/etc/icinga2/zones.conf.orig'.
277     information/cli: Updating constants.conf.
278     information/cli: Created backup file '/etc/icinga2/constants.conf.orig'.
279     information/cli: Updating constants file '/etc/icinga2/constants.conf'.
280     information/cli: Updating constants file '/etc/icinga2/constants.conf'.
281     Done.
282
283     Now restart your Icinga 2 daemon to finish the installation!
284
285
286 The setup wizard will do the following:
287
288 * Generate a new self-signed certificate and copy it into `/etc/icinga2/pki`
289 * Store the master's certificate as trusted certificate for requesting a new signed certificate
290 (manual step when using `node setup`).
291 * Request a new signed certificate from the master and store updated certificate and master CA in `/etc/icinga2/pki`
292 * Generate a local zone and endpoint configuration for this client and the provided master information
293 (based on FQDN)
294 * Disabling the `notification` feature for this client
295 * Enabling the `api` feature, and setting optional `bind_host` and `bind_port`
296 * Setting the `NodeName` constant in [constants.conf](5-configuring-icinga-2.md#constants-conf)
297
298 The setup wizard does not automatically restart Icinga 2.
299
300 Verify the modified configuration:
301
302     # grep 'NodeName' /etc/icinga2/constants.conf
303
304     # cat /etc/icinga2/zones.conf
305     /*
306      * Generated by Icinga 2 node setup commands
307      * on 2015-02-09 16:56:10 +0100
308      */
309
310     object Endpoint "icinga2-node1.localdomain" {
311         host = "192.168.56.101"
312     }
313
314     object Zone "master" {
315         endpoints = [ "icinga2-node1.localdomain" ]
316     }
317
318     object Endpoint "icinga2-node2.localdomain" {
319     }
320
321     object Zone "icinga2-node2.localdomain" {
322         //this is the local node = "icinga2-node2.localdomain"
323         endpoints = [ "icinga2-node2.localdomain" ]
324         parent = "master"
325     }
326
327 Validate the configuration and restart Icinga 2.
328
329 If you are getting an error when requesting the ticket number, please check the following:
330
331 * Can your client connect to the master instance?
332 * Is the CN the same (from pki ticket on the master and setup node on the client)?
333 * Is the ticket expired?
334
335
336
337 #### <a id="icinga2-client-installation-client-setup-linux-manual"></a> Manual Setup without Wizard
338
339 Instead of using the `node wizard` cli command, there is an alternative `node setup`
340 cli command available which has some pre-requisites. Make sure that the
341 `/etc/icinga2/pki` exists and is owned by the `icinga` user (or the user Icinga 2 is
342 running as).
343
344 `icinga2-node1.localdomain` is the already installed master instance while
345 `icinga2-node2.localdomain` is the instance where the installation cli commands
346 are executed.
347
348 Required information:
349
350 * The client common name (CN). Use the FQDN, e.g. `icinga2-node2.localdomain`.
351 * The master host and zone name. Pass that to `pki save-cert` as `--host` parameter for example.
352 * The client ticket number generated on the master (`icinga2 pki ticket --cn icinga2-node2.localdomain`)
353
354 Generate a new local self-signed certificate.
355
356     # icinga2 pki new-cert --cn icinga2-node2.localdomain \
357     --key /etc/icinga2/pki/icinga2-node2.localdomain.key \
358     --cert /etc/icinga2/pki/icinga2-node2.localdomain.crt
359
360 Request the master certificate from the master host (`icinga2-node1.localdomain`)
361 and store it as `trusted-master.crt`. Review it and continue.
362
363     # icinga2 pki save-cert --key /etc/icinga2/pki/icinga2-node2.localdomain.key \
364     --cert /etc/icinga2/pki/icinga2-node2.localdomain.crt \
365     --trustedcert /etc/icinga2/pki/trusted-master.crt \
366     --host icinga2-node1.localdomain
367
368 Send the self-signed certificate to the master host using the ticket number and
369 receive a CA signed certificate and the master's `ca.crt` certificate.
370 Specify the path to the previously stored trusted master certificate.
371
372     # icinga2 pki request --host icinga2-node1.localdomain \
373     --port 5665 \
374     --ticket ead2d570e18c78abf285d6b85524970a0f69c22d \
375     --key /etc/icinga2/pki/icinga2-node2.localdomain.key \
376     --cert /etc/icinga2/pki/icinga2-node2.localdomain.crt \
377     --trustedcert /etc/icinga2/pki/trusted-master.crt \
378     --ca /etc/icinga2/pki/ca.crt
379
380 Continue with the additional node setup steps. Specify a local endpoint and zone name (`icinga2-node2.localdomain`)
381 and set the master host (`icinga2-node1.localdomain`) as parent zone configuration. Specify the path to
382 the previously stored trusted master certificate.
383
384     # icinga2 node setup --ticket ead2d570e18c78abf285d6b85524970a0f69c22d \
385     --endpoint icinga2-node1.localdomain \
386     --zone icinga2-node2.localdomain \
387     --master_host icinga2-node1.localdomain \
388     --trustedcert /etc/icinga2/pki/trusted-master.crt
389
390 Restart Icinga 2 once complete.
391
392     # service icinga2 restart
393
394
395 ### <a id="icinga2-client-installation-client-setup-windows"></a> Setup the Client on Windows
396
397 Download the MSI-Installer package from [http://packages.icinga.org/windows/](http://packages.icinga.org/windows/).
398
399 Requirements:
400 * Windows Vista/Server 2008 or higher
401 * [Microsoft .NET Framework 2.0](http://www.microsoft.com/de-de/download/details.aspx?id=1639) if not already installed.
402
403 The setup wizard will install Icinga 2 and then continue with SSL certificate generation,
404 CSR-Autosigning and configuration setup.
405
406 You'll need the following configuration details:
407
408 * The client common name (CN). Defaults to FQDN.
409 * The client's local zone name. Defaults to FQDN.
410 * The master endpoint name. Look into your master setup `zones.conf` file for the proper name.
411 * The master endpoint connection information. Your master's IP address and port (defaults to 5665)
412 * The [request ticket number](10-icinga2-client.md#csr-autosigning-requirements) generated on your master
413 for CSR Auto-Signing
414 * Bind host/port for the Api feature (optional)
415
416 Once install is done, Icinga 2 is automatically started as a Windows service.
417
418 The Icinga 2 configuration is located inside the installation path and can be edited with
419 your favorite editor.
420
421 Configuration validation is done similar to the linux pendant on the Windows shell:
422
423     C:> icinga2.exe daemon -C
424
425
426
427
428 ## <a id="icinga2-client-configuration-modes"></a> Client Configuration Modes
429
430 * Clients with [local configuration](10-icinga2-client.md#icinga2-client-configuration-local), sending their inventory to the master
431 * Clients as [command execution bridge](10-icinga2-client.md#icinga2-client-configuration-command-bridge) without local configuration
432 * Clients receive their configuration from the master ([Cluster config sync](10-icinga2-client.md#icinga2-client-configuration-master-config-sync))
433
434 ### <a id="icinga2-client-configuration-local"></a> Clients with Local Configuration
435
436 This is considered as independant satellite using a local scheduler, configuration
437 and the possibility to add Icinga 2 features on demand.
438
439 There is no difference in the configuration syntax on clients to any other Icinga 2 installation.
440 You can also use additional features like notifications directly on the remote client, if you are
441 required to. Basically everything a single Icinga 2 instance provides by default.
442
443 The following convention applies to remote clients:
444
445 * The hostname in the default host object should be the same as the Common Name (CN) used for SSL setup
446 * Add new services and check commands locally
447
448 Local configured checks are transferred to the central master. There are additional `node`
449 cli commands available which allow you to list/add/remove/blacklist remote clients and
450 generate the configuration on the master.
451
452
453 #### <a id="icinga2-remote-monitoring-master-discovery"></a> Discover Client Services on the Master
454
455 Icinga 2 clients will sync their locally defined objects to the defined master node. That way you can
456 list, add, filter and remove nodes based on their `node`, `zone`, `host` or `service` name.
457
458 List all discovered nodes (satellites, agents) and their hosts/services:
459
460     # icinga2 node list
461     Node 'icinga2-node2.localdomain' (last seen: Mon Feb  9 16:58:21 2015)
462         * Host 'icinga2-node2.localdomain'
463             * Service 'ping4'
464             * Service 'ping6'
465             * Service 'ssh'
466             * Service 'http'
467             * Service 'disk'
468             * Service 'disk /'
469             * Service 'icinga'
470             * Service 'load'
471             * Service 'procs'
472             * Service 'swap'
473             * Service 'users'
474
475 Listing the node and its host(s) and service(s) does not modify the master configuration yet. You
476 meed to generate the configuration in the next step.
477
478
479 ### <a id="icinga2-client-master-discovery-generate-config"></a> Generate Configuration for Client Services on the Master
480
481 There is a dedicated Icinga 2 CLI command for updating the client services on the master,
482 generating all required configuration.
483
484     # icinga2 node update-config
485
486 The generated configuration of all nodes is stored in the `repository.d/` directory.
487
488 By default, the following additional configuration is generated:
489 * add `Endpoint` and `Zone` objects for the newly added node
490 * add `cluster-zone` health check for the master host for reachability and dependencies
491 * use the default templates `satellite-host` and `satellite-service` defined in `/etc/icinga2/conf.d/satellite.conf`
492 * apply a dependency for all other hosts on the remote satellite prevening failure checks/notifications
493
494 If hosts or services disappeared from the client discovery, it will remove the existing configuration objects
495 from the config repository. If there are existing hosts/services defined or modified, the CLI command will not
496 overwrite these (modified) configuration files.
497
498 After updating the configuration repository, make sure to reload Icinga 2.
499
500     # service icinga2 reload
501
502 Using systemd:
503     # systemctl reload icinga2
504
505
506 The `update-config` CLI command will fail, if there are uncommitted changes for the
507 configuration repository.
508 Please review these changes manually, or clear the commit and try again. This is a
509 safety hook to prevent unwanted manual changes to be committed by a updating the
510 client discovered objects only.
511
512     # icinga2 repository commit --simulate
513     # icinga2 repository clear-changes
514     # icinga2 repository commit
515
516
517 ### <a id="icinga2-client-configuration-command-bridge"></a> Clients as Command Execution Bridge
518
519 Similar to other addons (NRPE, NSClient++, etc) the remote Icinga 2 client will only
520 execute commands the master instance is sending. There are no local host or service
521 objects configured, only the check command definitions must be configured.
522
523 > **Note**
524 >
525 > Remote clients must explicitely accept commands in a similar
526 > fashion as cluster nodes [accept configuration](12-distributed-monitoring-ha.md#cluster-zone-config-sync).
527 > This is due to security reasons.
528
529 Edit the `api` feature configuration in `/etc/icinga2/features-enabled/api.conf` on your client
530 and set `accept_commands` to `true`.
531
532     object ApiListener "api" {
533       cert_path = SysconfDir + "/icinga2/pki/" + NodeName + ".crt"
534       key_path = SysconfDir + "/icinga2/pki/" + NodeName + ".key"
535       ca_path = SysconfDir + "/icinga2/pki/ca.crt"
536       accept_commands = true
537     }
538
539 Icinga 2 on the remote client does not schedule checks locally, or keep checking
540 hosts/services on connection loss. This mode also does not allow to use features
541 for backend data writing (DB IDO, Perfdata, etc.) as the client does not have
542 local objects configured.
543
544 Icinga 2 already provides a variety of `CheckCommand` definitions using the Plugin
545 Check Commands, but you should also modify the local configuration inside `commands.conf`
546 for example.
547
548 If you're wondering why you need to keep the same command configuration on the master and
549 remote client: Icinga 2 calculates all required runtime macros used as command arguments on
550 the master and sends that information to the client.
551 In case you want to limit command arguments or handles values in a different manner, you
552 can modify the check command configuration on the remote client only. See [this issue](https://dev.icinga.org/issues/8221#note-3)
553 for more details.
554
555 ### <a id="icinga2-client-configuration-command-bridge-master-config"></a> Master Configuration for Clients as Command Execution Bridge
556
557 This step involves little knowledge about the way the Icinga 2 nodes communication and trust
558 each other. Each client is configured as `Endpoint` object providing connection information.
559 As a matter of trust the client `Endpoint` is a member of its own `Zone` object which gets
560 the master zone configured as parent. That way the master knows how to connect to the client
561 and where to execute the check commands.
562
563 Add an `Endpoint` and `Zone` configuration object for the remote client
564 in `/etc/icinga2/zones.conf` and define a trusted master zone as `parent`.
565
566     object Endpoint "icinga2-node2.localdomain" {
567       host = "192.168.56.102"
568     }
569
570     object Zone "icinga2-node2.localdomain" {
571       parent = "master"
572       endpoints = [ "icinga2-node2.localdomain" ]
573     }
574
575 More details here:
576 * [configure endpoints](12-distributed-monitoring-ha.md#configure-cluster-endpoints)
577 * [configure zones](12-distributed-monitoring-ha.md#configure-cluster-zones)
578
579
580 Once you have configured the required `Endpoint` and `Zone` object definition, you can start
581 configuring your host and service objects. The configuration is simple: If the `command_endpoint`
582 attribute is set, Icinga 2 calculcates all required runtime macros and sends that over to the
583 defined endpoint. The check result is then received asynchronously through the cluster protocol.
584
585     object Host "host-remote" {
586       import "generic-host"
587
588       address = "127.0.0.1"
589       address6 = "::1"
590
591       vars.os = "Linux"
592     }
593
594     apply Service "users-remote" {
595       import "generic-service"
596
597       check_command = "users"
598       command_endpoint = "remote-client1"
599
600       vars.users_wgreater = 10
601       vars.users_cgreater = 20
602
603       /* assign where a remote client pattern is matched */
604       assign where match("*-remote", host.name)
605     }
606
607
608 If there is a failure on execution (for example, the local check command configuration or the plugin
609 is missing), the check will return `UNKNOWN` and populate the check output with the error message.
610 This will happen in a similar fashion if you forgot to enable the `accept_commands` attribute
611 inside the `api` feature.
612
613 If you don't want to define the endpoint name inside the service apply rule everytime, you can
614 also easily inherit this from a host's custom attribute like shown in the example below.
615
616     object Host "host-remote" {
617       import "generic-host"
618
619       address = "127.0.0.1"
620       address6 = "::1"
621
622       vars.os = "Linux"
623
624       vars.remote_client = "remote-client1"
625
626       /* host specific check arguments */
627       vars.users_wgreater = 10
628       vars.users_cgreater = 20
629     }
630
631     apply Service "users-remote" {
632       import "generic-service"
633
634       check_command = "users"
635       command_endpoint = host.vars.remote_client
636
637       /* override (remote) command arguments with host settings */
638       vars.users_wgreater = host.vars.users_wgreater
639       vars.users_cgreater = host.vars.users_cgreater
640
641       /* assign where a remote client is set */
642       assign where host.vars.remote_client
643     }
644
645 That way your generated host object is the information provider and the service apply
646 rules must only be configured once.
647
648 > **Tip**
649 >
650 > [Event commands](3-monitoring-basics.md#event-commands) are executed on the
651 > remote command endpoint as well. You do not need
652 > an additional transport layer such as SSH or similar.
653
654
655 ### <a id="icinga2-client-configuration-master-config-sync"></a> Clients with Master Config Sync
656
657 This is an advanced configuration mode which requires knowledge about the Icinga 2
658 cluster configuration and its object relation (Zones, Endpoints, etc) and the way you
659 will be able to sync the configuration from the master to the remote satellite or client.
660
661 Please continue reading in the [distributed monitoring chapter](12-distributed-monitoring-ha.md#distributed-monitoring-high-availability),
662 especially the [configuration synchronisation section](12-distributed-monitoring-ha.md#cluster-zone-config-sync).
663
664
665
666
667 ### <a id="icinga2-client-cli-node"></a> Advanced Node Cli Actions
668
669 #### <a id="icinga2-remote-monitoring-master-discovery-blacklist-whitelist"></a> Blacklist/Whitelist for Clients on the Master
670
671 It's sometimes necessary to `blacklist` an entire remote client, or specific hosts or services
672 provided by this client. While it's reasonable for the local admin to configure for example an
673 additional ping check, you're not interested in that on the master sending out notifications
674 and presenting the dashboard to your support team.
675
676 Blacklisting an entire set might not be sufficient for excluding several objects, be it a
677 specific remote client with one ping servie you're interested in. Therefore you can `whitelist`
678 clients, hosts, services in a similar manner
679
680 Example for blacklisting all `ping*` services, but allowing only `probe` host with `ping4`:
681
682     # icinga2 node blacklist add --zone "*" --host "*" --service "ping*"
683     # icinga2 node whitelist add --zone "*" --host "probe" --service "ping*"
684
685 You can `list` and `remove` existing blacklists:
686
687     # icinga2 node blacklist list
688     Listing all blacklist entries:
689     blacklist filter for Node: '*' Host: '*' Service: 'ping*'.
690
691     # icinga2 node whitelist list
692     Listing all whitelist entries:
693     whitelist filter for Node: '*' Host: 'probe' Service: 'ping*'.
694
695
696 > **Note**
697 >
698 > The blacklist feature only prevents future updates from creating and removing objects, but it does not remove already existing objects.
699 > The `--zone` and `--host` arguments are required. A zone is always where the remote client is in.
700 > If you are unsure about it, set a wildcard (`*`) for them and filter only by host/services.
701
702
703
704 #### <a id="icinga2-client-master-discovery-manual"></a> Manually Discover Clients on the Master
705
706 Add a to-be-discovered client to the master:
707
708     # icinga2 node add my-remote-client
709
710 Set the connection details, and the Icinga 2 master will attempt to connect to this node and sync its
711 object repository.
712
713     # icinga2 node set my-remote-client --host 192.168.33.101 --port 5665
714
715 You can control that by calling the `node list` command:
716
717     # icinga2 node list
718     Node 'my-remote-client' (host: 192.168.33.101, port: 5665, log duration: 1 day, last seen: Sun Nov  2 17:46:29 2014)
719
720 #### <a id="icinga2-remote-monitoring-master-discovery-remove"></a> Remove Discovered Clients
721
722 If you don't require a connected agent, you can manually remove it and its discovered hosts and services
723 using the following CLI command:
724
725     # icinga2 node remove my-discovered-agent
726
727 > **Note**
728 >
729 > Better use [blacklists and/or whitelists](10-icinga2-client.md#icinga2-remote-monitoring-master-discovery-blacklist-whitelist)
730 > to control which clients and hosts/services are integrated into your master configuration repository.