1 # <a id="configuring-icinga2-first-steps"></a> Configuring Icinga 2: First Steps
3 ## <a id="icinga2-conf"></a> icinga2.conf
5 An example configuration file is installed for you in `/etc/icinga2/icinga2.conf`.
7 Here's a brief description of the example configuration:
10 * Icinga 2 configuration file
11 * - this is where you define settings for the Icinga application including
12 * which hosts/services to check.
14 * For an overview of all available configuration options please refer
15 * to the documentation that is distributed as part of Icinga 2.
18 Icinga 2 supports [C/C++-style comments](13-language-reference.md#comments).
21 * The constants.conf defines global constants.
23 include "constants.conf"
25 The `include` directive can be used to include other files.
28 * The zones.conf defines zones for a cluster setup.
29 * Not required for single instance setups.
34 * The Icinga Template Library (ITL) provides a number of useful templates
35 * and command definitions.
36 * Common monitoring plugin command definitions are included separately.
42 * The features-available directory contains a number of configuration
43 * files for features which can be enabled and disabled using the
44 * icinga2 feature enable / icinga2 feature disable CLI commands.
45 * These commands work by creating and removing symbolic links in
46 * the features-enabled directory.
48 include "features-enabled/*.conf"
50 This `include` directive takes care of including the configuration files for all
51 the features which have been enabled with `icinga2 feature enable`. See
52 [Enabling/Disabling Features](6-cli-commands.md#features) for more details.
55 * The repository.d directory contains all configuration objects
56 * managed by the 'icinga2 repository' CLI commands.
58 include_recursive "repository.d"
60 This `include_recursive` directive is used for discovery of services on remote clients
61 and their generated configuration described in
62 [this chapter](5-monitoring-remote-systems.md#icinga2-remote-monitoring-master-discovery-generate-config).
66 * Although in theory you could define all your objects in this file
67 * the preferred way is to create separate directories and files in the conf.d
68 * directory. Each of these files must have the file extension ".conf".
70 include_recursive "conf.d"
72 You can put your own configuration files in the [conf.d](4-configuring-icinga-2.md#conf-d) directory. This
73 directive makes sure that all of your own configuration files are included.
77 > The example configuration is shipped in this directory too. You can either
78 > remove it entirely, or adapt the existing configuration structure with your
79 > own object configuration.
81 ## <a id="constants-conf"></a> constants.conf
83 The `constants.conf` configuration file can be used to define global constants.
85 By default, you need to make sure to set these constants:
87 * The `PluginDir` constant must be pointed to your [check plugins](2-getting-started.md#setting-up-check-plugins) path.
88 This constant is required by the shipped
89 [plugin check command configuration](16-icinga-template-library.md#plugin-check-commands).
90 * The `NodeName` constant defines your local node name. Should be set to FQDN which is the default
91 if not set. This constant is required for local host configuration, monitoring remote clients and
96 /* The directory which contains the plugins from the Monitoring Plugins project. */
97 const PluginDir = "/usr/lib64/nagios/plugins"
100 /* The directory which contains the Manubulon plugins.
101 * Check the documentation, chapter "SNMP Manubulon Plugin Check Commands", for details.
103 const ManubulonPluginDir = "/usr/lib64/nagios/plugins"
105 /* Our local instance name. By default this is the server's hostname as returned by `hostname --fqdn`.
106 * This should be the common name from the API certificate.
108 //const NodeName = "localhost"
110 /* Our local zone name. */
111 const ZoneName = NodeName
113 /* Secret key for remote node tickets */
114 const TicketSalt = ""
116 The `ZoneName` and `TicketSalt` constants are required for remote client
117 and distributed setups only.
119 ## <a id="conf-d"></a> The conf.d Directory
121 This directory contains example configuration which should help you get started
122 with monitoring the local host and its services. It is included in the
123 [icinga2.conf](4-configuring-icinga-2.md#icinga2-conf) configuration file by default.
125 It can be used as reference example for your own configuration strategy.
126 Just keep in mind to include the main directories in the
127 [icinga2.conf](4-configuring-icinga-2.md#icinga2-conf) file.
129 You are certainly not bound to it. Remove it, if you prefer your own
130 way of deploying Icinga 2 configuration.
132 Further details on configuration best practice and how to build your
133 own strategy is described in [this chapter](3-monitoring-basics.md#configuration-best-practice).
135 Available configuration files shipped by default:
137 * [hosts.conf](4-configuring-icinga-2.md#hosts-conf)
138 * [services.conf](4-configuring-icinga-2.md#services-conf)
139 * [users.conf](4-configuring-icinga-2.md#users-conf)
140 * [notifications.conf](4-configuring-icinga-2.md#notifications-conf)
141 * [commands.conf](4-configuring-icinga-2.md#commands-conf)
142 * [groups.conf](4-configuring-icinga-2.md#groups-conf)
143 * [templates.conf](4-configuring-icinga-2.md#templates-conf)
144 * [downtimes.conf](4-configuring-icinga-2.md#downtimes-conf)
145 * [timeperiods.conf](4-configuring-icinga-2.md#timeperiods-conf)
146 * [satellite.conf](4-configuring-icinga-2.md#satellite-conf)
148 ### <a id="hosts-conf"></a> hosts.conf
150 The `hosts.conf` file contains an example host based on your
151 `NodeName` setting in [constants.conf](4-configuring-icinga-2.md#constants-conf). You
152 can use global constants for your object names instead of string
155 The `import` keyword is used to import the `generic-host` template which
156 takes care of setting up the host check command to `hostalive`. If you
157 require a different check command, you can override it in the object definition.
159 The `vars` attribute can be used to define custom attributes which are available
160 for check and notification commands. Most of the [Plugin Check Commands](16-icinga-template-library.md#plugin-check-commands)
161 in the Icinga Template Library require an `address` attribute.
163 The custom attribute `os` is evaluated by the `linux-servers` group in
164 [groups.conf](4-configuring-icinga-2.md#groups-conf) making the local host a member.
166 The example host will show you how to
168 * define http vhost attributes for the `http` service apply rule defined
169 in [services.conf](4-configuring-icinga-2.md#services-conf).
170 * define disks (all, specific `/`) and their attributes for the `disk`
171 service apply rule defined in [services.conf](4-configuring-icinga-2.md#services-conf).
172 * define notification types (`mail`) and set the groups attribute. This
173 will be used by notification apply rules in [notifications.conf](notifications-conf).
175 If you've installed [Icinga Web 2](2-getting-started.md#setting-up-icingaweb2) you can
176 uncomment the http vhost attributes and relaod Icinga 2. The apply
177 rules in [services.conf](4-configuring-icinga-2.md#services-conf) will automatically
178 generate a new service checking the `/icingaweb2` URI using the `http`
182 * Host definitions with object attributes
183 * used for apply rules for Service, Notification,
184 * Dependency and ScheduledDowntime objects.
186 * Tip: Use `icinga2 object list --type Host` to
187 * list all host objects after running
188 * configuration validation (`icinga2 daemon -C`).
192 * This is an example host based on your
193 * local host's FQDN. Specify the NodeName
194 * constant in `constants.conf` or use your
195 * own description, e.g. "db-host-1".
198 object Host NodeName {
199 /* Import the default host template defined in `templates.conf`. */
200 import "generic-host"
202 /* Specify the address attributes for checks e.g. `ssh` or `http`. */
203 address = "127.0.0.1"
206 /* Set custom attribute `os` for hostgroup assignment in `groups.conf`. */
209 /* Define http vhost attributes for service apply rules in `services.conf`. */
210 vars.http_vhosts["http"] = {
213 /* Uncomment if you've sucessfully installed Icinga Web 2. */
214 //vars.http_vhosts["Icinga Web 2"] = {
215 // http_uri = "/icingaweb2"
218 /* Define disks and attributes for service apply rules in `services.conf`. */
219 vars.disks["disk"] = {
222 vars.disks["disk /"] = {
223 disk_partitions = "/"
226 /* Define notification mail attributes for notification apply rules in `notifications.conf`. */
227 vars.notification["mail"] = {
228 /* The UserGroup `icingaadmins` is defined in `users.conf`. */
229 groups = [ "icingaadmins" ]
233 This is only the host object definition. Now we'll need to make sure that this
234 host and your additional hosts are getting [services](4-configuring-icinga-2.md#services-conf) applied.
238 > If you don't understand all the attributes and how to use [apply rules](13-language-reference.md#apply)
239 > don't worry - the [monitoring basics](3-monitoring-basics.md#monitoring-basics) chapter will explain
242 ### <a id="services-conf"></a> services.conf
244 These service [apply rules](13-language-reference.md#apply) will show you how to monitor
245 the local host, but also allow you to re-use or modify them for
246 your own requirements.
248 You should define all your service apply rules in `services.conf`
249 or any other central location keeping them organized.
251 By default, the local host will be monitored by the following services
253 Service(s) | Applied on host(s)
254 --------------------------------------------|------------------------
255 `load`, `procs`, `swap`, `users`, `icinga` | The `NodeName` host only
256 `ping4`, `ping6` | All hosts with `address` resp. `address6` attribute
257 `ssh` | All hosts with `address` and `vars.os` set to `Linux`
258 `http`, optional: `Icinga Web 2` | All hosts with custom attribute `http_vhosts` defined as dictionary
259 `disk`, `disk /` | All hosts with custom attribute `disks` defined as dictionary
261 The Debian packages also ship an additional `apt` service check applied to the local host.
263 The command object `icinga` for the embedded health check is provided by the
264 [Icinga Template Library (ITL)](16-icinga-template-library.md#icinga-template-library) while `http_ip`, `ssh`, `load`, `processes`,
265 `users` and `disk` are all provided by the [Plugin Check Commands](16-icinga-template-library.md#plugin-check-commands)
266 which we enabled earlier by including the `itl` and `plugins` configuration file.
269 Example `load` service apply rule:
271 apply Service "load" {
272 import "generic-service"
274 check_command = "load"
276 /* Used by the ScheduledDowntime apply rule in `downtimes.conf`. */
277 vars.backup_downtime = "02:00-03:00"
279 assign where host.name == NodeName
282 The `apply` keyword can be used to create new objects which are associated with
283 another group of objects. You can `import` existing templates, define (custom)
286 The custom attribe `backup_downtime` is defined to a specific timerange string.
287 This variable value will be used for applying a `ScheduledDowntime` object to
288 these services in [downtimes.conf](4-configuring-icinga-2.md#downtimes-conf).
290 In this example the `assign where` condition is a boolean expression which is
291 evaluated for all objects of type `Host` and a new service with name "load"
292 is created for each matching host. [Expression operators](13-language-reference.md#expression-operators)
293 may be used in `assign where` conditions.
295 Multiple `assign where` condition can be combined with `AND` using the `&&` operator
296 as shown in the `ssh` example:
298 apply Service "ssh" {
299 import "generic-service"
301 check_command = "ssh"
303 assign where host.address && host.vars.os == "Linux"
306 In this example, the service `ssh` is applied to all hosts having the `address`
307 attribute defined `AND` having the custom attribute `os` set to the string
309 You can modify this condition to match multiple expressions by combinding `AND`
310 and `OR` using `&&` and `||` [operators](13-language-reference.md#expression-operators), for example
311 `assign where host.address && (vars.os == "Linux" || vars.os == "Windows")`.
314 A more advanced example is shown by the `http` and `disk` service apply
315 rules. While one `apply` rule for `ssh` will only create a service for matching
316 hosts, you can go one step further: Generate apply rules based on array items
317 or dictionary key-value pairs.
319 The idea is simple: Your host in [hosts.conf](4-configuring-icinga-2.md#hosts-conf) defines the
320 `disks` dictionary as custom attribute in `vars`.
322 Remember the example from [hosts.conf](4-configuring-icinga-2.md#hosts-conf):
326 /* Define disks and attributes for service apply rules in `services.conf`. */
327 vars.disks["disk"] = {
330 vars.disks["disk /"] = {
336 This dictionary contains multiple service names we want to monitor. `disk`
337 should just check all available disks, while `disk /` will pass an additional
338 parameter `disk_partition` to the check command.
340 You'll recognize that the naming is important - that's the very same name
341 as it is passed from a service to a check command argument. Read about services
342 and passing check commands in [this chapter](3-monitoring-basics.md#command-passing-parameters).
344 Using `apply Service for` omits the service name, it will take the key stored in
345 the `disk` variable in `key => config` as new service object name.
347 The `for` keyword expects a loop definition, for example `key => value in dictionary`
348 as known from Perl and other scripting languages.
350 Once defined like this, the `apply` rule defined below will do the following:
352 * only match hosts with `host.vars.disks` defined through the `assign where` condition
353 * loop through all entries in the `host.vars.disks` dictionary. That's `disk` and `disk /` as keys.
354 * call `apply` on each, and set the service object name from the provided key
355 * inside apply, the `generic-service` template is imported
356 * defining the [disk](16-icinga-template-library.md#plugin-check-command-disk) check command requiring command arguments like `disk_partition`
357 * adding the `config` dictionary items to `vars`. Simply said, there's now `vars.disk_partition` defined for the
360 Configuration example:
362 apply Service for (disk => config in host.vars.disks) {
363 import "generic-service"
365 check_command = "disk"
369 assign where host.vars.disks
372 A similar example is used for the `http` services. That way you can make your
373 host the information provider for all apply rules. Define them once, and only
376 Look into [notifications.conf](4-configuring-icinga-2.md#notifications-conf) how this technique is used
377 for applying notifications to hosts and services using their type and user
380 Don't forget to install the [check plugins](2-getting-started.md#setting-up-check-plugins) required by
381 the hosts and services and their check commands.
383 Further details on the monitoring configuration can be found in the
384 [monitoring basics](3-monitoring-basics.md#monitoring-basics) chapter.
386 ### <a id="users-conf"></a> users.conf
388 Defines the `icingaadmin` User and the `icingaadmins` UserGroup. The latter is used in
389 [hosts.conf](4-configuring-icinga-2.md#hosts-conf) for defining a custom host attribute later used in
390 [notifications.conf](4-configuring-icinga-2.md#notifications-conf) for notification apply rules.
392 object User "icingaadmin" {
393 import "generic-user"
395 display_name = "Icinga 2 Admin"
396 groups = [ "icingaadmins" ]
398 email = "icinga@localhost"
401 object UserGroup "icingaadmins" {
402 display_name = "Icinga 2 Admin Group"
406 ### <a id="notifications-conf"></a> notifications.conf
408 Notifications for check alerts are an integral part or your
409 Icinga 2 monitoring stack.
411 The shipped example defines two notification apply rules for hosts and services.
412 Both `apply` rules match on the same condition: They are only applied if the
413 nested dictionary attribute `notification.mail` is set.
415 Please note that the `to` keyword is important in [notification apply rules](3-monitoring-basics.md#using-apply-notifications)
416 defining whether these notifications are applies to hosts or services.
417 The `import` keyword imports the specific mail templates defined in [templates.conf](4-configuring-icinga-2.md#templates-conf).
419 The `interval` attribute is not explicitly set - it [defaults to 30 minutes](15-object-types.md#objecttype-notification).
421 By setting the `user_groups` to the value provided by the
422 respective [host.vars.notification.mail](4-configuring-icinga-2.md#hosts-conf) attribute we'll
423 implicitely use the`icingaadmins` UserGroup defined in [users.conf](4-configuring-icinga-2.md#users-conf).
425 apply Notification "mail-icingaadmin" to Host {
426 import "mail-host-notification"
428 user_groups = host.vars.notification.mail.groups
430 assign where host.vars.notification.mail
433 apply Notification "mail-icingaadmin" to Service {
434 import "mail-service-notification"
436 user_groups = host.vars.notification.mail.groups
438 assign where host.vars.notification.mail
441 More details on defining notifications and their additional attributes such as
442 filters can be read in [this chapter](3-monitoring-basics.md#notifications).
444 ### <a id="commands-conf"></a> commands.conf
446 This is the place where your own command configuration can be defined. By default
447 only the notification commands used by the notification templates defined in [templates.conf](4-configuring-icinga-2.md#templates-conf).
451 > Icinga 2 ships the most common command definitions already in the
452 > [Plugin Check Commands](16-icinga-template-library.md#plugin-check-commands) definitions. More details on
453 > that topic in the [troubleshooting section](10-troubleshooting.md#check-command-definitions).
455 You can freely customize these notification commands, and adapt them for your needs.
456 Read more on that topic [here](3-monitoring-basics.md#notification-commands).
458 ### <a id="groups-conf"></a> groups.conf
460 The example host defined in [hosts.conf](hosts-conf) already has the
461 custom attribute `os` set to `Linux` and is therefore automatically
462 a member of the host group `linux-servers`.
464 This is done by using the [group assign](13-language-reference.md#group-assign) expressions similar
465 to previously seen [apply rules](3-monitoring-basics.md#using-apply).
467 object HostGroup "linux-servers" {
468 display_name = "Linux Servers"
470 assign where host.vars.os == "Linux"
473 object HostGroup "windows-servers" {
474 display_name = "Windows Servers"
476 assign where host.vars.os == "Windows"
479 Service groups can be grouped together by similar pattern matches.
480 The [match() function](13-language-reference.md#function-calls) expects a wildcard match string
481 and the attribute string to match with.
483 object ServiceGroup "ping" {
484 display_name = "Ping Checks"
486 assign where match("ping*", service.name)
489 object ServiceGroup "http" {
490 display_name = "HTTP Checks"
492 assign where match("http*", service.check_command)
495 object ServiceGroup "disk" {
496 display_name = "Disk Checks"
498 assign where match("disk*", service.check_command)
502 ### <a id="templates-conf"></a> templates.conf
504 All shipped example configuration objects use generic global templates by
505 default. Be it setting a default `check_command` attribute in the `generic-host`
506 templates for your hosts defined in [hosts.conf](4-configuring-icinga-2.md#hosts-conf), or defining
507 the default `states` and `types` filters for notification apply rules defined in
508 [notifications.conf](4-configuring-icinga-2.md#notifications-conf).
511 template Host "generic-host" {
512 max_check_attempts = 5
516 check_command = "hostalive"
519 template Service "generic-service" {
520 max_check_attempts = 3
525 The `hostalive` check command is shipped with Icinga 2 in the
526 [Plugin Check Commands](16-icinga-template-library.md#plugin-check-commands).
529 template Notification "mail-host-notification" {
530 command = "mail-host-notification"
532 states = [ Up, Down ]
533 types = [ Problem, Acknowledgement, Recovery, Custom,
534 FlappingStart, FlappingEnd,
535 DowntimeStart, DowntimeEnd, DowntimeRemoved ]
540 template Notification "mail-service-notification" {
541 command = "mail-service-notification"
543 states = [ OK, Warning, Critical, Unknown ]
544 types = [ Problem, Acknowledgement, Recovery, Custom,
545 FlappingStart, FlappingEnd,
546 DowntimeStart, DowntimeEnd, DowntimeRemoved ]
551 More details on `Notification` object attributes can be found [here](15-object-types.md#objecttype-notification).
554 ### <a id="downtimes-conf"></a> downtimes.conf
556 The `load` service apply rule defined in [services.conf](4-configuring-icinga-2.md#services-conf) defines
557 the `backup_downtime` custom attribute.
559 The [ScheduledDowntime](15-object-types.md#objecttype-scheduleddowntime) apply rule uses this attribute
560 to define the default value for the time ranges required for recurring downtime slots.
562 apply ScheduledDowntime "backup-downtime" to Service {
563 author = "icingaadmin"
564 comment = "Scheduled downtime for backup"
567 monday = service.vars.backup_downtime
568 tuesday = service.vars.backup_downtime
569 wednesday = service.vars.backup_downtime
570 thursday = service.vars.backup_downtime
571 friday = service.vars.backup_downtime
572 saturday = service.vars.backup_downtime
573 sunday = service.vars.backup_downtime
576 assign where service.vars.backup_downtime != ""
580 ### <a id="timeperiods-conf"></a> timeperiods.conf
582 This file ships the default timeperiod definitions for `24x7`, `9to5`
583 and `never`. Timeperiod objects are referenced by `*period`
584 objects such as hosts, services or notifications.
587 ### <a id="satellite-conf"></a> satellite.conf
589 Ships default templates and dependencies for [monitoring remote clients](5-monitoring-remote-systems.md#icinga2-remote-client-monitoring)
590 using service discovery and [config generation](5-monitoring-remote-systems.md#icinga2-remote-monitoring-master-discovery-generate-config)
591 on the master. Can be ignored/removed on setups not using this features.
594 Further details on the monitoring configuration can be found in the
595 [monitoring basics](3-monitoring-basics.md#monitoring-basics) chapter.