Introduction

A Icinga 2 satellite is very useful to monitor external remote networks that are not directly accessible from the master server.

The Icinga 2 documentation clearly describes the master->satellite->client setup, but (hopefully) nowadays you use Icinga Director for the configuration management.

This raised a question for me: How to configure it and especially where. Define the zones in the Icinga core config? Director? Custom config which is shipped via the fileshipper?

Unfortunaly the docs remain silent about this topic. Or I didn’t read them properly.

My first try was to create the Zones and Endpoint in the Director, but this failed. Either I had duplicate endpoints or zones in the configuration, or the satellite did not get the configuration pushed correctly and thus didn’t execute the checks.

I tried a few setups of blog and forum posts and found one that works for me. If you know your guts in Icinga 2 and just need a thought provoking, a TL;DR is at the bottom.

My setup

I have a VPS which act as a my single Icinga master. On this server is also the Director installed.

At the offsite location I use a LXC Debian container on my proxmox host, which has access to my networks. This server also does not need any kind of port forwarding for this to work! The satellite initialize the connection.

The Steps

1. Master:

   #Get a PKI ticket for the satellite (You will need it later)
   root@BMSDEB01FRA2:~# icinga2 pki ticket --cn 'MONDEB01DEL.brand-web.net'
   randomlongStringIreplaced
   

2. Satellit:

   #Add the package key
   wget -O - https://packages.icinga.com/icinga.key | apt-key add -
   #Add the repository
   DIST=$(awk -F"[)(]+" '/VERSION=/ {print $2}' /etc/os-release); \
    echo "deb http://packages.icinga.com/debian icinga-${DIST} main" > \
    /etc/apt/sources.list.d/${DIST}-icinga.list
    echo "deb-src http://packages.icinga.com/debian icinga-${DIST} main" >> \
    /etc/apt/sources.list.d/${DIST}-icinga.list
   #Update packages list and install icinga2
   apt update
   apt install icinga2
   
   #Start the node wizard
   root@MONDEB01DEL:~# icinga2 node wizard
   Welcome to the Icinga 2 Setup Wizard!
   We will guide you through all required configuration details.
   Please specify if this is an agent/satellite setup ('n' installs a master setup) [Y/n]:
   
   Starting the Agent/Satellite setup routine...
   Please specify the common name (CN) [MONDEB01DEL.brand-web.net]:
   
   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): bmsdeb01fra2.biocrafting.net
   
   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): bmsdeb01fra2.biocrafting.net
   Master/Satellite endpoint port [5665]:
   
   Add more master/satellite endpoints? [y/N]:
   Parent certificate information:
   
    Version:             3
    Subject:             CN = bmsdeb01fra2.biocrafting.net
    Issuer:              CN = Icinga CA
    Valid From:          Dec 14 08:34:20 2020 GMT
    Valid Until:         Dec 11 08:34:20 2035 GMT
    Serial:              1d:88:15:44:ec:20:34:7a:62:17:0b:75:4e:f8:cc:5a:4d:89:b0:38
   
    Signature Algorithm: sha256WithRSAEncryption
    Subject Alt Names:   bmsdeb01fra2.biocrafting.net
    Fingerprint:         41 95 E8 2C 80 BE CC A3 9B E1 2E 6E 39 E0 09 A3 6D 05 E1 7C 28 86 D0 29 9E B2 33 06 D5 FA 9E 9E
   
   Is this information correct? [y/N]: y
   
   Please specify the request ticket generated on your Icinga 2 master (optional).
    (Hint: # icinga2 pki ticket --cn 'MONDEB01DEL.brand-web.net'): randomlongStringIreplaced
   Please specify the API bind host/port (optional):
   Bind Host []: ::
   Bind Port []:
   
   Accept config from parent node? [y/N]: y
   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.
   
   Local zone name [MONDEB01DEL.brand-web.net]:
   Parent zone name [master]:
   
   Default global zones: global-templates director-global
   Do you want to specify additional global zones? [y/N]:
   
   Do you want to disable the inclusion of the conf.d directory [Y/n]:
   Disabling the inclusion of the conf.d directory...
   
   Done.
   
   Now restart your Icinga 2 daemon to finish the installation!
   

3. Add the new endpoint and zone to the configuration of the master

   #/etc/icinga2/zones.conf
   ...
   object Endpoint "MONDEB01DEL.brand-web.net" {
   }
   
   object Zone "MONDEB01DEL.brand-web.net" {
           endpoints = [ "MONDEB01DEL.brand-web.net" ]
           parent = "master"
   }
   ...
   

4. Restart icinga2 on the master and the satellite. Afterwards you should see in the satellite log (cat /var/log/icinga2/icinga2.log) that the config from the master was pushed down.

5. Go to Icinga Director and re-run the Kickstart Wizard

   

   

   

6. Add a host which is only reachable via the satellite node and set the cluster zone

   

7. Deploy the changes

8. Verify it works

   

TL;DR

1. Run icinga2 node wizard on your satellite (selecting to configure it as satellite/agent with its own zone name and having your master as the parent)
2. Manually add zone and endpoint objects to zones.conf on your master
3. restart icinga2 services on the master and satellite
4. Open Icinga Director and run kickstart wizard
5. Start configuring your hosts, set the cluster zone to the desired satellite
6. Deploy