From d6eacc8a6f923746a2139adb593e502c714051d5 Mon Sep 17 00:00:00 2001 From: Michael Friedrich Date: Wed, 5 Feb 2014 18:09:38 +0100 Subject: [PATCH] Documentation: Add configuration best practice. Fixes #5477 Fixes #5505 --- doc/4.5-best-practice.md | 209 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 209 insertions(+) create mode 100644 doc/4.5-best-practice.md diff --git a/doc/4.5-best-practice.md b/doc/4.5-best-practice.md new file mode 100644 index 00000000000..32ba452e646 --- /dev/null +++ b/doc/4.5-best-practice.md @@ -0,0 +1,209 @@ +## Configuration Best Practice + +### 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. + +### 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 + } + +### 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" { + + } + + +