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