mirror of https://github.com/Icinga/icinga2.git
Documentation: Add configuration best practice.
Fixes #5477 Fixes #5505
This commit is contained in:
Michael Friedrich
parent
85fc79b325
commit
d6eacc8a6f
|
|
@ -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" {
|
||||
|
||||
}
|
||||
|
||||
|
||||
|
||||
Loading…
Reference in New Issue