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

   1 # Config Object Types <a id="object-types"></a>
   2
   3 This chapter provides an overview of all available config object types which can be
   4 instantiated using the `object` keyword.
   5
   6 Additional details on configuration and runtime attributes and their
   7 description are explained as well.
   8
   9 Config objects share these runtime attributes which cannot be
  10 modified by the user. You can access these attributes using
  11 the [Icinga 2 API](12-icinga2-api.md#icinga2-api-config-objects).
  12
  13   Name                      |Description
  14   --------------------------|--------------------------
  15   version                   | Timestamp when the object was created or modified. Synced throughout cluster nodes.
  16   type                      | Object type.
  17   original_attributes       | Original values of object attributes modified at runtime.
  18   active                    | Object is active (e.g. a service being checked).
  19   paused                    | Object has been paused at runtime (e.g. [IdoMysqlConnection](09-object-types.md#objecttype-idomysqlconnection). Defaults to `false`.
  20   templates                 | Templates imported on object compilation.
  21   package                   | [Configuration package name](12-icinga2-api.md#icinga2-api-config-management) this object belongs to. Local configuration is set to `_etc`, runtime created objects use `_api`.
  22
  23
  24 ## ApiListener <a id="objecttype-apilistener"></a>
  25
  26 ApiListener objects are used for distributed monitoring setups
  27 and API usage specifying the certificate files used for ssl
  28 authorization and additional restrictions.
  29
  30 The `NodeName` constant must be defined in [constants.conf](04-configuring-icinga-2.md#constants-conf).
  31
  32 Example:
  33
  34 ```
  35 object ApiListener "api" {
  36   cert_path = LocalStateDir + "/lib/icinga2/certs/" + NodeName + ".crt"
  37   key_path = LocalStateDir + "/lib/icinga2/certs/" + NodeName + ".key"
  38   ca_path = LocalStateDir + "/lib/icinga2/certs/ca.crt"
  39
  40   ticket_salt = TicketSalt
  41 }
  42 ```
  43
  44 Configuration Attributes:
  45
  46   Name                      |Description
  47   --------------------------|--------------------------
  48   cert\_path                |**Required.** Path to the public key.
  49   key\_path                 |**Required.** Path to the private key.
  50   ca\_path                  |**Required.** Path to the CA certificate file.
  51   ticket\_salt              |**Optional.** Private key for auto-signing. **Required** for a signing master instance.
  52   crl\_path                 |**Optional.** Path to the CRL file.
  53   bind\_host                |**Optional.** The IP address the api listener should be bound to. Defaults to `0.0.0.0`.
  54   bind\_port                |**Optional.** The port the api listener should be bound to. Defaults to `5665`.
  55   accept\_config            |**Optional.** Accept zone configuration. Defaults to `false`.
  56   accept\_commands          |**Optional.** Accept remote commands. Defaults to `false`.
  57   cipher\_list              |**Optional.** Cipher list that is allowed.
  58   tls\_protocolmin          |**Optional.** Minimum TLS protocol version. Must be one of `TLSv1`, `TLSv1.1` or `TLSv1.2`. Defaults to `TLSv1`.
  59
  60 ## ApiUser <a id="objecttype-apiuser"></a>
  61
  62 ApiUser objects are used for authentication against the Icinga 2 API.
  63
  64 Example:
  65
  66     object ApiUser "root" {
  67       password = "mysecretapipassword"
  68       permissions = [ "*" ]
  69     }
  70
  71
  72 Configuration Attributes:
  73
  74   Name                      |Description
  75   --------------------------|--------------------------
  76   password                  |**Optional.** Password string.
  77   client\_cn                |**Optional.** Client Common Name (CN).
  78   permissions               |**Required.** Array of permissions. Either as string or dictionary with the keys `permission` and `filter`. The latter must be specified as function.
  79
  80 Available permissions are described in the [API permissions](12-icinga2-api.md#icinga2-api-permissions)
  81 chapter.
  82
  83 ## CheckCommand <a id="objecttype-checkcommand"></a>
  84
  85 A check command definition. Additional default command custom attributes can be
  86 defined here.
  87
  88 > **Note**
  89 >
  90 > Icinga 2 versions < 2.6.0 require the import of the [plugin-check-command](10-icinga-template-library.md#itl-plugin-check-command) template.
  91
  92 Example:
  93
  94     object CheckCommand "check_http" {
  95       command = [ PluginDir + "/check_http" ]
  96
  97       arguments = {
  98         "-H" = "$http_vhost$"
  99         "-I" = "$http_address$"
 100         "-u" = "$http_uri$"
 101         "-p" = "$http_port$"
 102         "-S" = {
 103           set_if = "$http_ssl$"
 104         }
 105         "--sni" = {
 106           set_if = "$http_sni$"
 107         }
 108         "-a" = {
 109           value = "$http_auth_pair$"
 110           description = "Username:password on sites with basic authentication"
 111         }
 112         "--no-body" = {
 113           set_if = "$http_ignore_body$"
 114         }
 115         "-r" = "$http_expect_body_regex$"
 116         "-w" = "$http_warn_time$"
 117         "-c" = "$http_critical_time$"
 118         "-e" = "$http_expect$"
 119       }
 120
 121       vars.http_address = "$address$"
 122       vars.http_ssl = false
 123       vars.http_sni = false
 124     }
 125
 126
 127 Configuration Attributes:
 128
 129   Name            |Description
 130   ----------------|----------------
 131   execute         |**Required.** The "execute" script method takes care of executing the check. The default template "plugin-check-command" which is imported into all CheckCommand objects takes care of this setting.
 132   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. Can be specified as function for advanced implementations.
 133   env             |**Optional.** A dictionary of macros which should be exported as environment variables prior to executing the command.
 134   vars            |**Optional.** A dictionary containing custom attributes that are specific to this command.
 135   timeout         |**Optional.** The command timeout in seconds. Defaults to 60 seconds.
 136   arguments       |**Optional.** A dictionary of command arguments.
 137
 138
 139 ### CheckCommand Arguments <a id="objecttype-checkcommand-arguments"></a>
 140
 141 Command arguments can be defined as key-value-pairs in the `arguments`
 142 dictionary. If the argument requires additional configuration, for example
 143 a `description` attribute or an optional condition, the value can be defined
 144 as dictionary specifying additional options.
 145
 146 Service:
 147
 148     vars.x_val = "My command argument value."
 149     vars.have_x = "true"
 150
 151 CheckCommand:
 152
 153     arguments = {
 154       "-X" = {
 155         value = "$x_val$"
 156         key = "-Xnew"       /* optional, set a new key identifier */
 157         description = "My plugin requires this argument for doing X."
 158         required = false    /* optional, no error if not set */
 159         skip_key = false    /* always use "-X <value>" */
 160         set_if = "$have_x$" /* only set if variable defined and resolves to a numeric value. String values are not supported */
 161         order = -1          /* first position */
 162         repeat_key = true   /* if `value` is an array, repeat the key as parameter: ... 'key' 'value[0]' 'key' 'value[1]' 'key' 'value[2]' ... */
 163       }
 164       "-Y" = {
 165         value = "$y_val$"
 166         description = "My plugin requires this argument for doing Y."
 167         required = false    /* optional, no error if not set */
 168         skip_key = true     /* don't prefix "-Y" only use "<value>" */
 169         set_if = "$have_y$" /* only set if variable defined and resolves to a numeric value. String values are not supported */
 170         order = 0           /* second position */
 171         repeat_key = false  /* if `value` is an array, do not repeat the key as parameter: ... 'key' 'value[0]' 'value[1]' 'value[2]' ... */
 172       }
 173     }
 174
 175   Option      | Description
 176   ------------|--------------
 177   value       | Optional argument value set by a macro string or a function call.
 178   key         | Optional argument key overriding the key identifier.
 179   description | Optional argument description.
 180   required    | Required argument. Execution error if not set. Defaults to false (optional).
 181   skip_key    | Use the value as argument and skip the key.
 182   set_if      | Argument is added if the macro resolves to a defined numeric or boolean value. String values are not supported. Function calls returning a value are supported too.
 183   order       | Set if multiple arguments require a defined argument order.
 184   repeat_key  | If the argument value is an array, repeat the argument key, or not. Defaults to true (repeat).
 185
 186 Argument order:
 187
 188     `..., -3, -2, -1, <un-ordered keys>, 1, 2, 3, ...`
 189
 190 Argument array `repeat_key = true`:
 191
 192     `'key' 'value[0]' 'key' 'value[1]' 'key' 'value[2]'`
 193
 194 Argument array `repeat_key = false`:
 195
 196     `'key' 'value[0]' 'value[1]' 'value[2]'`
 197
 198 ## CheckerComponent <a id="objecttype-checkcomponent"></a>
 199
 200 The checker component is responsible for scheduling active checks.
 201
 202 Example:
 203
 204     library "checker"
 205
 206     object CheckerComponent "checker" {
 207       concurrent_checks = 512
 208     }
 209
 210 Configuration Attributes:
 211
 212   Name                |Description
 213   --------------------|----------------
 214   concurrent\_checks  |**Optional.** The maximum number of concurrent checks. Defaults to 512.
 215
 216 ## CheckResultReader <a id="objecttype-checkresultreader"></a>
 217
 218 Reads Icinga 1.x check results from a directory. This functionality is provided
 219 to help existing Icinga 1.x users and might be useful for certain cluster
 220 scenarios.
 221
 222 Example:
 223
 224     library "compat"
 225
 226     object CheckResultReader "reader" {
 227       spool_dir = "/data/check-results"
 228     }
 229
 230 Configuration Attributes:
 231
 232   Name            |Description
 233   ----------------|----------------
 234   spool\_dir      |**Optional.** The directory which contains the check result files. Defaults to LocalStateDir + "/lib/icinga2/spool/checkresults/".
 235
 236 ## Comment <a id="objecttype-comment"></a>
 237
 238 Comments created at runtime are represented as objects.
 239
 240 Example:
 241
 242     object Comment "localhost!my-comment" {
 243       host_name = "localhost"
 244       author = "icingaadmin"
 245       text = "This is a comment."
 246     }
 247
 248 Configuration Attributes:
 249
 250   Name            |Description
 251   ----------------|----------------
 252   host_name       | **Required.** The name of the host this comment belongs to.
 253   service_name    | **Optional.** The short name of the service this comment belongs to. If omitted, this comment object is treated as host comment.
 254   author          | **Required.** The author's name.
 255   text            | **Required.** The comment text.
 256   entry_time      | **Optional.** The unix timestamp when this comment was added.
 257   entry_type      | **Optional.** The comment type (`User` = 1, `Downtime` = 2, `Flapping` = 3, `Acknowledgement` = 4).
 258   expire_time     | **Optional.** The comment's expire time as unix timestamp.
 259   persistent      | **Optional.** Only evaluated for `entry_type` Acknowledgement. `true` does not remove the comment when the acknowledgement is removed.
 260
 261 ## CompatLogger <a id="objecttype-compatlogger"></a>
 262
 263 Writes log files in a format that's compatible with Icinga 1.x.
 264
 265 Example:
 266
 267     library "compat"
 268
 269     object CompatLogger "my-log" {
 270       log_dir = "/var/log/icinga2/compat"
 271       rotation_method = "HOURLY"
 272     }
 273
 274 Configuration Attributes:
 275
 276   Name            |Description
 277   ----------------|----------------
 278   log\_dir        |**Optional.** Path to the compat log directory. Defaults to LocalStateDir + "/log/icinga2/compat".
 279   rotation\_method|**Optional.** Specifies when to rotate log files. Can be one of "HOURLY", "DAILY", "WEEKLY" or "MONTHLY". Defaults to "HOURLY".
 280
 281
 282
 283 ## Dependency <a id="objecttype-dependency"></a>
 284
 285 Dependency objects are used to specify dependencies between hosts and services. Dependencies
 286 can be defined as Host-to-Host, Service-to-Service, Service-to-Host, or Host-to-Service
 287 relations.
 288
 289 > **Best Practice**
 290 >
 291 > Rather than creating a `Dependency` object for a specific host or service it is usually easier
 292 > to just create a `Dependency` template and use the `apply` keyword to assign the
 293 > dependency to a number of hosts or services. Use the `to` keyword to set the specific target
 294 > type for `Host` or `Service`.
 295 > Check the [dependencies](03-monitoring-basics.md#dependencies) chapter for detailed examples.
 296
 297 Service-to-Service Example:
 298
 299     object Dependency "webserver-internet" {
 300       parent_host_name = "internet"
 301       parent_service_name = "ping4"
 302
 303       child_host_name = "webserver"
 304       child_service_name = "ping4"
 305
 306       states = [ OK, Warning ]
 307
 308       disable_checks = true
 309     }
 310
 311 Host-to-Host Example:
 312
 313     object Dependency "webserver-internet" {
 314       parent_host_name = "internet"
 315
 316       child_host_name = "webserver"
 317
 318       states = [ Up ]
 319
 320       disable_checks = true
 321     }
 322
 323 Configuration Attributes:
 324
 325   Name                  |Description
 326   ----------------------|----------------
 327   parent_host_name      |**Required.** The parent host.
 328   parent_service_name   |**Optional.** The parent service. If omitted, this dependency object is treated as host dependency.
 329   child_host_name       |**Required.** The child host.
 330   child_service_name    |**Optional.** The child service. If omitted, this dependency object is treated as host dependency.
 331   disable_checks        |**Optional.** Whether to disable checks when this dependency fails. Defaults to false.
 332   disable_notifications |**Optional.** Whether to disable notifications when this dependency fails. Defaults to true.
 333   ignore_soft_states    |**Optional.** Whether to ignore soft states for the reachability calculation. Defaults to true.
 334   period                |**Optional.** Time period during which this dependency is enabled.
 335   states                |**Optional.** A list of state filters when this dependency should be OK. Defaults to [ OK, Warning ] for services and [ Up ] for hosts.
 336
 337 Available state filters:
 338
 339     OK
 340     Warning
 341     Critical
 342     Unknown
 343     Up
 344     Down
 345
 346 When using [apply rules](03-monitoring-basics.md#using-apply) for dependencies, you can leave out certain attributes which will be
 347 automatically determined by Icinga 2.
 348
 349 Service-to-Host Dependency Example:
 350
 351     apply Dependency "internet" to Service {
 352       parent_host_name = "dsl-router"
 353       disable_checks = true
 354
 355       assign where host.name != "dsl-router"
 356     }
 357
 358 This example sets all service objects matching the assign condition into a dependency relation to
 359 the parent host object `dsl-router` as implicit child services.
 360
 361 Service-to-Service-on-the-same-Host Dependency Example:
 362
 363     apply Dependency "disable-nrpe-checks" to Service {
 364       parent_service_name = "nrpe-health"
 365
 366       assign where service.check_command == "nrpe"
 367       ignore where service.name == "nrpe-health"
 368     }
 369
 370 This example omits the `parent_host_name` attribute and Icinga 2 automatically sets its value to the name of the
 371 host object matched by the apply rule condition. All services where apply matches are made implicit child services
 372 in this dependency relation.
 373
 374
 375 Dependency objects have composite names, i.e. their names are based on the `child_host_name` and `child_service_name` attributes and the
 376 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
 377 `child_service_name` attributes has a different value.
 378
 379 ## Downtime <a id="objecttype-downtime"></a>
 380
 381 Downtimes created at runtime are represented as objects.
 382
 383 Example:
 384
 385     object Downtime "localhost!my-downtime" {
 386       host_name = "localhost"
 387       author = "icingaadmin"
 388       comment = "This is a downtime."
 389       start_time = 1505312869
 390       end_time = 1505312924
 391     }
 392
 393 Configuration Attributes:
 394
 395   Name            |Description
 396   ----------------|----------------
 397   host_name       | **Required.** The name of the host this comment belongs to.
 398   service_name    | **Optional.** The short name of the service this comment belongs to. If omitted, this comment object is treated as host comment.
 399   author          | **Required.** The author's name.
 400   comment         | **Required.** The comment text.
 401   start_time      | **Required.** The start time as unix timestamp.
 402   end_time        | **Required.** The end time as unix timestamp.
 403   duration        | **Optional.** The duration as number.
 404   entry_time      | **Optional.** The unix timestamp when this downtime was added.
 405   fixed           | **Optional.** Whether the downtime is fixed (true) or flexible (false). Defaults to flexible. Details in the [advanced topics chapter](08-advanced-topics.md#fixed-flexible-downtimes).
 406   triggers        | **Optional.** List of downtimes which should be triggered by this downtime.
 407
 408 Runtime Attributes:
 409
 410   Name            |Description
 411   ----------------|----------------
 412   trigger_time    | The unix timestamp when this downtime was triggered.
 413   triggered_by    | The name of the downtime this downtime was triggered by.
 414
 415
 416
 417 ## Endpoint <a id="objecttype-endpoint"></a>
 418
 419 Endpoint objects are used to specify connection information for remote
 420 Icinga 2 instances.
 421
 422 Example:
 423
 424     object Endpoint "icinga2b" {
 425       host = "192.168.5.46"
 426       port = 5665
 427       log_duration = 1d
 428     }
 429
 430 Example (disable replay log):
 431
 432     object Endpoint "icinga2b" {
 433       host = "192.168.5.46"
 434       port = 5665
 435       log_duration = 0
 436     }
 437
 438 Configuration Attributes:
 439
 440   Name            |Description
 441   ----------------|----------------
 442   host            |**Optional.** The hostname/IP address of the remote Icinga 2 instance.
 443   port            |**Optional.** The service name/port of the remote Icinga 2 instance. Defaults to `5665`.
 444   log_duration    |**Optional.** Duration for keeping replay logs on connection loss. Defaults to `1d` (86400 seconds). Attribute is specified in seconds. If log_duration is set to 0, replaying logs is disabled. You could also specify the value in human readable format like `10m` for 10 minutes or `1h` for one hour.
 445
 446 Endpoint objects cannot currently be created with the API.
 447
 448 ## EventCommand <a id="objecttype-eventcommand"></a>
 449
 450 An event command definition.
 451
 452 > **Note**
 453 >
 454 > Icinga 2 versions < 2.6.0 require the import of the [plugin-event-command](10-icinga-template-library.md#itl-plugin-event-command) template.
 455
 456 Example:
 457
 458     object EventCommand "restart-httpd-event" {
 459       command = "/opt/bin/restart-httpd.sh"
 460     }
 461
 462
 463 Configuration Attributes:
 464
 465   Name            |Description
 466   ----------------|----------------
 467   execute         |**Required.** The "execute" script method takes care of executing the event handler. The default template "plugin-event-command" which is imported into all CheckCommand objects takes care of this setting.
 468   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.
 469   env             |**Optional.** A dictionary of macros which should be exported as environment variables prior to executing the command.
 470   vars            |**Optional.** A dictionary containing custom attributes that are specific to this command.
 471   timeout         |**Optional.** The command timeout in seconds. Defaults to 60 seconds.
 472   arguments       |**Optional.** A dictionary of command arguments.
 473
 474 Command arguments can be used the same way as for [CheckCommand objects](09-object-types.md#objecttype-checkcommand-arguments).
 475
 476 More advanced examples for event command usage can be found [here](03-monitoring-basics.md#event-commands).
 477
 478 ## ExternalCommandListener <a id="objecttype-externalcommandlistener"></a>
 479
 480 Implements the Icinga 1.x command pipe which can be used to send commands to Icinga.
 481
 482 Example:
 483
 484     library "compat"
 485
 486     object ExternalCommandListener "external" {
 487         command_path = "/var/run/icinga2/cmd/icinga2.cmd"
 488     }
 489
 490 Configuration Attributes:
 491
 492   Name            |Description
 493   ----------------|----------------
 494   command\_path   |**Optional.** Path to the command pipe. Defaults to RunDir + "/icinga2/cmd/icinga2.cmd".
 495
 496
 497
 498 ## FileLogger <a id="objecttype-filelogger"></a>
 499
 500 Specifies Icinga 2 logging to a file.
 501
 502 Example:
 503
 504     object FileLogger "debug-file" {
 505       severity = "debug"
 506       path = "/var/log/icinga2/debug.log"
 507     }
 508
 509 Configuration Attributes:
 510
 511   Name            |Description
 512   ----------------|----------------
 513   path            |**Required.** The log path.
 514   severity        |**Optional.** The minimum severity for this log. Can be "debug", "notice", "information", "warning" or "critical". Defaults to "information".
 515
 516
 517 ## GelfWriter <a id="objecttype-gelfwriter"></a>
 518
 519 Writes event log entries to a defined GELF receiver host (Graylog2, Logstash).
 520
 521 Example:
 522
 523     library "perfdata"
 524
 525     object GelfWriter "gelf" {
 526       host = "127.0.0.1"
 527       port = 12201
 528     }
 529
 530 Configuration Attributes:
 531
 532   Name                  |Description
 533   ----------------------|----------------------
 534   host                  |**Optional.** GELF receiver host address. Defaults to '127.0.0.1'.
 535   port                  |**Optional.** GELF receiver port. Defaults to `12201`.
 536   source                |**Optional.** Source name for this instance. Defaults to `icinga2`.
 537   enable_send_perfdata  |**Optional.** Enable performance data for 'CHECK RESULT' events.
 538
 539
 540 ## GraphiteWriter <a id="objecttype-graphitewriter"></a>
 541
 542 Writes check result metrics and performance data to a defined
 543 Graphite Carbon host.
 544
 545 Example:
 546
 547     library "perfdata"
 548
 549     object GraphiteWriter "graphite" {
 550       host = "127.0.0.1"
 551       port = 2003
 552     }
 553
 554 Configuration Attributes:
 555
 556   Name                  |Description
 557   ----------------------|----------------------
 558   host                  |**Optional.** Graphite Carbon host address. Defaults to '127.0.0.1'.
 559   port                  |**Optional.** Graphite Carbon port. Defaults to 2003.
 560   host_name_template    |**Optional.** Metric prefix for host name. Defaults to "icinga2.$host.name$.host.$host.check_command$".
 561   service_name_template |**Optional.** Metric prefix for service name. Defaults to "icinga2.$host.name$.services.$service.name$.$service.check_command$".
 562   enable_send_thresholds | **Optional.** Send additional threshold metrics. Defaults to `false`.
 563   enable_send_metadata  | **Optional.** Send additional metadata metrics. Defaults to `false`.
 564
 565 Additional usage examples can be found [here](14-features.md#graphite-carbon-cache-writer).
 566
 567
 568
 569 ## Host <a id="objecttype-host"></a>
 570
 571 A host.
 572
 573 Example:
 574
 575     object Host NodeName {
 576       display_name = "Local host on this node"
 577       address = "127.0.0.1"
 578       address6 = "::1"
 579
 580       groups = [ "all-hosts" ]
 581
 582       check_command = "hostalive"
 583     }
 584
 585 Configuration Attributes:
 586
 587   Name            |Description
 588   ----------------|----------------
 589   display_name    |**Optional.** A short description of the host (e.g. displayed by external interfaces instead of the name if set).
 590   address         |**Optional.** The host's address. Available as command runtime macro `$address$` if set.
 591   address6        |**Optional.** The host's address. Available as command runtime macro `$address6$` if set.
 592   groups          |**Optional.** A list of host groups this host belongs to.
 593   vars            |**Optional.** A dictionary containing custom attributes that are specific to this host.
 594   check\_command  |**Required.** The name of the check command.
 595   max\_check\_attempts|**Optional.** The number of times a host is re-checked before changing into a hard state. Defaults to 3.
 596   check\_period   |**Optional.** The name of a time period which determines when this host should be checked. Not set by default.
 597   check\_timeout  |**Optional.** Check command timeout in seconds. Overrides the CheckCommand's `timeout` attribute.
 598   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.
 599   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.
 600   enable\_notifications|**Optional.** Whether notifications are enabled. Defaults to true.
 601   enable\_active\_checks|**Optional.** Whether active checks are enabled. Defaults to true.
 602   enable\_passive\_checks|**Optional.** Whether passive checks are enabled. Defaults to true.
 603   enable\_event\_handler|**Optional.** Enables event handlers for this host. Defaults to true.
 604   enable\_flapping|**Optional.** Whether flap detection is enabled. Defaults to false.
 605   enable\_perfdata|**Optional.** Whether performance data processing is enabled. Defaults to true.
 606   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.
 607   flapping\_threshold|**Optional.** The flapping threshold in percent when a host is considered to be flapping.
 608   volatile        |**Optional.** The volatile setting enables always `HARD` state types if `NOT-OK` state changes occur.
 609   zone            |**Optional.** The zone this object is a member of.
 610   command\_endpoint|**Optional.** The endpoint where commands are executed on.
 611   notes           |**Optional.** Notes for the host.
 612   notes\_url      |**Optional.** Url for notes for the host (for example, in notification commands).
 613   action\_url     |**Optional.** Url for actions for the host (for example, an external graphing tool).
 614   icon\_image     |**Optional.** Icon image for the host. Used by external interfaces only.
 615   icon\_image\_alt|**Optional.** Icon image description for the host. Used by external interface only.
 616
 617 The actual check interval might deviate slightly from the configured values due to the fact that Icinga tries
 618 to evenly distribute all checks over a certain period of time, i.e. to avoid load spikes.
 619
 620 > **Best Practice**
 621 >
 622 > The `address` and `address6` attributes are required for running commands using
 623 > the `$address$` and `$address6$` runtime macros.
 624
 625 Runtime Attributes:
 626
 627   Name                      | Type          | Description
 628   --------------------------|---------------|-----------------
 629   next\_check               | Number        | When the next check occurs (as a UNIX timestamp).
 630   last\_check               | Number        | When the last check occured (as a UNIX timestamp).
 631   check\_attempt            | Number        | The current check attempt number.
 632   state\_type               | Number        | The current state type (0 = SOFT, 1 = HARD).
 633   last\_state\_type         | Number        | The previous state type (0 = SOFT, 1 = HARD).
 634   last\_reachable           | Boolean       | Whether the host was reachable when the last check occurred.
 635   last\_check\_result       | CheckResult   | The current check result.
 636   last\_state\_change       | Number        | When the last state change occurred (as a UNIX timestamp).
 637   last\_hard\_state\_change | Number        | When the last hard state change occurred (as a UNIX timestamp).
 638   last\_in\_downtime        | Boolean       | Whether the host was in a downtime when the last check occurred.
 639   acknowledgement           | Number        | The acknowledgement type (0 = NONE, 1 = NORMAL, 2 = STICKY).
 640   acknowledgement_expiry    | Number        | When the acknowledgement expires (as a UNIX timestamp; 0 = no expiry).
 641   downtime\_depth           | Number        | Whether the host has one or more active downtimes.
 642   flapping_last_change      | Number        | When the last flapping change occurred (as a UNIX timestamp).
 643   flapping                  | Boolean       | Whether the host is flapping between states.
 644   state                     | Number        | The current state (0 = UP, 1 = DOWN).
 645   last\_state               | Number        | The previous state (0 = UP, 1 = DOWN).
 646   last\_hard\_state         | Number        | The last hard state (0 = UP, 1 = DOWN).
 647   last_state_up             | Number        | When the last UP state occurred (as a UNIX timestamp).
 648   last_state_down           | Number        | When the last DOWN state occurred (as a UNIX timestamp).
 649
 650
 651
 652 ## HostGroup <a id="objecttype-hostgroup"></a>
 653
 654 A group of hosts.
 655
 656 > **Best Practice**
 657 >
 658 > Assign host group members using the [group assign](17-language-reference.md#group-assign) rules.
 659
 660 Example:
 661
 662     object HostGroup "my-hosts" {
 663       display_name = "My hosts"
 664     }
 665
 666 Configuration Attributes:
 667
 668   Name            |Description
 669   ----------------|----------------
 670   display_name    |**Optional.** A short description of the host group.
 671   groups          |**Optional.** An array of nested group names.
 672
 673 ## IcingaApplication <a id="objecttype-icingaapplication"></a>
 674
 675 The IcingaApplication object is required to start Icinga 2.
 676 The object name must be `app`. If the object configuration
 677 is missing, Icinga 2 will automatically create an IcingaApplication
 678 object.
 679
 680 Example:
 681
 682     object IcingaApplication "app" {
 683       enable_perfdata = false
 684     }
 685
 686 Configuration Attributes:
 687
 688   Name                  |Description
 689   ----------------------|--------------------------
 690   enable_notifications  |**Optional.** Whether notifications are globally enabled. Defaults to true.
 691   enable_event_handlers |**Optional.** Whether event handlers are globally enabled. Defaults to true.
 692   enable_flapping       |**Optional.** Whether flap detection is globally enabled. Defaults to true.
 693   enable_host_checks    |**Optional.** Whether active host checks are globally enabled. Defaults to true.
 694   enable_service_checks |**Optional.** Whether active service checks are globally enabled. Defaults to true.
 695   enable_perfdata       |**Optional.** Whether performance data processing is globally enabled. Defaults to true.
 696   vars                  |**Optional.** A dictionary containing custom attributes that are available globally.
 697
 698 ## IdoMySqlConnection <a id="objecttype-idomysqlconnection"></a>
 699
 700 IDO database adapter for MySQL.
 701
 702 Example:
 703
 704     library "db_ido_mysql"
 705
 706     object IdoMysqlConnection "mysql-ido" {
 707       host = "127.0.0.1"
 708       port = 3306
 709       user = "icinga"
 710       password = "icinga"
 711       database = "icinga"
 712
 713       cleanup = {
 714         downtimehistory_age = 48h
 715         contactnotifications_age = 31d
 716       }
 717     }
 718
 719 Configuration Attributes:
 720
 721   Name            |Description
 722   ----------------|----------------
 723   host            |**Optional.** MySQL database host address. Defaults to "localhost".
 724   port            |**Optional.** MySQL database port. Defaults to 3306.
 725   socket_path     |**Optional.** MySQL socket path.
 726   user            |**Optional.** MySQL database user with read/write permission to the icinga database. Defaults to "icinga".
 727   password        |**Optional.** MySQL database user's password. Defaults to "icinga".
 728   database        |**Optional.** MySQL database name. Defaults to "icinga".
 729   enable\_ssl     |**Optional.** Use SSL. Defaults to false. Change to `true` in case you want to use any of the SSL options.
 730   ssl\_key        |**Optional.** MySQL SSL client key file path.
 731   ssl\_cert       |**Optional.** MySQL SSL certificate file path.
 732   ssl\_ca         |**Optional.** MySQL SSL certificate authority certificate file path.
 733   ssl\_capath     |**Optional.** MySQL SSL trusted SSL CA certificates in PEM format directory path.
 734   ssl\_cipher     |**Optional.** MySQL SSL list of allowed ciphers.
 735   table\_prefix   |**Optional.** MySQL database table prefix. Defaults to "icinga\_".
 736   instance\_name  |**Optional.** Unique identifier for the local Icinga 2 instance. Defaults to "default".
 737   instance\_description|**Optional.** Description for the Icinga 2 instance.
 738   enable_ha       |**Optional.** Enable the high availability functionality. Only valid in a [cluster setup](06-distributed-monitoring.md#distributed-monitoring-high-availability-db-ido). Defaults to "true".
 739   failover_timeout | **Optional.** Set the failover timeout in a [HA cluster](06-distributed-monitoring.md#distributed-monitoring-high-availability-db-ido). Must not be lower than 60s. Defaults to "60s".
 740   cleanup         |**Optional.** Dictionary with items for historical table cleanup.
 741   categories      |**Optional.** Array of information types that should be written to the database.
 742
 743 Cleanup Items:
 744
 745   Name            | Description
 746   ----------------|----------------
 747   acknowledgements_age |**Optional.** Max age for acknowledgements table rows (entry_time). Defaults to 0 (never).
 748   commenthistory_age |**Optional.** Max age for commenthistory table rows (entry_time). Defaults to 0 (never).
 749   contactnotifications_age |**Optional.** Max age for contactnotifications table rows (start_time). Defaults to 0 (never).
 750   contactnotificationmethods_age |**Optional.** Max age for contactnotificationmethods table rows (start_time). Defaults to 0 (never).
 751   downtimehistory_age |**Optional.** Max age for downtimehistory table rows (entry_time). Defaults to 0 (never).
 752   eventhandlers_age |**Optional.** Max age for eventhandlers table rows (start_time). Defaults to 0 (never).
 753   externalcommands_age |**Optional.** Max age for externalcommands table rows (entry_time). Defaults to 0 (never).
 754   flappinghistory_age |**Optional.** Max age for flappinghistory table rows (event_time). Defaults to 0 (never).
 755   hostchecks_age |**Optional.** Max age for hostalives table rows (start_time). Defaults to 0 (never).
 756   logentries_age |**Optional.** Max age for logentries table rows (logentry_time). Defaults to 0 (never).
 757   notifications_age |**Optional.** Max age for notifications table rows (start_time). Defaults to 0 (never).
 758   processevents_age |**Optional.** Max age for processevents table rows (event_time). Defaults to 0 (never).
 759   statehistory_age |**Optional.** Max age for statehistory table rows (state_time). Defaults to 0 (never).
 760   servicechecks_age |**Optional.** Max age for servicechecks table rows (start_time). Defaults to 0 (never).
 761   systemcommands_age |**Optional.** Max age for systemcommands table rows (start_time). Defaults to 0 (never).
 762
 763 Data Categories:
 764
 765   Name                 | Description            | Required by
 766   ---------------------|------------------------|--------------------
 767   DbCatConfig          | Configuration data     | Icinga Web 2
 768   DbCatState           | Current state data     | Icinga Web 2
 769   DbCatAcknowledgement | Acknowledgements       | Icinga Web 2
 770   DbCatComment         | Comments               | Icinga Web 2
 771   DbCatDowntime        | Downtimes              | Icinga Web 2
 772   DbCatEventHandler    | Event handler data     | Icinga Web 2
 773   DbCatExternalCommand | External commands      | --
 774   DbCatFlapping        | Flap detection data    | Icinga Web 2
 775   DbCatCheck           | Check results          | --
 776   DbCatLog             | Log messages           | --
 777   DbCatNotification    | Notifications          | Icinga Web 2
 778   DbCatProgramStatus   | Program status data    | Icinga Web 2
 779   DbCatRetention       | Retention data         | Icinga Web 2
 780   DbCatStateHistory    | Historical state data  | Icinga Web 2
 781
 782 The default value for `categories` includes everything required
 783 by Icinga Web 2 in the table above.
 784
 785 In addition to the category flags listed above the `DbCatEverything`
 786 flag may be used as a shortcut for listing all flags.
 787
 788 ## IdoPgSqlConnection <a id="objecttype-idopgsqlconnection"></a>
 789
 790 IDO database adapter for PostgreSQL.
 791
 792 Example:
 793
 794     library "db_ido_pgsql"
 795
 796     object IdoPgsqlConnection "pgsql-ido" {
 797       host = "127.0.0.1"
 798       port = 5432
 799       user = "icinga"
 800       password = "icinga"
 801       database = "icinga"
 802
 803       cleanup = {
 804         downtimehistory_age = 48h
 805         contactnotifications_age = 31d
 806       }
 807     }
 808
 809 Configuration Attributes:
 810
 811   Name            |Description
 812   ----------------|----------------
 813   host            |**Optional.** PostgreSQL database host address. Defaults to "localhost".
 814   port            |**Optional.** PostgreSQL database port. Defaults to "5432".
 815   user            |**Optional.** PostgreSQL database user with read/write permission to the icinga database. Defaults to "icinga".
 816   password        |**Optional.** PostgreSQL database user's password. Defaults to "icinga".
 817   database        |**Optional.** PostgreSQL database name. Defaults to "icinga".
 818   table\_prefix   |**Optional.** PostgreSQL database table prefix. Defaults to "icinga\_".
 819   instance\_name  |**Optional.** Unique identifier for the local Icinga 2 instance. Defaults to "default".
 820   instance\_description|**Optional.** Description for the Icinga 2 instance.
 821   enable_ha       |**Optional.** Enable the high availability functionality. Only valid in a [cluster setup](06-distributed-monitoring.md#distributed-monitoring-high-availability-db-ido). Defaults to "true".
 822   failover_timeout | **Optional.** Set the failover timeout in a [HA cluster](06-distributed-monitoring.md#distributed-monitoring-high-availability-db-ido). Must not be lower than 60s. Defaults to "60s".
 823   cleanup         |**Optional.** Dictionary with items for historical table cleanup.
 824   categories      |**Optional.** Array of information types that should be written to the database.
 825
 826 Cleanup Items:
 827
 828   Name            | Description
 829   ----------------|----------------
 830   acknowledgements_age |**Optional.** Max age for acknowledgements table rows (entry_time). Defaults to 0 (never).
 831   commenthistory_age |**Optional.** Max age for commenthistory table rows (entry_time). Defaults to 0 (never).
 832   contactnotifications_age |**Optional.** Max age for contactnotifications table rows (start_time). Defaults to 0 (never).
 833   contactnotificationmethods_age |**Optional.** Max age for contactnotificationmethods table rows (start_time). Defaults to 0 (never).
 834   downtimehistory_age |**Optional.** Max age for downtimehistory table rows (entry_time). Defaults to 0 (never).
 835   eventhandlers_age |**Optional.** Max age for eventhandlers table rows (start_time). Defaults to 0 (never).
 836   externalcommands_age |**Optional.** Max age for externalcommands table rows (entry_time). Defaults to 0 (never).
 837   flappinghistory_age |**Optional.** Max age for flappinghistory table rows (event_time). Defaults to 0 (never).
 838   hostchecks_age |**Optional.** Max age for hostalives table rows (start_time). Defaults to 0 (never).
 839   logentries_age |**Optional.** Max age for logentries table rows (logentry_time). Defaults to 0 (never).
 840   notifications_age |**Optional.** Max age for notifications table rows (start_time). Defaults to 0 (never).
 841   processevents_age |**Optional.** Max age for processevents table rows (event_time). Defaults to 0 (never).
 842   statehistory_age |**Optional.** Max age for statehistory table rows (state_time). Defaults to 0 (never).
 843   servicechecks_age |**Optional.** Max age for servicechecks table rows (start_time). Defaults to 0 (never).
 844   systemcommands_age |**Optional.** Max age for systemcommands table rows (start_time). Defaults to 0 (never).
 845
 846 Data Categories:
 847
 848   Name                 | Description            | Required by
 849   ---------------------|------------------------|--------------------
 850   DbCatConfig          | Configuration data     | Icinga Web 2
 851   DbCatState           | Current state data     | Icinga Web 2
 852   DbCatAcknowledgement | Acknowledgements       | Icinga Web 2
 853   DbCatComment         | Comments               | Icinga Web 2
 854   DbCatDowntime        | Downtimes              | Icinga Web 2
 855   DbCatEventHandler    | Event handler data     | Icinga Web 2
 856   DbCatExternalCommand | External commands      | --
 857   DbCatFlapping        | Flap detection data    | Icinga Web 2
 858   DbCatCheck           | Check results          | --
 859   DbCatLog             | Log messages           | --
 860   DbCatNotification    | Notifications          | Icinga Web 2
 861   DbCatProgramStatus   | Program status data    | Icinga Web 2
 862   DbCatRetention       | Retention data         | Icinga Web 2
 863   DbCatStateHistory    | Historical state data  | Icinga Web 2
 864
 865 The default value for `categories` includes everything required
 866 by Icinga Web 2 in the table above.
 867
 868 In addition to the category flags listed above the `DbCatEverything`
 869 flag may be used as a shortcut for listing all flags.
 870
 871 ## InfluxdbWriter <a id="objecttype-influxdbwriter"></a>
 872
 873 Writes check result metrics and performance data to a defined InfluxDB host.
 874
 875 Example:
 876
 877     library "perfdata"
 878
 879     object InfluxdbWriter "influxdb" {
 880       host = "127.0.0.1"
 881       port = 8086
 882       database = "icinga2"
 883
 884       flush_threshold = 1024
 885       flush_interval = 10s
 886
 887       host_template = {
 888         measurement = "$host.check_command$"
 889         tags = {
 890           hostname = "$host.name$"
 891         }
 892       }
 893       service_template = {
 894         measurement = "$service.check_command$"
 895         tags = {
 896           hostname = "$host.name$"
 897           service = "$service.name$"
 898         }
 899       }
 900     }
 901
 902 Measurement names and tags are fully configurable by the end user. The InfluxdbWriter
 903 object will automatically add a `metric` tag to each data point. This correlates to the
 904 perfdata label. Fields (value, warn, crit, min, max) are created from data if available
 905 and the configuration allows it.  If a value associated with a tag is not able to be
 906 resolved, it will be dropped and not sent to the target host.
 907
 908 Backslashes are allowed in tag keys, tag values and field keys, however they are also
 909 escape characters when followed by a space or comma, but cannot be escaped themselves.
 910 As a result all trailling slashes in these fields are replaced with an underscore.  This
 911 predominantly affects Windows paths e.g. `C:\` becomes `C:_`.
 912
 913 The database is assumed to exist so this object will make no attempt to create it currently.
 914
 915 Configuration Attributes:
 916
 917   Name                   |Description
 918   -----------------------|---------------------------------------------------------------------------------------------------------
 919   host                   | **Required.** InfluxDB host address. Defaults to `127.0.0.1`.
 920   port                   | **Required.** InfluxDB HTTP port. Defaults to `8086`.
 921   database               | **Required.** InfluxDB database name. Defaults to `icinga2`.
 922   username               | **Optional.** InfluxDB user name. Defaults to `none`.
 923   password               | **Optional.** InfluxDB user password.  Defaults to `none`.
 924   ssl_enable             | **Optional.** Whether to use a TLS stream.  Defaults to `false`.
 925   ssl_ca_cert            | **Optional.** CA certificate to validate the remote host.
 926   ssl_cert               | **Optional.** Host certificate to present to the remote host for mutual verification.
 927   ssl_key                | **Optional.** Host key to accompany the ssl_cert
 928   host_template          | **Required.** Host template to define the InfluxDB line protocol.
 929   service_template       | **Required.** Service template to define the influxDB line protocol.
 930   enable_send_thresholds | **Optional.** Whether to send warn, crit, min & max tagged data.
 931   enable_send_metadata   | **Optional.** Whether to send check metadata e.g. states, execution time, latency etc.
 932   flush_interval         | **Optional.** How long to buffer data points before transfering to InfluxDB. Defaults to `10s`.
 933   flush_threshold        | **Optional.** How many data points to buffer before forcing a transfer to InfluxDB.  Defaults to `1024`.
 934
 935 Note: If `flush_threshold` is set too low, this will always force the feature to flush all data
 936 to InfluxDB. Experiment with the setting, if you are processing more than 1024 metrics per second
 937 or similar.
 938
 939 ### Instance Tagging <a id="objecttype-influxdbwriter-instance-tags"></a>
 940
 941 Consider the following service check:
 942
 943     apply Service "disk" for (disk => attributes in host.vars.disks) {
 944       import "generic-service"
 945       check_command = "disk"
 946       display_name = "Disk " + disk
 947       vars.disk_partitions = disk
 948       assign where host.vars.disks
 949     }
 950
 951 This is a typical pattern for checking individual disks, NICs, SSL certificates etc associated
 952 with a host.  What would be useful is to have the data points tagged with the specific instance
 953 for that check.  This would allow you to query time series data for a check on a host and for a
 954 specific instance e.g. /dev/sda.  To do this quite simply add the instance to the service variables:
 955
 956     apply Service "disk" for (disk => attributes in host.vars.disks) {
 957       ...
 958       vars.instance = disk
 959       ...
 960     }
 961
 962 Then modify your writer configuration to add this tag to your data points if the instance variable
 963 is associated with the service:
 964
 965     object InfluxdbWriter "influxdb" {
 966       ...
 967       service_template = {
 968         measurement = "$service.check_command$"
 969         tags = {
 970           hostname = "$host.name$"
 971           service = "$service.name$"
 972           instance = "$service.vars.instance$"
 973         }
 974       }
 975       ...
 976     }
 977
 978 ## ElasticWriter <a id="objecttype-elasticwriter"></a>
 979
 980 Writes check result metrics and performance data to an Elasticsearch instance.
 981
 982 Example:
 983
 984     library "perfdata"
 985
 986     object ElasticWriter "elastic" {
 987       host = "127.0.0.1"
 988       port = 9200
 989       index = "icinga2"
 990
 991       enable_send_perfdata = true
 992
 993       flush_threshold = 1024
 994       flush_interval = 10
 995     }
 996
 997 The index is rotated daily, as is recommended by Elastic, meaning the index will be renamed to `$index-$d.$M.$y`.
 998
 999 Configuration Attributes:
1000
1001   Name                   |Description
1002   -----------------------|---------------------------------------------------------------------------------------------------------
1003   host                   | **Required.** Elasticsearch host address. Defaults to `127.0.0.1`.
1004   port                   | **Required.** Elasticsearch port. Defaults to `9200`.
1005   index                  | **Required.** Elasticsearch index name. Defaults to `icinga2`.
1006   enable\_send\_perfdata | **Optional.** Send parsed performance data metrics for check results. Defaults to `false`.
1007   flush\_interval        | **Optional.** How long to buffer data points before transfering to Elasticsearch. Defaults to `10`.
1008   flush\_threshold       | **Optional.** How many data points to buffer before forcing a transfer to Elasticsearch.  Defaults to `1024`.
1009   username               | **Optional.** Basic auth username if Elasticsearch is hidden behind an HTTP proxy.
1010   password               | **Optional.** Basic auth password if Elasticsearch is hidden behind an HTTP proxy.
1011   enable\_tls            | **Optional.** Whether to use a TLS stream. Defaults to `false`. Requires an HTTP proxy.
1012   ca\_path               | **Optional.** CA certificate to validate the remote host. Requires `enable_tls` set to `true`.
1013   cert\_path             | **Optional.** Host certificate to present to the remote host for mutual verification. Requires `enable_tls` set to `true`.
1014   key\_path              | **Optional.** Host key to accompany the cert\_path. Requires `enable_tls` set to `true`.
1015
1016 Note: If `flush_threshold` is set too low, this will force the feature to flush all data to Elasticsearch too often.
1017 Experiment with the setting, if you are processing more than 1024 metrics per second or similar.
1018
1019 Basic auth is supported with the `username` and `password` attributes. This requires an
1020 HTTP proxy (Nginx, etc.) in front of the Elasticsearch instance.
1021
1022 TLS for the HTTP proxy can be enabled with `enable_tls`. In addition to that
1023 you can specify the certificates with the `ca_path`, `cert_path` and `cert_key` attributes.
1024
1025 ## LiveStatusListener <a id="objecttype-livestatuslistener"></a>
1026
1027 Livestatus API interface available as TCP or UNIX socket. Historical table queries
1028 require the [CompatLogger](09-object-types.md#objecttype-compatlogger) feature enabled
1029 pointing to the log files using the `compat_log_path` configuration attribute.
1030
1031 Example:
1032
1033     library "livestatus"
1034
1035     object LivestatusListener "livestatus-tcp" {
1036       socket_type = "tcp"
1037       bind_host = "127.0.0.1"
1038       bind_port = "6558"
1039     }
1040
1041     object LivestatusListener "livestatus-unix" {
1042       socket_type = "unix"
1043       socket_path = "/var/run/icinga2/cmd/livestatus"
1044     }
1045
1046 Configuration Attributes:
1047
1048   Name            |Description
1049   ----------------|----------------
1050   socket\_type      |**Optional.** Specifies the socket type. Can be either "tcp" or "unix". Defaults to "unix".
1051   bind\_host        |**Optional.** Only valid when socket\_type is "tcp". Host address to listen on for connections. Defaults to "127.0.0.1".
1052   bind\_port        |**Optional.** Only valid when `socket_type` is "tcp". Port to listen on for connections. Defaults to 6558.
1053   socket\_path      |**Optional.** Only valid when `socket_type` is "unix". Specifies the path to the UNIX socket file. Defaults to RunDir + "/icinga2/cmd/livestatus".
1054   compat\_log\_path |**Optional.** Required for historical table queries. Requires `CompatLogger` feature enabled. Defaults to LocalStateDir + "/log/icinga2/compat"
1055
1056 > **Note**
1057 >
1058 > UNIX sockets are not supported on Windows.
1059
1060
1061 ## Notification <a id="objecttype-notification"></a>
1062
1063 Notification objects are used to specify how users should be notified in case
1064 of host and service state changes and other events.
1065
1066 > **Best Practice**
1067 >
1068 > Rather than creating a `Notification` object for a specific host or service it is
1069 > usually easier to just create a `Notification` template and use the `apply` keyword
1070 > to assign the notification to a number of hosts or services. Use the `to` keyword
1071 > to set the specific target type for `Host` or `Service`.
1072 > Check the [notifications](03-monitoring-basics.md#alert-notifications) chapter for detailed examples.
1073
1074 Example:
1075
1076     object Notification "localhost-ping-notification" {
1077       host_name = "localhost"
1078       service_name = "ping4"
1079
1080       command = "mail-notification"
1081
1082       users = [ "user1", "user2" ]
1083
1084       types = [ Problem, Recovery ]
1085     }
1086
1087 Configuration Attributes:
1088
1089   Name                      | Description
1090   --------------------------|----------------
1091   host_name                 | **Required.** The name of the host this notification belongs to.
1092   service_name              | **Optional.** The short name of the service this notification belongs to. If omitted, this notification object is treated as host notification.
1093   vars                      | **Optional.** A dictionary containing custom attributes that are specific to this notification object.
1094   users                     | **Optional.** A list of user names who should be notified.
1095   user_groups               | **Optional.** A list of user group names who should be notified.
1096   times                     | **Optional.** A dictionary containing `begin` and `end` attributes for the notification.
1097   command                   | **Required.** The name of the notification command which should be executed when the notification is triggered.
1098   interval                  | **Optional.** The notification interval (in seconds). This interval is used for active notifications. Defaults to 30 minutes. If set to 0, [re-notifications](03-monitoring-basics.md#disable-renotification) are disabled.
1099   period                    | **Optional.** The name of a time period which determines when this notification should be triggered. Not set by default.
1100   zone                      |**Optional.** The zone this object is a member of.
1101   types                     | **Optional.** A list of type filters when this notification should be triggered. By default everything is matched.
1102   states                    | **Optional.** A list of state filters when this notification should be triggered. By default everything is matched.
1103
1104 Available notification state filters for Service:
1105
1106     OK
1107     Warning
1108     Critical
1109     Unknown
1110
1111 Available notification state filters for Host:
1112
1113     Up
1114     Down
1115
1116 Available notification type filters:
1117
1118     DowntimeStart
1119     DowntimeEnd
1120     DowntimeRemoved
1121     Custom
1122     Acknowledgement
1123     Problem
1124     Recovery
1125     FlappingStart
1126     FlappingEnd
1127
1128 Runtime Attributes:
1129
1130   Name                      | Type          | Description
1131   --------------------------|---------------|-----------------
1132   last\_notification        | Number        | When the last notification was sent for this Notification object (as a UNIX timestamp).
1133   next\_notification         | Number        | When the next notification is going to be sent for this assuming the associated host/service is still in a non-OK state (as a UNIX timestamp).
1134   notification\_number      | Number        | The notification number
1135   last\_problem\_notification | Number      | When the last notification was sent for a problem (as a UNIX timestamp).
1136
1137
1138 ## NotificationCommand <a id="objecttype-notificationcommand"></a>
1139
1140 A notification command definition.
1141
1142 > **Note**
1143 >
1144 > Icinga 2 versions < 2.6.0 require the import of the [plugin-notification-command](10-icinga-template-library.md#itl-plugin-notification-command) template.
1145
1146 Example:
1147
1148      object NotificationCommand "mail-service-notification" {
1149        command = [ SysconfDir + "/icinga2/scripts/mail-service-notification.sh" ]
1150
1151        arguments += {
1152          "-4" = {
1153            required = true
1154            value = "$notification_address$"
1155          }
1156          "-6" = "$notification_address6$"
1157          "-b" = "$notification_author$"
1158          "-c" = "$notification_comment$"
1159          "-d" = {
1160            required = true
1161            value = "$notification_date$"
1162          }
1163          "-e" = {
1164            required = true
1165            value = "$notification_servicename$"
1166          }
1167          "-f" = {
1168            value = "$notification_from$"
1169            description = "Set from address. Requires GNU mailutils (Debian/Ubuntu) or mailx (RHEL/SUSE)"
1170          }
1171          "-i" = "$notification_icingaweb2url$"
1172          "-l" = {
1173            required = true
1174            value = "$notification_hostname$"
1175          }
1176          "-n" = {
1177            required = true
1178            value = "$notification_hostdisplayname$"
1179          }
1180          "-o" = {
1181            required = true
1182            value = "$notification_serviceoutput$"
1183          }
1184          "-r" = {
1185            required = true
1186            value = "$notification_useremail$"
1187          }
1188          "-s" = {
1189            required = true
1190            value = "$notification_servicestate$"
1191          }
1192          "-t" = {
1193            required = true
1194            value = "$notification_type$"
1195          }
1196          "-u" = {
1197            required = true
1198            value = "$notification_servicedisplayname$"
1199          }
1200          "-v" = "$notification_logtosyslog$"
1201        }
1202
1203        vars += {
1204          notification_address = "$address$"
1205          notification_address6 = "$address6$"
1206          notification_author = "$notification.author$"
1207          notification_comment = "$notification.comment$"
1208          notification_type = "$notification.type$"
1209          notification_date = "$icinga.long_date_time$"
1210          notification_hostname = "$host.name$"
1211          notification_hostdisplayname = "$host.display_name$"
1212          notification_servicename = "$service.name$"
1213          notification_serviceoutput = "$service.output$"
1214          notification_servicestate = "$service.state$"
1215          notification_useremail = "$user.email$"
1216          notification_servicedisplayname = "$service.display_name$"
1217        }
1218      }
1219
1220
1221 Configuration Attributes:
1222
1223   Name            |Description
1224   ----------------|----------------
1225   execute         |**Required.** The "execute" script method takes care of executing the notification. The default template "plugin-notification-command" which is imported into all CheckCommand objects takes care of this setting.
1226   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.
1227   env             |**Optional.** A dictionary of macros which should be exported as environment variables prior to executing the command.
1228   vars            |**Optional.** A dictionary containing custom attributes that are specific to this command.
1229   timeout         |**Optional.** The command timeout in seconds. Defaults to 60 seconds.
1230   arguments       |**Optional.** A dictionary of command arguments.
1231
1232 Command arguments can be used the same way as for [CheckCommand objects](09-object-types.md#objecttype-checkcommand-arguments).
1233
1234 More details on specific attributes can be found in [this chapter](03-monitoring-basics.md#notification-commands).
1235
1236 ## NotificationComponent <a id="objecttype-notificationcomponent"></a>
1237
1238 The notification component is responsible for sending notifications. There are no configurable options.
1239
1240 Example:
1241
1242     library "notification"
1243
1244     object NotificationComponent "notification" { }
1245
1246 Configuration Attributes:
1247
1248   Name            |Description
1249   ----------------|----------------
1250   enable\_ha      |**Optional.** Enable the high availability functionality. Only valid in a [cluster setup](06-distributed-monitoring.md#distributed-monitoring-high-availability-notifications). Disabling this currently only affects reminder notifications. Defaults to "true".
1251
1252 ## OpenTsdbWriter <a id="objecttype-opentsdbwriter"></a>
1253
1254 Writes check result metrics and performance data to [OpenTSDB](http://opentsdb.net).
1255
1256 Example:
1257
1258     library "perfdata"
1259
1260     object OpenTsdbWriter "opentsdb" {
1261       host = "127.0.0.1"
1262       port = 4242
1263     }
1264
1265 Configuration Attributes:
1266
1267   Name                  |Description
1268   ----------------------|----------------------
1269   host                  |**Optional.** OpenTSDB host address. Defaults to '127.0.0.1'.
1270   port                  |**Optional.** OpenTSDB port. Defaults to 4242.
1271
1272
1273 ## PerfdataWriter <a id="objecttype-perfdatawriter"></a>
1274
1275 Writes check result performance data to a defined path using macro
1276 pattern consisting of custom attributes and runtime macros.
1277
1278 Example:
1279
1280     library "perfdata"
1281
1282     object PerfdataWriter "pnp" {
1283       host_perfdata_path = "/var/spool/icinga2/perfdata/host-perfdata"
1284
1285       service_perfdata_path = "/var/spool/icinga2/perfdata/service-perfdata"
1286
1287       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$"
1288       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$"
1289
1290       rotation_interval = 15s
1291     }
1292
1293 Configuration Attributes:
1294
1295   Name                    |Description
1296   ------------------------|----------------
1297   host_perfdata\_path     |**Optional.** Path to the host performance data file. Defaults to LocalStateDir + "/spool/icinga2/perfdata/host-perfdata".
1298   service_perfdata\_path  |**Optional.** Path to the service performance data file. Defaults to LocalStateDir + "/spool/icinga2/perfdata/service-perfdata".
1299   host_temp\_path         |**Optional.** Path to the temporary host file. Defaults to LocalStateDir + "/spool/icinga2/tmp/host-perfdata".
1300   service_temp\_path      |**Optional.** Path to the temporary service file. Defaults to LocalStateDir + "/spool/icinga2/tmp/service-perfdata".
1301   host_format\_template   |**Optional.** Host Format template for the performance data file. Defaults to a template that's suitable for use with PNP4Nagios.
1302   service_format\_template|**Optional.** Service Format template for the performance data file. Defaults to a template that's suitable for use with PNP4Nagios.
1303   rotation\_interval      |**Optional.** Rotation interval for the files specified in `{host,service}_perfdata_path`. Defaults to 30 seconds.
1304
1305 When rotating the performance data file the current UNIX timestamp is appended to the path specified
1306 in `host_perfdata_path` and `service_perfdata_path` to generate a unique filename.
1307
1308
1309 ## ScheduledDowntime <a id="objecttype-scheduleddowntime"></a>
1310
1311 ScheduledDowntime objects can be used to set up recurring downtimes for hosts/services.
1312
1313 > **Best Practice**
1314 >
1315 > Rather than creating a `ScheduledDowntime` object for a specific host or service it is usually easier
1316 > to just create a `ScheduledDowntime` template and use the `apply` keyword to assign the
1317 > scheduled downtime to a number of hosts or services. Use the `to` keyword to set the specific target
1318 > type for `Host` or `Service`.
1319 > Check the [recurring downtimes](08-advanced-topics.md#recurring-downtimes) example for details.
1320
1321 Example:
1322
1323     object ScheduledDowntime "some-downtime" {
1324       host_name = "localhost"
1325       service_name = "ping4"
1326
1327       author = "icingaadmin"
1328       comment = "Some comment"
1329
1330       fixed = false
1331       duration = 30m
1332
1333       ranges = {
1334         "sunday" = "02:00-03:00"
1335       }
1336     }
1337
1338 Configuration Attributes:
1339
1340   Name            |Description
1341   ----------------|----------------
1342   host_name       |**Required.** The name of the host this scheduled downtime belongs to.
1343   service_name    |**Optional.** The short name of the service this scheduled downtime belongs to. If omitted, this downtime object is treated as host downtime.
1344   author          |**Required.** The author of the downtime.
1345   comment         |**Required.** A comment for the downtime.
1346   fixed           |**Optional.** Whether this is a fixed downtime. Defaults to true.
1347   duration        |**Optional.** How long the downtime lasts. Only has an effect for flexible (non-fixed) downtimes.
1348   ranges          |**Required.** A dictionary containing information which days and durations apply to this timeperiod.
1349
1350 ScheduledDowntime objects have composite names, i.e. their names are based
1351 on the `host_name` and `service_name` attributes and the
1352 name you specified. This means you can define more than one object
1353 with the same (short) name as long as one of the `host_name` and
1354 `service_name` attributes has a different value.
1355
1356
1357 ## Service <a id="objecttype-service"></a>
1358
1359 Service objects describe network services and how they should be checked
1360 by Icinga 2.
1361
1362 > **Best Practice**
1363 >
1364 > Rather than creating a `Service` object for a specific host it is usually easier
1365 > to just create a `Service` template and use the `apply` keyword to assign the
1366 > service to a number of hosts.
1367 > Check the [apply](03-monitoring-basics.md#using-apply) chapter for details.
1368
1369 Example:
1370
1371     object Service "uptime" {
1372       host_name = "localhost"
1373
1374       display_name = "localhost Uptime"
1375
1376       check_command = "check_snmp"
1377
1378       vars.community = "public"
1379       vars.oid = "DISMAN-EVENT-MIB::sysUpTimeInstance"
1380
1381       check_interval = 60s
1382       retry_interval = 15s
1383
1384       groups = [ "all-services", "snmp" ]
1385     }
1386
1387 Configuration Attributes:
1388
1389   Name            |Description
1390   ----------------|----------------
1391   display_name    |**Optional.** A short description of the service.
1392   host_name       |**Required.** The host this service belongs to. There must be a `Host` object with that name.
1393   name            |**Required.** The service name. Must be unique on a per-host basis (Similar to the service_description attribute in Icinga 1.x).
1394   groups          |**Optional.** The service groups this service belongs to.
1395   vars            |**Optional.** A dictionary containing custom attributes that are specific to this service.
1396   check\_command  |**Required.** The name of the check command.
1397   max\_check\_attempts|**Optional.** The number of times a service is re-checked before changing into a hard state. Defaults to 3.
1398   check\_period   |**Optional.** The name of a time period which determines when this service should be checked. Not set by default.
1399   check\_timeout  |**Optional.** Check command timeout in seconds. Overrides the CheckCommand's `timeout` attribute.
1400   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.
1401   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.
1402   enable\_notifications|**Optional.** Whether notifications are enabled. Defaults to true.
1403   enable\_active\_checks|**Optional.** Whether active checks are enabled. Defaults to true.
1404   enable\_passive\_checks|**Optional.** Whether passive checks are enabled. Defaults to true.
1405   enable\_event\_handler|**Optional.** Enables event handlers for this host. Defaults to true.
1406   enable\_flapping|**Optional.** Whether flap detection is enabled. Defaults to false.
1407   enable\_perfdata|**Optional.** Whether performance data processing is enabled. Defaults to true.
1408   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.
1409   flapping\_threshold|**Optional.** The flapping threshold in percent when a service is considered to be flapping.
1410   volatile        |**Optional.** The volatile setting enables always `HARD` state types if `NOT-OK` state changes occur.
1411   zone            |**Optional.** The zone this object is a member of.
1412   command\_endpoint|**Optional.** The endpoint where commands are executed on.
1413   notes           |**Optional.** Notes for the service.
1414   notes\_url      |**Optional.** Url for notes for the service (for example, in notification commands).
1415   action_url      |**Optional.** Url for actions for the service (for example, an external graphing tool).
1416   icon\_image     |**Optional.** Icon image for the service. Used by external interfaces only.
1417   icon\_image\_alt|**Optional.** Icon image description for the service. Used by external interface only.
1418
1419 Service objects have composite names, i.e. their names are based on the host_name attribute and the name you specified. This means
1420 you can define more than one object with the same (short) name as long as the `host_name` attribute has a different value.
1421
1422 The actual check interval might deviate slightly from the configured values due to the fact that Icinga tries
1423 to evenly distribute all checks over a certain period of time, i.e. to avoid load spikes.
1424
1425 Runtime Attributes:
1426
1427   Name                      | Type          | Description
1428   --------------------------|---------------|-----------------
1429   next\_check               | Number        | When the next check occurs (as a UNIX timestamp).
1430   last\_check               | Number        | When the last check occured (as a UNIX timestamp).
1431   check\_attempt            | Number        | The current check attempt number.
1432   state\_type               | Number        | The current state type (0 = SOFT, 1 = HARD).
1433   last\_state\_type         | Number        | The previous state type (0 = SOFT, 1 = HARD).
1434   last\_reachable           | Boolean       | Whether the service was reachable when the last check occurred.
1435   last\_check\_result       | CheckResult   | The current check result.
1436   last\_state\_change       | Number        | When the last state change occurred (as a UNIX timestamp).
1437   last\_hard\_state\_change | Number        | When the last hard state change occurred (as a UNIX timestamp).
1438   last\_in\_downtime        | Boolean       | Whether the service was in a downtime when the last check occurred.
1439   acknowledgement           | Number        | The acknowledgement type (0 = NONE, 1 = NORMAL, 2 = STICKY).
1440   acknowledgement_expiry    | Number        | When the acknowledgement expires (as a UNIX timestamp; 0 = no expiry).
1441   downtime\_depth           | Number        | Whether the service has one or more active downtimes.
1442   flapping_last_change      | Number        | When the last flapping change occurred (as a UNIX timestamp).
1443   flapping                  | Boolean       | Whether the host is flapping between states.
1444   state                     | Number        | The current state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).
1445   last\_state               | Number        | The previous state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).
1446   last\_hard\_state         | Number        | The last hard state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).
1447   last_state_ok             | Number        | When the last OK state occurred (as a UNIX timestamp).
1448   last_state_warning        | Number        | When the last WARNING state occurred (as a UNIX timestamp).
1449   last_state_critical       | Number        | When the last CRITICAL state occurred (as a UNIX timestamp).
1450   last_state_unknown        | Number        | When the last UNKNOWN state occurred (as a UNIX timestamp).
1451
1452
1453 ## ServiceGroup <a id="objecttype-servicegroup"></a>
1454
1455 A group of services.
1456
1457 > **Best Practice**
1458 >
1459 > Assign service group members using the [group assign](17-language-reference.md#group-assign) rules.
1460
1461 Example:
1462
1463     object ServiceGroup "snmp" {
1464       display_name = "SNMP services"
1465     }
1466
1467 Configuration Attributes:
1468
1469   Name            |Description
1470   ----------------|----------------
1471   display_name    |**Optional.** A short description of the service group.
1472   groups          |**Optional.** An array of nested group names.
1473
1474
1475 ## StatusDataWriter <a id="objecttype-statusdatawriter"></a>
1476
1477 Periodically writes status data files which are used by the Classic UI and other third-party tools.
1478
1479 Example:
1480
1481     library "compat"
1482
1483     object StatusDataWriter "status" {
1484         status_path = "/var/cache/icinga2/status.dat"
1485         objects_path = "/var/cache/icinga2/objects.cache"
1486         update_interval = 30s
1487     }
1488
1489 Configuration Attributes:
1490
1491   Name            |Description
1492   ----------------|----------------
1493   status\_path    |**Optional.** Path to the status.dat file. Defaults to LocalStateDir + "/cache/icinga2/status.dat".
1494   objects\_path   |**Optional.** Path to the objects.cache file. Defaults to LocalStateDir + "/cache/icinga2/objects.cache".
1495   update\_interval|**Optional.** The interval in which the status files are updated. Defaults to 15 seconds.
1496
1497
1498 ## SyslogLogger <a id="objecttype-sysloglogger"></a>
1499
1500 Specifies Icinga 2 logging to syslog.
1501
1502 Example:
1503
1504     object SyslogLogger "crit-syslog" {
1505       severity = "critical"
1506     }
1507
1508 Configuration Attributes:
1509
1510   Name            |Description
1511   ----------------|----------------
1512   severity        |**Optional.** The minimum severity for this log. Can be "debug", "notice", "information", "warning" or "critical". Defaults to "warning".
1513
1514
1515 ## TimePeriod <a id="objecttype-timeperiod"></a>
1516
1517 Time periods can be used to specify when hosts/services should be checked or to limit
1518 when notifications should be sent out.
1519
1520 Examples:
1521
1522     object TimePeriod "nonworkhours" {
1523       import "legacy-timeperiod"
1524
1525       display_name = "Icinga 2 TimePeriod for non working hours"
1526
1527       ranges = {
1528         monday = "00:00-8:00,17:00-24:00"
1529         tuesday = "00:00-8:00,17:00-24:00"
1530         wednesday = "00:00-8:00,17:00-24:00"
1531         thursday = "00:00-8:00,17:00-24:00"
1532         friday = "00:00-8:00,16:00-24:00"
1533         saturday = "00:00-24:00"
1534         sunday = "00:00-24:00"
1535       }
1536     }
1537
1538     object TimePeriod "exampledays" {
1539         import "legacy-timeperiod"
1540
1541         display_name = "Icinga 2 TimePeriod for random example days"
1542
1543         ranges = {
1544             //We still believe in Santa, no peeking!
1545             //Applies every 25th of December every year
1546             "december 25" = "00:00-24:00"
1547
1548             //Any point in time can be specified,
1549             //but you still have to use a range
1550             "2038-01-19" = "03:13-03:15"
1551
1552             //Evey 3rd day from the second monday of February
1553             //to 8th of November
1554             "monday 2 february - november 8 / 3" = "00:00-24:00"
1555         }
1556     }
1557
1558
1559 Additional examples can be found [here](08-advanced-topics.md#timeperiods).
1560
1561 Configuration Attributes:
1562
1563   Name            |Description
1564   ----------------|----------------
1565   display_name    |**Optional.** A short description of the time period.
1566   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.
1567   ranges          |**Required.** A dictionary containing information which days and durations apply to this timeperiod.
1568   prefer_includes |**Optional.** Boolean whether to prefer timeperiods `includes` or `excludes`. Default to true.
1569   excludes        |**Optional.** An array of timeperiods, which should exclude from your timerange.
1570   includes        |**Optional.** An array of timeperiods, which should include into your timerange
1571
1572 The `/etc/icinga2/conf.d/timeperiods.conf` file is usually used to define
1573 timeperiods including this one.
1574
1575 Runtime Attributes:
1576
1577   Name                      | Type          | Description
1578   --------------------------|---------------|-----------------
1579   is\_inside                | Boolean       | Whether we're currently inside this timeperiod.
1580
1581
1582 ## User <a id="objecttype-user"></a>
1583
1584 A user.
1585
1586 Example:
1587
1588     object User "icingaadmin" {
1589       display_name = "Icinga 2 Admin"
1590       groups = [ "icingaadmins" ]
1591       email = "icinga@localhost"
1592       pager = "icingaadmin@localhost.localdomain"
1593
1594       period = "24x7"
1595
1596       states = [ OK, Warning, Critical, Unknown ]
1597       types = [ Problem, Recovery ]
1598
1599       vars.additional_notes = "This is the Icinga 2 Admin account."
1600     }
1601
1602 Available notification state filters:
1603
1604     OK
1605     Warning
1606     Critical
1607     Unknown
1608     Up
1609     Down
1610
1611 Available notification type filters:
1612
1613     DowntimeStart
1614     DowntimeEnd
1615     DowntimeRemoved
1616     Custom
1617     Acknowledgement
1618     Problem
1619     Recovery
1620     FlappingStart
1621     FlappingEnd
1622
1623 Configuration Attributes:
1624
1625   Name            |Description
1626   ----------------|----------------
1627   display_name    |**Optional.** A short description of the user.
1628   email           |**Optional.** An email string for this user. Useful for notification commands.
1629   pager           |**Optional.** A pager string for this user. Useful for notification commands.
1630   vars            |**Optional.** A dictionary containing custom attributes that are specific to this user.
1631   groups          |**Optional.** An array of group names.
1632   enable_notifications|**Optional.** Whether notifications are enabled for this user.
1633   period          |**Optional.** The name of a time period which determines when a notification for this user should be triggered. Not set by default.
1634   types           |**Optional.** A set of type filters when this notification should be triggered. By default everything is matched.
1635   states          |**Optional.** A set of state filters when this notification should be triggered. By default everything is matched.
1636
1637 Runtime Attributes:
1638
1639   Name                      | Type          | Description
1640   --------------------------|---------------|-----------------
1641   last\_notification        | Number        | When the last notification was sent for this user (as a UNIX timestamp).
1642
1643 ## UserGroup <a id="objecttype-usergroup"></a>
1644
1645 A user group.
1646
1647 > **Best Practice**
1648 >
1649 > Assign user group members using the [group assign](17-language-reference.md#group-assign) rules.
1650
1651 Example:
1652
1653     object UserGroup "icingaadmins" {
1654         display_name = "Icinga 2 Admin Group"
1655     }
1656
1657 Configuration Attributes:
1658
1659   Name            |Description
1660   ----------------|----------------
1661   display_name    |**Optional.** A short description of the user group.
1662   groups          |**Optional.** An array of nested group names.
1663
1664
1665 ## Zone <a id="objecttype-zone"></a>
1666
1667 Zone objects are used to specify which Icinga 2 instances are located in a zone.
1668
1669 Example:
1670
1671     object Zone "config-ha-master" {
1672       endpoints = [ "icinga2a", "icinga2b" ]
1673
1674     }
1675
1676     object Zone "check-satellite" {
1677       endpoints = [ "icinga2c" ]
1678       parent = "config-ha-master"
1679     }
1680
1681 Configuration Attributes:
1682
1683   Name            |Description
1684   ----------------|----------------
1685   endpoints       |**Optional.** Array of endpoint names located in this zone.
1686   parent          |**Optional.** The name of the parent zone.
1687   global          |**Optional.** Whether configuration files for this zone should be synced to all endpoints. Defaults to false.
1688
1689 Zone objects cannot currently be created with the API.
1690
1691 # Value Types <a id="value-types"></a>
1692
1693 In addition to [configuration objects](09-object-types.md#object-types) Icinga 2 also uses a few other types to represent its internal state. The following types are exposed via the [API](12-icinga2-api.md#icinga2-api).
1694
1695 ## CheckResult <a id="value-types-checkresult"></a>
1696
1697   Name                      | Type          | Description
1698   --------------------------|---------------|-----------------
1699   exit_status               | Number        | The exit status returned by the check execution.
1700   output                    | String        | The check output.
1701   performance_data          | Array         | Array of [performance data values](09-object-types.md#value-types-perfdatavalue).
1702   check_source              | String        | Name of the node executing the check.
1703   state                     | Number        | The current state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).
1704   command                   | Value         | Array of command with shell-escaped arguments or command line string.
1705   execution_start           | Number        | Check execution start time (as a UNIX timestamp).
1706   execution_end             | Number        | Check execution end time (as a UNIX timestamp).
1707   schedule_start            | Number        | Scheduled check execution start time (as a UNIX timestamp).
1708   schedule_end              | Number        | Scheduled check execution end time (as a UNIX timestamp).
1709   active                    | Boolean       | Whether the result is from an active or passive check.
1710   vars_before               | Dictionary    | Internal attribute used for calculations.
1711   vars_after                | Dictionary    | Internal attribute used for calculations.
1712
1713 ## PerfdataValue <a id="value-types-perfdatavalue"></a>
1714
1715 Icinga 2 parses performance data strings returned by check plugins and makes the information available to external interfaces (e.g. [GraphiteWriter](09-object-types.md#objecttype-graphitewriter) or the [Icinga 2 API](12-icinga2-api.md#icinga2-api)).
1716
1717   Name                      | Type          | Description
1718   --------------------------|---------------|-----------------
1719   label                     | String        | Performance data label.
1720   value                     | Number        | Normalized performance data value without unit.
1721   counter                   | Boolean       | Enabled if the original value contains `c` as unit. Defaults to `false`.
1722   unit                      | String        | Unit of measurement (`seconds`, `bytes`. `percent`) according to the [plugin API](05-service-monitoring.md#service-monitoring-plugin-api).
1723   crit                      | Value         | Critical threshold value.
1724   warn                      | Value         | Warning threshold value.
1725   min                       | Value         | Minimum value returned by the check.
1726   max                       | Value         | Maximum value returned by the check.
1727
1728