1 # <a id="object-types"></a> Object Types
3 ## <a id="objecttype-host"></a> Host
9 object Host "localhost" {
10 display_name = "The best host there is"
14 groups = [ "all-hosts" ]
16 check_command = "hostalive"
22 ----------------|----------------
23 display_name |**Optional.** A short description of the host.
24 address |**Optional.** The host's address. Available as command runtime macro `$address$` if set.
25 address6 |**Optional.** The host's address. Available as command runtime macro `$address6$` if set.
26 groups |**Optional.** A list of host groups this host belongs to.
27 vars |**Optional.** A dictionary containing custom attributes that are specific to this host.
28 check\_command |**Required.** The name of the check command.
29 max\_check\_attempts|**Optional.** The number of times a host is re-checked before changing into a hard state. Defaults to 3.
30 check\_period |**Optional.** The name of a time period which determines when this host should be checked. Not set by default.
31 check\_interval |**Optional.** The check interval (in seconds). This interval is used for checks when the host is in a `HARD` state. Defaults to 5 minutes.
32 retry\_interval |**Optional.** The retry interval (in seconds). This interval is used for checks when the host is in a `SOFT` state. Defaults to 1 minute.
33 enable\_notifications|**Optional.** Whether notifications are enabled. Defaults to true.
34 enable\_active\_checks|**Optional.** Whether active checks are enabled. Defaults to true.
35 enable\_passive\_checks|**Optional.** Whether passive checks are enabled. Defaults to true.
36 enable\_event\_handler|**Optional.** Enables event handlers for this host. Defaults to true.
37 enable\_flapping|**Optional.** Whether flap detection is enabled. Defaults to true.
38 enable\_perfdata|**Optional.** Whether performance data processing is enabled. Defaults to true.
39 event\_command |**Optional.** The name of an event command that should be executed every time the host's state changes or the host is in a `SOFT` state.
40 flapping\_threshold|**Optional.** The flapping threshold in percent when a host is considered to be flapping.
41 volatile |**Optional.** The volatile setting enables always `HARD` state types if `NOT-OK` state changes occur.
42 zone |**Optional.** The zone this object is a member of.
43 command\_endpoint|**Optional.** The endpoint where commands are executed on.
44 notes |**Optional.** Notes for the host.
45 notes\_url |**Optional.** Url for notes for the host (for example, in notification commands).
46 action\_url |**Optional.** Url for actions for the host (for example, an external graphing tool).
47 icon\_image |**Optional.** Icon image for the host. Used by external interfaces only.
48 icon\_image\_alt|**Optional.** Icon image description for the host. Used by external interface only.
52 > The `address` and `address6` attributes are required for running commands using
53 > the `$address$` and `$address6$` runtime macros.
56 ## <a id="objecttype-hostgroup"></a> HostGroup
62 > Assign host group members using the [group assign](10-language-reference.md#group-assign) rules.
66 object HostGroup "my-hosts" {
67 display_name = "My hosts"
73 ----------------|----------------
74 display_name |**Optional.** A short description of the host group.
75 groups |**Optional.** An array of nested group names.
77 ## <a id="objecttype-service"></a> Service
79 Service objects describe network services and how they should be checked
84 > Rather than creating a `Service` object for a specific host it is usually easier
85 > to just create a `Service` template and use the `apply` keyword to assign the
86 > service to a number of hosts.
87 > Check the [apply](3-monitoring-basics.md#using-apply) chapter for details.
91 object Service "uptime" {
92 host_name = "localhost"
94 display_name = "localhost Uptime"
96 check_command = "check_snmp"
98 vars.community = "public"
99 vars.oid = "DISMAN-EVENT-MIB::sysUpTimeInstance"
104 groups = [ "all-services", "snmp" ]
110 ----------------|----------------
111 display_name |**Optional.** A short description of the service.
112 host_name |**Required.** The host this service belongs to. There must be a `Host` object with that name.
113 name |**Required.** The service name. Must be unique on a per-host basis (Similar to the service_description attribute in Icinga 1.x).
114 groups |**Optional.** The service groups this service belongs to.
115 vars |**Optional.** A dictionary containing custom attributes that are specific to this service.
116 check\_command |**Required.** The name of the check command.
117 max\_check\_attempts|**Optional.** The number of times a service is re-checked before changing into a hard state. Defaults to 3.
118 check\_period |**Optional.** The name of a time period which determines when this service should be checked. Not set by default.
119 check\_interval |**Optional.** The check interval (in seconds). This interval is used for checks when the service is in a `HARD` state. Defaults to 5 minutes.
120 retry\_interval |**Optional.** The retry interval (in seconds). This interval is used for checks when the service is in a `SOFT` state. Defaults to 1 minute.
121 enable\_notifications|**Optional.** Whether notifications are enabled. Defaults to true.
122 enable\_active\_checks|**Optional.** Whether active checks are enabled. Defaults to true.
123 enable\_passive\_checks|**Optional.** Whether passive checks are enabled. Defaults to true.
124 enable\_event\_handler|**Optional.** Enables event handlers for this host. Defaults to true.
125 enable\_flapping|**Optional.** Whether flap detection is enabled. Defaults to true.
126 enable\_perfdata|**Optional.** Whether performance data processing is enabled. Defaults to true.
127 event\_command |**Optional.** The name of an event command that should be executed every time the service's state changes or the service is in a `SOFT` state.
128 flapping\_threshold|**Optional.** The flapping threshold in percent when a service is considered to be flapping.
129 volatile |**Optional.** The volatile setting enables always `HARD` state types if `NOT-OK` state changes occur.
130 zone |**Optional.** The zone this object is a member of.
131 command\_endpoint|**Optional.** The endpoint where commands are executed on.
132 notes |**Optional.** Notes for the service.
133 notes\_url |**Optional.** Url for notes for the service (for example, in notification commands).
134 action_url |**Optional.** Url for actions for the service (for example, an external graphing tool).
135 icon\_image |**Optional.** Icon image for the service. Used by external interfaces only.
136 icon\_image\_alt|**Optional.** Icon image description for the service. Used by external interface only.
139 Service objects have composite names, i.e. their names are based on the host_name attribute and the name you specified. This means
140 you can define more than one object with the same (short) name as long as the `host_name` attribute has a different value.
142 ## <a id="objecttype-servicegroup"></a> ServiceGroup
148 > Assign service group members using the [group assign](10-language-reference.md#group-assign) rules.
152 object ServiceGroup "snmp" {
153 display_name = "SNMP services"
159 ----------------|----------------
160 display_name |**Optional.** A short description of the service group.
161 groups |**Optional.** An array of nested group names.
164 ## <a id="objecttype-user"></a> User
170 object User "icingaadmin" {
171 display_name = "Icinga 2 Admin"
172 groups = [ "icingaadmins" ]
173 email = "icinga@localhost"
174 pager = "icingaadmin@localhost.localdomain"
178 states = [ OK, Warning, Critical, Unknown ]
179 types = [ Problem, Recovery ]
181 vars.additional_notes = "This is the Icinga 2 Admin account."
184 Available notification state filters:
193 Available notification type filters:
208 ----------------|----------------
209 display_name |**Optional.** A short description of the user.
210 email |**Optional.** An email string for this user. Useful for notification commands.
211 pager |**Optional.** A pager string for this user. Useful for notification commands.
212 vars |**Optional.** A dictionary containing custom attributes that are specific to this user.
213 groups |**Optional.** An array of group names.
214 enable_notifications|**Optional.** Whether notifications are enabled for this user.
215 period |**Optional.** The name of a time period which determines when a notification for this user should be triggered. Not set by default.
216 types |**Optional.** A set of type filters when this notification should be triggered. By default everything is matched.
217 states |**Optional.** A set of state filters when this notification should be triggered. By default everything is matched.
218 zone |**Optional.** The zone this object is a member of.
221 ## <a id="objecttype-usergroup"></a> UserGroup
227 > Assign user group members using the [group assign](10-language-reference.md#group-assign) rules.
231 object UserGroup "icingaadmins" {
232 display_name = "Icinga 2 Admin Group"
238 ----------------|----------------
239 display_name |**Optional.** A short description of the user group.
240 groups |**Optional.** An array of nested group names.
241 zone |**Optional.** The zone this object is a member of.
245 ## <a id="objecttype-checkcommand"></a> CheckCommand
247 A check command definition. Additional default command custom attributes can be
252 object CheckCommand "check_http" {
253 import "plugin-check-command"
255 command = [ PluginDir + "/check_http" ]
258 "-H" = "$http_vhost$"
259 "-I" = "$http_address$"
263 set_if = "$http_ssl$"
266 set_if = "$http_sni$"
269 value = "$http_auth_pair$"
270 description = "Username:password on sites with basic authentication"
273 set_if = "$http_ignore_body$"
275 "-r" = "$http_expect_body_regex$"
276 "-w" = "$http_warn_time$"
277 "-c" = "$http_critical_time$"
278 "-e" = "$http_expect$"
281 vars.http_address = "$address$"
282 vars.http_ssl = false
283 vars.http_sni = false
290 ----------------|----------------
291 execute |**Required.** The "execute" script method takes care of executing the check. In virtually all cases you should import the "plugin-check-command" template to take care of this setting.
292 command |**Required.** The command. This can either be an array of individual command arguments. Alternatively a string can be specified in which case the shell interpreter (usually /bin/sh) takes care of parsing the command. When using the "arguments" attribute this must be an array.
293 env |**Optional.** A dictionary of macros which should be exported as environment variables prior to executing the command.
294 vars |**Optional.** A dictionary containing custom attributes that are specific to this command.
295 timeout |**Optional.** The command timeout in seconds. Defaults to 60 seconds.
296 zone |**Optional.** The zone this object is a member of.
297 arguments |**Optional.** A dictionary of command arguments.
300 ### <a id="objecttype-checkcommand-arguments"></a> CheckCommand Arguments
302 Command arguments can be defined as key-value-pairs in the `arguments`
303 dictionary. If the argument requires additional configuration for example
304 a `description` attribute or an optional condition, the value can be defined
305 as dictionary specifying additional options.
309 vars.x_val = "My command argument value."
317 key = "-Xnew" /* optional, set a new key identifier */
318 description = "My plugin requires this argument for doing X."
319 required = false /* optional, no error if not set */
320 skip_key = false /* always use "-X <value>" */
321 set_if = "$have_x$" /* only set if variable defined and resolves to a numeric value. String values are not supported */
322 order = -1 /* first position */
323 repeat_key = true /* if `value` is an array, repeat the key as parameter: ... 'key' 'value[0]' 'key' 'value[1]' 'key' 'value[2]' ... */
327 description = "My plugin requires this argument for doing Y."
328 required = false /* optional, no error if not set */
329 skip_key = true /* don't prefix "-Y" only use "<value>" */
330 set_if = "$have_y$" /* only set if variable defined and resolves to a numeric value. String values are not supported */
331 order = 0 /* second position */
332 repeat_key = false /* if `value` is an array, do not repeat the key as parameter: ... 'key' 'value[0]' 'value[1]' 'value[2]' ... */
337 ------------|--------------
338 value | Optional argument value.
339 key | Optional argument key overriding the key identifier.
340 description | Optional argument description.
341 required | Required argument. Execution error if not set. Defaults to false (optional).
342 skip_key | Use the value as argument and skip the key.
343 set_if | Argument is added if the macro resolves to a defined numeric value. String values are not supported.
344 order | Set if multiple arguments require a defined argument order.
345 repeat_key | If the argument value is an array, repeat the argument key, or not. Defaults to true (repeat).
349 `..., -3, -2, -1, <un-ordered keys>, 1, 2, 3, ...`
351 Argument array `repeat_key = true`:
353 `'key' 'value[0]' 'key' 'value[1]' 'key' 'value[2]'`
355 Argument array `repeat_key = false`:
357 `'key' 'value[0]' 'value[1]' 'value[2]'`
360 ## <a id="objecttype-notificationcommand"></a> NotificationCommand
362 A notification command definition.
366 object NotificationCommand "mail-service-notification" {
367 import "plugin-notification-command"
370 SysconfDir + "/icinga2/scripts/mail-notification.sh"
374 NOTIFICATIONTYPE = "$notification.type$"
375 SERVICEDESC = "$service.name$"
376 HOSTALIAS = "$host.display_name$"
377 HOSTADDRESS = "$address$"
378 SERVICESTATE = "$service.state$"
379 LONGDATETIME = "$icinga.long_date_time$"
380 SERVICEOUTPUT = "$service.output$"
381 NOTIFICATIONAUTHORNAME = "$notification.author$"
382 NOTIFICATIONCOMMENT = "$notification.comment$"
383 HOSTDISPLAYNAME = "$host.display_name$"
384 SERVICEDISPLAYNAME = "$service.display_name$"
385 USEREMAIL = "$user.email$"
392 ----------------|----------------
393 execute |**Required.** The "execute" script method takes care of executing the notification. In virtually all cases you should import the "plugin-notification-command" template to take care of this setting.
394 command |**Required.** The command. This can either be an array of individual command arguments. Alternatively a string can be specified in which case the shell interpreter (usually /bin/sh) takes care of parsing the command.
395 env |**Optional.** A dictionary of macros which should be exported as environment variables prior to executing the command.
396 vars |**Optional.** A dictionary containing custom attributes that are specific to this command.
397 timeout |**Optional.** The command timeout in seconds. Defaults to 60 seconds.
398 zone |**Optional.** The zone this object is a member of.
399 arguments |**Optional.** A dictionary of command arguments.
401 Command arguments can be used the same way as for [CheckCommand objects](12-object-types.md#objecttype-checkcommand-arguments).
404 ## <a id="objecttype-eventcommand"></a> EventCommand
406 An event command definition.
410 object EventCommand "restart-httpd-event" {
411 import "plugin-event-command"
413 command = "/opt/bin/restart-httpd.sh"
420 ----------------|----------------
421 execute |**Required.** The "execute" script method takes care of executing the event handler. In virtually all cases you should import the "plugin-event-command" template to take care of this setting.
422 command |**Required.** The command. This can either be an array of individual command arguments. Alternatively a string can be specified in which case the shell interpreter (usually /bin/sh) takes care of parsing the command.
423 env |**Optional.** A dictionary of macros which should be exported as environment variables prior to executing the command.
424 vars |**Optional.** A dictionary containing custom attributes that are specific to this command.
425 timeout |**Optional.** The command timeout in seconds. Defaults to 60 seconds.
426 arguments |**Optional.** A dictionary of command arguments.
428 Command arguments can be used the same way as for [CheckCommand objects](12-object-types.md#objecttype-checkcommand-arguments).
431 ## <a id="objecttype-notification"></a> Notification
433 Notification objects are used to specify how users should be notified in case
434 of host and service state changes and other events.
438 > Rather than creating a `Notification` object for a specific host or service it is
439 > usually easier to just create a `Notification` template and use the `apply` keyword
440 > to assign the notification to a number of hosts or services. Use the `to` keyword
441 > to set the specific target type for `Host` or `Service`.
442 > Check the [notifications](3-monitoring-basics.md#notifications) chapter for detailed examples.
446 object Notification "localhost-ping-notification" {
447 host_name = "localhost"
448 service_name = "ping4"
450 command = "mail-notification"
452 users = [ "user1", "user2" ]
454 types = [ Problem, Recovery ]
460 --------------------------|----------------
461 host_name | **Required.** The name of the host this notification belongs to.
462 service_name | **Optional.** The short name of the service this notification belongs to. If omitted this notification object is treated as host notification.
463 vars | **Optional.** A dictionary containing custom attributes that are specific to this notification object.
464 users | **Optional.** A list of user names who should be notified.
465 user_groups | **Optional.** A list of user group names who should be notified.
466 times | **Optional.** A dictionary containing `begin` and `end` attributes for the notification.
467 command | **Required.** The name of the notification command which should be executed when the notification is triggered.
468 interval | **Optional.** The notification interval (in seconds). This interval is used for active notifications. Defaults to 30 minutes. If set to 0, [re-notifications](3-monitoring-basics.md#disable-renotification) are disabled.
469 period | **Optional.** The name of a time period which determines when this notification should be triggered. Not set by default.
470 zone |**Optional.** The zone this object is a member of.
471 types | **Optional.** A list of type filters when this notification should be triggered. By default everything is matched.
472 states | **Optional.** A list of state filters when this notification should be triggered. By default everything is matched.
474 Available notification state filters:
483 Available notification type filters:
497 ## <a id="objecttype-timeperiod"></a> TimePeriod
499 Time periods can be used to specify when hosts/services should be checked or to limit
500 when notifications should be sent out.
504 object TimePeriod "24x7" {
505 import "legacy-timeperiod"
507 display_name = "Icinga 2 24x7 TimePeriod"
510 monday = "00:00-24:00"
511 tuesday = "00:00-24:00"
512 wednesday = "00:00-24:00"
513 thursday = "00:00-24:00"
514 friday = "00:00-24:00"
515 saturday = "00:00-24:00"
516 sunday = "00:00-24:00"
523 ----------------|----------------
524 display_name |**Optional.** A short description of the time period.
525 update |**Required.** The "update" script method takes care of updating the internal representation of the time period. In virtually all cases you should import the "legacy-timeperiod" template to take care of this setting.
526 zone |**Optional.** The zone this object is a member of.
527 ranges |**Required.** A dictionary containing information which days and durations apply to this timeperiod.
529 The `/etc/icinga2/conf.d/timeperiods.conf` file is usually used to define
530 timeperiods including this one.
533 ## <a id="objecttype-scheduleddowntime"></a> ScheduledDowntime
535 ScheduledDowntime objects can be used to set up recurring downtimes for hosts/services.
539 > Rather than creating a `ScheduledDowntime` object for a specific host or service it is usually easier
540 > to just create a `ScheduledDowntime` template and use the `apply` keyword to assign the
541 > scheduled downtime to a number of hosts or services. Use the `to` keyword to set the specific target
542 > type for `Host` or `Service`.
543 > Check the [recurring downtimes](3-monitoring-basics.md#recurring-downtimes) example for details.
547 object ScheduledDowntime "some-downtime" {
548 host_name = "localhost"
549 service_name = "ping4"
551 author = "icingaadmin"
552 comment = "Some comment"
558 "sunday" = "02:00-03:00"
565 ----------------|----------------
566 host_name |**Required.** The name of the host this scheduled downtime belongs to.
567 service_name |**Optional.** The short name of the service this scheduled downtime belongs to. If omitted this downtime object is treated as host downtime.
568 author |**Required.** The author of the downtime.
569 comment |**Required.** A comment for the downtime.
570 fixed |**Optional.** Whether this is a fixed downtime. Defaults to true.
571 duration |**Optional.** How long the downtime lasts. Only has an effect for flexible (non-fixed) downtimes.
572 zone |**Optional.** The zone this object is a member of.
573 ranges |**Required.** A dictionary containing information which days and durations apply to this timeperiod.
575 ScheduledDowntime objects have composite names, i.e. their names are based
576 on the `host_name` and `service_name` attributes and the
577 name you specified. This means you can define more than one object
578 with the same (short) name as long as one of the `host_name` and
579 `service_name` attributes has a different value.
582 ## <a id="objecttype-dependency"></a> Dependency
584 Dependency objects are used to specify dependencies between hosts and services. Dependencies
585 can be defined as Host-to-Host, Service-to-Service, Service-to-Host, or Host-to-Service
590 > Rather than creating a `Dependency` object for a specific host or service it is usually easier
591 > to just create a `Dependency` template and use the `apply` keyword to assign the
592 > dependency to a number of hosts or services. Use the `to` keyword to set the specific target
593 > type for `Host` or `Service`.
594 > Check the [dependencies](3-monitoring-basics.md#dependencies) chapter for detailed examples.
596 Service-to-Service Example:
598 object Dependency "webserver-internet" {
599 parent_host_name = "internet"
600 parent_service_name = "ping4"
602 child_host_name = "webserver"
603 child_service_name = "ping4"
605 states = [ OK, Warning ]
607 disable_checks = true
610 Host-to-Host Example:
612 object Dependency "webserver-internet" {
613 parent_host_name = "internet"
615 child_host_name = "webserver"
619 disable_checks = true
625 ----------------------|----------------
626 parent_host_name |**Required.** The parent host.
627 parent_service_name |**Optional.** The parent service. If omitted this dependency object is treated as host dependency.
628 child_host_name |**Required.** The child host.
629 child_service_name |**Optional.** The child service. If omitted this dependency object is treated as host dependency.
630 disable_checks |**Optional.** Whether to disable checks when this dependency fails. Defaults to false.
631 disable_notifications |**Optional.** Whether to disable notifications when this dependency fails. Defaults to true.
632 period |**Optional.** Time period during which this dependency is enabled.
633 zone |**Optional.** The zone this object is a member of.
634 states |**Optional.** A list of state filters when this dependency should be OK. Defaults to [ OK, Warning ] for services and [ Up ] for hosts.
636 Available state filters:
645 When using [apply rules](3-monitoring-basics.md#using-apply) for dependencies, you can leave out certain attributes which will be
646 automatically determined by Icinga 2.
648 Service-to-Host Dependency Example:
650 apply Dependency "internet" to Service {
651 parent_host_name = "dsl-router"
652 disable_checks = true
654 assign where host.name != "dsl-router"
657 This example sets all service objects matching the assign condition into a dependency relation to
658 the parent host object `dsl-router` as implicit child services.
660 Service-to-Service-on-the-same-Host Dependency Example:
662 apply Dependency "disable-nrpe-checks" to Service {
663 parent_service_name = "nrpe-health"
665 assign where service.check_command == "nrpe"
666 ignore where service.name == "nrpe-health"
669 This example omits the `parent_host_name` attribute and Icinga 2 automatically sets its value to the name of the
670 host object matched by the apply rule condition. All services where apply matches are made implicit child services
671 in this dependency relation.
674 Dependency objects have composite names, i.e. their names are based on the `child_host_name` and `child_service_name` attributes and the
675 name you specified. This means you can define more than one object with the same (short) name as long as one of the `child_host_name` and
676 `child_service_name` attributes has a different value.
679 ## <a id="objecttype-perfdatawriter"></a> PerfdataWriter
681 Writes check result performance data to a defined path using macro
682 pattern consisting of custom attributes and runtime macros.
688 object PerfdataWriter "pnp" {
689 host_perfdata_path = "/var/spool/icinga2/perfdata/host-perfdata"
691 service_perfdata_path = "/var/spool/icinga2/perfdata/service-perfdata"
693 host_format_template = "DATATYPE::HOSTPERFDATA\tTIMET::$icinga.timet$\tHOSTNAME::$host.name$\tHOSTPERFDATA::$host.perfdata$\tHOSTCHECKCOMMAND::$host.check_command$\tHOSTSTATE::$host.state$\tHOSTSTATETYPE::$host.state_type$"
694 service_format_template = "DATATYPE::SERVICEPERFDATA\tTIMET::$icinga.timet$\tHOSTNAME::$host.name$\tSERVICEDESC::$service.name$\tSERVICEPERFDATA::$service.perfdata$\tSERVICECHECKCOMMAND::$service.check_command$\tHOSTSTATE::$host.state$\tHOSTSTATETYPE::$host.state_type$\tSERVICESTATE::$service.state$\tSERVICESTATETYPE::$service.state_type$"
696 rotation_interval = 15s
702 ------------------------|----------------
703 host_perfdata\_path |**Optional.** Path to the host performance data file. Defaults to LocalStateDir + "/spool/icinga2/perfdata/host-perfdata".
704 service_perfdata\_path |**Optional.** Path to the service performance data file. Defaults to LocalStateDir + "/spool/icinga2/perfdata/service-perfdata".
705 host_temp\_path |**Optional.** Path to the temporary host file. Defaults to LocalStateDir + "/spool/icinga2/tmp/host-perfdata".
706 service_temp\_path |**Optional.** Path to the temporary service file. Defaults to LocalStateDir + "/spool/icinga2/tmp/service-perfdata".
707 host_format\_template |**Optional.** Host Format template for the performance data file. Defaults to a template that's suitable for use with PNP4Nagios.
708 service_format\_template|**Optional.** Service Format template for the performance data file. Defaults to a template that's suitable for use with PNP4Nagios.
709 rotation\_interval |**Optional.** Rotation interval for the files specified in `{host,service}_perfdata_path`. Defaults to 30 seconds.
711 When rotating the performance data file the current UNIX timestamp is appended to the path specified
712 in `host_perfdata_path` and `service_perfdata_path` to generate a unique filename.
715 ## <a id="objecttype-graphitewriter"></a> GraphiteWriter
717 Writes check result metrics and performance data to a defined
718 Graphite Carbon host.
724 object GraphiteWriter "graphite" {
732 ----------------------|----------------------
733 host |**Optional.** Graphite Carbon host address. Defaults to '127.0.0.1'.
734 port |**Optional.** Graphite Carbon port. Defaults to 2003.
735 host_name_template |**Optional.** Metric prefix for host name. Defaults to "icinga.$host.name$".
736 service_name_template |**Optional.** Metric prefix for service name. Defaults to "icinga.$host.name$.$service.name$".
738 Metric prefix names can be modified using [runtime macros](3-monitoring-basics.md#runtime-macros).
740 Example with your custom [global constant](10-language-reference.md#constants) `GraphiteEnv`:
742 const GraphiteEnv = "icinga.env1"
744 host_name_template = GraphiteEnv + ".$host.name$"
745 service_name_template = GraphiteEnv + ".$host.name$.$service.name$"
747 ## <a id="objecttype-gelfwriter"></a> GelfWriter
749 Writes event log entries to a defined GELF receiver host (Graylog2, Logstash).
755 object GelfWriter "gelf" {
763 ----------------------|----------------------
764 host |**Optional.** GELF receiver host address. Defaults to '127.0.0.1'.
765 port |**Optional.** GELF receiver port. Defaults to `12201`.
766 source |**Optional.** Source name for this instance. Defaults to `icinga2`.
769 ## <a id="objecttype-idomysqlconnection"></a> IdoMySqlConnection
771 IDO database adapter for MySQL.
775 library "db_ido_mysql"
777 object IdoMysqlConnection "mysql-ido" {
783 table_prefix = "icinga_"
784 instance_name = "icinga2"
785 instance_description = "icinga2 instance"
788 downtimehistory_age = 48h
792 categories = DbCatConfig | DbCatState
798 ----------------|----------------
799 host |**Optional.** MySQL database host address. Defaults to "localhost".
800 port |**Optional.** MySQL database port. Defaults to 3306.
801 socket_path |**Optional.** MySQL socket path.
802 user |**Optional.** MySQL database user with read/write permission to the icinga database. Defaults to "icinga".
803 password |**Optional.** MySQL database user's password. Defaults to "icinga".
804 database |**Optional.** MySQL database name. Defaults to "icinga".
805 table\_prefix |**Optional.** MySQL database table prefix. Defaults to "icinga\_".
806 instance\_name |**Optional.** Unique identifier for the local Icinga 2 instance. Defaults to "default".
807 instance\_description|**Optional.** Description for the Icinga 2 instance.
808 enable_ha |**Optional.** Enable the high availability functionality. Only valid in a [cluster setup](4-monitoring-remote-systems.md#high-availability-db-ido). Defaults to "true".
809 failover_timeout | **Optional.** Set the failover timeout in a [HA cluster](4-monitoring-remote-systems.md#high-availability-db-ido). Must not be lower than 60s. Defaults to "60s".
810 cleanup |**Optional.** Dictionary with items for historical table cleanup.
811 categories |**Optional.** The types of information that should be written to the database.
816 ----------------|----------------
817 acknowledgements_age |**Optional.** Max age for acknowledgements table rows (entry_time). Defaults to 0 (never).
818 commenthistory_age |**Optional.** Max age for commenthistory table rows (entry_time). Defaults to 0 (never).
819 contactnotifications_age |**Optional.** Max age for contactnotifications table rows (start_time). Defaults to 0 (never).
820 contactnotificationmethods_age |**Optional.** Max age for contactnotificationmethods table rows (start_time). Defaults to 0 (never).
821 downtimehistory_age |**Optional.** Max age for downtimehistory table rows (entry_time). Defaults to 0 (never).
822 eventhandlers_age |**Optional.** Max age for eventhandlers table rows (start_time). Defaults to 0 (never).
823 externalcommands_age |**Optional.** Max age for externalcommands table rows (entry_time). Defaults to 0 (never).
824 flappinghistory_age |**Optional.** Max age for flappinghistory table rows (event_time). Defaults to 0 (never).
825 hostchecks_age |**Optional.** Max age for hostalives table rows (start_time). Defaults to 0 (never).
826 logentries_age |**Optional.** Max age for logentries table rows (logentry_time). Defaults to 0 (never).
827 notifications_age |**Optional.** Max age for notifications table rows (start_time). Defaults to 0 (never).
828 processevents_age |**Optional.** Max age for processevents table rows (event_time). Defaults to 0 (never).
829 statehistory_age |**Optional.** Max age for statehistory table rows (state_time). Defaults to 0 (never).
830 servicechecks_age |**Optional.** Max age for servicechecks table rows (start_time). Defaults to 0 (never).
831 systemcommands_age |**Optional.** Max age for systemcommands table rows (start_time). Defaults to 0 (never).
835 Name | Description | Required by
836 ---------------------|------------------------|--------------------
837 DbCatConfig | Configuration data | Icinga Web/Reporting
838 DbCatState | Current state data | Icinga Web/Reporting
839 DbCatAcknowledgement | Acknowledgements | Icinga Web/Reporting
840 DbCatComment | Comments | Icinga Web/Reporting
841 DbCatDowntime | Downtimes | Icinga Web/Reporting
842 DbCatEventHandler | Event handler data | Icinga Web/Reporting
843 DbCatExternalCommand | External commands | Icinga Web/Reporting
844 DbCatFlapping | Flap detection data | Icinga Web/Reporting
845 DbCatCheck | Check results | --
846 DbCatLog | Log messages | Icinga Web/Reporting
847 DbCatNotification | Notifications | Icinga Web/Reporting
848 DbCatProgramStatus | Program status data | Icinga Web/Reporting
849 DbCatRetention | Retention data | Icinga Web/Reporting
850 DbCatStateHistory | Historical state data | Icinga Web/Reporting
852 Multiple categories can be combined using the `|` operator. In addition to
853 the category flags listed above the `DbCatEverything` flag may be used as
854 a shortcut for listing all flags.
856 External interfaces like Icinga Web require everything except `DbCatCheck`
857 which is the default value if `categories` is not set.
859 ## <a id="objecttype-idopgsqlconnection"></a> IdoPgSqlConnection
861 IDO database adapter for PostgreSQL.
865 library "db_ido_pgsql"
867 object IdoMysqlConnection "pgsql-ido" {
873 table_prefix = "icinga_"
874 instance_name = "icinga2"
875 instance_description = "icinga2 instance"
878 downtimehistory_age = 48h
882 categories = DbCatConfig | DbCatState
888 ----------------|----------------
889 host |**Optional.** PostgreSQL database host address. Defaults to "localhost".
890 port |**Optional.** PostgreSQL database port. Defaults to "5432".
891 user |**Optional.** PostgreSQL database user with read/write permission to the icinga database. Defaults to "icinga".
892 password |**Optional.** PostgreSQL database user's password. Defaults to "icinga".
893 database |**Optional.** PostgreSQL database name. Defaults to "icinga".
894 table\_prefix |**Optional.** PostgreSQL database table prefix. Defaults to "icinga\_".
895 instance\_name |**Optional.** Unique identifier for the local Icinga 2 instance. Defaults to "default".
896 instance\_description|**Optional.** Description for the Icinga 2 instance.
897 enable_ha |**Optional.** Enable the high availability functionality. Only valid in a [cluster setup](4-monitoring-remote-systems.md#high-availability-db-ido). Defaults to "true".
898 failover_timeout | **Optional.** Set the failover timeout in a [HA cluster](4-monitoring-remote-systems.md#high-availability-db-ido). Must not be lower than 60s. Defaults to "60s".
899 cleanup |**Optional.** Dictionary with items for historical table cleanup.
900 categories |**Optional.** The types of information that should be written to the database.
905 ----------------|----------------
906 acknowledgements_age |**Optional.** Max age for acknowledgements table rows (entry_time). Defaults to 0 (never).
907 commenthistory_age |**Optional.** Max age for commenthistory table rows (entry_time). Defaults to 0 (never).
908 contactnotifications_age |**Optional.** Max age for contactnotifications table rows (start_time). Defaults to 0 (never).
909 contactnotificationmethods_age |**Optional.** Max age for contactnotificationmethods table rows (start_time). Defaults to 0 (never).
910 downtimehistory_age |**Optional.** Max age for downtimehistory table rows (entry_time). Defaults to 0 (never).
911 eventhandlers_age |**Optional.** Max age for eventhandlers table rows (start_time). Defaults to 0 (never).
912 externalcommands_age |**Optional.** Max age for externalcommands table rows (entry_time). Defaults to 0 (never).
913 flappinghistory_age |**Optional.** Max age for flappinghistory table rows (event_time). Defaults to 0 (never).
914 hostchecks_age |**Optional.** Max age for hostalives table rows (start_time). Defaults to 0 (never).
915 logentries_age |**Optional.** Max age for logentries table rows (logentry_time). Defaults to 0 (never).
916 notifications_age |**Optional.** Max age for notifications table rows (start_time). Defaults to 0 (never).
917 processevents_age |**Optional.** Max age for processevents table rows (event_time). Defaults to 0 (never).
918 statehistory_age |**Optional.** Max age for statehistory table rows (state_time). Defaults to 0 (never).
919 servicechecks_age |**Optional.** Max age for servicechecks table rows (start_time). Defaults to 0 (never).
920 systemcommands_age |**Optional.** Max age for systemcommands table rows (start_time). Defaults to 0 (never).
924 Name | Description | Required by
925 ---------------------|------------------------|--------------------
926 DbCatConfig | Configuration data | Icinga Web/Reporting
927 DbCatState | Current state data | Icinga Web/Reporting
928 DbCatAcknowledgement | Acknowledgements | Icinga Web/Reporting
929 DbCatComment | Comments | Icinga Web/Reporting
930 DbCatDowntime | Downtimes | Icinga Web/Reporting
931 DbCatEventHandler | Event handler data | Icinga Web/Reporting
932 DbCatExternalCommand | External commands | Icinga Web/Reporting
933 DbCatFlapping | Flap detection data | Icinga Web/Reporting
934 DbCatCheck | Check results | --
935 DbCatLog | Log messages | Icinga Web/Reporting
936 DbCatNotification | Notifications | Icinga Web/Reporting
937 DbCatProgramStatus | Program status data | Icinga Web/Reporting
938 DbCatRetention | Retention data | Icinga Web/Reporting
939 DbCatStateHistory | Historical state data | Icinga Web/Reporting
941 Multiple categories can be combined using the `|` operator. In addition to
942 the category flags listed above the `DbCatEverything` flag may be used as
943 a shortcut for listing all flags.
945 External interfaces like Icinga Web require everything except `DbCatCheck`
946 which is the default value if `categories` is not set.
948 ## <a id="objecttype-livestatuslistener"></a> LiveStatusListener
950 Livestatus API interface available as TCP or UNIX socket. Historical table queries
951 require the `CompatLogger` feature enabled pointing to the log files using the
952 `compat_log_path` configuration attribute.
958 object LivestatusListener "livestatus-tcp" {
960 bind_host = "127.0.0.1"
964 object LivestatusListener "livestatus-unix" {
966 socket_path = "/var/run/icinga2/cmd/livestatus"
972 ----------------|----------------
973 socket\_type |**Optional.** Specifies the socket type. Can be either "tcp" or "unix". Defaults to "unix".
974 bind\_host |**Optional.** Only valid when socket\_type is "tcp". Host address to listen on for connections. Defaults to "127.0.0.1".
975 bind\_port |**Optional.** Only valid when `socket_type` is "tcp". Port to listen on for connections. Defaults to 6558.
976 socket\_path |**Optional.** Only valid when `socket_type` is "unix". Specifies the path to the UNIX socket file. Defaults to RunDir + "/icinga2/cmd/livestatus".
977 compat\_log\_path |**Optional.** Required for historical table queries. Requires `CompatLogger` feature enabled. Defaults to LocalStateDir + "/log/icinga2/compat"
981 > UNIX sockets are not supported on Windows.
983 ## <a id="objecttype-statusdatawriter"></a> StatusDataWriter
985 Periodically writes status data files which are used by the Classic UI and other third-party tools.
991 object StatusDataWriter "status" {
992 status_path = "/var/cache/icinga2/status.dat"
993 objects_path = "/var/cache/icinga2/objects.cache"
994 update_interval = 30s
1000 ----------------|----------------
1001 status\_path |**Optional.** Path to the status.dat file. Defaults to LocalStateDir + "/cache/icinga2/status.dat".
1002 objects\_path |**Optional.** Path to the objects.cache file. Defaults to LocalStateDir + "/cache/icinga2/objects.cache".
1003 update\_interval|**Optional.** The interval in which the status files are updated. Defaults to 15 seconds.
1006 ## <a id="objecttype-externalcommandlistener"></a> ExternalCommandListener
1008 Implements the Icinga 1.x command pipe which can be used to send commands to Icinga.
1014 object ExternalCommandListener "external" {
1015 command_path = "/var/run/icinga2/cmd/icinga2.cmd"
1021 ----------------|----------------
1022 command\_path |**Optional.** Path to the command pipe. Defaults to RunDir + "/icinga2/cmd/icinga2.cmd".
1024 ## <a id="objecttype-compatlogger"></a> CompatLogger
1026 Writes log files in a format that's compatible with Icinga 1.x.
1032 object CompatLogger "my-log" {
1033 log_dir = "/var/log/icinga2/compat"
1034 rotation_method = "HOURLY"
1040 ----------------|----------------
1041 log\_dir |**Optional.** Path to the compat log directory. Defaults to LocalStateDir + "/log/icinga2/compat".
1042 rotation\_method|**Optional.** Specifies when to rotate log files. Can be one of "HOURLY", "DAILY", "WEEKLY" or "MONTHLY". Defaults to "HOURLY".
1045 ## <a id="objecttype-checkresultreader"></a> CheckResultReader
1047 Reads Icinga 1.x check results from a directory. This functionality is provided
1048 to help existing Icinga 1.x users and might be useful for certain cluster
1055 object CheckResultReader "reader" {
1056 spool_dir = "/data/check-results"
1062 ----------------|----------------
1063 spool\_dir |**Optional.** The directory which contains the check result files. Defaults to LocalStateDir + "/lib/icinga2/spool/checkresults/".
1066 ## <a id="objecttype-checkcomponent"></a> CheckerComponent
1068 The checker component is responsible for scheduling active checks. There are no configurable options.
1074 object CheckerComponent "checker" { }
1077 ## <a id="objecttype-notificationcomponent"></a> NotificationComponent
1079 The notification component is responsible for sending notifications. There are no configurable options.
1083 library "notification"
1085 object NotificationComponent "notification" { }
1090 ----------------|----------------
1091 enable_ha |**Optional.** Enable the high availability functionality. Only valid in a [cluster setup](#high-availability). Defaults to "true".
1094 ## <a id="objecttype-filelogger"></a> FileLogger
1096 Specifies Icinga 2 logging to a file.
1100 object FileLogger "debug-file" {
1102 path = "/var/log/icinga2/debug.log"
1108 ----------------|----------------
1109 path |**Required.** The log path.
1110 severity |**Optional.** The minimum severity for this log. Can be "debug", "notice", "information", "warning" or "critical". Defaults to "information".
1113 ## <a id="objecttype-sysloglogger"></a> SyslogLogger
1115 Specifies Icinga 2 logging to syslog.
1119 object SyslogLogger "crit-syslog" {
1120 severity = "critical"
1126 ----------------|----------------
1127 severity |**Optional.** The minimum severity for this log. Can be "debug", "notice", "information", "notice", "warning" or "critical". Defaults to "warning".
1131 ## <a id="objecttype-icingastatuswriter"></a> IcingaStatusWriter
1133 The IcingaStatusWriter feature periodically dumps the current status
1134 and performance data from Icinga 2 and all registered features into
1135 a defined JSON file.
1139 object IcingaStatusWriter "status" {
1140 status_path = LocalStateDir + "/cache/icinga2/status.json"
1141 update_interval = 15s
1147 --------------------------|--------------------------
1148 status\_path |**Optional.** Path to cluster status file. Defaults to LocalStateDir + "/cache/icinga2/status.json"
1149 update\_interval |**Optional.** The interval in which the status files are updated. Defaults to 15 seconds.
1152 ## <a id="objecttype-apilistener"></a> ApiListener
1154 ApiListener objects are used for distributed monitoring setups
1155 specifying the certificate files used for ssl authorization.
1157 The `NodeName` constant must be defined in [constants.conf](2-getting-started.md#constants-conf).
1161 object ApiListener "api" {
1162 cert_path = SysconfDir + "/icinga2/pki/" + NodeName + ".crt"
1163 key_path = SysconfDir + "/icinga2/pki/" + NodeName + ".key"
1164 ca_path = SysconfDir + "/icinga2/pki/ca.crt"
1171 --------------------------|--------------------------
1172 cert\_path |**Required.** Path to the public key.
1173 key\_path |**Required.** Path to the private key.
1174 ca\_path |**Required.** Path to the CA certificate file.
1175 crl\_path |**Optional.** Path to the CRL file.
1176 bind\_host |**Optional.** The IP address the api listener should be bound to. Defaults to `0.0.0.0`.
1177 bind\_port |**Optional.** The port the api listener should be bound to. Defaults to `5665`.
1178 accept\_config |**Optional.** Accept zone configuration. Defaults to `false`.
1179 accept\_commands |**Optional.** Accept remote commands. Defaults to `false`.
1182 ## <a id="objecttype-endpoint"></a> Endpoint
1184 Endpoint objects are used to specify connection information for remote
1189 object Endpoint "icinga2b" {
1190 host = "192.168.5.46"
1197 ----------------|----------------
1198 host |**Optional.** The hostname/IP address of the remote Icinga 2 instance.
1199 port |**Optional.** The service name/port of the remote Icinga 2 instance. Defaults to `5665`.
1200 log_duration |**Optional.** Duration for keeping replay logs on connection loss. Defaults to `1d`.
1203 ## <a id="objecttype-zone"></a> Zone
1205 Zone objects are used to specify which Icinga 2 instances are located in a zone.
1206 All zone endpoints elect one active master instance among them (required for High-Availability setups).
1210 object Zone "config-ha-master" {
1211 endpoints = [ "icinga2a", "icinga2b" ]
1215 object Zone "check-satellite" {
1216 endpoints = [ "icinga2c" ]
1217 parent = "config-ha-master"
1223 ----------------|----------------
1224 endpoints |**Optional.** Dictionary with endpoints located in this zone.
1225 parent |**Optional.** The name of the parent zone.