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](10-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](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))
28 ### <a id="icinga2-client-configuration-combined-scenarios"></a> Combined Client Scenarios
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.
34 Keep the following hints in mind:
36 * You can blacklist remote nodes entirely. They are then ignored on `node update-config`
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
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.
50 ## <a id="icinga2-client-requirements"></a> Requirements
52 * Overview of Configuration Objects
53 * SSL Certificates (manual or using CSR-Autosigning by the setup wizard)
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
61 port `5665`. The communication is bi-directional and the first node opening the
62 connection "wins" if there are both connection ways enabled in your firewall policies.
64 If you are going to use CSR-Autosigning, you must (temporarly) allow the client
65 connecting to the master instance and open the firewall port. Once the client install is done,
66 you can close the port and use a different communication direction (master-to-client).
68 ### <a id="icinga2-client-installation-master-setup"></a> Setup the Master for Remote Clients
70 If you are planning to use the [remote Icinga 2 clients](10-icinga2-client.md#icinga2-client)
71 you'll first need to update your master setup.
73 Your master setup requires the following
75 * SSL CA and signed certificate for the master
76 * Enabled API feature, and a local Endpoint and Zone object configuration
77 * Firewall ACLs for the communication port (default 5665)
79 You can use the [CLI command](8-cli-commands.md#cli-command-node) `node wizard` for setting up a new node
80 on the master. The command must be run as root, all Icinga 2 specific files
81 will be updated to the icinga user the daemon is running as (certificate files
84 Make sure to answer the first question with `n` (no).
87 Welcome to the Icinga 2 Setup Wizard!
89 We'll guide you through all required configuration details.
91 Please specify if this is a satellite setup ('n' installs a master setup) [Y/n]: n
92 Starting the Master setup routine...
93 Please specifiy the common name (CN) [icinga2-node1.localdomain]:
94 information/base: Writing private key to '/var/lib/icinga2/ca/ca.key'.
95 information/base: Writing X509 certificate to '/var/lib/icinga2/ca/ca.crt'.
96 information/cli: Initializing serial file in '/var/lib/icinga2/ca/serial.txt'.
97 information/cli: Generating new CSR in '/etc/icinga2/pki/icinga2-node1.localdomain.csr'.
98 information/base: Writing private key to '/etc/icinga2/pki/icinga2-node1.localdomain.key'.
99 information/base: Writing certificate signing request to '/etc/icinga2/pki/icinga2-node1.localdomain.csr'.
100 information/cli: Signing CSR with CA and writing certificate to '/etc/icinga2/pki/icinga2-node1.localdomain.crt'.
101 information/cli: Copying CA certificate to '/etc/icinga2/pki/ca.crt'.
102 information/cli: Dumping config items to file '/etc/icinga2/zones.conf'.
103 information/cli: Created backup file '/etc/icinga2/zones.conf.orig'.
104 Please specify the API bind host/port (optional):
107 information/cli: Enabling the APIlistener feature.
108 Enabling feature api. Make sure to restart Icinga 2 for these changes to take effect.
109 information/cli: Created backup file '/etc/icinga2/features-available/api.conf.orig'.
110 information/cli: Updating constants.conf.
111 information/cli: Created backup file '/etc/icinga2/constants.conf.orig'.
112 information/cli: Updating constants file '/etc/icinga2/constants.conf'.
113 information/cli: Updating constants file '/etc/icinga2/constants.conf'.
114 Please edit the constants.conf file '/etc/icinga2/constants.conf' and set a secure 'TicketSalt' constant.
117 Now restart your Icinga 2 daemon to finish the installation!
120 The setup wizard will do the following:
122 * Generate a local CA in `/var/lib/icinga2/ca` or use the existing one
123 * Generate a new CSR, sign it with the local CA and copying it into `/etc/icinga2/pki`
124 * Generate a local zone and endpoint configuration for this master based on FQDN
125 * Enabling the API feature, and setting optional `bind_host` and `bind_port`
126 * Setting the `NodeName` and `TicketSalt` constants in [constants.conf](5-configuring-icinga-2.md#constants-conf)
128 The setup wizard does not automatically restart Icinga 2.
130 Verify the modified configuration:
132 # egrep 'NodeName|TicketSalt' /etc/icinga2/constants.conf
134 # cat /etc/icinga2/zones.conf
136 * Generated by Icinga 2 node setup commands
137 * on 2015-02-09 15:21:49 +0100
140 object Endpoint "icinga2-node1.localdomain" {
143 object Zone "master" {
144 //this is the local node master named = "master"
145 endpoints = [ "icinga2-node1.localdomain" ]
148 Validate the configuration and restart Icinga 2.
153 > This setup wizard will install a standalone master, HA cluster scenarios are currently
154 > not supported and require manual modifications afterwards.
156 ## <a id="icinga2-client-setup"></a> Client Setup for Remote Monitoring
158 Icinga 2 can be installed on Linux/Unix and Windows. While
159 [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)
160 `node wizard` for a guided setup, you will need to use the
161 graphical installer for Windows based client setup.
163 Your client setup requires the following
165 * A ready configured and installed [master node](10-icinga2-client.md#icinga2-client-installation-master-setup)
166 * SSL signed certificate for communication with the master (Use [CSR auto-signing](certifiates-csr-autosigning)).
167 * Enabled API feature, and a local Endpoint and Zone object configuration
168 * Firewall ACLs for the communication port (default 5665)
172 ### <a id="csr-autosigning-requirements"></a> Requirements for CSR Auto-Signing
174 If your remote clients are capable of connecting to the central master, Icinga 2
175 supports CSR auto-signing.
177 First you'll need to define a secure ticket salt in the [constants.conf](5-configuring-icinga-2.md#constants-conf).
178 The [setup wizard for the master setup](10-icinga2-client.md#icinga2-client-installation-master-setup) will create
181 # grep TicketSalt /etc/icinga2/constants.conf
183 The client setup wizard will ask you to generate a valid ticket number using its CN.
184 If you already know your remote client's Common Names (CNs) - usually the FQDN - you
185 can generate all ticket numbers on-demand.
187 This is also reasonable if you are not capable of installing the remote client, but
188 a colleague of yours, or a customer.
190 Example for a client:
192 # icinga2 pki ticket --cn icinga2-node2.localdomain
197 > You can omit the `--salt` parameter using the `TicketSalt` constant from
198 > [constants.conf](5-configuring-icinga-2.md#constants-conf) if already defined and Icinga 2 was
199 > reloaded after the master setup.
201 ### <a id="certificates-manual-creation"></a> Manual SSL Certificate Generation
203 This is described separately in the [cluster setup chapter](12-distributed-monitoring-ha.md#manual-certificate-generation).
207 > If you're using [CSR Auto-Signing](10-icinga2-client.md#csr-autosigning-requirements), skip this step.
210 ### <a id="icinga2-client-installation-client-setup-linux"></a> Setup the Client on Linux
212 There is no extra client binary or package required. Install Icinga 2 from your distribution's package
213 repository as described in the general [installation instructions](2-getting-started.md#setting-up-icinga2).
215 Please make sure that either [CSR Auto-Signing](10-icinga2-client.md#csr-autosigning-requirements) requirements
216 are fulfilled, or that you're using [manual SSL certificate generation](12-distributed-monitoring-ha.md#manual-certificate-generation).
220 > You don't need any features (DB IDO, Livestatus) or user interfaces on the remote client.
221 > Install them only if you're planning to use them.
223 Once the package installation succeeded, use the `node wizard` CLI command to install
224 a new Icinga 2 node as client setup.
226 You'll need the following configuration details:
228 * The client common name (CN). Defaults to FQDN.
229 * The client's local zone name. Defaults to FQDN.
230 * The master endpoint name. Look into your master setup `zones.conf` file for the proper name.
231 * The master endpoint connection information. Your master's IP address and port (port defaults to 5665)
232 * The [request ticket number](10-icinga2-client.md#csr-autosigning-requirements) generated on your master
234 * Bind host/port for the Api feature (optional)
236 The command must be run as root, all Icinga 2 specific files will be updated to the icinga
237 user the daemon is running as (certificate files for example). The wizard creates backups
238 of configuration and certificate files if already existing.
240 Capitalized options in square brackets (e.g. `[Y/n]`) signal the default value and
241 allow you to continue pressing `Enter` instead of entering a value.
243 # icinga2 node wizard
244 Welcome to the Icinga 2 Setup Wizard!
245 We'll guide you through all required configuration details.
247 Please specify if this is a satellite setup ('n' installs a master setup) [Y/n]:
248 Starting the Node setup routine...
249 Please specifiy the common name (CN) [icinga2-node2.localdomain]:
250 Please specifiy the local zone name [icinga2-node2.localdomain]:
251 Please specify the master endpoint(s) this node should connect to:
252 Master Common Name (CN from your master setup): icinga2-node1.localdomain
253 Please fill out the master connection information:
254 Master endpoint host (optional, your master's IP address or FQDN): 192.168.56.101
255 Master endpoint port (optional) []:
256 Add more master endpoints? [y/N]
257 Please specify the master connection for CSR auto-signing (defaults to master endpoint host):
258 Host [192.168.56.101]:
260 information/base: Writing private key to '/etc/icinga2/pki/icinga2-node2.localdomain.key'.
261 information/base: Writing X509 certificate to '/etc/icinga2/pki/icinga2-node2.localdomain.crt'.
262 information/cli: Generating self-signed certifiate:
263 information/cli: Fetching public certificate from master (192.168.56.101, 5665):
265 information/cli: Writing trusted certificate to file '/etc/icinga2/pki/trusted-master.crt'.
266 information/cli: Stored trusted master certificate in '/etc/icinga2/pki/trusted-master.crt'.
268 Please specify the request ticket generated on your Icinga 2 master.
269 (Hint: # icinga2 pki ticket --cn 'icinga2-node2.localdomain'): ead2d570e18c78abf285d6b85524970a0f69c22d
270 information/cli: Processing self-signed certificate request. Ticket 'ead2d570e18c78abf285d6b85524970a0f69c22d'.
272 information/cli: Writing signed certificate to file '/etc/icinga2/pki/icinga2-node2.localdomain.crt'.
273 information/cli: Writing CA certificate to file '/etc/icinga2/pki/ca.crt'.
274 Please specify the API bind host/port (optional):
277 information/cli: Disabling the Notification feature.
278 Disabling feature notification. Make sure to restart Icinga 2 for these changes to take effect.
279 information/cli: Enabling the Apilistener feature.
280 Enabling feature api. Make sure to restart Icinga 2 for these changes to take effect.
281 information/cli: Created backup file '/etc/icinga2/features-available/api.conf.orig'.
282 information/cli: Generating local zones.conf.
283 information/cli: Dumping config items to file '/etc/icinga2/zones.conf'.
284 information/cli: Created backup file '/etc/icinga2/zones.conf.orig'.
285 information/cli: Updating constants.conf.
286 information/cli: Created backup file '/etc/icinga2/constants.conf.orig'.
287 information/cli: Updating constants file '/etc/icinga2/constants.conf'.
288 information/cli: Updating constants file '/etc/icinga2/constants.conf'.
291 Now restart your Icinga 2 daemon to finish the installation!
294 The setup wizard will do the following:
296 * Generate a new self-signed certificate and copy it into `/etc/icinga2/pki`
297 * Store the master's certificate as trusted certificate for requesting a new signed certificate
298 (manual step when using `node setup`).
299 * Request a new signed certificate from the master and store updated certificate and master CA in `/etc/icinga2/pki`
300 * Generate a local zone and endpoint configuration for this client and the provided master information
302 * Disabling the `notification` feature for this client
303 * Enabling the `api` feature, and setting optional `bind_host` and `bind_port`
304 * Setting the `NodeName` constant in [constants.conf](5-configuring-icinga-2.md#constants-conf)
306 The setup wizard does not automatically restart Icinga 2.
308 Verify the modified configuration:
310 # grep 'NodeName' /etc/icinga2/constants.conf
312 # cat /etc/icinga2/zones.conf
314 * Generated by Icinga 2 node setup commands
315 * on 2015-02-09 16:56:10 +0100
318 object Endpoint "icinga2-node1.localdomain" {
319 host = "192.168.56.101"
322 object Zone "master" {
323 endpoints = [ "icinga2-node1.localdomain" ]
326 object Endpoint "icinga2-node2.localdomain" {
329 object Zone "icinga2-node2.localdomain" {
330 //this is the local node = "icinga2-node2.localdomain"
331 endpoints = [ "icinga2-node2.localdomain" ]
335 Validate the configuration and restart Icinga 2.
337 If you are getting an error when requesting the ticket number, please check the following:
339 * Can your client connect to the master instance?
340 * Is the CN the same (from pki ticket on the master and setup node on the client)?
341 * Is the ticket expired?
345 #### <a id="icinga2-client-installation-client-setup-linux-manual"></a> Manual Setup without Wizard
347 Instead of using the `node wizard` cli command, there is an alternative `node setup`
348 cli command available which has some pre-requisites. Make sure that the
349 `/etc/icinga2/pki` exists and is owned by the `icinga` user (or the user Icinga 2 is
352 `icinga2-node1.localdomain` is the already installed master instance while
353 `icinga2-node2.localdomain` is the instance where the installation cli commands
356 Required information:
358 * The client common name (CN). Use the FQDN, e.g. `icinga2-node2.localdomain`.
359 * The master host and zone name. Pass that to `pki save-cert` as `--host` parameter for example.
360 * The client ticket number generated on the master (`icinga2 pki ticket --cn icinga2-node2.localdomain`)
362 Generate a new local self-signed certificate.
364 # icinga2 pki new-cert --cn icinga2-node2.localdomain \
365 --key /etc/icinga2/pki/icinga2-node2.localdomain.key \
366 --cert /etc/icinga2/pki/icinga2-node2.localdomain.crt
368 Request the master certificate from the master host (`icinga2-node1.localdomain`)
369 and store it as `trusted-master.crt`. Review it and continue.
371 # icinga2 pki save-cert --key /etc/icinga2/pki/icinga2-node2.localdomain.key \
372 --cert /etc/icinga2/pki/icinga2-node2.localdomain.crt \
373 --trustedcert /etc/icinga2/pki/trusted-master.crt \
374 --host icinga2-node1.localdomain
376 Send the self-signed certificate to the master host using the ticket number and
377 receive a CA signed certificate and the master's `ca.crt` certificate.
378 Specify the path to the previously stored trusted master certificate.
380 # icinga2 pki request --host icinga2-node1.localdomain \
382 --ticket ead2d570e18c78abf285d6b85524970a0f69c22d \
383 --key /etc/icinga2/pki/icinga2-node2.localdomain.key \
384 --cert /etc/icinga2/pki/icinga2-node2.localdomain.crt \
385 --trustedcert /etc/icinga2/pki/trusted-master.crt \
386 --ca /etc/icinga2/pki/ca.crt
388 Continue with the additional node setup steps. Specify a local endpoint and zone name (`icinga2-node2.localdomain`)
389 and set the master host (`icinga2-node1.localdomain`) as parent zone configuration. Specify the path to
390 the previously stored trusted master certificate.
392 # icinga2 node setup --ticket ead2d570e18c78abf285d6b85524970a0f69c22d \
393 --endpoint icinga2-node1.localdomain \
394 --zone icinga2-node2.localdomain \
395 --master_host icinga2-node1.localdomain \
396 --trustedcert /etc/icinga2/pki/trusted-master.crt
398 Restart Icinga 2 once complete.
400 # service icinga2 restart
403 ### <a id="icinga2-client-installation-client-setup-windows"></a> Setup the Client on Windows
405 Download the MSI-Installer package from [http://packages.icinga.org/windows/](http://packages.icinga.org/windows/).
408 * [Microsoft .NET Framework 2.0](http://www.microsoft.com/de-de/download/details.aspx?id=1639) if not already installed.
410 The setup wizard will install Icinga 2 and then continue with SSL certificate generation,
411 CSR-Autosigning and configuration setup.
413 You'll need the following configuration details:
415 * The client common name (CN). Defaults to FQDN.
416 * The client's local zone name. Defaults to FQDN.
417 * The master endpoint name. Look into your master setup `zones.conf` file for the proper name.
418 * The master endpoint connection information. Your master's IP address and port (defaults to 5665)
419 * The [request ticket number](10-icinga2-client.md#csr-autosigning-requirements) generated on your master
421 * Bind host/port for the Api feature (optional)
423 Once install is done, Icinga 2 is automatically started as a Windows service.
425 The Icinga 2 configuration is located inside the installation path and can be edited with
426 your favorite editor.
428 Configuration validation is done similar to the linux pendant on the Windows shell:
430 C:> icinga2.exe daemon -C
435 ## <a id="icinga2-client-configuration-modes"></a> Client Configuration Modes
437 * Clients with [local configuration](10-icinga2-client.md#icinga2-client-configuration-local), sending their inventory to the master
438 * Clients as [command execution bridge](10-icinga2-client.md#icinga2-client-configuration-command-bridge) without local configuration
439 * Clients receive their configuration from the master ([Cluster config sync](10-icinga2-client.md#icinga2-client-configuration-master-config-sync))
441 ### <a id="icinga2-client-configuration-local"></a> Clients with Local Configuration
443 This is considered as independant satellite using a local scheduler, configuration
444 and the possibility to add Icinga 2 features on demand.
446 There is no difference in the configuration syntax on clients to any other Icinga 2 installation.
447 You can also use additional features like notifications directly on the remote client, if you are
448 required to. Basically everything a single Icinga 2 instance provides by default.
450 The following convention applies to remote clients:
452 * The hostname in the default host object should be the same as the Common Name (CN) used for SSL setup
453 * Add new services and check commands locally
455 Local configured checks are transferred to the central master. There are additional `node`
456 cli commands available which allow you to list/add/remove/blacklist remote clients and
457 generate the configuration on the master.
460 #### <a id="icinga2-remote-monitoring-master-discovery"></a> Discover Client Services on the Master
462 Icinga 2 clients will sync their locally defined objects to the defined master node. That way you can
463 list, add, filter and remove nodes based on their `node`, `zone`, `host` or `service` name.
465 List all discovered nodes (satellites, agents) and their hosts/services:
468 Node 'icinga2-node2.localdomain' (last seen: Mon Feb 9 16:58:21 2015)
469 * Host 'icinga2-node2.localdomain'
482 Listing the node and its host(s) and service(s) does not modify the master configuration yet. You
483 meed to generate the configuration in the next step.
486 ### <a id="icinga2-client-master-discovery-generate-config"></a> Generate Configuration for Client Services on the Master
488 There is a dedicated Icinga 2 CLI command for updating the client services on the master,
489 generating all required configuration.
491 # icinga2 node update-config
493 The generated configuration of all nodes is stored in the `repository.d/` directory.
495 By default, the following additional configuration is generated:
496 * add `Endpoint` and `Zone` objects for the newly added node
497 * add `cluster-zone` health check for the master host for reachability and dependencies
498 * use the default templates `satellite-host` and `satellite-service` defined in `/etc/icinga2/conf.d/satellite.conf`
499 * apply a dependency for all other hosts on the remote satellite prevening failure checks/notifications
501 If hosts or services disappeared from the client discovery, it will remove the existing configuration objects
502 from the config repository. If there are existing hosts/services defined or modified, the CLI command will not
503 overwrite these (modified) configuration files.
505 After updating the configuration repository, make sure to reload Icinga 2.
507 # service icinga2 reload
510 # systemctl reload icinga2
513 The `update-config` CLI command will fail, if there are uncommitted changes for the
514 configuration repository.
515 Please review these changes manually, or clear the commit and try again. This is a
516 safety hook to prevent unwanted manual changes to be committed by a updating the
517 client discovered objects only.
519 # icinga2 repository commit --simulate
520 # icinga2 repository clear-changes
521 # icinga2 repository commit
524 ### <a id="icinga2-client-configuration-command-bridge"></a> Clients as Command Execution Bridge
526 Similar to other addons (NRPE, NSClient++, etc) the remote Icinga 2 client will only
527 execute commands the master instance is sending. There are no local host or service
528 objects configured, only the check command definitions must be configured.
532 > Remote clients must explicitely accept commands in a similar
533 > fashion as cluster nodes [accept configuration](#cluster-zone-config-sync).
534 > This is due to security reasons.
536 Edit the `api` feature configuration in `/etc/icinga2/features-enabled/api.conf` on your client
537 and set `accept_commands` to `true`.
539 object ApiListener "api" {
540 cert_path = SysconfDir + "/icinga2/pki/" + NodeName + ".crt"
541 key_path = SysconfDir + "/icinga2/pki/" + NodeName + ".key"
542 ca_path = SysconfDir + "/icinga2/pki/ca.crt"
543 accept_commands = true
546 Icinga 2 on the remote client does not schedule checks locally, or keep checking
547 hosts/services on connection loss. This mode also does not allow to use features
548 for backend data writing (DB IDO, Perfdata, etc.) as the client does not have
549 local objects configured.
551 Icinga 2 already provides a variety of `CheckCommand` definitions using the Plugin
552 Check Commands, but you should also modify the local configuration inside `commands.conf`
555 If you're wondering why you need to keep the same command configuration on the master and
556 remote client: Icinga 2 calculates all required runtime macros used as command arguments on
557 the master and sends that information to the client.
558 In case you want to limit command arguments or handles values in a different manner, you
559 can modify the check command configuration on the remote client only. See [this issue](https://dev.icinga.org/issues/8221#note-3)
562 ### <a id="icinga2-client-configuration-command-bridge-master-config"></a> Master Configuration for Clients as Command Execution Bridge
564 This step involves little knowledge about the way the Icinga 2 nodes communication and trust
565 each other. Each client is configured as `Endpoint` object providing connection information.
566 As a matter of trust the client `Endpoint` is a member of its own `Zone` object which gets
567 the master zone configured as parent. That way the master knows how to connect to the client
568 and where to execute the check commands.
570 Add an `Endpoint` and `Zone` configuration object for the remote client
571 in `/etc/icinga2/zones.conf` and define a trusted master zone as `parent`.
573 object Endpoint "icinga2-node2.localdomain" {
574 host = "192.168.56.102"
577 object Zone "icinga2-node2.localdomain" {
579 endpoints = [ "icinga2-node2.localdomain" ]
583 * [configure endpoints](12-distributed-monitoring-ha.md#configure-cluster-endpoints)
584 * [configure zones](12-distributed-monitoring-ha.md#configure-cluster-zones)
587 Once you have configured the required `Endpoint` and `Zone` object definition, you can start
588 configuring your host and service objects. The configuration is simple: If the `command_endpoint`
589 attribute is set, Icinga 2 calculcates all required runtime macros and sends that over to the
590 defined endpoint. The check result is then received asynchronously through the cluster protocol.
592 object Host "host-remote" {
593 import "generic-host"
595 address = "127.0.0.1"
601 apply Service "users-remote" {
602 import "generic-service"
604 check_command = "users"
605 command_endpoint = "remote-client1"
607 vars.users_wgreater = 10
608 vars.users_cgreater = 20
610 /* assign where a remote client is set */
611 assign where host.vars.remote_client
615 If there is a failure on execution (for example, the local check command configuration or the plugin
616 is missing), the check will return `UNKNOWN` and populate the check output with the error message.
617 This will happen in a similar fashion if you forgot to enable the `accept_commands` attribute
618 inside the `api` feature.
620 If you don't want to define the endpoint name inside the service apply rule everytime, you can
621 also easily inherit this from a host's custom attribute like shown in the example below.
623 object Host "host-remote" {
624 import "generic-host"
626 address = "127.0.0.1"
631 vars.remote_client = "remote-client1"
633 /* host specific check arguments */
634 vars.users_wgreater = 10
635 vars.users_cgreater = 20
638 apply Service "users-remote" {
639 import "generic-service"
641 check_command = "users"
642 command_endpoint = host.vars.remote_client
644 /* override (remote) command arguments with host settings */
645 vars.users_wgreater = host.vars.users_wgreater
646 vars.users_cgreater = host.vars.users_cgreater
648 /* assign where a remote client is set */
649 assign where host.vars.remote_client
652 That way your generated host object is the information provider and the service apply
653 rules must only be configured once.
657 > [Event commands](3-monitoring-basics.md#event-commands) are executed on the
658 > remote command endpoint as well. You do not need
659 > an additional transport layer such as SSH or similar.
662 ### <a id="icinga2-client-configuration-master-config-sync"></a> Clients with Master Config Sync
664 This is an advanced configuration mode which requires knowledge about the Icinga 2
665 cluster configuration and its object relation (Zones, Endpoints, etc) and the way you
666 will be able to sync the configuration from the master to the remote satellite or client.
668 Please continue reading in the [distributed monitoring chapter](12-distributed-monitoring-ha.md#distributed-monitoring-high-availability),
669 especially the [configuration synchronisation section](12-distributed-monitoring-ha.md#cluster-zone-config-sync).
674 ### <a id="icinga2-client-cli-node"></a> Advanced Node Cli Actions
676 #### <a id="icinga2-remote-monitoring-master-discovery-blacklist-whitelist"></a> Blacklist/Whitelist for Clients on the Master
678 It's sometimes necessary to `blacklist` an entire remote client, or specific hosts or services
679 provided by this client. While it's reasonable for the local admin to configure for example an
680 additional ping check, you're not interested in that on the master sending out notifications
681 and presenting the dashboard to your support team.
683 Blacklisting an entire set might not be sufficient for excluding several objects, be it a
684 specific remote client with one ping servie you're interested in. Therefore you can `whitelist`
685 clients, hosts, services in a similar manner
687 Example for blacklisting all `ping*` services, but allowing only `probe` host with `ping4`:
689 # icinga2 node blacklist add --zone "*" --host "*" --service "ping*"
690 # icinga2 node whitelist add --zone "*" --host "probe" --service "ping*"
692 You can `list` and `remove` existing blacklists:
694 # icinga2 node blacklist list
695 Listing all blacklist entries:
696 blacklist filter for Node: '*' Host: '*' Service: 'ping*'.
698 # icinga2 node whitelist list
699 Listing all whitelist entries:
700 whitelist filter for Node: '*' Host: 'probe' Service: 'ping*'.
705 > The `--zone` and `--host` arguments are required. A zone is always where the remote client is in.
706 > If you are unsure about it, set a wildcard (`*`) for them and filter only by host/services.
710 #### <a id="icinga2-client-master-discovery-manual"></a> Manually Discover Clients on the Master
712 Add a to-be-discovered client to the master:
714 # icinga2 node add my-remote-client
716 Set the connection details, and the Icinga 2 master will attempt to connect to this node and sync its
719 # icinga2 node set my-remote-client --host 192.168.33.101 --port 5665
721 You can control that by calling the `node list` command:
724 Node 'my-remote-client' (host: 192.168.33.101, port: 5665, log duration: 1 day, last seen: Sun Nov 2 17:46:29 2014)
726 #### <a id="icinga2-remote-monitoring-master-discovery-remove"></a> Remove Discovered Clients
728 If you don't require a connected agent, you can manually remove it and its discovered hosts and services
729 using the following CLI command:
731 # icinga2 node remove my-discovered-agent
735 > Better use [blacklists and/or whitelists](10-icinga2-client.md#icinga2-remote-monitoring-master-discovery-blacklist-whitelist)
736 > to control which clients and hosts/services are integrated into your master configuration repository.