Download PDF here.
Abstract
Version 2.3
January 9, 2018
The purpose of this document is to provide the steps necessary for connecting a client instance of Icinga 2, version 2.8 or later, to a master node. The steps contained within are sourced from the official Icinga 2 documentation, “Distributed Monitoring with Master, Satellites, and Clients”
This version of the documentation has been adapted to match the necessary upgrade steps for an instance of the Shadow-Soft Marketplace VHD image.
Distributed Monitoring
Your Shadow-Soft Marketplace VHD image for Icinga 2 is already configured with a “Master” node. If you have a second Icinga 2 node that you would like to have as a part of your monitoring environment, you can connect the two Icinga 2 daemons together securely using the icinga2 node wizard
commands. This creates an SSL-authenticated tunnel between the daemons over port 5665. This connection will allow configuration to be distributed outward to the satellite, and allow local checks on the satellite node to be executed, then communicated upstream to the master.
- A master node has no parent node
- A master node is where you usually install Icinga Web 2.
- A master node can combine executed checks from child nodes into backends and notifications.
- A satellite node has a parent node, and may have a child node.
- A satellite node may execute checks on its own or delegate check execution to child nodes.
- A satellite node can receive configuration for hosts/services, etc. from the parent node.
- A satellite node continues to run even if the master node is temporarily unavailable.
- A client node only has a parent node.
- A client node will either run its own configured checks or receive command execution events from the parent node.

This guide only covers a two-level deep configuration, one Master to one Satellite/Client. For more complex scenarios, please see Section 6.10, “Scenarios” of the Official Icinga 2 Documentation. |
Security
- SSL certificates are mandatory for communication between nodes. The CLI commands help you create those certs automatically.
- Child zones only receive updates (check results, commands, etc.) for their configured objects.
- Zones cannot interfere with other zones and influence each other. Each checkable host or service object is assigned to one zone only.
- Config sync and remote command endpoint execution is disabled by default.
Connecting a Linux Client
To install the Icinga 2 client on a Linux host, refer to the official Icinga 2 Documentation at Section 2 – Getting Started
yum install -y epel-release https://packages.icinga.org/epel/7/release/noarch/icinga-rpm-release-7-2.el7.centos.noarch.rpm yum install -y icinga2-2.8.1-1.el7.icinga.x86_64 icinga2-selinux-2.8.1-1.el7.icinga.x86_64 nagios-plugins-all |
OPTIONAL: Change the hostname before anything else is done.
[root@master normaluser]# hostnamectl --static set-hostname {newhostname} |
[root@icinga-client ~]# icinga2 node wizard Welcome to the Icinga 2 Setup Wizard! We will guide you through all required configuration details. Please specify if this is a satellite/client setup ('n' installs a master setup) [Y/n]: Y Starting the Client/Satellite setup routine... Please specify the common name (CN) [linux.lkgjae410gcenioewmnm2iwj0d.bx.internal.cloudapp.net]: linux Please specify the parent endpoint(s) (master or satellite) where this node should connect to: Master/Satellite Common Name (CN from your master/satellite node): master0 Do you want to establish a connection to the parent node from this node? [Y/n]: Y Please specify the master/satellite connection information: Master/Satellite endpoint host (IP address or FQDN): 10.5.2.4 Master/Satellite endpoint port [5665]: Add more master/satellite endpoints? [y/N]: N Parent certificate information: Subject: CN = master0 Issuer: CN = Icinga CA Valid From: Jan 19 13:44:14 2018 GMT Valid Until: Jan 15 13:44:14 2033 GMT Fingerprint: BD 82 0B 16 0C 2D 21 3F AB 20 C7 A7 00 0D 5D 84 7C E3 62 50 Is this information correct? [y/N]: y Please specify the request ticket generated on your Icinga 2 master (optional). (Hint: # icinga2 pki ticket --cn 'linux'): No ticket was specified. Please approve the certificate signing request manually on the master (see 'icinga2 ca list' and 'icinga2 ca sign --help' for details). Please specify the API bind host/port (optional): Bind Host []: Bind Port []: Accept config from parent node? [y/N]: N Accept commands from parent node? [y/N]: y Reconfiguring Icinga... Disabling feature notification. Make sure to restart Icinga 2 for these changes to take effect. Enabling feature api. Make sure to restart Icinga 2 for these changes to take effect. Done. Now restart your Icinga 2 daemon to finish the installation! [root@icinga-client ~]# systemctl restart icinga2 [root@icinga-client ~]# |
Sign certificate from the Master
[root@master0 icinga2]# icinga2 ca list Fingerprint | Timestamp | Signed | Subject -----------------------------------------------------------------|--------------------------|--------|-------- 90ca3133dcfd8b90981fa9c14889dff7e7520680b7a393a416598d4c15205572 | Jan 19 14:13:48 2018 GMT | | CN = linux [root@master0 icinga2]# icinga2 ca sign 90ca3133dcfd8b90981fa9c14889dff7e7520680b7a393a416598d4c15205572 information/cli: Signed certificate for 'CN = linux'. |
After icinga2 node wizard
is complete, comment out the last line (include_recursive “conf.d”) in /etc/icinga2/icinga2.conf
Connecting a Windows Client
To install the Icinga 2 client on a Windows host, refer to the official Icinga 2 Documentation at Section 6.8.3 – Client/Satellite Windows Setup
OPTIONAL: Change the hostname before anything else is done. Follow these steps:
- Type sysdm.cpl into the start menu search box
- On the Computer Name tab, click on the “Change” button to rename the computer
- Reboot
The installer package includes the NSClient++ so that Icinga 2 can use its built-in plugins. You can find more details in this chapter. The Windows package also installs native monitoring plugin binaries to get you started more easily.
The graphical installer will offer to run the Icinga 2 setup wizard after the installation. You can also manually run the Icinga 2 setup wizard from the Start menu. On a fresh installation the setup wizard will guide you through the initial configuration and offer to use CSR auto-signing for generating the SSL certificate.

-
For ‘Instance Name’ use the client’s Common name
- Click “Add” and fill in the Instance Name and Host with the Common Name and FQDN/DNS Address of your host
- Select “Accept commands from master”
- Optionally Install/Update NSClient++ to provide additional check command plugins
- Click Next, confirm that the displayed certificate information is valid, then click next again
- The installer will either prompt you to install NSClient++, or complete the installation, depending on your previous choice
- Click “Finish” to complete the installation
NOTE: Windows does not have Ping
activated out of the box. To enable it, follow these steps:
- Open
Windows Firewall
- From the left pane of the resulting window, click
- In the right pane, find the rule titled
After icinga2 setup wizard
is complete, comment out the last line (include_recursive “conf.d”) in /etc/icinga2/icinga2.conf
Sign certificate from the Master
[root@master0 icinga2]# icinga2 ca list Fingerprint | Timestamp | Signed | Subject -----------------------------------------------------------------|--------------------------|--------|-------- 90ca3133dcfd8b90981fa9c14889dff7e7520680b7a393a416598d4c15205572 | Jan 19 14:13:48 2018 GMT | | CN = linux [root@master0 icinga2]# icinga2 ca sign 90ca3133dcfd8b90981fa9c14889dff7e7520680b7a393a416598d4c15205572 information/cli: Signed certificate for 'CN = linux'. |
Connecting Clients Using Director
Follow the director documentation for connecting clients via the Director module. Github: Icingaweb2 module director
Verifying Connectivity
To confirm that the Master and Client nodes are now connected, use netstat
and grep for port :5665 on both hosts.
Master Node
[root@icinga-master ~]# netstat | grep :5665 tcp 0 0 0.0.0.0:5665 0.0.0.0:* LISTEN tcp 0 0 $MASTER-IP:5665 $WINDOWS-CLIENT-IP:xxxxx ESTABLISHED tcp 0 0 $MASTER-IP:5665 $LINUX-CLIENT-IP:xxxxx ESTABLISHED |
Client Node
[root@icinga-client ~]# clear [root@icinga-client ~]# netstat | grep :5665 tcp 0 0 0.0.0.0:5665 0.0.0.0:* LISTEN tcp 0 0 $CLIENT-IP:xxxxx $MASTER-IP:5665 ESTABLISHED |
Configuration Modifications:
After the master and the client are connected, the following changes need to be made on the master:
- Edit the /etc/icinga2/hosts.d/$fqdn.conf file
object Zone "fqdn" { endpoints = [ "fqdn" ] parent = ZoneName } object Endpoint "fqdn" { host = "DNS" } object Host "fqdn" { import "generic-linux-host" address = "DNS" }
- Restart the Icinga2 service