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 ''
  2. Satellit:

    #Add the package key
    wget -O - | apt-key add -
    #Add the repository
    DIST=$(awk -F"[)(]+" '/VERSION=/ {print $2}' /etc/os-release); \
     echo "deb icinga-${DIST} main" > \
     echo "deb-src icinga-${DIST} main" >> \
    #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) []:
    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):
    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):
    Master/Satellite endpoint port [5665]:
    Add more master/satellite endpoints? [y/N]:
    Parent certificate information:
     Version:             3
     Subject:             CN =
     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:
     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 ''): 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 []:
    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...
    Now restart your Icinga 2 daemon to finish the installation!
  3. Add the new endpoint and zone to the configuration of the master

    object Endpoint "" {
    object Zone "" {
            endpoints = [ "" ]
            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

    You should see an added endpoint with the corrosponding zone

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

    Note: I configured it here with an agentless host, but this also works for agents!

  7. Deploy the changes

  8. Verify it works


  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