granicus.if.org Git - icinga2/blob - doc/15-object-types.md

   1 # <a id="object-types"></a> Object Types
   2
   3 ## <a id="objecttype-host"></a> Host
   4
   5 A host.
   6
   7 Example:
   8
   9     object Host "localhost" {
  10       display_name = "The best host there is"
  11       address = "127.0.0.1"
  12       address6 = "::1"
  13
  14       groups = [ "all-hosts" ]
  15
  16       check_command = "hostalive"
  17     }
  18
  19 Attributes:
  20
  21   Name            |Description
  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.
  49
  50 > **Best Practice**
  51 >
  52 > The `address` and `address6` attributes are required for running commands using
  53 > the `$address$` and `$address6$` runtime macros.
  54
  55
  56 ## <a id="objecttype-hostgroup"></a> HostGroup
  57
  58 A group of hosts.
  59
  60 > **Best Practice**
  61 >
  62 > Assign host group members using the [group assign](13-language-reference.md#group-assign) rules.
  63
  64 Example:
  65
  66     object HostGroup "my-hosts" {
  67       display_name = "My hosts"
  68     }
  69
  70 Attributes:
  71
  72   Name            |Description
  73   ----------------|----------------
  74   display_name    |**Optional.** A short description of the host group.
  75   groups          |**Optional.** An array of nested group names.
  76
  77 ## <a id="objecttype-service"></a> Service
  78
  79 Service objects describe network services and how they should be checked
  80 by Icinga 2.
  81
  82 > **Best Practice**
  83 >
  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.
  88
  89 Example:
  90
  91     object Service "uptime" {
  92       host_name = "localhost"
  93
  94       display_name = "localhost Uptime"
  95
  96       check_command = "check_snmp"
  97
  98       vars.community = "public"
  99       vars.oid = "DISMAN-EVENT-MIB::sysUpTimeInstance"
 100
 101       check_interval = 60s
 102       retry_interval = 15s
 103
 104       groups = [ "all-services", "snmp" ]
 105     }
 106
 107 Attributes:
 108
 109   Name            |Description
 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.
 137
 138
 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.
 141
 142 ## <a id="objecttype-servicegroup"></a> ServiceGroup
 143
 144 A group of services.
 145
 146 > **Best Practice**
 147 >
 148 > Assign service group members using the [group assign](13-language-reference.md#group-assign) rules.
 149
 150 Example:
 151
 152     object ServiceGroup "snmp" {
 153       display_name = "SNMP services"
 154     }
 155
 156 Attributes:
 157
 158   Name            |Description
 159   ----------------|----------------
 160   display_name    |**Optional.** A short description of the service group.
 161   groups          |**Optional.** An array of nested group names.
 162
 163
 164 ## <a id="objecttype-user"></a> User
 165
 166 A user.
 167
 168 Example:
 169
 170     object User "icingaadmin" {
 171       display_name = "Icinga 2 Admin"
 172       groups = [ "icingaadmins" ]
 173       email = "icinga@localhost"
 174       pager = "icingaadmin@localhost.localdomain"
 175
 176       period = "24x7"
 177
 178       states = [ OK, Warning, Critical, Unknown ]
 179       types = [ Problem, Recovery ]
 180
 181       vars.additional_notes = "This is the Icinga 2 Admin account."
 182     }
 183
 184 Available notification state filters:
 185
 186     OK
 187     Warning
 188     Critical
 189     Unknown
 190     Up
 191     Down
 192
 193 Available notification type filters:
 194
 195     DowntimeStart
 196     DowntimeEnd
 197     DowntimeRemoved
 198     Custom
 199     Acknowledgement
 200     Problem
 201     Recovery
 202     FlappingStart
 203     FlappingEnd
 204
 205 Attributes:
 206
 207   Name            |Description
 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.
 219
 220
 221 ## <a id="objecttype-usergroup"></a> UserGroup
 222
 223 A user group.
 224
 225 > **Best Practice**
 226 >
 227 > Assign user group members using the [group assign](13-language-reference.md#group-assign) rules.
 228
 229 Example:
 230
 231     object UserGroup "icingaadmins" {
 232         display_name = "Icinga 2 Admin Group"
 233     }
 234
 235 Attributes:
 236
 237   Name            |Description
 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.
 242
 243
 244
 245 ## <a id="objecttype-checkcommand"></a> CheckCommand
 246
 247 A check command definition. Additional default command custom attributes can be
 248 defined here.
 249
 250 Example:
 251
 252     object CheckCommand "check_http" {
 253       import "plugin-check-command"
 254
 255       command = [ PluginDir + "/check_http" ]
 256
 257       arguments = {
 258         "-H" = "$http_vhost$"
 259         "-I" = "$http_address$"
 260         "-u" = "$http_uri$"
 261         "-p" = "$http_port$"
 262         "-S" = {
 263           set_if = "$http_ssl$"
 264         }
 265         "--sni" = {
 266           set_if = "$http_sni$"
 267         }
 268         "-a" = {
 269           value = "$http_auth_pair$"
 270           description = "Username:password on sites with basic authentication"
 271         }
 272         "--no-body" = {
 273           set_if = "$http_ignore_body$"
 274         }
 275         "-r" = "$http_expect_body_regex$"
 276         "-w" = "$http_warn_time$"
 277         "-c" = "$http_critical_time$"
 278         "-e" = "$http_expect$"
 279       }
 280
 281       vars.http_address = "$address$"
 282       vars.http_ssl = false
 283       vars.http_sni = false
 284     }
 285
 286
 287 Attributes:
 288
 289   Name            |Description
 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.
 298
 299
 300 ### <a id="objecttype-checkcommand-arguments"></a> CheckCommand Arguments
 301
 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.
 306
 307 Service:
 308
 309     vars.x_val = "My command argument value."
 310     vars.have_x = "true"
 311
 312 CheckCommand:
 313
 314     arguments = {
 315       "-X" = {
 316         value = "$x_val$"
 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]' ... */
 324       }
 325       "-Y" = {
 326         value = "$y_val$"
 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]' ... */
 333       }
 334     }
 335
 336   Option      | Description
 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).
 346
 347 Argument order:
 348
 349     `..., -3, -2, -1, <un-ordered keys>, 1, 2, 3, ...`
 350
 351 Argument array `repeat_key = true`:
 352
 353     `'key' 'value[0]' 'key' 'value[1]' 'key' 'value[2]'`
 354
 355 Argument array `repeat_key = false`:
 356
 357     `'key' 'value[0]' 'value[1]' 'value[2]'`
 358
 359
 360 ## <a id="objecttype-notificationcommand"></a> NotificationCommand
 361
 362 A notification command definition.
 363
 364 Example:
 365
 366     object NotificationCommand "mail-service-notification" {
 367       import "plugin-notification-command"
 368
 369       command = [
 370         SysconfDir + "/icinga2/scripts/mail-notification.sh"
 371       ]
 372
 373       env = {
 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$"
 386       }
 387     }
 388
 389 Attributes:
 390
 391   Name            |Description
 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.
 400
 401 Command arguments can be used the same way as for [CheckCommand objects](15-object-types.md#objecttype-checkcommand-arguments).
 402
 403
 404 ## <a id="objecttype-eventcommand"></a> EventCommand
 405
 406 An event command definition.
 407
 408 Example:
 409
 410     object EventCommand "restart-httpd-event" {
 411       import "plugin-event-command"
 412
 413       command = "/opt/bin/restart-httpd.sh"
 414     }
 415
 416
 417 Attributes:
 418
 419   Name            |Description
 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.
 427
 428 Command arguments can be used the same way as for [CheckCommand objects](15-object-types.md#objecttype-checkcommand-arguments).
 429
 430
 431 ## <a id="objecttype-notification"></a> Notification
 432
 433 Notification objects are used to specify how users should be notified in case
 434 of host and service state changes and other events.
 435
 436 > **Best Practice**
 437 >
 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.
 443
 444 Example:
 445
 446     object Notification "localhost-ping-notification" {
 447       host_name = "localhost"
 448       service_name = "ping4"
 449
 450       command = "mail-notification"
 451
 452       users = [ "user1", "user2" ]
 453
 454       types = [ Problem, Recovery ]
 455     }
 456
 457 Attributes:
 458
 459   Name                      | Description
 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.
 473
 474 Available notification state filters:
 475
 476     OK
 477     Warning
 478     Critical
 479     Unknown
 480     Up
 481     Down
 482
 483 Available notification type filters:
 484
 485     DowntimeStart
 486     DowntimeEnd
 487     DowntimeRemoved
 488     Custom
 489     Acknowledgement
 490     Problem
 491     Recovery
 492     FlappingStart
 493     FlappingEnd
 494
 495
 496
 497 ## <a id="objecttype-timeperiod"></a> TimePeriod
 498
 499 Time periods can be used to specify when hosts/services should be checked or to limit
 500 when notifications should be sent out.
 501
 502 Example:
 503
 504     object TimePeriod "24x7" {
 505       import "legacy-timeperiod"
 506
 507       display_name = "Icinga 2 24x7 TimePeriod"
 508
 509       ranges = {
 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"
 517       }
 518     }
 519
 520 Attributes:
 521
 522   Name            |Description
 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.
 528
 529 The `/etc/icinga2/conf.d/timeperiods.conf` file is usually used to define
 530 timeperiods including this one.
 531
 532
 533 ## <a id="objecttype-scheduleddowntime"></a> ScheduledDowntime
 534
 535 ScheduledDowntime objects can be used to set up recurring downtimes for hosts/services.
 536
 537 > **Best Practice**
 538 >
 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.
 544
 545 Example:
 546
 547     object ScheduledDowntime "some-downtime" {
 548       host_name = "localhost"
 549       service_name = "ping4"
 550
 551       author = "icingaadmin"
 552       comment = "Some comment"
 553
 554       fixed = false
 555       duration = 30m
 556
 557       ranges = {
 558         "sunday" = "02:00-03:00"
 559       }
 560     }
 561
 562 Attributes:
 563
 564   Name            |Description
 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.
 574
 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.
 580
 581
 582 ## <a id="objecttype-dependency"></a> Dependency
 583
 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
 586 relations.
 587
 588 > **Best Practice**
 589 >
 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.
 595
 596 Service-to-Service Example:
 597
 598     object Dependency "webserver-internet" {
 599       parent_host_name = "internet"
 600       parent_service_name = "ping4"
 601
 602       child_host_name = "webserver"
 603       child_service_name = "ping4"
 604
 605       states = [ OK, Warning ]
 606
 607       disable_checks = true
 608     }
 609
 610 Host-to-Host Example:
 611
 612     object Dependency "webserver-internet" {
 613       parent_host_name = "internet"
 614
 615       child_host_name = "webserver"
 616
 617       states = [ Up ]
 618
 619       disable_checks = true
 620     }
 621
 622 Attributes:
 623
 624   Name                  |Description
 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.
 635
 636 Available state filters:
 637
 638     OK
 639     Warning
 640     Critical
 641     Unknown
 642     Up
 643     Down
 644
 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.
 647
 648 Service-to-Host Dependency Example:
 649
 650     apply Dependency "internet" to Service {
 651       parent_host_name = "dsl-router"
 652       disable_checks = true
 653
 654       assign where host.name != "dsl-router"
 655     }
 656
 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.
 659
 660 Service-to-Service-on-the-same-Host Dependency Example:
 661
 662     apply Dependency "disable-nrpe-checks" to Service {
 663       parent_service_name = "nrpe-health"
 664
 665       assign where service.check_command == "nrpe"
 666       ignore where service.name == "nrpe-health"
 667     }
 668
 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.
 672
 673
 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.
 677
 678
 679 ## <a id="objecttype-perfdatawriter"></a> PerfdataWriter
 680
 681 Writes check result performance data to a defined path using macro
 682 pattern consisting of custom attributes and runtime macros.
 683
 684 Example:
 685
 686     library "perfdata"
 687
 688     object PerfdataWriter "pnp" {
 689       host_perfdata_path = "/var/spool/icinga2/perfdata/host-perfdata"
 690
 691       service_perfdata_path = "/var/spool/icinga2/perfdata/service-perfdata"
 692
 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$"
 695
 696       rotation_interval = 15s
 697     }
 698
 699 Attributes:
 700
 701   Name                    |Description
 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.
 710
 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.
 713
 714
 715 ## <a id="objecttype-graphitewriter"></a> GraphiteWriter
 716
 717 Writes check result metrics and performance data to a defined
 718 Graphite Carbon host.
 719
 720 Example:
 721
 722     library "perfdata"
 723
 724     object GraphiteWriter "graphite" {
 725       host = "127.0.0.1"
 726       port = 2003
 727     }
 728
 729 Attributes:
 730
 731   Name                  |Description
 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$".
 737
 738 Metric prefix names can be modified using [runtime macros](3-monitoring-basics.md#runtime-macros).
 739
 740 Example with your custom [global constant](13-language-reference.md#constants) `GraphiteEnv`:
 741
 742     const GraphiteEnv = "icinga.env1"
 743
 744     host_name_template = GraphiteEnv + ".$host.name$"
 745     service_name_template = GraphiteEnv + ".$host.name$.$service.name$"
 746
 747 ## <a id="objecttype-gelfwriter"></a> GelfWriter
 748
 749 Writes event log entries to a defined GELF receiver host (Graylog2, Logstash).
 750
 751 Example:
 752
 753     library "perfdata"
 754
 755     object GelfWriter "gelf" {
 756       host = "127.0.0.1"
 757       port = 12201
 758     }
 759
 760 Attributes:
 761
 762   Name                  |Description
 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`.
 767
 768
 769 ## <a id="objecttype-idomysqlconnection"></a> IdoMySqlConnection
 770
 771 IDO database adapter for MySQL.
 772
 773 Example:
 774
 775     library "db_ido_mysql"
 776
 777     object IdoMysqlConnection "mysql-ido" {
 778       host = "127.0.0.1"
 779       port = 3306
 780       user = "icinga"
 781       password = "icinga"
 782       database = "icinga"
 783       table_prefix = "icinga_"
 784       instance_name = "icinga2"
 785       instance_description = "icinga2 instance"
 786
 787       cleanup = {
 788         downtimehistory_age = 48h
 789         logentries_age = 31d
 790       }
 791
 792       categories = DbCatConfig | DbCatState
 793     }
 794
 795 Attributes:
 796
 797   Name            |Description
 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](5-monitoring-remote-systems.md#high-availability-db-ido). Defaults to "true".
 809   failover_timeout | **Optional.** Set the failover timeout in a [HA cluster](5-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.
 812
 813 Cleanup Items:
 814
 815   Name            | Description
 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).
 832
 833 Data Categories:
 834
 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
 851
 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.
 855
 856 External interfaces like Icinga Web require everything except `DbCatCheck`
 857 which is the default value if `categories` is not set.
 858
 859 ## <a id="objecttype-idopgsqlconnection"></a> IdoPgSqlConnection
 860
 861 IDO database adapter for PostgreSQL.
 862
 863 Example:
 864
 865     library "db_ido_pgsql"
 866
 867     object IdoMysqlConnection "pgsql-ido" {
 868       host = "127.0.0.1"
 869       port = 5432
 870       user = "icinga"
 871       password = "icinga"
 872       database = "icinga"
 873       table_prefix = "icinga_"
 874       instance_name = "icinga2"
 875       instance_description = "icinga2 instance"
 876
 877       cleanup = {
 878         downtimehistory_age = 48h
 879         logentries_age = 31d
 880       }
 881
 882       categories = DbCatConfig | DbCatState
 883     }
 884
 885 Attributes:
 886
 887   Name            |Description
 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](5-monitoring-remote-systems.md#high-availability-db-ido). Defaults to "true".
 898   failover_timeout | **Optional.** Set the failover timeout in a [HA cluster](5-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.
 901
 902 Cleanup Items:
 903
 904   Name            | Description
 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).
 921
 922 Data Categories:
 923
 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
 940
 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.
 944
 945 External interfaces like Icinga Web require everything except `DbCatCheck`
 946 which is the default value if `categories` is not set.
 947
 948 ## <a id="objecttype-livestatuslistener"></a> LiveStatusListener
 949
 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.
 953
 954 Example:
 955
 956     library "livestatus"
 957
 958     object LivestatusListener "livestatus-tcp" {
 959       socket_type = "tcp"
 960       bind_host = "127.0.0.1"
 961       bind_port = "6558"
 962     }
 963
 964     object LivestatusListener "livestatus-unix" {
 965       socket_type = "unix"
 966       socket_path = "/var/run/icinga2/cmd/livestatus"
 967     }
 968
 969 Attributes:
 970
 971   Name            |Description
 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"
 978
 979 > **Note**
 980 >
 981 > UNIX sockets are not supported on Windows.
 982
 983 ## <a id="objecttype-statusdatawriter"></a> StatusDataWriter
 984
 985 Periodically writes status data files which are used by the Classic UI and other third-party tools.
 986
 987 Example:
 988
 989     library "compat"
 990
 991     object StatusDataWriter "status" {
 992         status_path = "/var/cache/icinga2/status.dat"
 993         objects_path = "/var/cache/icinga2/objects.cache"
 994         update_interval = 30s
 995     }
 996
 997 Attributes:
 998
 999   Name            |Description
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.
1004
1005
1006 ## <a id="objecttype-externalcommandlistener"></a> ExternalCommandListener
1007
1008 Implements the Icinga 1.x command pipe which can be used to send commands to Icinga.
1009
1010 Example:
1011
1012     library "compat"
1013
1014     object ExternalCommandListener "external" {
1015         command_path = "/var/run/icinga2/cmd/icinga2.cmd"
1016     }
1017
1018 Attributes:
1019
1020   Name            |Description
1021   ----------------|----------------
1022   command\_path   |**Optional.** Path to the command pipe. Defaults to RunDir + "/icinga2/cmd/icinga2.cmd".
1023
1024 ## <a id="objecttype-compatlogger"></a> CompatLogger
1025
1026 Writes log files in a format that's compatible with Icinga 1.x.
1027
1028 Example:
1029
1030     library "compat"
1031
1032     object CompatLogger "my-log" {
1033       log_dir = "/var/log/icinga2/compat"
1034       rotation_method = "HOURLY"
1035     }
1036
1037 Attributes:
1038
1039   Name            |Description
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".
1043
1044
1045 ## <a id="objecttype-checkresultreader"></a> CheckResultReader
1046
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
1049 scenarios.
1050
1051 Example:
1052
1053     library "compat"
1054
1055     object CheckResultReader "reader" {
1056       spool_dir = "/data/check-results"
1057     }
1058
1059 Attributes:
1060
1061   Name            |Description
1062   ----------------|----------------
1063   spool\_dir      |**Optional.** The directory which contains the check result files. Defaults to LocalStateDir + "/lib/icinga2/spool/checkresults/".
1064
1065
1066 ## <a id="objecttype-checkcomponent"></a> CheckerComponent
1067
1068 The checker component is responsible for scheduling active checks. There are no configurable options.
1069
1070 Example:
1071
1072     library "checker"
1073
1074     object CheckerComponent "checker" { }
1075
1076
1077 ## <a id="objecttype-notificationcomponent"></a> NotificationComponent
1078
1079 The notification component is responsible for sending notifications. There are no configurable options.
1080
1081 Example:
1082
1083     library "notification"
1084
1085     object NotificationComponent "notification" { }
1086
1087 Attributes:
1088
1089   Name            |Description
1090   ----------------|----------------
1091   enable_ha       |**Optional.** Enable the high availability functionality. Only valid in a [cluster setup](#high-availability). Defaults to "true".
1092
1093
1094 ## <a id="objecttype-filelogger"></a> FileLogger
1095
1096 Specifies Icinga 2 logging to a file.
1097
1098 Example:
1099
1100     object FileLogger "debug-file" {
1101       severity = "debug"
1102       path = "/var/log/icinga2/debug.log"
1103     }
1104
1105 Attributes:
1106
1107   Name            |Description
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".
1111
1112
1113 ## <a id="objecttype-sysloglogger"></a> SyslogLogger
1114
1115 Specifies Icinga 2 logging to syslog.
1116
1117 Example:
1118
1119     object SyslogLogger "crit-syslog" {
1120       severity = "critical"
1121     }
1122
1123 Attributes:
1124
1125   Name            |Description
1126   ----------------|----------------
1127   severity        |**Optional.** The minimum severity for this log. Can be "debug", "notice", "information", "notice", "warning" or "critical". Defaults to "warning".
1128
1129
1130
1131 ## <a id="objecttype-icingastatuswriter"></a> IcingaStatusWriter
1132
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.
1136
1137 Example:
1138
1139     object IcingaStatusWriter "status" {
1140       status_path = LocalStateDir + "/cache/icinga2/status.json"
1141       update_interval = 15s
1142     }
1143
1144 Attributes:
1145
1146   Name                      |Description
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.
1150
1151
1152 ## <a id="objecttype-apilistener"></a> ApiListener
1153
1154 ApiListener objects are used for distributed monitoring setups
1155 specifying the certificate files used for ssl authorization.
1156
1157 The `NodeName` constant must be defined in [constants.conf](4-configuring-icinga-2.md#constants-conf).
1158
1159 Example:
1160
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"
1165     }
1166
1167
1168 Attributes:
1169
1170   Name                      |Description
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`.
1180
1181
1182 ## <a id="objecttype-endpoint"></a> Endpoint
1183
1184 Endpoint objects are used to specify connection information for remote
1185 Icinga 2 instances.
1186
1187 Example:
1188
1189     object Endpoint "icinga2b" {
1190       host = "192.168.5.46"
1191       port = 5665
1192     }
1193
1194 Attributes:
1195
1196   Name            |Description
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`.
1201
1202
1203 ## <a id="objecttype-zone"></a> Zone
1204
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).
1207
1208 Example:
1209
1210     object Zone "config-ha-master" {
1211       endpoints = [ "icinga2a", "icinga2b" ]
1212
1213     }
1214
1215     object Zone "check-satellite" {
1216       endpoints = [ "icinga2c" ]
1217       parent = "config-ha-master"
1218     }
1219
1220 Attributes:
1221
1222   Name            |Description
1223   ----------------|----------------
1224   endpoints       |**Optional.** Dictionary with endpoints located in this zone.
1225   parent          |**Optional.** The name of the parent zone.
1226