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