diff --git a/doc/15-troubleshooting.md b/doc/15-troubleshooting.md
index 727c56c34..12817e940 100644
--- a/doc/15-troubleshooting.md
+++ b/doc/15-troubleshooting.md
@@ -1628,53 +1628,26 @@ In order to solve this problem, remove the mentioned files from `zones.d` and us
of syncing plugin binaries to your satellites and agents.
-#### Zones in Zones doesn't work
+#### Zones in Zones
-The cluster config sync works in the way that configuration
-put into `/etc/icinga2/zones.d` only is included when configured
-outside in `/etc/icinga2/zones.conf`.
+The cluster config sync works in a such manner that any `/etc/icinga2/zones.d/` subdirectory is included only when it is
+named after a known zone by the local `Endpoint`.
-If you for example create a "Zone Inception" with defining the
-`satellite` zone in `zones.d/master`, the config compiler does not
-re-run and include this zone config recursively from `zones.d/satellite`.
+If you for example add some configs in to `zones.d/satellite` and forgot to define the `satellite` zone
+in `zones.d/master` or outside in `/etc/icinga2/zones.conf`, the config compiler will not include
+this config from the `zones.d/satellite` zone directory.
Since v2.11, the config compiler is only including directories where a
-zone has been configured. Otherwise it would include renamed old zones,
+zone has been configured. Otherwise, it would include renamed old zones,
broken zones, etc. and those long-lasting bugs have been now fixed.
-A more concrete example: Masters and Satellites still need to know the Zone hierarchy outside of `zones.d` synced configuration.
+Here are some working examples:
-**Doesn't work**
+**Example: Everything in `zones.conf`**
-```
-vim /etc/icinga2/zones.conf
-
-object Zone "master" {
- endpoints = [ "icinga2-master1.localdomain", "icinga2-master2.localdomain" ]
-}
-```
-
-```
-vim /etc/icinga2/zones.d/master/satellite-zones.conf
-
-object Zone "satellite" {
- endpoints = [ "icinga2-satellite1.localdomain", "icinga2-satellite1.localdomain" ]
-}
-```
-
-```
-vim /etc/icinga2/zones.d/satellite/satellite-hosts.conf
-
-object Host "agent" { ... }
-```
-
-The `agent` host object will never reach the satellite, since the master does not have
-the `satellite` zone configured outside of zones.d.
-
-
-**Works**
-
-Each instance needs to know this, and know about the endpoints first:
+Each instance needs to know the `Zone` and `Endpoint` definitions for itself and all directly connected instances in order
+to successfully establish a connection with each other. This can be achieved by placing all `Endpoint` and `Zone` definitions
+of all Icinga 2 instances known by the local endpoint in this single file.
```
vim /etc/icinga2/zones.conf
@@ -1682,24 +1655,41 @@ vim /etc/icinga2/zones.conf
object Endpoint "icinga2-master1.localdomain" { ... }
object Endpoint "icinga2-master2.localdomain" { ... }
-object Endpoint "icinga2-satellite1.localdomain" { ... }
-object Endpoint "icinga2-satellite2.localdomain" { ... }
-```
-
-Then the zone hierarchy as trust and also config sync inclusion is required.
-
-```
-vim /etc/icinga2/zones.conf
-
object Zone "master" {
endpoints = [ "icinga2-master1.localdomain", "icinga2-master2.localdomain" ]
}
+object Endpoint "icinga2-satellite1.localdomain" { ... }
+object Endpoint "icinga2-satellite2.localdomain" { ... }
+
object Zone "satellite" {
endpoints = [ "icinga2-satellite1.localdomain", "icinga2-satellite1.localdomain" ]
+ parent = "master"
}
```
+**Example: Child zones in `zones.d/`**
+
+An additional option that Icinga 2 offers is the possibility to outsource all *child* `Endpoint` definitions of the
+local Icinga 2 instance to the `zones.d/` directory. As an example, we can place the satellite `Zone` and `Endpoint` definition
+from the above example into `zones.d/` underneath a directory named exactly like the local endpoint `Zone` name, which
+in our case is `master`.
+
+```
+mkdir /etc/icinga2/zones.d/master
+vim /etc/icinga2/zones.d/master/satellite.conf
+
+object Endpoint "icinga2-satellite1.localdomain" { ... }
+object Endpoint "icinga2-satellite2.localdomain" { ... }
+
+object Zone "satellite" {
+ endpoints = [ "icinga2-satellite1.localdomain", "icinga2-satellite1.localdomain" ]
+ parent = "master"
+}
+
+...
+```
+
Once done, you can start deploying actual monitoring objects into the satellite zone.
```
@@ -1708,10 +1698,12 @@ vim /etc/icinga2/zones.d/satellite/satellite-hosts.conf
object Host "agent" { ... }
```
-That's also explained and described in the [documentation](06-distributed-monitoring.md#distributed-monitoring-scenarios-master-satellite-agents).
+Keep in mind that the `agent` host object will never reach the satellite, when the master does not have the
+`satellite` zone configured either in `zones.d/master` nor outside the `zones.d` directory. That's also explained and
+described in the [documentation](06-distributed-monitoring.md#distributed-monitoring-scenarios-master-satellite-agents).
The thing you can do: For `command_endpoint` agents like inside the Director:
-Host -> Agent -> yes, there is no config sync for this zone in place. Therefore
+Host -> Agent -> yes, there is no config sync for this zone in place. Therefore,
it is valid to just sync their zones via the config sync.
#### Director Changes