Documentation: Add configuration best practice.

Fixes #5477
Fixes #5505

doc/4.5-best-practice.md

@@ -0,0 +1,209 @@
+## <a id="configuration-best-practice"></a> Configuration Best Practice
+
+### <a id="best-practice-config-structure"></a> Configuration File and Directory Structure
+
+Icinga 2 does not care how you name your files and/or directories as long as
+you'll include them accordingly in the [icinga2.conf](#icinga2-conf) file.
+
+By default, `conf.d` is included recursively looking for `*.conf` file endings.
+If you're putting/generating your configuration structure in there, you do not
+need to touch the [icinga2.conf](#icinga2-conf) file. This becomes useful with
+external addons not having write permissions to this file such as LConf.
+
+Example:
+
+    include_recursive "conf.d" "*.conf"
+
+Below `conf.d` you're free to choose. An Example based on host objects with
+inline services in `conf.d/hosts` and their templates below `conf.d/services/`
+would be:
+
+    conf.d/
+      services/
+        templates.conf
+      hosts/
+        hosts.conf
+
+If your setup consists of location based monitoring, you could reflect that with
+your configuration directory tree and files:
+
+    conf.d/
+      germany/
+        nuremberg/
+          hosts.conf
+          osmc.conf
+        berlin/
+          hosts.conf
+          osdc.conf
+      austria/
+        linz/
+          hosts.conf
+        vienna/
+          hosts.conf
+
+
+If you're planning to create a [cluster](#cluster) setup with Icinga 2 and your
+configuration master should deploy specific configuration parts to slave nodes,
+it's reasonable not to confuse it with configuration below `conf.d`. Rather
+create a dedicated directory and put all nodes into their own directories:
+
+    include_recursive "cluster" "*.conf"
+
+    cluster/
+      node1/
+      node2/
+      node99/
+
+
+
+If you are preferring to control what several parties drop into the configuration
+pool (for example different departments with their own standalone configuration),
+you can still deactivate the `conf.d` inclusion and use your own strategy.
+
+Example:
+
+    include_recursive "dep1" "*.conf"
+    include_recursive "dep2" "*.conf"
+    include_recursive "dep3" "*.conf"
+    include_recursive "remotecust" "*.conf"
+    include_recursive "cmdb" "*.conf"
+
+> **Note**
+>
+> You can omit the file pattern `"*.conf"` because that's the Icinga 2 default already.
+
+### <a id="best-practice-use-templates"></a> Use Templates
+
+Templates are the key to minimize configuration overhead, and share widely
+used attributes among objects inheriting their values. And if one template
+does not fit everyone, split it into two.
+
+Or rather inherit that template into a new template, and override/disable
+unwanted values.
+
+    template Service "generic-service-disable-notifications" inherits "generic-service" {
+      notifications["mail-icingaadmin"] = null
+    }
+
+### <a id="best-practice-inline-objects-using-templates"></a> Inline Objects using Templates
+
+While it is reasonable to create single objects by your preferred configuration
+tool, using templates and inheriting their attributes in inline objects will
+save you a lot of typing extra work.
+
+For instance, you can still create a host object, then a service object linking
+to it, after that a notification object referencing the service object, and last
+but not least defining scheduled downtime objects linked to services.
+
+    object Host "localhost" {
+      display_name = "The best host there is",
+
+      groups = [ "all-hosts" ],
+
+      host_dependencies = [ "router" ],
+    }
+
+    object Service "localhost-ping4" {
+      host = "localhost",
+      short_name = "ping4",
+
+      display_name = "localhost ping4",
+
+      check_command = "ping4",
+
+      check_interval = 60s,
+      retry_interval = 15s,
+
+      servicegroups = [ "all-services" ],
+    }
+
+    object Notification "localhost-ping4-notification" {
+      host = "localhost",
+      service = "ping4",
+
+      notification_command = "mail-service-notification",
+
+      users = [ "user1", "user2" ]
+    }
+
+    object ScheduledDowntime "some-downtime" {
+      host = "localhost",
+      service = "ping4",
+
+      author = "icingaadmin",
+      comment = "Some comment",
+
+      fixed = false,
+      duration = 30m,
+
+      ranges = {
+        "sunday" = "02:00-03:00"
+      }
+    }
+
+By doing that everytime for such a series of linked objects, your configuration
+will get bloated and unreadable. You've already read that [using templates](#best-practice-use-templates)
+will help here.
+
+The `Notification` and `ScheduledDowntime` templates will be referenced in the service template and
+inline definition (both locations are possible).
+The `Service` template is referenced within the inline service array for the `Host` template. In the end
+the `Host` object inherits from the `Host` template named `linux-server`.
+That way similar hosts may just inherit the host template and get all services, notifications, scheduled
+downtimes through the template automatism.
+
+    template Notification "mail-notification" {
+      notification_command = "mail-service-notification",
+
+      users = [ "user1", "user2" ]
+    }
+
+    template ScheduledDowntime "backup-downtime" {
+      author = "icingaadmin",
+      comment = "Some comment",
+
+      fixed = false,
+      duration = 30m,
+
+      ranges = {
+        "sunday" = "02:00-03:00"
+      }
+    }
+
+    template Service "generic-service" {
+      max_check_attempts = 3,
+      check_interval = 5m,
+      retry_interval = 1m,
+      enable_perfdata = true,
+
+      notifications["mail"] = {
+        templates = [ "mail-notification" ]
+      }
+    }
+
+    template Host "linux-server" {
+      display_name = "The best host there is",
+
+      groups = [ "all-hosts" ],
+
+      host_dependencies = [ "router" ],
+
+      services["ping4"] = {
+        templates = [ "generic-service" ],
+
+        check_command = "ping4",
+
+        scheduled_downtimes["backup"] = {
+          templates = [ "backup-downtime" ]
+        }
+      },
+
+      check = "ping4"
+    }
+
+    object Host "localhost" inherits "linux-server" {
+
+    }
+
+
+