--- /dev/null
+## <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" {
+
+ }
+
+
+
projects / icinga2 / commitdiff