icinga2/doc/4.5-best-practice.md

## <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" {

    }