Documentation: Add a note about multiple cluster nodes and LocalStateDir.

Fixes #5619

diff --git a/doc/2.6-running-icinga-2.md b/doc/2.6-running-icinga-2.md
index b338b8e224897144f9734de081557391ae5a4a1f..960dcb864ade18bae5b768f49a872a267c2efdc7 100644 (file)
--- a/doc/2.6-running-icinga-2.md
+++ b/doc/2.6-running-icinga-2.md
@@ -113,3 +113,27 @@ You can disable features using the `icinga2-disable-feature` command:
 > **Note**
 >
 > The `icinga2-enable-feature` and `icinga2-disable-feature` commands do not restart Icinga 2.
+
+
+### <a id="runtime-locations"></a> Runtime Locations
+
+This list describes the default package installation locations. Additional subdirectories
+may be required.
+These paths may differ depending on your installation method, or changed
+[global constants](#global-constants) regarding path settings.
+
+  Name                                  | Description
+  --------------------------------------|--------------------------
+  /etc/icinga2                          | Icinga 2 configuration.
+  /usr/sbin/icinga2*                    | Icinga 2 daemon and feature enable/disable scripts.
+  /usr/bin/icinga2*                     | Helper scripts for Icinga 2.
+  /var/cache/icinga2                    | Runtime files written such as status files.
+  /var/lib/icinga2                      | Icinga 2 state file, cluster feature replay log and configuration files.
+  /var/log/icinga2                      | Used for application, debug and compat log files.
+  /var/spool/icinga2                    | Used for performance data spool files.
+  /var/run/icinga2                      | Runtime data such as PID file, or ExternalCommandListener/LivestatusListener pipes/sockets.
+  /usr/lib/icinga2                      | Icinga 2 Libraries.
+  /usr/share/icinga2                    | [ITL](#itl) and [certificate helpers](#cluster).
+  /usr/share/doc/icinga2*               | This documentation.
+
+

diff --git a/doc/6-advanced-topics.md b/doc/6-advanced-topics.md
index 8641bc962fc1c228ac486107dce813433468685e..9905b06e8790fbaac72695c6daeee293089b05e6 100644 (file)
--- a/doc/6-advanced-topics.md
+++ b/doc/6-advanced-topics.md
@@ -257,6 +257,7 @@ If you update the configuration files on the configured file sender, it will
 force a restart on all receiving nodes after validating the new config.
 
 By default these configuration files are saved in /var/lib/icinga2/cluster/config.
+
 In order to load configuration files which were received from a remote Icinga 2
 instance you will have to add the following include directive to your
 `icinga2.conf` configuration file:
@@ -320,6 +321,22 @@ Example:
 > point of views. Use the `authorities` attribute to assign the service
 > check to the configured node.
 
+### <a id="host-multiple-cluster-nodes"></a> Host With Multiple Cluster Nodes
+
+Special scenarios might require multiple cluster nodes running on a single host.
+By default Icinga 2 and its features will drop their runtime data below the prefix
+`IcingaLocalStateDir`. By default packages will set that path to `/var`.
+You can either set that variable as constant configuration
+definition in [icinga2.conf](#icinga2-conf) or pass it as runtime variable to
+the Icinga 2 daemon.
+
+    # icinga2 -c /etc/icinga2/node1/icinga2.conf -DIcingaLocalStateDir=/opt/node1/var
+
+> **Note**
+>
+> You are required to ship the same directory layout known from a default
+> Icinga 2 installation. Details in [Runtime Locations](#runtime-locations).
+
 ## <a id="dependencies"></a> Dependencies
 
 Icinga 2 uses host and service dependencies as attribute directly on the host or