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

   1 ## <a id="object-types"></a> Object Types
   2
   3 ### <a id="objecttype-host"></a> Host
   4
   5 A host.
   6
   7 Example:
   8
   9     object Host "localhost" {
  10       display_name = "The best host there is"
  11
  12       groups = [ "all-hosts" ]
  13
  14       check_command = "hostalive"
  15     }
  16
  17 Attributes:
  18
  19   Name            |Description
  20   ----------------|----------------
  21   display_name    |**Optional.** A short description of the host.
  22   groups          |**Optional.** A list of host groups this host belongs to.
  23   vars            |**Optional.** A dictionary containing custom attributes that are specific to this host.
  24   check\_command  |**Required.** The name of the check command.
  25   max\_check\_attempts|**Optional.** The number of times a host is re-checked before changing into a hard state. Defaults to 3.
  26   check\_period   |**Optional.** The name of a time period which determines when this host should be checked. Not set by default.
  27   check\_interval |**Optional.** The check interval (in seconds). This interval is used for checks when the host is in a `HARD` state. Defaults to 5 minutes.
  28   retry\_interval |**Optional.** The retry interval (in seconds). This interval is used for checks when the host is in a `SOFT` state. Defaults to 1 minute.
  29   enable\_notifications|**Optional.** Whether notifications are enabled. Defaults to true.
  30   enable\_active\_checks|**Optional.** Whether active checks are enabled. Defaults to true.
  31   enable\_passive\_checks|**Optional.** Whether passive checks are enabled. Defaults to true.
  32   enable\_event\_handler|**Optional.** Enables event handlers for this host. Defaults to true.
  33   enable\_flap\_detection|**Optional.** Whether flap detection is enabled. Defaults to true.
  34   enable\_perfdata|**Optional.** Whether performance data processing is enabled. Defaults to true.
  35   event\_command  |**Optional.** The name of an event command that should be executed every time the host's state changes.
  36   flapping\_threshold|**Optional.** The flapping threshold in percent when a host is considered to be flapping.
  37   volatile        |**Optional.** The volatile setting enables always `HARD` state types if `NOT-OK` state changes occur.
  38   authorities     |**Optional.** A list of Endpoints on which this host check will be executed in a cluster scenario.
  39   domains         |**Optional.** A list of Domains for this host object in a cluster scenario.
  40
  41 ### <a id="objecttype-hostgroup"></a> HostGroup
  42
  43 A group of hosts.
  44
  45 Example:
  46
  47     object HostGroup "my-hosts" {
  48       display_name = "My hosts"
  49     }
  50
  51 Attributes:
  52
  53   Name            |Description
  54   ----------------|----------------
  55   display_name    |**Optional.** A short description of the host group.
  56
  57 ### <a id="objecttype-service"></a> Service
  58
  59 Service objects describe network services and how they should be checked
  60 by Icinga 2.
  61
  62 > **Best Practice**
  63 >
  64 > Rather than creating a `Service` object for a specific host it is usually easier
  65 > to just create a `Service` template and use the `apply` keyword to assign the
  66 > service to a number of hosts.
  67
  68 Example:
  69
  70     object Service "uptime" {
  71       host_name = "localhost"
  72
  73       display_name = "localhost Uptime"
  74
  75       check_command = "check_snmp"
  76
  77       vars = {
  78         community = "public"
  79         oid = "DISMAN-EVENT-MIB::sysUpTimeInstance"
  80       }
  81
  82       check_interval = 60s
  83       retry_interval = 15s
  84
  85       groups = [ "all-services", "snmp" ]
  86     }
  87
  88 Attributes:
  89
  90   Name            |Description
  91   ----------------|----------------
  92   host_name       |**Required.** The host this service belongs to. There must be a `Host` object with that name.
  93   name            |**Required.** The service name. Must be unique on a per-host basis (Similar to the service_description attribute in Icinga 1.x).
  94   groups          |**Optional.** The service groups this service belongs to.
  95
  96 In addition to these attributes you can also use any of the attributes which are also valid for `Host` objects.
  97
  98 Service objects have composite names, i.e. their names are based on the host_name attribute and the name you specified. This means
  99 you can define more than one object with the same (short) name as long as the `host_name` attribute has a different value.
 100
 101 ### <a id="objecttype-servicegroup"></a> ServiceGroup
 102
 103 A group of services.
 104
 105 Example:
 106
 107     object ServiceGroup "snmp" {
 108       display_name = "SNMP services"
 109     }
 110
 111 Attributes:
 112
 113   Name            |Description
 114   ----------------|----------------
 115   display_name    |**Optional.** A short description of the service group.
 116
 117 ### <a id="objecttype-notification"></a> Notification
 118
 119 Notification objects are used to specify how users should be notified in case
 120 of service state changes and other events.
 121
 122 > **Best Practice**
 123 >
 124 > Rather than creating a `Notification` object for a specific service it is usually easier
 125 > to just create a `Notification` template and use the `apply` keyword to assign the
 126 > notification to a number of services.
 127
 128 Example:
 129
 130     object Notification "localhost-ping-notification" {
 131       host_name = "localhost"
 132       service_name = "ping4"
 133
 134       notification_command = "mail-notification"
 135
 136       users = [ "user1", "user2" ]
 137
 138       notification_type_filter = [ Problem, Recovery ]
 139     }
 140
 141 Attributes:
 142
 143   Name                      | Description
 144   --------------------------|----------------
 145   host_name                 | **Required.** The name of the host this notification belongs to.
 146   service_name              | **Required.** The short name of the service this notification belongs to.
 147   vars                      | **Optional.** A dictionary containing custom attributes that are specific to this notification object.
 148   users                     | **Optional.** A list of user names who should be notified.
 149   user_groups               | **Optional.** A list of user group names who should be notified.
 150   times                     | **Optional.** A dictionary containing `begin` and `end` attributes for the notification.
 151   notification_command      | **Required.** The name of the notification command which should be executed when the notification is triggered.
 152   notification_interval     | **Optional.** The notification interval (in seconds). This interval is used for active notifications. Defaults to 5 minutes.
 153   notification_period       | **Optional.** The name of a time period which determines when this notification should be triggered. Not set by default.
 154   notification_type_filter  | **Optional.** A list of state filters when this notification should be triggered. By default everything is matched.
 155   notification_state_filter | **Optional.** A list of type filters when this notification should be triggered. By default everything is matched.
 156
 157 Available notification state filters:
 158
 159     OK
 160     Warning
 161     Critical
 162     Unknown
 163     Up
 164     Down
 165
 166 Available notification type filters:
 167
 168     DowntimeStart
 169     DowntimeEnd
 170     DowntimeRemoved
 171     Custom
 172     Acknowledgement
 173     Problem
 174     Recovery
 175     FlappingStart
 176     FlappingEnd
 177
 178 ### <a id="objecttype-dependency"></a> Dependency
 179
 180 Dependency objects are used to specify dependencies between hosts and services.
 181
 182 > **Best Practice**
 183 >
 184 > Rather than creating a `Dependency` object for a specific service it is usually easier
 185 > to just create a `Dependency` template and use the `apply` keyword to assign the
 186 > dependency to a number of services.
 187
 188 Example:
 189
 190     object Dependency "webserver-internet" {
 191       child_host_name = "webserver"
 192       child_service_name = "ping4"
 193
 194       parent_host_name = "internet"
 195       parent_service_name = "ping4"
 196
 197       state_filter = [ OK, Warning ]
 198
 199       disable_checks = true
 200     }
 201
 202 Attributes:
 203
 204   Name            |Description
 205   ----------------|----------------
 206   parent_host_name     |**Required.** The parent host.
 207   parent_service_name  |**Optional.** The parent service. When not specified the host's check service is used.
 208   child_host_name      |**Required.** The child host.
 209   child_service_name   |**Optional.** The child service. When not specified the host's check service is used.
 210   disable_checks  |**Optional.** Whether to disable checks when this dependency fails. Defaults to false.
 211   disable_notifications|**Optional.** Whether to disable notifications when this dependency fails. Defaults to true.
 212   period          |**Optional.** Time period during which this dependency is enabled.
 213   state_filter    |**Optional.** A list of type filters when this dependency should be OK. Defaults to [ OK, Warning ] for services and [ Up ] for hosts.
 214
 215 Available state filters:
 216
 217     OK
 218     Warning
 219     Critical
 220     Unknown
 221     Up
 222     Down
 223
 224 Dependency objects have composite names, i.e. their names are based on the `child_host_name` and `child_service_name` attributes and the
 225 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
 226 `child_service_name` attributes has a different value.
 227
 228 ### <a id="objecttype-user"></a> User
 229
 230 A user.
 231
 232 Example:
 233
 234     object User "icingaadmin" {
 235       display_name = "Icinga 2 Admin"
 236       groups = [ "icingaadmins" ]
 237
 238       enable_notifications = 1
 239       notification_period = "24x7"
 240
 241       notification_state_filter = [ OK, Warning, Critical, Unknown ]
 242       notification_type_filter = [ Problem, Recovery ]
 243
 244       vars = {
 245         name = "Icinga 2 Admin"
 246         email = "icinga@localhost"
 247         pager = "icingaadmin@localhost.localdomain"
 248       }
 249
 250       custom = {
 251         notes = "This is the Icinga 2 Admin account."
 252       }
 253     }
 254
 255 Available notification state filters:
 256
 257     OK
 258     Warning
 259     Critical
 260     Unknown
 261     Up
 262     Down
 263
 264 Available notification type filters:
 265
 266     DowntimeStart
 267     DowntimeEnd
 268     DowntimeRemoved
 269     Custom
 270     Acknowledgement
 271     Problem
 272     Recovery
 273     FlappingStart
 274     FlappingEnd
 275
 276 Attributes:
 277
 278   Name            |Description
 279   ----------------|----------------
 280   display_name    |**Optional.** A short description of the user.
 281   vars            |**Optional.** A dictionary containing custom attributes that are specific to this user.
 282   groups          |**Optional.** An array of group names.
 283   enable_notifications|**Optional.** Whether notifications are enabled for this user.
 284   notification_period|**Optional.** The name of a time period which determines when this notification should be triggered. Not set by default.
 285   notification_type_filter|**Optional.** A set of state filters when this notification should be triggered. By default everything is matched.
 286   notification_state_filter|**Optional.** A set of type filters when this notification should be triggered. By default everything is matched.
 287
 288 ### <a id="objecttype-usergroup"></a> UserGroup
 289
 290 A user group.
 291
 292 Example:
 293
 294     object UserGroup "icingaadmins" {
 295         display_name = "Icinga 2 Admin Group"
 296     }
 297
 298 Attributes:
 299
 300   Name            |Description
 301   ----------------|----------------
 302   display_name    |**Optional.** A short description of the user group.
 303
 304 ### <a id="objecttype-timeperiod"></a> TimePeriod
 305
 306 Time periods can be used to specify when services should be checked or to limit
 307 when notifications should be sent out.
 308
 309 Example:
 310
 311     object TimePeriod "24x7" {
 312       import "legacy-timeperiod"
 313
 314       display_name = "Icinga 2 24x7 TimePeriod"
 315
 316       ranges = {
 317         monday = "00:00-24:00"
 318         tuesday = "00:00-24:00"
 319         wednesday = "00:00-24:00"
 320         thursday = "00:00-24:00"
 321         friday = "00:00-24:00"
 322         saturday = "00:00-24:00"
 323         sunday = "00:00-24:00"
 324       }
 325     }
 326
 327 Attributes:
 328
 329   Name            |Description
 330   ----------------|----------------
 331   display_name    |**Optional.** A short description of the time period.
 332   methods         |**Required.** The "update" script method takes care of updating the internal representation of the time period. In virtually all cases you should import the "legacy-timeperiod" template to take care of this setting.
 333   ranges          |**Required.** A dictionary containing information which days and durations apply to this timeperiod.
 334
 335 The `/etc/icinga2/conf.d/timeperiods.conf` file is usually used to define
 336 timeperiods including this one.
 337
 338 ### <a id="objecttype-scheduleddowntime"></a> ScheduledDowntime
 339
 340 ScheduledDowntime objects can be used to set up recurring downtimes for services.
 341
 342 > **Best Practice**
 343 >
 344 > Rather than creating a `ScheduledDowntime` object for a specific service it is usually easier
 345 > to just create a `ScheduledDowntime` template and use the `apply` keyword to assign the
 346 > scheduled downtime to a number of services.
 347
 348 Example:
 349
 350     object ScheduledDowntime "some-downtime" {
 351       host_name = "localhost"
 352       service_name = "ping4"
 353
 354       author = "icingaadmin"
 355       comment = "Some comment"
 356
 357       fixed = false
 358       duration = 30m
 359
 360       ranges = {
 361         "sunday" = "02:00-03:00"
 362       }
 363     }
 364
 365 Attributes:
 366
 367   Name            |Description
 368   ----------------|----------------
 369   host_name       |**Required.** The name of the host this notification belongs to.
 370   service_name    |**Required.** The short name of the service this notification belongs to.
 371   author          |**Required.** The author of the downtime.
 372   comment         |**Required.** A comment for the downtime.
 373   fixed           |**Optional.** Whether this is a fixed downtime. Defaults to true.
 374   duration        |**Optional.** How long the downtime lasts. Only has an effect for flexible (non-fixed) downtimes.
 375   ranges          |**Required.** A dictionary containing information which days and durations apply to this timeperiod.
 376
 377 ScheduledDowntime objects have composite names, i.e. their names are based
 378 on the `host_name` and `service_name` attributes and the
 379 name you specified. This means you can define more than one object
 380 with the same (short) name as long as one of the `host_name` and
 381 `service_name` attributes has a different value.
 382
 383 ### <a id="objecttype-filelogger"></a> FileLogger
 384
 385 Specifies Icinga 2 logging to a file.
 386
 387 Example:
 388
 389     object FileLogger "my-debug-file" {
 390       severity = "debug"
 391       path = "/var/log/icinga2/icinga2-debug.log"
 392     }
 393
 394 Attributes:
 395
 396   Name            |Description
 397   ----------------|----------------
 398   path            |**Required.** The log path.
 399   severity        |**Optional.** The minimum severity for this log. Can be "debug", "information", "warning" or "critical". Defaults to "information".
 400
 401 ### <a id="objecttype-sysloglogger"></a> SyslogLogger
 402
 403 Specifies Icinga 2 logging to syslog.
 404
 405 Example:
 406
 407     object SyslogLogger "my-crit-syslog" {
 408       severity = "critical"
 409     }
 410
 411 Attributes:
 412
 413   Name            |Description
 414   ----------------|----------------
 415   severity        |**Optional.** The minimum severity for this log. Can be "debug", "information", "warning" or "critical". Defaults to "information".
 416
 417 ### <a id="objecttype-checkcommand"></a> CheckCommand
 418
 419 A check command definition. Additional default command custom attributes can be
 420 defined here.
 421
 422 Example:
 423
 424     object CheckCommand "check_snmp" {
 425       import "plugin-check-command"
 426
 427       command = [
 428         PluginDir + "/check_snmp",
 429         "-H", "$address$",
 430         "-C", "$community$",
 431         "-o", "$oid$"
 432       ]
 433
 434       vars = {
 435         address = "127.0.0.1"
 436         community = "public"
 437       }
 438     }
 439
 440 Attributes:
 441
 442   Name            |Description
 443   ----------------|----------------
 444   methods         |**Required.** The "execute" script method takes care of executing the check. In virtually all cases you should import the "plugin-check-command" template to take care of this setting.
 445   command         |**Required.** The command. This can either be an array of individual command arguments. Alternatively a string can be specified in which case the shell interpreter (usually /bin/sh) takes care of parsing the command.
 446   env             |**Optional.** A dictionary of macros which should be exported as environment variables prior to executing the command.
 447   vars            |**Optional.** A dictionary containing custom attributes that are specific to this command.
 448   timeout         |**Optional.** The command timeout in seconds. Defaults to 5 minutes.
 449
 450 ### <a id="objecttype-notificationcommand"></a> NotificationCommand
 451
 452 A notification command definition.
 453
 454 Example:
 455
 456     object NotificationCommand "mail-service-notification" {
 457       import "plugin-notification-command"
 458
 459       command = [
 460         SysconfDir + "/icinga2/scripts/mail-notification.sh"
 461       ]
 462
 463       env = {
 464         "NOTIFICATIONTYPE" = "$notification.type$"
 465         "SERVICEDESC" = "$service.description$"
 466         "HOSTALIAS" = "$host.displayname$",
 467         "HOSTADDRESS" = "$host.vars.address$",
 468         "SERVICESTATE" = "$service.state$",
 469         "LONGDATETIME" = "$icinga.longdatetime$",
 470         "SERVICEOUTPUT" = "$service.output$",
 471         "NOTIFICATIONAUTHORNAME" = "$notification.author$",
 472         "NOTIFICATIONCOMMENT" = "$notification.comment$",
 473         "HOSTDISPLAYNAME" = "$host.displayname$",
 474         "SERVICEDISPLAYNAME" = "$service.displayname$",
 475         "USEREMAIL" = "$user.vars.email$"
 476       }
 477     }
 478
 479 Attributes:
 480
 481   Name            |Description
 482   ----------------|----------------
 483   methods         |**Required.** The "execute" script method takes care of executing the notification. In virtually all cases you should import the "plugin-notification-command" template to take care of this setting.
 484   command         |**Required.** The command. This can either be an array of individual command arguments. Alternatively a string can be specified in which case the shell interpreter (usually /bin/sh) takes care of parsing the command.
 485   env             |**Optional.** A dictionary of macros which should be exported as environment variables prior to executing the command.
 486   vars            |**Optional.** A dictionary containing custom attributes that are specific to this command.
 487   timeout         |**Optional.** The command timeout in seconds. Defaults to 5 minutes.
 488
 489 ### <a id="objecttype-eventcommand"></a> EventCommand
 490
 491 An event command definition.
 492
 493 Example:
 494
 495     object EventCommand "restart-httpd-event" {
 496       import "plugin-event-command"
 497
 498       command = "/opt/bin/restart-httpd.sh"
 499     }
 500
 501
 502 Attributes:
 503
 504   Name            |Description
 505   ----------------|----------------
 506   methods         |**Required.** The "execute" script method takes care of executing the event handler. In virtually all cases you should import the "plugin-event-command" template to take care of this setting.
 507   command         |**Required.** The command. This can either be an array of individual command arguments. Alternatively a string can be specified in which case the shell interpreter (usually /bin/sh) takes care of parsing the command.
 508   env             |**Optional.** A dictionary of macros which should be exported as environment variables prior to executing the command.
 509   vars            |**Optional.** A dictionary containing custom attributes that are specific to this command.
 510   timeout         |**Optional.** The command timeout in seconds. Defaults to 5 minutes.
 511
 512 ### <a id="objecttype-perfdatawriter"></a> PerfdataWriter
 513
 514 Writes check result performance data to a defined path using macro
 515 pattern.
 516
 517 Example:
 518
 519     library "perfdata"
 520
 521     object PerfdataWriter "pnp" {
 522       host_perfdata_path = "/var/spool/icinga2/perfdata/host-perfdata"
 523
 524       service_perfdata_path = "/var/spool/icinga2/perfdata/service-perfdata"
 525
 526       host_format_template = "DATATYPE::HOSTPERFDATA\tTIMET::$icinga.timet$\tHOSTNAME::$host.name$\tHOSTPERFDATA::$host.perfdata$\tHOSTCHECKCOMMAND::$host.checkcommand$\tHOSTSTATE::$host.state$\tHOSTSTATETYPE::$host.statetype$"
 527       service_format_template = "DATATYPE::SERVICEPERFDATA\tTIMET::$icinga.timet$\tHOSTNAME::$host.name$\tSERVICEDESC::$service.description$\tSERVICEPERFDATA::$service.perfdata$\tSERVICECHECKCOMMAND::$service.checkcommand$\tHOSTSTATE::$host.state$\tHOSTSTATETYPE::$host.statetype$\tSERVICESTATE::$service.state$\tSERVICESTATETYPE::$service.statetype$"
 528
 529       rotation_interval = 15s
 530     }
 531
 532 Attributes:
 533
 534   Name                    |Description
 535   ------------------------|----------------
 536   host_perfdata\_path     |**Optional.** Path to the host performance data file. Defaults to LocalStateDir + "/spool/icinga2/perfdata/host-perfdata".
 537   service_perfdata\_path  |**Optional.** Path to the service performance data file. Defaults to LocalStateDir + "/spool/icinga2/perfdata/service-perfdata".
 538   host_temp\_path         |**Optional.** Path to the temporary host file. Defaults to LocalStateDir + "/spool/icinga2/tmp/host-perfdata".
 539   service_temp\_path      |**Optional.** Path to the temporary service file. Defaults to LocalStateDir + "/spool/icinga2/tmp/service-perfdata".
 540   host_format\_template   |**Optional.** Host Format template for the performance data file. Defaults to a template that's suitable for use with PNP4Nagios.
 541   service_format\_template|**Optional.** Service Format template for the performance data file. Defaults to a template that's suitable for use with PNP4Nagios.
 542   rotation\_interval      |**Optional.** Rotation interval for the files specified in `{host,service}\_perfdata\_path`. Defaults to 30 seconds.
 543
 544 When rotating the performance data file the current UNIX timestamp is appended to the path specified
 545 in `host_perfdata\_path` and `service_perfdata\_path` to generate a unique filename.
 546
 547 ### <a id="objecttype-graphitewriter"></a> GraphiteWriter
 548
 549 Writes check result metrics and performance data to a defined
 550 Graphite Carbon host.
 551
 552 Example:
 553
 554     library "perfdata"
 555
 556     object GraphiteWriter "graphite" {
 557       host = "127.0.0.1"
 558       port = 2003
 559     }
 560
 561 Attributes:
 562
 563   Name            |Description
 564   ----------------|----------------
 565   host            |**Optional.** Graphite Carbon host address. Defaults to '127.0.0.1'.
 566   port            |**Optional.** Graphite Carbon port. Defaults to 2003.
 567
 568 ### <a id="objecttype-idomysqlconnection"></a> IdoMySqlConnection
 569
 570 IDO database adapter for MySQL.
 571
 572 Example:
 573
 574     library "db_ido_mysql"
 575
 576     object IdoMysqlConnection "mysql-ido" {
 577       host = "127.0.0.1"
 578       port = 3306
 579       user = "icinga"
 580       password = "icinga"
 581       database = "icinga"
 582       table_prefix = "icinga_"
 583       instance_name = "icinga2"
 584       instance_description = "icinga2 dev instance"
 585
 586       cleanup = {
 587         downtimehistory_age = 48h
 588         logentries_age = 31d
 589       }
 590
 591       categories = DbCatConfig | DbCatState
 592     }
 593
 594 Attributes:
 595
 596   Name            |Description
 597   ----------------|----------------
 598   host            |**Optional.** MySQL database host address. Defaults to "localhost".
 599   port            |**Optional.** MySQL database port. Defaults to 3306.
 600   user            |**Optional.** MySQL database user with read/write permission to the icinga database. Defaults to "icinga".
 601   password        |**Optional.** MySQL database user's password. Defaults to "icinga".
 602   database        |**Optional.** MySQL database name. Defaults to "icinga".
 603   table\_prefix   |**Optional.** MySQL database table prefix. Defaults to "icinga\_".
 604   instance\_name  |**Optional.** Unique identifier for the local Icinga 2 instance. Defaults to "default".
 605   instance\_description|**Optional.** Description for the Icinga 2 instance.
 606   cleanup         |**Optional.** Dictionary with items for historical table cleanup.
 607   categories      |**Optional.** The types of information that should be written to the database.
 608
 609 Cleanup Items:
 610
 611   Name            | Description
 612   ----------------|----------------
 613   acknowledgements_age |**Optional.** Max age for acknowledgements table rows (entry_time). Defaults to 0 (never).
 614   commenthistory_age |**Optional.** Max age for commenthistory table rows (entry_time). Defaults to 0 (never).
 615   contactnotifications_age |**Optional.** Max age for contactnotifications table rows (start_time). Defaults to 0 (never).
 616   contactnotificationmethods_age |**Optional.** Max age for contactnotificationmethods table rows (start_time). Defaults to 0 (never).
 617   downtimehistory_age |**Optional.** Max age for downtimehistory table rows (entry_time). Defaults to 0 (never).
 618   eventhandlers_age |**Optional.** Max age for eventhandlers table rows (start_time). Defaults to 0 (never).
 619   externalcommands_age |**Optional.** Max age for externalcommands table rows (entry_time). Defaults to 0 (never).
 620   flappinghistory_age |**Optional.** Max age for flappinghistory table rows (event_time). Defaults to 0 (never).
 621   hostchecks_age |**Optional.** Max age for hostalives table rows (start_time). Defaults to 0 (never).
 622   logentries_age |**Optional.** Max age for logentries table rows (logentry_time). Defaults to 0 (never).
 623   notifications_age |**Optional.** Max age for notifications table rows (start_time). Defaults to 0 (never).
 624   processevents_age |**Optional.** Max age for processevents table rows (event_time). Defaults to 0 (never).
 625   statehistory_age |**Optional.** Max age for statehistory table rows (state_time). Defaults to 0 (never).
 626   servicechecks_age |**Optional.** Max age for servicechecks table rows (start_time). Defaults to 0 (never).
 627   systemcommands_age |**Optional.** Max age for systemcommands table rows (start_time). Defaults to 0 (never).
 628
 629 Data Categories:
 630
 631   Name                 | Description
 632   ---------------------|----------------
 633   DbCatConfig          | Configuration data
 634   DbCatState           | Current state data
 635   DbCatAcknowledgement | Acknowledgements
 636   DbCatComment         | Comments
 637   DbCatDowntime        | Downtimes
 638   DbCatEventHandler    | Event handler data
 639   DbCatExternalCommand | External commands
 640   DbCatFlapping        | Flap detection data
 641   DbCatCheck           | Check results
 642   DbCatLog             | Log messages
 643   DbCatNotification    | Notifications
 644   DbCatProgramStatus   | Program status data
 645   DbCatRetention       | Retention data
 646   DbCatStateHistory    | Historical state data
 647
 648 Multiple categories can be combined using the `|` operator. In addition to
 649 the category flags listed above the `DbCatEverything` flag may be used as
 650 a shortcut for listing all flags.
 651
 652 ### <a id="objecttype-idomysqlconnection"></a> IdoPgSqlConnection
 653
 654 IDO database adapter for PostgreSQL.
 655
 656 Example:
 657
 658     library "db_ido_pgsql"
 659
 660     object IdoMysqlConnection "pgsql-ido" {
 661       host = "127.0.0.1"
 662       port = 5432
 663       user = "icinga"
 664       password = "icinga"
 665       database = "icinga"
 666       table_prefix = "icinga_"
 667       instance_name = "icinga2"
 668       instance_description = "icinga2 dev instance"
 669
 670       cleanup = {
 671         downtimehistory_age = 48h
 672         logentries_age = 31d
 673       }
 674
 675       categories = DbCatConfig | DbCatState
 676     }
 677
 678 Attributes:
 679
 680   Name            |Description
 681   ----------------|----------------
 682   host            |**Optional.** PostgreSQL database host address. Defaults to "localhost".
 683   port            |**Optional.** PostgreSQL database port. Defaults to "5432".
 684   user            |**Optional.** PostgreSQL database user with read/write permission to the icinga database. Defaults to "icinga".
 685   password        |**Optional.** PostgreSQL database user's password. Defaults to "icinga".
 686   database        |**Optional.** PostgreSQL database name. Defaults to "icinga".
 687   table\_prefix   |**Optional.** PostgreSQL database table prefix. Defaults to "icinga\_".
 688   instance\_name  |**Optional.** Unique identifier for the local Icinga 2 instance. Defaults to "default".
 689   instance\_description|**Optional.** Description for the Icinga 2 instance.
 690   cleanup         |**Optional.** Dictionary with items for historical table cleanup.
 691   categories      |**Optional.** The types of information that should be written to the database.
 692
 693 Cleanup Items:
 694
 695   Name            | Description
 696   ----------------|----------------
 697   acknowledgements_age |**Optional.** Max age for acknowledgements table rows (entry_time). Defaults to 0 (never).
 698   commenthistory_age |**Optional.** Max age for commenthistory table rows (entry_time). Defaults to 0 (never).
 699   contactnotifications_age |**Optional.** Max age for contactnotifications table rows (start_time). Defaults to 0 (never).
 700   contactnotificationmethods_age |**Optional.** Max age for contactnotificationmethods table rows (start_time). Defaults to 0 (never).
 701   downtimehistory_age |**Optional.** Max age for downtimehistory table rows (entry_time). Defaults to 0 (never).
 702   eventhandlers_age |**Optional.** Max age for eventhandlers table rows (start_time). Defaults to 0 (never).
 703   externalcommands_age |**Optional.** Max age for externalcommands table rows (entry_time). Defaults to 0 (never).
 704   flappinghistory_age |**Optional.** Max age for flappinghistory table rows (event_time). Defaults to 0 (never).
 705   hostchecks_age |**Optional.** Max age for hostalives table rows (start_time). Defaults to 0 (never).
 706   logentries_age |**Optional.** Max age for logentries table rows (logentry_time). Defaults to 0 (never).
 707   notifications_age |**Optional.** Max age for notifications table rows (start_time). Defaults to 0 (never).
 708   processevents_age |**Optional.** Max age for processevents table rows (event_time). Defaults to 0 (never).
 709   statehistory_age |**Optional.** Max age for statehistory table rows (state_time). Defaults to 0 (never).
 710   servicechecks_age |**Optional.** Max age for servicechecks table rows (start_time). Defaults to 0 (never).
 711   systemcommands_age |**Optional.** Max age for systemcommands table rows (start_time). Defaults to 0 (never).
 712
 713 Data Categories:
 714
 715   Name                 | Description
 716   ---------------------|----------------
 717   DbCatConfig          | Configuration data
 718   DbCatState           | Current state data
 719   DbCatAcknowledgement | Acknowledgements
 720   DbCatComment         | Comments
 721   DbCatDowntime        | Downtimes
 722   DbCatEventHandler    | Event handler data
 723   DbCatExternalCommand | External commands
 724   DbCatFlapping        | Flap detection data
 725   DbCatCheck           | Check results
 726   DbCatLog             | Log messages
 727   DbCatNotification    | Notifications
 728   DbCatProgramStatus   | Program status data
 729   DbCatRetention       | Retention data
 730   DbCatStateHistory    | Historical state data
 731
 732 Multiple categories can be combined using the `|` operator. In addition to
 733 the category flags listed above the `DbCatEverything` flag may be used as
 734 a shortcut for listing all flags.
 735
 736 ### <a id="objecttype-livestatuslistener"></a> LiveStatusListener
 737
 738 Livestatus API interface available as TCP or UNIX socket. Historical table queries
 739 require the `CompatLogger` feature enabled pointing to the log files using the
 740 `compat_log_path` configuration attribute.
 741
 742 Example:
 743
 744     library "livestatus"
 745
 746     object LivestatusListener "livestatus-tcp" {
 747       socket_type = "tcp"
 748       bind_host = "127.0.0.1"
 749       bind_port = "6558"
 750     }
 751
 752     object LivestatusListener "livestatus-unix" {
 753       socket_type = "unix"
 754       socket_path = "/var/run/icinga2/cmd/livestatus"
 755     }
 756
 757 Attributes:
 758
 759   Name            |Description
 760   ----------------|----------------
 761   socket\_type      |**Optional.** Specifies the socket type. Can be either "tcp" or "unix". Defaults to "unix".
 762   bind\_host        |**Optional.** Only valid when socket\_type is "tcp". Host address to listen on for connections. Defaults to "127.0.0.1".
 763   bind\_port        |**Optional.** Only valid when `socket\_type` is "tcp". Port to listen on for connections. Defaults to 6558.
 764   socket\_path      |**Optional.** Only valid when `socket\_type` is "unix". Specifies the path to the UNIX socket file. Defaults to LocalStateDir + "/run/icinga2/cmd/livestatus".
 765   compat\_log\_path |**Optional.** Required for historical table queries. Requires `CompatLogger` feature enabled. Defaults to LocalStateDir + "/log/icinga2/compat"
 766
 767 > **Note**
 768 >
 769 > UNIX sockets are not supported on Windows.
 770
 771 ### <a id="objecttype-statusdatawriter"></a> StatusDataWriter
 772
 773 Periodically writes status data files which are used by the Classic UI and other third-party tools.
 774
 775 Example:
 776
 777     library "compat"
 778
 779     object StatusDataWriter "status" {
 780         status\_path = "/var/cache/icinga2/status.dat"
 781         objects\_path = "/var/cache/icinga2/objects.path"
 782         update\_interval = 30s
 783     }
 784
 785 Attributes:
 786
 787   Name            |Description
 788   ----------------|----------------
 789   status\_path    |**Optional.** Path to the status.dat file. Defaults to LocalStateDir + "/cache/icinga2/status.dat".
 790   objects\_path   |**Optional.** Path to the objects.cache file. Defaults to LocalStateDir + "/cache/icinga2/objects.cache".
 791   update\_interval|**Optional.** The interval in which the status files are updated. Defaults to 15 seconds.
 792
 793 ### <a id="objecttype-externalcommandlistener"></a> ExternalCommandListener
 794
 795 Implements the Icinga 1.x command pipe which can be used to send commands to Icinga.
 796
 797 Example:
 798
 799     library "compat"
 800
 801     object ExternalCommandListener "external" {
 802         command\_path = "/var/run/icinga2/cmd/icinga2.cmd"
 803     }
 804
 805 Attributes:
 806
 807   Name            |Description
 808   ----------------|----------------
 809   command\_path   |**Optional.** Path to the command pipe. Defaults to LocalStateDir + "/run/icinga2/cmd/icinga2.cmd".
 810
 811 ### <a id="objecttype-compatlogger"></a> CompatLogger
 812
 813 Writes log files in a format that's compatible with Icinga 1.x.
 814
 815 Example:
 816
 817     library "compat"
 818
 819     object CompatLogger "my-log" {
 820       log\_dir = "/var/log/icinga2/compat"
 821       rotation\_method = "HOURLY"
 822     }
 823
 824 Attributes:
 825
 826   Name            |Description
 827   ----------------|----------------
 828   log\_dir        |**Optional.** Path to the compat log directory. Defaults to LocalStateDir + "/log/icinga2/compat".
 829   rotation\_method|**Optional.** Specifies when to rotate log files. Can be one of "HOURLY", "DAILY", "WEEKLY" or "MONTHLY". Defaults to "HOURLY".
 830
 831 ### <a id="objecttype-checkresultreader"></a> CheckResultReader
 832
 833 Reads Icinga 1.x check results from a directory. This functionality is provided
 834 to help existing Icinga 1.x users and might be useful for certain cluster
 835 scenarios.
 836
 837 Example:
 838
 839     library "compat"
 840
 841     object CheckResultReader "reader" {
 842       spool_dir = "/data/check-results"
 843     }
 844
 845 Attributes:
 846
 847   Name            |Description
 848   ----------------|----------------
 849   spool\_dir      |**Optional.** The directory which contains the check result files. Defaults to LocalStateDir + "/lib/icinga2/spool/checkresults/".
 850
 851 ### <a id="objecttype-checkcomponent"></a> CheckerComponent
 852
 853 The checker component is responsible for scheduling active checks. There are no configurable options.
 854
 855 Example:
 856
 857     library "checker"
 858
 859     object CheckerComponent "checker" { }
 860
 861 ### <a id="objecttype-notificationcomponent"></a> NotificationComponent
 862
 863 The notification component is responsible for sending notifications. There are no configurable options.
 864
 865 Example:
 866
 867     library "notification"
 868
 869     object NotificationComponent "notification" { }
 870
 871 ### <a id="objecttype-icingastatuswriter"></a> IcingaStatusWriter
 872
 873 The IcingaStatusWriter feature periodically dumps the current status
 874 and performance data from Icinga 2 and all registered features into
 875 a defined JSON file.
 876
 877 Example:
 878
 879     object IcingaStatusWriter "status" {
 880       status_path = LocalStateDir + "/cache/icinga2/status.json"
 881       update_interval = 15s
 882     }
 883
 884 Attributes:
 885
 886   Name                      |Description
 887   --------------------------|--------------------------
 888   status\_path              |**Optional.** Path to cluster status file. Defaults to LocalStateDir + "/cache/icinga2/status.json"
 889   update\_interval          |**Optional.** The interval in which the status files are updated. Defaults to 15 seconds.
 890
 891 ### <a id="objecttype-clusterlistener"></a> ClusterListener
 892
 893 ClusterListener objects are used to specify remote cluster
 894 node peers and the certificate files used for ssl
 895 authorization.
 896
 897 Example:
 898
 899     library "cluster"
 900
 901     object ClusterListener "cluster" {
 902       ca_path = "/etc/icinga2/ca/ca.crt"
 903       cert_path = "/etc/icinga2/ca/icinga-node-1.crt"
 904       key_path = "/etc/icinga2/ca/icinga-node-1.key"
 905
 906       bind_port = 8888
 907
 908       peers = [ "icinga-node-2" ]
 909     }
 910
 911 Attributes:
 912
 913   Name                      |Description
 914   --------------------------|--------------------------
 915   cert\_path                |**Required.** Path to the public key.
 916   key\_path                 |**Required.** Path to the private key.
 917   ca\_path                  |**Required.** Path to the CA certificate file.
 918   crl\_path                 |**Optional.** Path to the CRL file.
 919   bind\_host                |**Optional.** The IP address the cluster listener should be bound to.
 920   bind\_port                |**Optional.** The port the cluster listener should be bound to.
 921   peers                     |**Optional.** A list of
 922
 923 ### <a id="objecttype-endpoint"></a> Endpoint
 924
 925 Endpoint objects are used to specify connection information for remote
 926 Icinga 2 instances.
 927
 928 Example:
 929
 930     library "cluster"
 931
 932     object Endpoint "icinga-c2" {
 933       host = "192.168.5.46"
 934       port = 7777
 935
 936       config_files = [ "/etc/icinga2/cluster.d/*" ]
 937
 938       config_files_recursive = [
 939         "/etc/icinga2/cluster2",
 940         { path = "/etc/icinga2/cluster3"; pattern = "*.myconf" }
 941       ]
 942     }
 943
 944 Attributes:
 945
 946   Name            |Description
 947   ----------------|----------------
 948   host            |**Required.** The hostname/IP address of the remote Icinga 2 instance.
 949   port            |**Required.** The service name/port of the remote Icinga 2 instance.
 950   config\_files   |**Optional.** A list of configuration files sent to remote peers (wildcards possible).
 951   config_files_recursive |**Optional.** A list of configuration files sent to remote peers. Array elements can either be a string (in which case all files in that directory matching the pattern *.conf are included) or a dictionary with elements "path" and "pattern".
 952   accept\_config  |**Optional.** A list of endpoint names from which this endpoint accepts configuration files.
 953
 954 ### <a id="objecttype-domain"></a> Domain
 955
 956 A [Service](#objecttype-service) object can be restricted using the `domains` attribute
 957 array specifying endpoint privileges.
 958
 959 A Domain object specifices the ACLs applied for each [Endpoint](#objecttype-endpoint).
 960
 961 Example:
 962
 963     object Domain "dmz-1" {
 964       acl = {
 965         node1 = DomainPrivCheckResult
 966         node2 = DomainPrivReadWrite
 967       }
 968     }
 969
 970 Attributes:
 971
 972   Name            |Description
 973   ----------------|----------------
 974   acl             |**Required.** Dictionary with items for Domain ACLs.
 975
 976 Domain ACLs:
 977
 978   Name                  |Description
 979   ----------------------|----------------
 980   DomainPrivRead        | Endpoint reads local messages and relays them to remote nodes.
 981   DomainPrivCheckResult | Endpoint accepts check result messages from remote nodes.
 982   DomainPrivCommand     | Endpoint accepts command messages from remote nodes.
 983   DomainPrevReadOnly    | Equivalent to DomainPrivRead.
 984   DomainPrivReadWrite   | Equivalent to DomainPrivRead &#124; DomainPrivCheckResult &#124; DomainPrivCommand.