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       text = "This is a comment."
 389     }
 390
 391 Configuration Attributes:
 392
 393   Name            |Description
 394   ----------------|----------------
 395   host_name       | **Required.** The name of the host this comment belongs to.
 396   service_name    | **Optional.** The short name of the service this comment belongs to. If omitted, this comment object is treated as host comment.
 397   author          | **Required.** The author's name.
 398   comment         | **Required.** The comment text.
 399   start_time      | **Required.** The start time as unix timestamp.
 400   end_time        | **Required.** The end time as unix timestamp.
 401   duration        | **Required.** The duration as number.
 402   entry_time      | **Optional.** The unix timestamp when this downtime was added.
 403   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).
 404   triggers        | **Optional.** List of downtimes which should be triggered by this downtime.
 405
 406 Runtime Attributes:
 407
 408   Name            |Description
 409   ----------------|----------------
 410   trigger_time    | The unix timestamp when this downtime was triggered.
 411   triggered_by    | The name of the downtime this downtime was triggered by.
 412
 413
 414
 415 ## Endpoint <a id="objecttype-endpoint"></a>
 416
 417 Endpoint objects are used to specify connection information for remote
 418 Icinga 2 instances.
 419
 420 Example:
 421
 422     object Endpoint "icinga2b" {
 423       host = "192.168.5.46"
 424       port = 5665
 425       log_duration = 1d
 426     }
 427
 428 Example (disable replay log):
 429
 430     object Endpoint "icinga2b" {
 431       host = "192.168.5.46"
 432       port = 5665
 433       log_duration = 0
 434     }
 435
 436 Configuration Attributes:
 437
 438   Name            |Description
 439   ----------------|----------------
 440   host            |**Optional.** The hostname/IP address of the remote Icinga 2 instance.
 441   port            |**Optional.** The service name/port of the remote Icinga 2 instance. Defaults to `5665`.
 442   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.
 443
 444 Endpoint objects cannot currently be created with the API.
 445
 446 ## EventCommand <a id="objecttype-eventcommand"></a>
 447
 448 An event command definition.
 449
 450 > **Note**
 451 >
 452 > Icinga 2 versions < 2.6.0 require the import of the [plugin-event-command](10-icinga-template-library.md#itl-plugin-event-command) template.
 453
 454 Example:
 455
 456     object EventCommand "restart-httpd-event" {
 457       command = "/opt/bin/restart-httpd.sh"
 458     }
 459
 460
 461 Configuration Attributes:
 462
 463   Name            |Description
 464   ----------------|----------------
 465   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.
 466   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.
 467   env             |**Optional.** A dictionary of macros which should be exported as environment variables prior to executing the command.
 468   vars            |**Optional.** A dictionary containing custom attributes that are specific to this command.
 469   timeout         |**Optional.** The command timeout in seconds. Defaults to 60 seconds.
 470   arguments       |**Optional.** A dictionary of command arguments.
 471
 472 Command arguments can be used the same way as for [CheckCommand objects](09-object-types.md#objecttype-checkcommand-arguments).
 473
 474 More advanced examples for event command usage can be found [here](03-monitoring-basics.md#event-commands).
 475
 476 ## ExternalCommandListener <a id="objecttype-externalcommandlistener"></a>
 477
 478 Implements the Icinga 1.x command pipe which can be used to send commands to Icinga.
 479
 480 Example:
 481
 482     library "compat"
 483
 484     object ExternalCommandListener "external" {
 485         command_path = "/var/run/icinga2/cmd/icinga2.cmd"
 486     }
 487
 488 Configuration Attributes:
 489
 490   Name            |Description
 491   ----------------|----------------
 492   command\_path   |**Optional.** Path to the command pipe. Defaults to RunDir + "/icinga2/cmd/icinga2.cmd".
 493
 494
 495
 496 ## FileLogger <a id="objecttype-filelogger"></a>
 497
 498 Specifies Icinga 2 logging to a file.
 499
 500 Example:
 501
 502     object FileLogger "debug-file" {
 503       severity = "debug"
 504       path = "/var/log/icinga2/debug.log"
 505     }
 506
 507 Configuration Attributes:
 508
 509   Name            |Description
 510   ----------------|----------------
 511   path            |**Required.** The log path.
 512   severity        |**Optional.** The minimum severity for this log. Can be "debug", "notice", "information", "warning" or "critical". Defaults to "information".
 513
 514
 515 ## GelfWriter <a id="objecttype-gelfwriter"></a>
 516
 517 Writes event log entries to a defined GELF receiver host (Graylog2, Logstash).
 518
 519 Example:
 520
 521     library "perfdata"
 522
 523     object GelfWriter "gelf" {
 524       host = "127.0.0.1"
 525       port = 12201
 526     }
 527
 528 Configuration Attributes:
 529
 530   Name                  |Description
 531   ----------------------|----------------------
 532   host                  |**Optional.** GELF receiver host address. Defaults to '127.0.0.1'.
 533   port                  |**Optional.** GELF receiver port. Defaults to `12201`.
 534   source                |**Optional.** Source name for this instance. Defaults to `icinga2`.
 535   enable_send_perfdata  |**Optional.** Enable performance data for 'CHECK RESULT' events.
 536
 537
 538 ## GraphiteWriter <a id="objecttype-graphitewriter"></a>
 539
 540 Writes check result metrics and performance data to a defined
 541 Graphite Carbon host.
 542
 543 Example:
 544
 545     library "perfdata"
 546
 547     object GraphiteWriter "graphite" {
 548       host = "127.0.0.1"
 549       port = 2003
 550     }
 551
 552 Configuration Attributes:
 553
 554   Name                  |Description
 555   ----------------------|----------------------
 556   host                  |**Optional.** Graphite Carbon host address. Defaults to '127.0.0.1'.
 557   port                  |**Optional.** Graphite Carbon port. Defaults to 2003.
 558   host_name_template    |**Optional.** Metric prefix for host name. Defaults to "icinga2.$host.name$.host.$host.check_command$".
 559   service_name_template |**Optional.** Metric prefix for service name. Defaults to "icinga2.$host.name$.services.$service.name$.$service.check_command$".
 560   enable_send_thresholds | **Optional.** Send additional threshold metrics. Defaults to `false`.
 561   enable_send_metadata  | **Optional.** Send additional metadata metrics. Defaults to `false`.
 562
 563 Additional usage examples can be found [here](14-features.md#graphite-carbon-cache-writer).
 564
 565
 566
 567 ## Host <a id="objecttype-host"></a>
 568
 569 A host.
 570
 571 Example:
 572
 573     object Host NodeName {
 574       display_name = "Local host on this node"
 575       address = "127.0.0.1"
 576       address6 = "::1"
 577
 578       groups = [ "all-hosts" ]
 579
 580       check_command = "hostalive"
 581     }
 582
 583 Configuration Attributes:
 584
 585   Name            |Description
 586   ----------------|----------------
 587   display_name    |**Optional.** A short description of the host (e.g. displayed by external interfaces instead of the name if set).
 588   address         |**Optional.** The host's address. Available as command runtime macro `$address$` if set.
 589   address6        |**Optional.** The host's address. Available as command runtime macro `$address6$` if set.
 590   groups          |**Optional.** A list of host groups this host belongs to.
 591   vars            |**Optional.** A dictionary containing custom attributes that are specific to this host.
 592   check\_command  |**Required.** The name of the check command.
 593   max\_check\_attempts|**Optional.** The number of times a host is re-checked before changing into a hard state. Defaults to 3.
 594   check\_period   |**Optional.** The name of a time period which determines when this host should be checked. Not set by default.
 595   check\_timeout  |**Optional.** Check command timeout in seconds. Overrides the CheckCommand's `timeout` attribute.
 596   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.
 597   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.
 598   enable\_notifications|**Optional.** Whether notifications are enabled. Defaults to true.
 599   enable\_active\_checks|**Optional.** Whether active checks are enabled. Defaults to true.
 600   enable\_passive\_checks|**Optional.** Whether passive checks are enabled. Defaults to true.
 601   enable\_event\_handler|**Optional.** Enables event handlers for this host. Defaults to true.
 602   enable\_flapping|**Optional.** Whether flap detection is enabled. Defaults to false.
 603   enable\_perfdata|**Optional.** Whether performance data processing is enabled. Defaults to true.
 604   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.
 605   flapping\_threshold|**Optional.** The flapping threshold in percent when a host is considered to be flapping.
 606   volatile        |**Optional.** The volatile setting enables always `HARD` state types if `NOT-OK` state changes occur.
 607   zone            |**Optional.** The zone this object is a member of.
 608   command\_endpoint|**Optional.** The endpoint where commands are executed on.
 609   notes           |**Optional.** Notes for the host.
 610   notes\_url      |**Optional.** Url for notes for the host (for example, in notification commands).
 611   action\_url     |**Optional.** Url for actions for the host (for example, an external graphing tool).
 612   icon\_image     |**Optional.** Icon image for the host. Used by external interfaces only.
 613   icon\_image\_alt|**Optional.** Icon image description for the host. Used by external interface only.
 614
 615 The actual check interval might deviate slightly from the configured values due to the fact that Icinga tries
 616 to evenly distribute all checks over a certain period of time, i.e. to avoid load spikes.
 617
 618 > **Best Practice**
 619 >
 620 > The `address` and `address6` attributes are required for running commands using
 621 > the `$address$` and `$address6$` runtime macros.
 622
 623 Runtime Attributes:
 624
 625   Name                      | Type          | Description
 626   --------------------------|---------------|-----------------
 627   next\_check               | Number        | When the next check occurs (as a UNIX timestamp).
 628   last\_check               | Number        | When the last check occured (as a UNIX timestamp).
 629   check\_attempt            | Number        | The current check attempt number.
 630   state\_type               | Number        | The current state type (0 = SOFT, 1 = HARD).
 631   last\_state\_type         | Number        | The previous state type (0 = SOFT, 1 = HARD).
 632   last\_reachable           | Boolean       | Whether the host was reachable when the last check occurred.
 633   last\_check\_result       | CheckResult   | The current check result.
 634   last\_state\_change       | Number        | When the last state change occurred (as a UNIX timestamp).
 635   last\_hard\_state\_change | Number        | When the last hard state change occurred (as a UNIX timestamp).
 636   last\_in\_downtime        | Boolean       | Whether the host was in a downtime when the last check occurred.
 637   acknowledgement           | Number        | The acknowledgement type (0 = NONE, 1 = NORMAL, 2 = STICKY).
 638   acknowledgement_expiry    | Number        | When the acknowledgement expires (as a UNIX timestamp; 0 = no expiry).
 639   downtime\_depth           | Number        | Whether the host has one or more active downtimes.
 640   flapping_last_change      | Number        | When the last flapping change occurred (as a UNIX timestamp).
 641   flapping                  | Boolean       | Whether the host is flapping between states.
 642   state                     | Number        | The current state (0 = UP, 1 = DOWN).
 643   last\_state               | Number        | The previous state (0 = UP, 1 = DOWN).
 644   last\_hard\_state         | Number        | The last hard state (0 = UP, 1 = DOWN).
 645   last_state_up             | Number        | When the last UP state occurred (as a UNIX timestamp).
 646   last_state_down           | Number        | When the last DOWN state occurred (as a UNIX timestamp).
 647
 648
 649
 650 ## HostGroup <a id="objecttype-hostgroup"></a>
 651
 652 A group of hosts.
 653
 654 > **Best Practice**
 655 >
 656 > Assign host group members using the [group assign](17-language-reference.md#group-assign) rules.
 657
 658 Example:
 659
 660     object HostGroup "my-hosts" {
 661       display_name = "My hosts"
 662     }
 663
 664 Configuration Attributes:
 665
 666   Name            |Description
 667   ----------------|----------------
 668   display_name    |**Optional.** A short description of the host group.
 669   groups          |**Optional.** An array of nested group names.
 670
 671 ## IcingaApplication <a id="objecttype-icingaapplication"></a>
 672
 673 The IcingaApplication object is required to start Icinga 2.
 674 The object name must be `app`. If the object configuration
 675 is missing, Icinga 2 will automatically create an IcingaApplication
 676 object.
 677
 678 Example:
 679
 680     object IcingaApplication "app" {
 681       enable_perfdata = false
 682     }
 683
 684 Configuration Attributes:
 685
 686   Name                  |Description
 687   ----------------------|--------------------------
 688   enable_notifications  |**Optional.** Whether notifications are globally enabled. Defaults to true.
 689   enable_event_handlers |**Optional.** Whether event handlers are globally enabled. Defaults to true.
 690   enable_flapping       |**Optional.** Whether flap detection is globally enabled. Defaults to true.
 691   enable_host_checks    |**Optional.** Whether active host checks are globally enabled. Defaults to true.
 692   enable_service_checks |**Optional.** Whether active service checks are globally enabled. Defaults to true.
 693   enable_perfdata       |**Optional.** Whether performance data processing is globally enabled. Defaults to true.
 694   vars                  |**Optional.** A dictionary containing custom attributes that are available globally.
 695
 696 ## IdoMySqlConnection <a id="objecttype-idomysqlconnection"></a>
 697
 698 IDO database adapter for MySQL.
 699
 700 Example:
 701
 702     library "db_ido_mysql"
 703
 704     object IdoMysqlConnection "mysql-ido" {
 705       host = "127.0.0.1"
 706       port = 3306
 707       user = "icinga"
 708       password = "icinga"
 709       database = "icinga"
 710
 711       cleanup = {
 712         downtimehistory_age = 48h
 713         contactnotifications_age = 31d
 714       }
 715     }
 716
 717 Configuration Attributes:
 718
 719   Name            |Description
 720   ----------------|----------------
 721   host            |**Optional.** MySQL database host address. Defaults to "localhost".
 722   port            |**Optional.** MySQL database port. Defaults to 3306.
 723   socket_path     |**Optional.** MySQL socket path.
 724   user            |**Optional.** MySQL database user with read/write permission to the icinga database. Defaults to "icinga".
 725   password        |**Optional.** MySQL database user's password. Defaults to "icinga".
 726   database        |**Optional.** MySQL database name. Defaults to "icinga".
 727   enable\_ssl     |**Optional.** Use SSL. Defaults to false. Change to `true` in case you want to use any of the SSL options.
 728   ssl\_key        |**Optional.** MySQL SSL client key file path.
 729   ssl\_cert       |**Optional.** MySQL SSL certificate file path.
 730   ssl\_ca         |**Optional.** MySQL SSL certificate authority certificate file path.
 731   ssl\_capath     |**Optional.** MySQL SSL trusted SSL CA certificates in PEM format directory path.
 732   ssl\_cipher     |**Optional.** MySQL SSL list of allowed ciphers.
 733   table\_prefix   |**Optional.** MySQL database table prefix. Defaults to "icinga\_".
 734   instance\_name  |**Optional.** Unique identifier for the local Icinga 2 instance. Defaults to "default".
 735   instance\_description|**Optional.** Description for the Icinga 2 instance.
 736   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".
 737   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".
 738   cleanup         |**Optional.** Dictionary with items for historical table cleanup.
 739   categories      |**Optional.** Array of information types that should be written to the database.
 740
 741 Cleanup Items:
 742
 743   Name            | Description
 744   ----------------|----------------
 745   acknowledgements_age |**Optional.** Max age for acknowledgements table rows (entry_time). Defaults to 0 (never).
 746   commenthistory_age |**Optional.** Max age for commenthistory table rows (entry_time). Defaults to 0 (never).
 747   contactnotifications_age |**Optional.** Max age for contactnotifications table rows (start_time). Defaults to 0 (never).
 748   contactnotificationmethods_age |**Optional.** Max age for contactnotificationmethods table rows (start_time). Defaults to 0 (never).
 749   downtimehistory_age |**Optional.** Max age for downtimehistory table rows (entry_time). Defaults to 0 (never).
 750   eventhandlers_age |**Optional.** Max age for eventhandlers table rows (start_time). Defaults to 0 (never).
 751   externalcommands_age |**Optional.** Max age for externalcommands table rows (entry_time). Defaults to 0 (never).
 752   flappinghistory_age |**Optional.** Max age for flappinghistory table rows (event_time). Defaults to 0 (never).
 753   hostchecks_age |**Optional.** Max age for hostalives table rows (start_time). Defaults to 0 (never).
 754   logentries_age |**Optional.** Max age for logentries table rows (logentry_time). Defaults to 0 (never).
 755   notifications_age |**Optional.** Max age for notifications table rows (start_time). Defaults to 0 (never).
 756   processevents_age |**Optional.** Max age for processevents table rows (event_time). Defaults to 0 (never).
 757   statehistory_age |**Optional.** Max age for statehistory table rows (state_time). Defaults to 0 (never).
 758   servicechecks_age |**Optional.** Max age for servicechecks table rows (start_time). Defaults to 0 (never).
 759   systemcommands_age |**Optional.** Max age for systemcommands table rows (start_time). Defaults to 0 (never).
 760
 761 Data Categories:
 762
 763   Name                 | Description            | Required by
 764   ---------------------|------------------------|--------------------
 765   DbCatConfig          | Configuration data     | Icinga Web 2
 766   DbCatState           | Current state data     | Icinga Web 2
 767   DbCatAcknowledgement | Acknowledgements       | Icinga Web 2
 768   DbCatComment         | Comments               | Icinga Web 2
 769   DbCatDowntime        | Downtimes              | Icinga Web 2
 770   DbCatEventHandler    | Event handler data     | Icinga Web 2
 771   DbCatExternalCommand | External commands      | --
 772   DbCatFlapping        | Flap detection data    | Icinga Web 2
 773   DbCatCheck           | Check results          | --
 774   DbCatLog             | Log messages           | --
 775   DbCatNotification    | Notifications          | Icinga Web 2
 776   DbCatProgramStatus   | Program status data    | Icinga Web 2
 777   DbCatRetention       | Retention data         | Icinga Web 2
 778   DbCatStateHistory    | Historical state data  | Icinga Web 2
 779
 780 The default value for `categories` includes everything required
 781 by Icinga Web 2 in the table above.
 782
 783 In addition to the category flags listed above the `DbCatEverything`
 784 flag may be used as a shortcut for listing all flags.
 785
 786 ## IdoPgSqlConnection <a id="objecttype-idopgsqlconnection"></a>
 787
 788 IDO database adapter for PostgreSQL.
 789
 790 Example:
 791
 792     library "db_ido_pgsql"
 793
 794     object IdoPgsqlConnection "pgsql-ido" {
 795       host = "127.0.0.1"
 796       port = 5432
 797       user = "icinga"
 798       password = "icinga"
 799       database = "icinga"
 800
 801       cleanup = {
 802         downtimehistory_age = 48h
 803         contactnotifications_age = 31d
 804       }
 805     }
 806
 807 Configuration Attributes:
 808
 809   Name            |Description
 810   ----------------|----------------
 811   host            |**Optional.** PostgreSQL database host address. Defaults to "localhost".
 812   port            |**Optional.** PostgreSQL database port. Defaults to "5432".
 813   user            |**Optional.** PostgreSQL database user with read/write permission to the icinga database. Defaults to "icinga".
 814   password        |**Optional.** PostgreSQL database user's password. Defaults to "icinga".
 815   database        |**Optional.** PostgreSQL database name. Defaults to "icinga".
 816   table\_prefix   |**Optional.** PostgreSQL database table prefix. Defaults to "icinga\_".
 817   instance\_name  |**Optional.** Unique identifier for the local Icinga 2 instance. Defaults to "default".
 818   instance\_description|**Optional.** Description for the Icinga 2 instance.
 819   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".
 820   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".
 821   cleanup         |**Optional.** Dictionary with items for historical table cleanup.
 822   categories      |**Optional.** Array of information types that should be written to the database.
 823
 824 Cleanup Items:
 825
 826   Name            | Description
 827   ----------------|----------------
 828   acknowledgements_age |**Optional.** Max age for acknowledgements table rows (entry_time). Defaults to 0 (never).
 829   commenthistory_age |**Optional.** Max age for commenthistory table rows (entry_time). Defaults to 0 (never).
 830   contactnotifications_age |**Optional.** Max age for contactnotifications table rows (start_time). Defaults to 0 (never).
 831   contactnotificationmethods_age |**Optional.** Max age for contactnotificationmethods table rows (start_time). Defaults to 0 (never).
 832   downtimehistory_age |**Optional.** Max age for downtimehistory table rows (entry_time). Defaults to 0 (never).
 833   eventhandlers_age |**Optional.** Max age for eventhandlers table rows (start_time). Defaults to 0 (never).
 834   externalcommands_age |**Optional.** Max age for externalcommands table rows (entry_time). Defaults to 0 (never).
 835   flappinghistory_age |**Optional.** Max age for flappinghistory table rows (event_time). Defaults to 0 (never).
 836   hostchecks_age |**Optional.** Max age for hostalives table rows (start_time). Defaults to 0 (never).
 837   logentries_age |**Optional.** Max age for logentries table rows (logentry_time). Defaults to 0 (never).
 838   notifications_age |**Optional.** Max age for notifications table rows (start_time). Defaults to 0 (never).
 839   processevents_age |**Optional.** Max age for processevents table rows (event_time). Defaults to 0 (never).
 840   statehistory_age |**Optional.** Max age for statehistory table rows (state_time). Defaults to 0 (never).
 841   servicechecks_age |**Optional.** Max age for servicechecks table rows (start_time). Defaults to 0 (never).
 842   systemcommands_age |**Optional.** Max age for systemcommands table rows (start_time). Defaults to 0 (never).
 843
 844 Data Categories:
 845
 846   Name                 | Description            | Required by
 847   ---------------------|------------------------|--------------------
 848   DbCatConfig          | Configuration data     | Icinga Web 2
 849   DbCatState           | Current state data     | Icinga Web 2
 850   DbCatAcknowledgement | Acknowledgements       | Icinga Web 2
 851   DbCatComment         | Comments               | Icinga Web 2
 852   DbCatDowntime        | Downtimes              | Icinga Web 2
 853   DbCatEventHandler    | Event handler data     | Icinga Web 2
 854   DbCatExternalCommand | External commands      | --
 855   DbCatFlapping        | Flap detection data    | Icinga Web 2
 856   DbCatCheck           | Check results          | --
 857   DbCatLog             | Log messages           | --
 858   DbCatNotification    | Notifications          | Icinga Web 2
 859   DbCatProgramStatus   | Program status data    | Icinga Web 2
 860   DbCatRetention       | Retention data         | Icinga Web 2
 861   DbCatStateHistory    | Historical state data  | Icinga Web 2
 862
 863 The default value for `categories` includes everything required
 864 by Icinga Web 2 in the table above.
 865
 866 In addition to the category flags listed above the `DbCatEverything`
 867 flag may be used as a shortcut for listing all flags.
 868
 869 ## InfluxdbWriter <a id="objecttype-influxdbwriter"></a>
 870
 871 Writes check result metrics and performance data to a defined InfluxDB host.
 872
 873 Example:
 874
 875     library "perfdata"
 876
 877     object InfluxdbWriter "influxdb" {
 878       host = "127.0.0.1"
 879       port = 8086
 880       database = "icinga2"
 881
 882       flush_threshold = 1024
 883       flush_interval = 10s
 884
 885       host_template = {
 886         measurement = "$host.check_command$"
 887         tags = {
 888           hostname = "$host.name$"
 889         }
 890       }
 891       service_template = {
 892         measurement = "$service.check_command$"
 893         tags = {
 894           hostname = "$host.name$"
 895           service = "$service.name$"
 896         }
 897       }
 898     }
 899
 900 Measurement names and tags are fully configurable by the end user. The InfluxdbWriter
 901 object will automatically add a `metric` tag to each data point. This correlates to the
 902 perfdata label. Fields (value, warn, crit, min, max) are created from data if available
 903 and the configuration allows it.  If a value associated with a tag is not able to be
 904 resolved, it will be dropped and not sent to the target host.
 905
 906 Backslashes are allowed in tag keys, tag values and field keys, however they are also
 907 escape characters when followed by a space or comma, but cannot be escaped themselves.
 908 As a result all trailling slashes in these fields are replaced with an underscore.  This
 909 predominantly affects Windows paths e.g. `C:\` becomes `C:_`.
 910
 911 The database is assumed to exist so this object will make no attempt to create it currently.
 912
 913 Configuration Attributes:
 914
 915   Name                   |Description
 916   -----------------------|---------------------------------------------------------------------------------------------------------
 917   host                   | **Required.** InfluxDB host address. Defaults to `127.0.0.1`.
 918   port                   | **Required.** InfluxDB HTTP port. Defaults to `8086`.
 919   database               | **Required.** InfluxDB database name. Defaults to `icinga2`.
 920   username               | **Optional.** InfluxDB user name. Defaults to `none`.
 921   password               | **Optional.** InfluxDB user password.  Defaults to `none`.
 922   ssl_enable             | **Optional.** Whether to use a TLS stream.  Defaults to `false`.
 923   ssl_ca_cert            | **Optional.** CA certificate to validate the remote host.
 924   ssl_cert               | **Optional.** Host certificate to present to the remote host for mutual verification.
 925   ssl_key                | **Optional.** Host key to accompany the ssl_cert
 926   host_template          | **Required.** Host template to define the InfluxDB line protocol.
 927   service_template       | **Required.** Service template to define the influxDB line protocol.
 928   enable_send_thresholds | **Optional.** Whether to send warn, crit, min & max tagged data.
 929   enable_send_metadata   | **Optional.** Whether to send check metadata e.g. states, execution time, latency etc.
 930   flush_interval         | **Optional.** How long to buffer data points before transfering to InfluxDB. Defaults to `10s`.
 931   flush_threshold        | **Optional.** How many data points to buffer before forcing a transfer to InfluxDB.  Defaults to `1024`.
 932
 933 Note: If `flush_threshold` is set too low, this will always force the feature to flush all data
 934 to InfluxDB. Experiment with the setting, if you are processing more than 1024 metrics per second
 935 or similar.
 936
 937 ### Instance Tagging <a id="objecttype-influxdbwriter-instance-tags"></a>
 938
 939 Consider the following service check:
 940
 941     apply Service "disk" for (disk => attributes in host.vars.disks) {
 942       import "generic-service"
 943       check_command = "disk"
 944       display_name = "Disk " + disk
 945       vars.disk_partitions = disk
 946       assign where host.vars.disks
 947     }
 948
 949 This is a typical pattern for checking individual disks, NICs, SSL certificates etc associated
 950 with a host.  What would be useful is to have the data points tagged with the specific instance
 951 for that check.  This would allow you to query time series data for a check on a host and for a
 952 specific instance e.g. /dev/sda.  To do this quite simply add the instance to the service variables:
 953
 954     apply Service "disk" for (disk => attributes in host.vars.disks) {
 955       ...
 956       vars.instance = disk
 957       ...
 958     }
 959
 960 Then modify your writer configuration to add this tag to your data points if the instance variable
 961 is associated with the service:
 962
 963     object InfluxdbWriter "influxdb" {
 964       ...
 965       service_template = {
 966         measurement = "$service.check_command$"
 967         tags = {
 968           hostname = "$host.name$"
 969           service = "$service.name$"
 970           instance = "$service.vars.instance$"
 971         }
 972       }
 973       ...
 974     }
 975
 976 ## ElasticWriter <a id="objecttype-elasticwriter"></a>
 977
 978 Writes check result metrics and performance data to an Elasticsearch instance.
 979
 980 Example:
 981
 982     library "perfdata"
 983
 984     object ElasticWriter "elastic" {
 985       host = "127.0.0.1"
 986       port = 9200
 987       index = "icinga2"
 988
 989       enable_send_perfdata = true
 990
 991       flush_threshold = 1024
 992       flush_interval = 10
 993     }
 994
 995 The index is rotated daily, as is recommended by Elastic, meaning the index will be renamed to `$index-$d.$M.$y`.
 996
 997 Configuration Attributes:
 998
 999   Name                   |Description
1000   -----------------------|---------------------------------------------------------------------------------------------------------
1001   host                   | **Required.** Elasticsearch host address. Defaults to `127.0.0.1`.
1002   port                   | **Required.** Elasticsearch port. Defaults to `9200`.
1003   index                  | **Required.** Elasticsearch index name. Defaults to `icinga2`.
1004   enable\_send\_perfdata | **Optional.** Send parsed performance data metrics for check results. Defaults to `false`.
1005   flush\_interval        | **Optional.** How long to buffer data points before transfering to Elasticsearch. Defaults to `10`.
1006   flush\_threshold       | **Optional.** How many data points to buffer before forcing a transfer to Elasticsearch.  Defaults to `1024`.
1007   username               | **Optional.** Basic auth username if Elasticsearch is hidden behind an HTTP proxy.
1008   password               | **Optional.** Basic auth password if Elasticsearch is hidden behind an HTTP proxy.
1009   enable\_tls            | **Optional.** Whether to use a TLS stream. Defaults to `false`. Requires an HTTP proxy.
1010   ca\_path               | **Optional.** CA certificate to validate the remote host. Requires `enable_tls` set to `true`.
1011   cert\_path             | **Optional.** Host certificate to present to the remote host for mutual verification. Requires `enable_tls` set to `true`.
1012   key\_path              | **Optional.** Host key to accompany the cert\_path. Requires `enable_tls` set to `true`.
1013
1014 Note: If `flush_threshold` is set too low, this will force the feature to flush all data to Elasticsearch too often.
1015 Experiment with the setting, if you are processing more than 1024 metrics per second or similar.
1016
1017 Basic auth is supported with the `username` and `password` attributes. This requires an
1018 HTTP proxy (Nginx, etc.) in front of the Elasticsearch instance.
1019
1020 TLS for the HTTP proxy can be enabled with `enable_tls`. In addition to that
1021 you can specify the certificates with the `ca_path`, `cert_path` and `cert_key` attributes.
1022
1023 ## LiveStatusListener <a id="objecttype-livestatuslistener"></a>
1024
1025 Livestatus API interface available as TCP or UNIX socket. Historical table queries
1026 require the [CompatLogger](09-object-types.md#objecttype-compatlogger) feature enabled
1027 pointing to the log files using the `compat_log_path` configuration attribute.
1028
1029 Example:
1030
1031     library "livestatus"
1032
1033     object LivestatusListener "livestatus-tcp" {
1034       socket_type = "tcp"
1035       bind_host = "127.0.0.1"
1036       bind_port = "6558"
1037     }
1038
1039     object LivestatusListener "livestatus-unix" {
1040       socket_type = "unix"
1041       socket_path = "/var/run/icinga2/cmd/livestatus"
1042     }
1043
1044 Configuration Attributes:
1045
1046   Name            |Description
1047   ----------------|----------------
1048   socket\_type      |**Optional.** Specifies the socket type. Can be either "tcp" or "unix". Defaults to "unix".
1049   bind\_host        |**Optional.** Only valid when socket\_type is "tcp". Host address to listen on for connections. Defaults to "127.0.0.1".
1050   bind\_port        |**Optional.** Only valid when `socket_type` is "tcp". Port to listen on for connections. Defaults to 6558.
1051   socket\_path      |**Optional.** Only valid when `socket_type` is "unix". Specifies the path to the UNIX socket file. Defaults to RunDir + "/icinga2/cmd/livestatus".
1052   compat\_log\_path |**Optional.** Required for historical table queries. Requires `CompatLogger` feature enabled. Defaults to LocalStateDir + "/log/icinga2/compat"
1053
1054 > **Note**
1055 >
1056 > UNIX sockets are not supported on Windows.
1057
1058
1059 ## Notification <a id="objecttype-notification"></a>
1060
1061 Notification objects are used to specify how users should be notified in case
1062 of host and service state changes and other events.
1063
1064 > **Best Practice**
1065 >
1066 > Rather than creating a `Notification` object for a specific host or service it is
1067 > usually easier to just create a `Notification` template and use the `apply` keyword
1068 > to assign the notification to a number of hosts or services. Use the `to` keyword
1069 > to set the specific target type for `Host` or `Service`.
1070 > Check the [notifications](03-monitoring-basics.md#alert-notifications) chapter for detailed examples.
1071
1072 Example:
1073
1074     object Notification "localhost-ping-notification" {
1075       host_name = "localhost"
1076       service_name = "ping4"
1077
1078       command = "mail-notification"
1079
1080       users = [ "user1", "user2" ]
1081
1082       types = [ Problem, Recovery ]
1083     }
1084
1085 Configuration Attributes:
1086
1087   Name                      | Description
1088   --------------------------|----------------
1089   host_name                 | **Required.** The name of the host this notification belongs to.
1090   service_name              | **Optional.** The short name of the service this notification belongs to. If omitted, this notification object is treated as host notification.
1091   vars                      | **Optional.** A dictionary containing custom attributes that are specific to this notification object.
1092   users                     | **Optional.** A list of user names who should be notified.
1093   user_groups               | **Optional.** A list of user group names who should be notified.
1094   times                     | **Optional.** A dictionary containing `begin` and `end` attributes for the notification.
1095   command                   | **Required.** The name of the notification command which should be executed when the notification is triggered.
1096   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.
1097   period                    | **Optional.** The name of a time period which determines when this notification should be triggered. Not set by default.
1098   zone                      |**Optional.** The zone this object is a member of.
1099   types                     | **Optional.** A list of type filters when this notification should be triggered. By default everything is matched.
1100   states                    | **Optional.** A list of state filters when this notification should be triggered. By default everything is matched.
1101
1102 Available notification state filters for Service:
1103
1104     OK
1105     Warning
1106     Critical
1107     Unknown
1108
1109 Available notification state filters for Host:
1110
1111     Up
1112     Down
1113
1114 Available notification type filters:
1115
1116     DowntimeStart
1117     DowntimeEnd
1118     DowntimeRemoved
1119     Custom
1120     Acknowledgement
1121     Problem
1122     Recovery
1123     FlappingStart
1124     FlappingEnd
1125
1126 Runtime Attributes:
1127
1128   Name                      | Type          | Description
1129   --------------------------|---------------|-----------------
1130   last\_notification        | Number        | When the last notification was sent for this Notification object (as a UNIX timestamp).
1131   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).
1132   notification\_number      | Number        | The notification number
1133   last\_problem\_notification | Number      | When the last notification was sent for a problem (as a UNIX timestamp).
1134
1135
1136 ## NotificationCommand <a id="objecttype-notificationcommand"></a>
1137
1138 A notification command definition.
1139
1140 > **Note**
1141 >
1142 > Icinga 2 versions < 2.6.0 require the import of the [plugin-notification-command](10-icinga-template-library.md#itl-plugin-notification-command) template.
1143
1144 Example:
1145
1146      object NotificationCommand "mail-service-notification" {
1147        command = [ SysconfDir + "/icinga2/scripts/mail-service-notification.sh" ]
1148
1149        arguments += {
1150          "-4" = {
1151            required = true
1152            value = "$notification_address$"
1153          }
1154          "-6" = "$notification_address6$"
1155          "-b" = "$notification_author$"
1156          "-c" = "$notification_comment$"
1157          "-d" = {
1158            required = true
1159            value = "$notification_date$"
1160          }
1161          "-e" = {
1162            required = true
1163            value = "$notification_servicename$"
1164          }
1165          "-f" = {
1166            value = "$notification_from$"
1167            description = "Set from address. Requires GNU mailutils (Debian/Ubuntu) or mailx (RHEL/SUSE)"
1168          }
1169          "-i" = "$notification_icingaweb2url$"
1170          "-l" = {
1171            required = true
1172            value = "$notification_hostname$"
1173          }
1174          "-n" = {
1175            required = true
1176            value = "$notification_hostdisplayname$"
1177          }
1178          "-o" = {
1179            required = true
1180            value = "$notification_serviceoutput$"
1181          }
1182          "-r" = {
1183            required = true
1184            value = "$notification_useremail$"
1185          }
1186          "-s" = {
1187            required = true
1188            value = "$notification_servicestate$"
1189          }
1190          "-t" = {
1191            required = true
1192            value = "$notification_type$"
1193          }
1194          "-u" = {
1195            required = true
1196            value = "$notification_servicedisplayname$"
1197          }
1198          "-v" = "$notification_logtosyslog$"
1199        }
1200
1201        vars += {
1202          notification_address = "$address$"
1203          notification_address6 = "$address6$"
1204          notification_author = "$notification.author$"
1205          notification_comment = "$notification.comment$"
1206          notification_type = "$notification.type$"
1207          notification_date = "$icinga.long_date_time$"
1208          notification_hostname = "$host.name$"
1209          notification_hostdisplayname = "$host.display_name$"
1210          notification_servicename = "$service.name$"
1211          notification_serviceoutput = "$service.output$"
1212          notification_servicestate = "$service.state$"
1213          notification_useremail = "$user.email$"
1214          notification_servicedisplayname = "$service.display_name$"
1215        }
1216      }
1217
1218
1219 Configuration Attributes:
1220
1221   Name            |Description
1222   ----------------|----------------
1223   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.
1224   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.
1225   env             |**Optional.** A dictionary of macros which should be exported as environment variables prior to executing the command.
1226   vars            |**Optional.** A dictionary containing custom attributes that are specific to this command.
1227   timeout         |**Optional.** The command timeout in seconds. Defaults to 60 seconds.
1228   arguments       |**Optional.** A dictionary of command arguments.
1229
1230 Command arguments can be used the same way as for [CheckCommand objects](09-object-types.md#objecttype-checkcommand-arguments).
1231
1232 More details on specific attributes can be found in [this chapter](03-monitoring-basics.md#notification-commands).
1233
1234 ## NotificationComponent <a id="objecttype-notificationcomponent"></a>
1235
1236 The notification component is responsible for sending notifications. There are no configurable options.
1237
1238 Example:
1239
1240     library "notification"
1241
1242     object NotificationComponent "notification" { }
1243
1244 Configuration Attributes:
1245
1246   Name            |Description
1247   ----------------|----------------
1248   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".
1249
1250 ## OpenTsdbWriter <a id="objecttype-opentsdbwriter"></a>
1251
1252 Writes check result metrics and performance data to [OpenTSDB](http://opentsdb.net).
1253
1254 Example:
1255
1256     library "perfdata"
1257
1258     object OpenTsdbWriter "opentsdb" {
1259       host = "127.0.0.1"
1260       port = 4242
1261     }
1262
1263 Configuration Attributes:
1264
1265   Name                  |Description
1266   ----------------------|----------------------
1267   host                  |**Optional.** OpenTSDB host address. Defaults to '127.0.0.1'.
1268   port                  |**Optional.** OpenTSDB port. Defaults to 4242.
1269
1270
1271 ## PerfdataWriter <a id="objecttype-perfdatawriter"></a>
1272
1273 Writes check result performance data to a defined path using macro
1274 pattern consisting of custom attributes and runtime macros.
1275
1276 Example:
1277
1278     library "perfdata"
1279
1280     object PerfdataWriter "pnp" {
1281       host_perfdata_path = "/var/spool/icinga2/perfdata/host-perfdata"
1282
1283       service_perfdata_path = "/var/spool/icinga2/perfdata/service-perfdata"
1284
1285       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$"
1286       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$"
1287
1288       rotation_interval = 15s
1289     }
1290
1291 Configuration Attributes:
1292
1293   Name                    |Description
1294   ------------------------|----------------
1295   host_perfdata\_path     |**Optional.** Path to the host performance data file. Defaults to LocalStateDir + "/spool/icinga2/perfdata/host-perfdata".
1296   service_perfdata\_path  |**Optional.** Path to the service performance data file. Defaults to LocalStateDir + "/spool/icinga2/perfdata/service-perfdata".
1297   host_temp\_path         |**Optional.** Path to the temporary host file. Defaults to LocalStateDir + "/spool/icinga2/tmp/host-perfdata".
1298   service_temp\_path      |**Optional.** Path to the temporary service file. Defaults to LocalStateDir + "/spool/icinga2/tmp/service-perfdata".
1299   host_format\_template   |**Optional.** Host Format template for the performance data file. Defaults to a template that's suitable for use with PNP4Nagios.
1300   service_format\_template|**Optional.** Service Format template for the performance data file. Defaults to a template that's suitable for use with PNP4Nagios.
1301   rotation\_interval      |**Optional.** Rotation interval for the files specified in `{host,service}_perfdata_path`. Defaults to 30 seconds.
1302
1303 When rotating the performance data file the current UNIX timestamp is appended to the path specified
1304 in `host_perfdata_path` and `service_perfdata_path` to generate a unique filename.
1305
1306
1307 ## ScheduledDowntime <a id="objecttype-scheduleddowntime"></a>
1308
1309 ScheduledDowntime objects can be used to set up recurring downtimes for hosts/services.
1310
1311 > **Best Practice**
1312 >
1313 > Rather than creating a `ScheduledDowntime` object for a specific host or service it is usually easier
1314 > to just create a `ScheduledDowntime` template and use the `apply` keyword to assign the
1315 > scheduled downtime to a number of hosts or services. Use the `to` keyword to set the specific target
1316 > type for `Host` or `Service`.
1317 > Check the [recurring downtimes](08-advanced-topics.md#recurring-downtimes) example for details.
1318
1319 Example:
1320
1321     object ScheduledDowntime "some-downtime" {
1322       host_name = "localhost"
1323       service_name = "ping4"
1324
1325       author = "icingaadmin"
1326       comment = "Some comment"
1327
1328       fixed = false
1329       duration = 30m
1330
1331       ranges = {
1332         "sunday" = "02:00-03:00"
1333       }
1334     }
1335
1336 Configuration Attributes:
1337
1338   Name            |Description
1339   ----------------|----------------
1340   host_name       |**Required.** The name of the host this scheduled downtime belongs to.
1341   service_name    |**Optional.** The short name of the service this scheduled downtime belongs to. If omitted, this downtime object is treated as host downtime.
1342   author          |**Required.** The author of the downtime.
1343   comment         |**Required.** A comment for the downtime.
1344   fixed           |**Optional.** Whether this is a fixed downtime. Defaults to true.
1345   duration        |**Optional.** How long the downtime lasts. Only has an effect for flexible (non-fixed) downtimes.
1346   ranges          |**Required.** A dictionary containing information which days and durations apply to this timeperiod.
1347
1348 ScheduledDowntime objects have composite names, i.e. their names are based
1349 on the `host_name` and `service_name` attributes and the
1350 name you specified. This means you can define more than one object
1351 with the same (short) name as long as one of the `host_name` and
1352 `service_name` attributes has a different value.
1353
1354
1355 ## Service <a id="objecttype-service"></a>
1356
1357 Service objects describe network services and how they should be checked
1358 by Icinga 2.
1359
1360 > **Best Practice**
1361 >
1362 > Rather than creating a `Service` object for a specific host it is usually easier
1363 > to just create a `Service` template and use the `apply` keyword to assign the
1364 > service to a number of hosts.
1365 > Check the [apply](03-monitoring-basics.md#using-apply) chapter for details.
1366
1367 Example:
1368
1369     object Service "uptime" {
1370       host_name = "localhost"
1371
1372       display_name = "localhost Uptime"
1373
1374       check_command = "check_snmp"
1375
1376       vars.community = "public"
1377       vars.oid = "DISMAN-EVENT-MIB::sysUpTimeInstance"
1378
1379       check_interval = 60s
1380       retry_interval = 15s
1381
1382       groups = [ "all-services", "snmp" ]
1383     }
1384
1385 Configuration Attributes:
1386
1387   Name            |Description
1388   ----------------|----------------
1389   display_name    |**Optional.** A short description of the service.
1390   host_name       |**Required.** The host this service belongs to. There must be a `Host` object with that name.
1391   name            |**Required.** The service name. Must be unique on a per-host basis (Similar to the service_description attribute in Icinga 1.x).
1392   groups          |**Optional.** The service groups this service belongs to.
1393   vars            |**Optional.** A dictionary containing custom attributes that are specific to this service.
1394   check\_command  |**Required.** The name of the check command.
1395   max\_check\_attempts|**Optional.** The number of times a service is re-checked before changing into a hard state. Defaults to 3.
1396   check\_period   |**Optional.** The name of a time period which determines when this service should be checked. Not set by default.
1397   check\_timeout  |**Optional.** Check command timeout in seconds. Overrides the CheckCommand's `timeout` attribute.
1398   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.
1399   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.
1400   enable\_notifications|**Optional.** Whether notifications are enabled. Defaults to true.
1401   enable\_active\_checks|**Optional.** Whether active checks are enabled. Defaults to true.
1402   enable\_passive\_checks|**Optional.** Whether passive checks are enabled. Defaults to true.
1403   enable\_event\_handler|**Optional.** Enables event handlers for this host. Defaults to true.
1404   enable\_flapping|**Optional.** Whether flap detection is enabled. Defaults to false.
1405   enable\_perfdata|**Optional.** Whether performance data processing is enabled. Defaults to true.
1406   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.
1407   flapping\_threshold|**Optional.** The flapping threshold in percent when a service is considered to be flapping.
1408   volatile        |**Optional.** The volatile setting enables always `HARD` state types if `NOT-OK` state changes occur.
1409   zone            |**Optional.** The zone this object is a member of.
1410   command\_endpoint|**Optional.** The endpoint where commands are executed on.
1411   notes           |**Optional.** Notes for the service.
1412   notes\_url      |**Optional.** Url for notes for the service (for example, in notification commands).
1413   action_url      |**Optional.** Url for actions for the service (for example, an external graphing tool).
1414   icon\_image     |**Optional.** Icon image for the service. Used by external interfaces only.
1415   icon\_image\_alt|**Optional.** Icon image description for the service. Used by external interface only.
1416
1417 Service objects have composite names, i.e. their names are based on the host_name attribute and the name you specified. This means
1418 you can define more than one object with the same (short) name as long as the `host_name` attribute has a different value.
1419
1420 The actual check interval might deviate slightly from the configured values due to the fact that Icinga tries
1421 to evenly distribute all checks over a certain period of time, i.e. to avoid load spikes.
1422
1423 Runtime Attributes:
1424
1425   Name                      | Type          | Description
1426   --------------------------|---------------|-----------------
1427   next\_check               | Number        | When the next check occurs (as a UNIX timestamp).
1428   last\_check               | Number        | When the last check occured (as a UNIX timestamp).
1429   check\_attempt            | Number        | The current check attempt number.
1430   state\_type               | Number        | The current state type (0 = SOFT, 1 = HARD).
1431   last\_state\_type         | Number        | The previous state type (0 = SOFT, 1 = HARD).
1432   last\_reachable           | Boolean       | Whether the service was reachable when the last check occurred.
1433   last\_check\_result       | CheckResult   | The current check result.
1434   last\_state\_change       | Number        | When the last state change occurred (as a UNIX timestamp).
1435   last\_hard\_state\_change | Number        | When the last hard state change occurred (as a UNIX timestamp).
1436   last\_in\_downtime        | Boolean       | Whether the service was in a downtime when the last check occurred.
1437   acknowledgement           | Number        | The acknowledgement type (0 = NONE, 1 = NORMAL, 2 = STICKY).
1438   acknowledgement_expiry    | Number        | When the acknowledgement expires (as a UNIX timestamp; 0 = no expiry).
1439   downtime\_depth           | Number        | Whether the service has one or more active downtimes.
1440   flapping_last_change      | Number        | When the last flapping change occurred (as a UNIX timestamp).
1441   flapping                  | Boolean       | Whether the host is flapping between states.
1442   state                     | Number        | The current state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).
1443   last\_state               | Number        | The previous state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).
1444   last\_hard\_state         | Number        | The last hard state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).
1445   last_state_ok             | Number        | When the last OK state occurred (as a UNIX timestamp).
1446   last_state_warning        | Number        | When the last WARNING state occurred (as a UNIX timestamp).
1447   last_state_critical       | Number        | When the last CRITICAL state occurred (as a UNIX timestamp).
1448   last_state_unknown        | Number        | When the last UNKNOWN state occurred (as a UNIX timestamp).
1449
1450
1451 ## ServiceGroup <a id="objecttype-servicegroup"></a>
1452
1453 A group of services.
1454
1455 > **Best Practice**
1456 >
1457 > Assign service group members using the [group assign](17-language-reference.md#group-assign) rules.
1458
1459 Example:
1460
1461     object ServiceGroup "snmp" {
1462       display_name = "SNMP services"
1463     }
1464
1465 Configuration Attributes:
1466
1467   Name            |Description
1468   ----------------|----------------
1469   display_name    |**Optional.** A short description of the service group.
1470   groups          |**Optional.** An array of nested group names.
1471
1472
1473 ## StatusDataWriter <a id="objecttype-statusdatawriter"></a>
1474
1475 Periodically writes status data files which are used by the Classic UI and other third-party tools.
1476
1477 Example:
1478
1479     library "compat"
1480
1481     object StatusDataWriter "status" {
1482         status_path = "/var/cache/icinga2/status.dat"
1483         objects_path = "/var/cache/icinga2/objects.cache"
1484         update_interval = 30s
1485     }
1486
1487 Configuration Attributes:
1488
1489   Name            |Description
1490   ----------------|----------------
1491   status\_path    |**Optional.** Path to the status.dat file. Defaults to LocalStateDir + "/cache/icinga2/status.dat".
1492   objects\_path   |**Optional.** Path to the objects.cache file. Defaults to LocalStateDir + "/cache/icinga2/objects.cache".
1493   update\_interval|**Optional.** The interval in which the status files are updated. Defaults to 15 seconds.
1494
1495
1496 ## SyslogLogger <a id="objecttype-sysloglogger"></a>
1497
1498 Specifies Icinga 2 logging to syslog.
1499
1500 Example:
1501
1502     object SyslogLogger "crit-syslog" {
1503       severity = "critical"
1504     }
1505
1506 Configuration Attributes:
1507
1508   Name            |Description
1509   ----------------|----------------
1510   severity        |**Optional.** The minimum severity for this log. Can be "debug", "notice", "information", "warning" or "critical". Defaults to "warning".
1511
1512
1513 ## TimePeriod <a id="objecttype-timeperiod"></a>
1514
1515 Time periods can be used to specify when hosts/services should be checked or to limit
1516 when notifications should be sent out.
1517
1518 Examples:
1519
1520     object TimePeriod "nonworkhours" {
1521       import "legacy-timeperiod"
1522
1523       display_name = "Icinga 2 TimePeriod for non working hours"
1524
1525       ranges = {
1526         monday = "00:00-8:00,17:00-24:00"
1527         tuesday = "00:00-8:00,17:00-24:00"
1528         wednesday = "00:00-8:00,17:00-24:00"
1529         thursday = "00:00-8:00,17:00-24:00"
1530         friday = "00:00-8:00,16:00-24:00"
1531         saturday = "00:00-24:00"
1532         sunday = "00:00-24:00"
1533       }
1534     }
1535
1536     object TimePeriod "exampledays" {
1537         import "legacy-timeperiod"
1538
1539         display_name = "Icinga 2 TimePeriod for random example days"
1540
1541         ranges = {
1542             //We still believe in Santa, no peeking!
1543             //Applies every 25th of December every year
1544             "december 25" = "00:00-24:00"
1545
1546             //Any point in time can be specified,
1547             //but you still have to use a range
1548             "2038-01-19" = "03:13-03:15"
1549
1550             //Evey 3rd day from the second monday of February
1551             //to 8th of November
1552             "monday 2 february - november 8 / 3" = "00:00-24:00"
1553         }
1554     }
1555
1556
1557 Additional examples can be found [here](08-advanced-topics.md#timeperiods).
1558
1559 Configuration Attributes:
1560
1561   Name            |Description
1562   ----------------|----------------
1563   display_name    |**Optional.** A short description of the time period.
1564   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.
1565   ranges          |**Required.** A dictionary containing information which days and durations apply to this timeperiod.
1566   prefer_includes |**Optional.** Boolean whether to prefer timeperiods `includes` or `excludes`. Default to true.
1567   excludes        |**Optional.** An array of timeperiods, which should exclude from your timerange.
1568   includes        |**Optional.** An array of timeperiods, which should include into your timerange
1569
1570 The `/etc/icinga2/conf.d/timeperiods.conf` file is usually used to define
1571 timeperiods including this one.
1572
1573 Runtime Attributes:
1574
1575   Name                      | Type          | Description
1576   --------------------------|---------------|-----------------
1577   is\_inside                | Boolean       | Whether we're currently inside this timeperiod.
1578
1579
1580 ## User <a id="objecttype-user"></a>
1581
1582 A user.
1583
1584 Example:
1585
1586     object User "icingaadmin" {
1587       display_name = "Icinga 2 Admin"
1588       groups = [ "icingaadmins" ]
1589       email = "icinga@localhost"
1590       pager = "icingaadmin@localhost.localdomain"
1591
1592       period = "24x7"
1593
1594       states = [ OK, Warning, Critical, Unknown ]
1595       types = [ Problem, Recovery ]
1596
1597       vars.additional_notes = "This is the Icinga 2 Admin account."
1598     }
1599
1600 Available notification state filters:
1601
1602     OK
1603     Warning
1604     Critical
1605     Unknown
1606     Up
1607     Down
1608
1609 Available notification type filters:
1610
1611     DowntimeStart
1612     DowntimeEnd
1613     DowntimeRemoved
1614     Custom
1615     Acknowledgement
1616     Problem
1617     Recovery
1618     FlappingStart
1619     FlappingEnd
1620
1621 Configuration Attributes:
1622
1623   Name            |Description
1624   ----------------|----------------
1625   display_name    |**Optional.** A short description of the user.
1626   email           |**Optional.** An email string for this user. Useful for notification commands.
1627   pager           |**Optional.** A pager string for this user. Useful for notification commands.
1628   vars            |**Optional.** A dictionary containing custom attributes that are specific to this user.
1629   groups          |**Optional.** An array of group names.
1630   enable_notifications|**Optional.** Whether notifications are enabled for this user.
1631   period          |**Optional.** The name of a time period which determines when a notification for this user should be triggered. Not set by default.
1632   types           |**Optional.** A set of type filters when this notification should be triggered. By default everything is matched.
1633   states          |**Optional.** A set of state filters when this notification should be triggered. By default everything is matched.
1634
1635 Runtime Attributes:
1636
1637   Name                      | Type          | Description
1638   --------------------------|---------------|-----------------
1639   last\_notification        | Number        | When the last notification was sent for this user (as a UNIX timestamp).
1640
1641 ## UserGroup <a id="objecttype-usergroup"></a>
1642
1643 A user group.
1644
1645 > **Best Practice**
1646 >
1647 > Assign user group members using the [group assign](17-language-reference.md#group-assign) rules.
1648
1649 Example:
1650
1651     object UserGroup "icingaadmins" {
1652         display_name = "Icinga 2 Admin Group"
1653     }
1654
1655 Configuration Attributes:
1656
1657   Name            |Description
1658   ----------------|----------------
1659   display_name    |**Optional.** A short description of the user group.
1660   groups          |**Optional.** An array of nested group names.
1661
1662
1663 ## Zone <a id="objecttype-zone"></a>
1664
1665 Zone objects are used to specify which Icinga 2 instances are located in a zone.
1666
1667 Example:
1668
1669     object Zone "config-ha-master" {
1670       endpoints = [ "icinga2a", "icinga2b" ]
1671
1672     }
1673
1674     object Zone "check-satellite" {
1675       endpoints = [ "icinga2c" ]
1676       parent = "config-ha-master"
1677     }
1678
1679 Configuration Attributes:
1680
1681   Name            |Description
1682   ----------------|----------------
1683   endpoints       |**Optional.** Array of endpoint names located in this zone.
1684   parent          |**Optional.** The name of the parent zone.
1685   global          |**Optional.** Whether configuration files for this zone should be synced to all endpoints. Defaults to false.
1686
1687 Zone objects cannot currently be created with the API.
1688
1689 # Value Types <a id="value-types"></a>
1690
1691 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).
1692
1693 ## CheckResult <a id="value-types-checkresult"></a>
1694
1695   Name                      | Type          | Description
1696   --------------------------|---------------|-----------------
1697   exit_status               | Number        | The exit status returned by the check execution.
1698   output                    | String        | The check output.
1699   performance_data          | Array         | Array of [performance data values](09-object-types.md#value-types-perfdatavalue).
1700   check_source              | String        | Name of the node executing the check.
1701   state                     | Number        | The current state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).
1702   command                   | Value         | Array of command with shell-escaped arguments or command line string.
1703   execution_start           | Number        | Check execution start time (as a UNIX timestamp).
1704   execution_end             | Number        | Check execution end time (as a UNIX timestamp).
1705   schedule_start            | Number        | Scheduled check execution start time (as a UNIX timestamp).
1706   schedule_end              | Number        | Scheduled check execution end time (as a UNIX timestamp).
1707   active                    | Boolean       | Whether the result is from an active or passive check.
1708   vars_before               | Dictionary    | Internal attribute used for calculations.
1709   vars_after                | Dictionary    | Internal attribute used for calculations.
1710
1711 ## PerfdataValue <a id="value-types-perfdatavalue"></a>
1712
1713 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)).
1714
1715   Name                      | Type          | Description
1716   --------------------------|---------------|-----------------
1717   label                     | String        | Performance data label.
1718   value                     | Number        | Normalized performance data value without unit.
1719   counter                   | Boolean       | Enabled if the original value contains `c` as unit. Defaults to `false`.
1720   unit                      | String        | Unit of measurement (`seconds`, `bytes`. `percent`) according to the [plugin API](05-service-monitoring.md#service-monitoring-plugin-api).
1721   crit                      | Value         | Critical threshold value.
1722   warn                      | Value         | Warning threshold value.
1723   min                       | Value         | Minimum value returned by the check.
1724   max                       | Value         | Maximum value returned by the check.
1725
1726