1 # <a id="configuring-icinga2-first-steps"></a> Configuring Icinga 2: First Steps
3 This chapter provides an introduction into best practices with your Icinga 2 configuration.
4 The configuration files which are automatically created when installing the Icinga 2 packages
5 are a good way to start with Icinga 2.
7 If you're interested in a detailed explanation of each language feature used in those
8 configuration files you can find more information in the [Language Reference](19-language-reference.md#language-reference)
11 ## <a id="configuration-best-practice"></a> Configuration Best Practice
13 If you are ready to configure additional hosts, services, notifications,
14 dependencies, etc, you should think about the requirements first and then
15 decide for a possible strategy.
17 There are many ways of creating Icinga 2 configuration objects:
19 * Manually with your preferred editor, for example vi(m), nano, notepad, etc.
20 * Generated by a [configuration management tool](13-addons-plugins.md#configuration-tools) such as Puppet, Chef, Ansible, etc.
21 * A configuration addon for Icinga 2
22 * A custom exporter script from your CMDB or inventory tool
25 In order to find the best strategy for your own configuration, ask yourself the following questions:
27 * Do your hosts share a common group of services (for example linux hosts with disk, load, etc checks)?
28 * Only a small set of users receives notifications and escalations for all hosts/services?
30 If you can at least answer one of these questions with yes, look for the
31 [apply rules](3-monitoring-basics.md#using-apply) logic instead of defining objects on a per
32 host and service basis.
34 * You are required to define specific configuration for each host/service?
35 * Does your configuration generation tool already know about the host-service-relationship?
37 Then you should look for the object specific configuration setting `host_name` etc accordingly.
39 Finding the best files and directory tree for your configuration is up to you. Make sure that
40 the [icinga2.conf](5-configuring-icinga-2.md#icinga2-conf) configuration file includes them,
43 * tree-based on locations, hostgroups, specific host attributes with sub levels of directories.
44 * flat `hosts.conf`, `services.conf`, etc files for rule based configuration.
45 * generated configuration with one file per host and a global configuration for groups, users, etc.
46 * one big file generated from an external application (probably a bad idea for maintaining changes).
49 In either way of choosing the right strategy you should additionally check the following:
51 * Are there any specific attributes describing the host/service you could set as `vars` custom attributes?
52 You can later use them for applying assign/ignore rules, or export them into external interfaces.
53 * Put hosts into hostgroups, services into servicegroups and use these attributes for your apply rules.
54 * Use templates to store generic attributes for your objects and apply rules making your configuration more readable.
55 Details can be found in the [using templates](3-monitoring-basics.md#object-inheritance-using-templates) chapter.
56 * Apply rules may overlap. Keep a central place (for example, [services.conf](5-configuring-icinga-2.md#services-conf) or [notifications.conf](5-configuring-icinga-2.md#notifications-conf)) storing
57 the configuration instead of defining apply rules deep in your configuration tree.
58 * Every plugin used as check, notification or event command requires a `Command` definition.
59 Further details can be looked up in the [check commands](3-monitoring-basics.md#check-commands) chapter.
61 If you happen to have further questions, do not hesitate to join the
62 [community support channels](https://support.icinga.org)
63 and ask community members for their experience and best practices.
65 ## <a id="configuring-icinga2-overview"></a> Configuration Overview
67 ### <a id="icinga2-conf"></a> icinga2.conf
69 An example configuration file is installed for you in `/etc/icinga2/icinga2.conf`.
71 Here's a brief description of the example configuration:
74 * Icinga 2 configuration file
75 * - this is where you define settings for the Icinga application including
76 * which hosts/services to check.
78 * For an overview of all available configuration options please refer
79 * to the documentation that is distributed as part of Icinga 2.
82 Icinga 2 supports [C/C++-style comments](19-language-reference.md#comments).
85 * The constants.conf defines global constants.
87 include "constants.conf"
89 The `include` directive can be used to include other files.
92 * The zones.conf defines zones for a cluster setup.
93 * Not required for single instance setups.
98 * The Icinga Template Library (ITL) provides a number of useful templates
99 * and command definitions.
100 * Common monitoring plugin command definitions are included separately.
106 * The features-available directory contains a number of configuration
107 * files for features which can be enabled and disabled using the
108 * icinga2 feature enable / icinga2 feature disable CLI commands.
109 * These commands work by creating and removing symbolic links in
110 * the features-enabled directory.
112 include "features-enabled/*.conf"
114 This `include` directive takes care of including the configuration files for all
115 the features which have been enabled with `icinga2 feature enable`. See
116 [Enabling/Disabling Features](8-cli-commands.md#features) for more details.
119 * The repository.d directory contains all configuration objects
120 * managed by the 'icinga2 repository' CLI commands.
122 include_recursive "repository.d"
124 This `include_recursive` directive is used for discovery of services on remote clients
125 and their generated configuration described in
126 [this chapter](10-icinga2-client.md#icinga2-remote-monitoring-master-discovery).
130 * Although in theory you could define all your objects in this file
131 * the preferred way is to create separate directories and files in the conf.d
132 * directory. Each of these files must have the file extension ".conf".
134 include_recursive "conf.d"
136 You can put your own configuration files in the [conf.d](5-configuring-icinga-2.md#conf-d) directory. This
137 directive makes sure that all of your own configuration files are included.
139 ### <a id="constants-conf"></a> constants.conf
141 The `constants.conf` configuration file can be used to define global constants.
143 By default, you need to make sure to set these constants:
145 * The `PluginDir` constant must be set to the path where the [Monitoring Project plugins](2-getting-started.md#setting-up-check-plugins) are installed.
146 This constant is used by a number of
147 [built-in check command definitions](7-icinga-template-library.md#plugin-check-commands).
148 * The `NodeName` constant defines your local node name. Should be set to FQDN which is the default
149 if not set. This constant is required for local host configuration, monitoring remote clients and
154 /* The directory which contains the plugins from the Monitoring Plugins project. */
155 const PluginDir = "/usr/lib64/nagios/plugins"
158 /* The directory which contains the Manubulon plugins.
159 * Check the documentation, chapter "SNMP Manubulon Plugin Check Commands", for details.
161 const ManubulonPluginDir = "/usr/lib64/nagios/plugins"
163 /* Our local instance name. By default this is the server's hostname as returned by `hostname --fqdn`.
164 * This should be the common name from the API certificate.
166 //const NodeName = "localhost"
168 /* Our local zone name. */
169 const ZoneName = NodeName
171 /* Secret key for remote node tickets */
172 const TicketSalt = ""
174 The `ZoneName` and `TicketSalt` constants are required for remote client
175 and distributed setups only.
177 ### <a id="conf-d"></a> The conf.d Directory
179 This directory contains example configuration which should help you get started
180 with monitoring the local host and its services. It is included in the
181 [icinga2.conf](5-configuring-icinga-2.md#icinga2-conf) configuration file by default.
183 It can be used as reference example for your own configuration strategy.
184 Just keep in mind to include the main directories in the
185 [icinga2.conf](5-configuring-icinga-2.md#icinga2-conf) file.
187 You are certainly not bound to it. Remove it, if you prefer your own
188 way of deploying Icinga 2 configuration.
190 Further details on configuration best practice and how to build your
191 own strategy is described in [this chapter](5-configuring-icinga-2.md#configuration-best-practice).
193 Available configuration files which are installed by default:
195 * [hosts.conf](5-configuring-icinga-2.md#hosts-conf)
196 * [services.conf](5-configuring-icinga-2.md#services-conf)
197 * [users.conf](5-configuring-icinga-2.md#users-conf)
198 * [notifications.conf](5-configuring-icinga-2.md#notifications-conf)
199 * [commands.conf](5-configuring-icinga-2.md#commands-conf)
200 * [groups.conf](5-configuring-icinga-2.md#groups-conf)
201 * [templates.conf](5-configuring-icinga-2.md#templates-conf)
202 * [downtimes.conf](5-configuring-icinga-2.md#downtimes-conf)
203 * [timeperiods.conf](5-configuring-icinga-2.md#timeperiods-conf)
204 * [satellite.conf](5-configuring-icinga-2.md#satellite-conf)
206 #### <a id="hosts-conf"></a> hosts.conf
208 The `hosts.conf` file contains an example host based on your
209 `NodeName` setting in [constants.conf](5-configuring-icinga-2.md#constants-conf). You
210 can use global constants for your object names instead of string
213 The `import` keyword is used to import the `generic-host` template which
214 takes care of setting up the host check command to `hostalive`. If you
215 require a different check command, you can override it in the object definition.
217 The `vars` attribute can be used to define custom attributes which are available
218 for check and notification commands. Most of the [Plugin Check Commands](7-icinga-template-library.md#plugin-check-commands)
219 in the Icinga Template Library require an `address` attribute.
221 The custom attribute `os` is evaluated by the `linux-servers` group in
222 [groups.conf](5-configuring-icinga-2.md#groups-conf) making the local host a member.
224 The example host will show you how to
226 * define http vhost attributes for the `http` service apply rule defined
227 in [services.conf](5-configuring-icinga-2.md#services-conf).
228 * define disks (all, specific `/`) and their attributes for the `disk`
229 service apply rule defined in [services.conf](5-configuring-icinga-2.md#services-conf).
230 * define notification types (`mail`) and set the groups attribute. This
231 will be used by notification apply rules in [notifications.conf](notifications-conf).
233 If you've installed [Icinga Web 2](2-getting-started.md#setting-up-icingaweb2) you can
234 uncomment the http vhost attributes and reload Icinga 2. The apply
235 rules in [services.conf](5-configuring-icinga-2.md#services-conf) will automatically
236 generate a new service checking the `/icingaweb2` URI using the `http`
240 * Host definitions with object attributes
241 * used for apply rules for Service, Notification,
242 * Dependency and ScheduledDowntime objects.
244 * Tip: Use `icinga2 object list --type Host` to
245 * list all host objects after running
246 * configuration validation (`icinga2 daemon -C`).
250 * This is an example host based on your
251 * local host's FQDN. Specify the NodeName
252 * constant in `constants.conf` or use your
253 * own description, e.g. "db-host-1".
256 object Host NodeName {
257 /* Import the default host template defined in `templates.conf`. */
258 import "generic-host"
260 /* Specify the address attributes for checks e.g. `ssh` or `http`. */
261 address = "127.0.0.1"
264 /* Set custom attribute `os` for hostgroup assignment in `groups.conf`. */
267 /* Define http vhost attributes for service apply rules in `services.conf`. */
268 vars.http_vhosts["http"] = {
271 /* Uncomment if you've sucessfully installed Icinga Web 2. */
272 //vars.http_vhosts["Icinga Web 2"] = {
273 // http_uri = "/icingaweb2"
276 /* Define disks and attributes for service apply rules in `services.conf`. */
277 vars.disks["disk"] = {
280 vars.disks["disk /"] = {
281 disk_partitions = "/"
284 /* Define notification mail attributes for notification apply rules in `notifications.conf`. */
285 vars.notification["mail"] = {
286 /* The UserGroup `icingaadmins` is defined in `users.conf`. */
287 groups = [ "icingaadmins" ]
291 This is only the host object definition. Now we'll need to make sure that this
292 host and your additional hosts are getting [services](5-configuring-icinga-2.md#services-conf) applied.
296 > If you don't understand all the attributes and how to use [apply rules](19-language-reference.md#apply)
297 > don't worry - the [monitoring basics](3-monitoring-basics.md#monitoring-basics) chapter will explain
300 #### <a id="services-conf"></a> services.conf
302 These service [apply rules](19-language-reference.md#apply) will show you how to monitor
303 the local host, but also allow you to re-use or modify them for
304 your own requirements.
306 You should define all your service apply rules in `services.conf`
307 or any other central location keeping them organized.
309 By default, the local host will be monitored by the following services
311 Service(s) | Applied on host(s)
312 --------------------------------------------|------------------------
313 `load`, `procs`, `swap`, `users`, `icinga` | The `NodeName` host only
314 `ping4`, `ping6` | All hosts with `address` resp. `address6` attribute
315 `ssh` | All hosts with `address` and `vars.os` set to `Linux`
316 `http`, optional: `Icinga Web 2` | All hosts with custom attribute `http_vhosts` defined as dictionary
317 `disk`, `disk /` | All hosts with custom attribute `disks` defined as dictionary
319 The Debian packages also include an additional `apt` service check applied to the local host.
321 The command object `icinga` for the embedded health check is provided by the
322 [Icinga Template Library (ITL)](7-icinga-template-library.md#icinga-template-library) while `http_ip`, `ssh`, `load`, `processes`,
323 `users` and `disk` are all provided by the [Plugin Check Commands](7-icinga-template-library.md#plugin-check-commands)
324 which we enabled earlier by including the `itl` and `plugins` configuration file.
327 Example `load` service apply rule:
329 apply Service "load" {
330 import "generic-service"
332 check_command = "load"
334 /* Used by the ScheduledDowntime apply rule in `downtimes.conf`. */
335 vars.backup_downtime = "02:00-03:00"
337 assign where host.name == NodeName
340 The `apply` keyword can be used to create new objects which are associated with
341 another group of objects. You can `import` existing templates, define (custom)
344 The custom attribe `backup_downtime` is defined to a specific timerange string.
345 This variable value will be used for applying a `ScheduledDowntime` object to
346 these services in [downtimes.conf](5-configuring-icinga-2.md#downtimes-conf).
348 In this example the `assign where` condition is a boolean expression which is
349 evaluated for all objects of type `Host` and a new service with name "load"
350 is created for each matching host. [Expression operators](19-language-reference.md#expression-operators)
351 may be used in `assign where` conditions.
353 Multiple `assign where` condition can be combined with `AND` using the `&&` operator
354 as shown in the `ssh` example:
356 apply Service "ssh" {
357 import "generic-service"
359 check_command = "ssh"
361 assign where host.address && host.vars.os == "Linux"
364 In this example, the service `ssh` is applied to all hosts having the `address`
365 attribute defined `AND` having the custom attribute `os` set to the string
367 You can modify this condition to match multiple expressions by combinding `AND`
368 and `OR` using `&&` and `||` [operators](19-language-reference.md#expression-operators), for example
369 `assign where host.address && (vars.os == "Linux" || vars.os == "Windows")`.
372 A more advanced example is shown by the `http` and `disk` service apply
373 rules. While one `apply` rule for `ssh` will only create a service for matching
374 hosts, you can go one step further: Generate apply rules based on array items
375 or dictionary key-value pairs.
377 The idea is simple: Your host in [hosts.conf](5-configuring-icinga-2.md#hosts-conf) defines the
378 `disks` dictionary as custom attribute in `vars`.
380 Remember the example from [hosts.conf](5-configuring-icinga-2.md#hosts-conf):
384 /* Define disks and attributes for service apply rules in `services.conf`. */
385 vars.disks["disk"] = {
388 vars.disks["disk /"] = {
394 This dictionary contains multiple service names we want to monitor. `disk`
395 should just check all available disks, while `disk /` will pass an additional
396 parameter `disk_partition` to the check command.
398 You'll recognize that the naming is important - that's the very same name
399 as it is passed from a service to a check command argument. Read about services
400 and passing check commands in [this chapter](3-monitoring-basics.md#command-passing-parameters).
402 Using `apply Service for` omits the service name, it will take the key stored in
403 the `disk` variable in `key => config` as new service object name.
405 The `for` keyword expects a loop definition, for example `key => value in dictionary`
406 as known from Perl and other scripting languages.
408 Once defined like this, the `apply` rule defined below will do the following:
410 * only match hosts with `host.vars.disks` defined through the `assign where` condition
411 * loop through all entries in the `host.vars.disks` dictionary. That's `disk` and `disk /` as keys.
412 * call `apply` on each, and set the service object name from the provided key
413 * inside apply, the `generic-service` template is imported
414 * defining the [disk](7-icinga-template-library.md#plugin-check-command-disk) check command requiring command arguments like `disk_partition`
415 * adding the `config` dictionary items to `vars`. Simply said, there's now `vars.disk_partition` defined for the
418 Configuration example:
420 apply Service for (disk => config in host.vars.disks) {
421 import "generic-service"
423 check_command = "disk"
428 A similar example is used for the `http` services. That way you can make your
429 host the information provider for all apply rules. Define them once, and only
432 Look into [notifications.conf](5-configuring-icinga-2.md#notifications-conf) how this technique is used
433 for applying notifications to hosts and services using their type and user
436 Don't forget to install the [check plugins](2-getting-started.md#setting-up-check-plugins) required by
437 the hosts and services and their check commands.
439 Further details on the monitoring configuration can be found in the
440 [monitoring basics](3-monitoring-basics.md#monitoring-basics) chapter.
442 #### <a id="users-conf"></a> users.conf
444 Defines the `icingaadmin` User and the `icingaadmins` UserGroup. The latter is used in
445 [hosts.conf](5-configuring-icinga-2.md#hosts-conf) for defining a custom host attribute later used in
446 [notifications.conf](5-configuring-icinga-2.md#notifications-conf) for notification apply rules.
448 object User "icingaadmin" {
449 import "generic-user"
451 display_name = "Icinga 2 Admin"
452 groups = [ "icingaadmins" ]
454 email = "icinga@localhost"
457 object UserGroup "icingaadmins" {
458 display_name = "Icinga 2 Admin Group"
462 #### <a id="notifications-conf"></a> notifications.conf
464 Notifications for check alerts are an integral part or your
465 Icinga 2 monitoring stack.
467 The examples in this file define two notification apply rules for hosts and services.
468 Both `apply` rules match on the same condition: They are only applied if the
469 nested dictionary attribute `notification.mail` is set.
471 Please note that the `to` keyword is important in [notification apply rules](3-monitoring-basics.md#using-apply-notifications)
472 defining whether these notifications are applies to hosts or services.
473 The `import` keyword imports the specific mail templates defined in [templates.conf](5-configuring-icinga-2.md#templates-conf).
475 The `interval` attribute is not explicitly set - it [defaults to 30 minutes](6-object-types.md#objecttype-notification).
477 By setting the `user_groups` to the value provided by the
478 respective [host.vars.notification.mail](5-configuring-icinga-2.md#hosts-conf) attribute we'll
479 implicitely use the `icingaadmins` UserGroup defined in [users.conf](5-configuring-icinga-2.md#users-conf).
481 apply Notification "mail-icingaadmin" to Host {
482 import "mail-host-notification"
484 user_groups = host.vars.notification.mail.groups
485 users = host.vars.notification.mail.users
487 assign where host.vars.notification.mail
490 apply Notification "mail-icingaadmin" to Service {
491 import "mail-service-notification"
493 user_groups = host.vars.notification.mail.groups
494 users = host.vars.notification.mail.users
496 assign where host.vars.notification.mail
499 More details on defining notifications and their additional attributes such as
500 filters can be read in [this chapter](3-monitoring-basics.md#notifications).
502 ### <a id="commands-conf"></a> commands.conf
504 This is the place where your own command configuration can be defined. By default
505 only the notification commands used by the notification templates defined in [templates.conf](5-configuring-icinga-2.md#templates-conf).
507 You can freely customize these notification commands, and adapt them for your needs.
508 Read more on that topic [here](3-monitoring-basics.md#notification-commands).
510 ### <a id="groups-conf"></a> groups.conf
512 The example host defined in [hosts.conf](hosts-conf) already has the
513 custom attribute `os` set to `Linux` and is therefore automatically
514 a member of the host group `linux-servers`.
516 This is done by using the [group assign](19-language-reference.md#group-assign) expressions similar
517 to previously seen [apply rules](3-monitoring-basics.md#using-apply).
519 object HostGroup "linux-servers" {
520 display_name = "Linux Servers"
522 assign where host.vars.os == "Linux"
525 object HostGroup "windows-servers" {
526 display_name = "Windows Servers"
528 assign where host.vars.os == "Windows"
531 Service groups can be grouped together by similar pattern matches.
532 The [match() function](19-language-reference.md#function-calls) expects a wildcard match string
533 and the attribute string to match with.
535 object ServiceGroup "ping" {
536 display_name = "Ping Checks"
538 assign where match("ping*", service.name)
541 object ServiceGroup "http" {
542 display_name = "HTTP Checks"
544 assign where match("http*", service.check_command)
547 object ServiceGroup "disk" {
548 display_name = "Disk Checks"
550 assign where match("disk*", service.check_command)
554 #### <a id="templates-conf"></a> templates.conf
556 Most of the example configuration objects use generic global templates by
559 template Host "generic-host" {
560 max_check_attempts = 5
564 check_command = "hostalive"
567 template Service "generic-service" {
568 max_check_attempts = 3
573 The `hostalive` check command is part of the
574 [Plugin Check Commands](7-icinga-template-library.md#plugin-check-commands).
577 template Notification "mail-host-notification" {
578 command = "mail-host-notification"
580 states = [ Up, Down ]
581 types = [ Problem, Acknowledgement, Recovery, Custom,
582 FlappingStart, FlappingEnd,
583 DowntimeStart, DowntimeEnd, DowntimeRemoved ]
588 template Notification "mail-service-notification" {
589 command = "mail-service-notification"
591 states = [ OK, Warning, Critical, Unknown ]
592 types = [ Problem, Acknowledgement, Recovery, Custom,
593 FlappingStart, FlappingEnd,
594 DowntimeStart, DowntimeEnd, DowntimeRemoved ]
599 More details on `Notification` object attributes can be found [here](6-object-types.md#objecttype-notification).
602 #### <a id="downtimes-conf"></a> downtimes.conf
604 The `load` service apply rule defined in [services.conf](5-configuring-icinga-2.md#services-conf) defines
605 the `backup_downtime` custom attribute.
607 The [ScheduledDowntime](6-object-types.md#objecttype-scheduleddowntime) apply rule uses this attribute
608 to define the default value for the time ranges required for recurring downtime slots.
610 apply ScheduledDowntime "backup-downtime" to Service {
611 author = "icingaadmin"
612 comment = "Scheduled downtime for backup"
615 monday = service.vars.backup_downtime
616 tuesday = service.vars.backup_downtime
617 wednesday = service.vars.backup_downtime
618 thursday = service.vars.backup_downtime
619 friday = service.vars.backup_downtime
620 saturday = service.vars.backup_downtime
621 sunday = service.vars.backup_downtime
624 assign where service.vars.backup_downtime != ""
628 #### <a id="timeperiods-conf"></a> timeperiods.conf
630 This file contains the default timeperiod definitions for `24x7`, `9to5`
631 and `never`. Timeperiod objects are referenced by `*period`
632 objects such as hosts, services or notifications.
635 #### <a id="satellite-conf"></a> satellite.conf
637 Includes default templates and dependencies for
638 [monitoring remote clients](10-icinga2-client.md#icinga2-client)
639 using service discovery and
640 [config generation](10-icinga2-client.md#icinga2-remote-monitoring-master-discovery)
641 on the master. Can be ignored/removed on setups not using this features.
644 Further details on the monitoring configuration can be found in the
645 [monitoring basics](3-monitoring-basics.md#monitoring-basics) chapter.