## Object Types

### <a id="objecttype-host"></a> Host

A host.

> **Note**
>
> Unlike in Icinga 1.x hosts are not checkable objects in Icinga 2. Instead
> hosts inherit their state from the service that is specified using the `check`
> attribute.

Example:

    object Host "localhost" {
      display_name = "The best host there is",

      groups = [ "all-hosts" ],

      host_dependencies = [ "router" ],

      service_dependencies = [
        { host = "db-server", service = "mysql" }
      ],

      services["ping"] = {
        templates = [ "ping" ]
      },

      services["http"] = {
        templates = [ "my-http" ],

        macros = {
          vhost = "test1.example.org",
          port = 81
        }
      },

      check = "ping"
    }

Attributes:

  Name            |Description
  ----------------|----------------
  display_name    |**Optional.** A short description of the host.
  check           |**Optional.** A service that is used to determine whether the host is up or down. This must be a service short name of a service that belongs to the host.
  groups          |**Optional.** A list of host groups this host belongs to.
  host_dependencies|**Optional.** A list of host names which this host depends on. These dependencies are used to determine whether the host is unreachable.
  service_dependencies|**Optional.** A list of services which this host depends on. Each array element must be a dictionary containing the keys "host" and "service". These dependencies are used to determine whether the host is unreachable.
  services        |**Optional.** Inline definition of services. Each dictionary item specifies a service.<br /><br />The `templates` attribute can be used to specify an array of templates that should be inherited by the service.<br /><br />The new service's name is "hostname:service" - where "service" is the dictionary key in the services dictionary.<br /><br />The dictionary key is used as the service's short name.
  macros          |**Optional.** A dictionary containing macros that are specific to this host.

### <a id="objecttype-hostgroup"></a> HostGroup

A group of hosts.

Example:

    object HostGroup "my-hosts" {
      display_name = "My hosts",
    }

Attributes:

  Name            |Description
  ----------------|----------------
  display_name    |**Optional.** A short description of the host group.

### <a id="objecttype-service"></a> Service

Service objects describe network services and how they should be checked
by Icinga 2.

> **Best Practice**
>
> Rather than creating a `Service` object for a specific host it is usually easier
> to just create a `Service` template and using the `services` attribute in the `Host`
> object to associate these templates with a host.

Example:

    object Service "localhost-uptime" {
      host = "localhost",
      short_name = "uptime",

      display_name = "localhost Uptime",

      check_command = "check_snmp",

      macros = {
        community = "public",
        oid = "DISMAN-EVENT-MIB::sysUpTimeInstance"
      }

      check_interval = 60s,
      retry_interval = 15s,

      servicegroups = [ "all-services", "snmp" ],
    }

Attributes:

  Name            |Description
  ----------------|----------------
  host            |**Required.** The host this service belongs to. There must be a `Host` object with that name.
  short_name      |**Required.** The service name. Must be unique on a per-host basis (Similar to the service_description attribute in Icinga 1.x).
  display_name    |**Optional.** A short description of the service.
  macros          |**Optional.** A dictionary containing macros that are specific to this host.
  check\_command  |**Required.** The name of the check command.
  max\_check\_attempts|**Optional.** The number of times a service is re-checked before changing into a hard state. Defaults to 3.
  check\_period   |**Optional.** The name of a time period which determines when this service should be checked. Not set by default.
  check\_interval |**Optional.** The check interval (in seconds). This interval is used for checks when the service is in a `HARD` state. Defaults to 5 minutes.
  retry\_interval |**Optional.** The retry interval (in seconds). This interval is used for checks when the service is in a `SOFT` state. Defaults to 1/5th of the check interval if not specified.
  enable\_active\_checks|**Optional.** Whether active checks are enabled. Defaults to true.
  enable\_passive\_checks|**Optional.** Whether passive checks are enabled. Defaults to true.
  enable\_event\_handler|**Optional.** Enables event handlers for this service. Defaults to true.
  event\_command  |**Optional.** The name of an event command that should be executed every time the service's state changes.
  flapping\_threshold|TODO
  volatile        |TODO
  host_dependencies|**Optional.** A list of host names which this host depends on. These dependencies are used to determine whether the host is unreachable.
  service_dependencies|**Optional.** A list of services which this host depends on. Each array element must be a dictionary containing the keys "host" and "service". These dependencies are used to determine whether the host is unreachable.
  groups          |**Optional.** The service groups this service belongs to.
  notifications   |**Optional.** Inline definition of notifications. Each dictionary item specifies a notification.<br /><br />The `templates` attribute can be used to specify an array of templates that should be inherited by the notification object.<br /><br />The new notification object's name is "hostname:service:notification" - where "notification" is the dictionary key in the notifications dictionary.

### <a id="objecttype-servicegroup"></a> ServiceGroup

A group of services.

Example:

    object ServiceGroup "snmp" {
      display_name = "SNMP services",
    }

Attributes:

  Name            |Description
  ----------------|----------------
  display_name    |**Optional.** A short description of the service group.

### <a id="objecttype-notification"></a> Notification

Notification objects are used to specify how users should be notified in case
of service state changes and other events.

> **Best Practice**
>
> Rather than creating a `Notification` object for a specific service it is usually easier
> to just create a `Notification` template and using the `notifications` attribute in the `Service`
> object to associate these templates with a service.

Example:

    object Notification "localhost-ping-notification" {
      host = "localhost",
      service = "ping4",

      notification_command = "mail-notification",

      users = [ "user1", "user2" ]
    }

Attributes:

  Name            |Description
  ----------------|----------------
  host            |**Required.** The name of the host this notification belongs to.
  service         |**Required.** The short name of the service this notification belongs to.
  macros          |**Optional.** A dictionary containing macros that are specific to this notification object.
  users           |**Optional.** A list of user names who should be notified.
  user_groups     |**Optional.** A list of user group names who should be notified.
  times           |TODO
  notification_command|TODO
  notification_interval|TODO
  notification_period|TODO
  notification_type_filter|TODO
  notification_state_filter|TODO

### <a id="objecttype-user"></a> User

A user.

Example:

    object User "icingaadmin" {
      display_name = "Icinga 2 Admin",
      groups = [ "icingaadmins" ],

      enable_notifications = 1,
      notification_period = "24x7",

      notification_state_filter = (StateFilterWarning |
                                   StateFilterCritical |
                                   StateFilterUnknown),
      notification_type_filter = (NotificationFilterProblem |
                                  NotificationFilterRecovery),
      macros = {
        "name" = "Icinga 2 Admin",
        "email" = "icinga@localhost",
        "pager" = "icingaadmin@localhost.localdomain"
      },

      custom = {
        notes = "This is the Icinga 2 Admin account.",
      }
    }


Attributes:

  Name            |Description
  ----------------|----------------
  display_name    |**Optional.** A short description of the user.
  macros          |**Optional.** A dictionary containing macros that are specific to this user.
  custom          |**Optional.** A dictionary containing custom attributes that are specific to this user.
  groups          |TODO
  enable_notifications|TODO
  notification_period|TODO
  notification_type_filter|TODO
  notification_state_filter|TODO

### <a id="objecttype-usergroup"></a> UserGroup

A user group.

Example:

    object UserGroup "icingaadmins" {
        display_name = "Icinga 2 Admin Group"
    }

Attributes:

  Name            |Description
  ----------------|----------------
  display_name    |**Optional.** A short description of the user group.

### <a id="objecttype-timeperiod"></a> TimePeriod

Time periods can be used to specify when services should be checked or to limit
when notifications should be sent out.

Example:

    object TimePeriod "24x7" inherits "legacy-timeperiod" {
      display_name = "Icinga 2 24x7 TimePeriod",
      ranges = {
        "monday"    = "00:00-24:00",
        "tuesday"   = "00:00-24:00",
        "wednesday" = "00:00-24:00",
        "thursday"  = "00:00-24:00",
        "friday"    = "00:00-24:00",
        "saturday"  = "00:00-24:00",
        "sunday"    = "00:00-24:00",
      }
    }

Attributes:

  Name            |Description
  ----------------|----------------
  display_name    |**Optional.** A short description of the time period.
  methods         |**Required.** The "update" script method takes care of updating the internal representation of the time period. In virtually all cases you should just inherit from the "legacy-timeperiod" template to take care of this setting.
  ranges          |TODO

The `/etc/icinga2/conf.d/timeperiods.conf` file is usually used to define
timeperiods including this one.


### <a id="objecttype-consolelogger"></a> ConsoleLogger

Specifies Icinga 2 logging to the console.

Example:

    object ConsoleLogger "my-debug-console" {
      severity = "debug"
    }

Attributes:

  Name            |Description
  ----------------|----------------
  severity        |**Optional.** The minimum severity for this log. Can be "debug", "information", "warning" or "critical". Defaults to "information".

### <a id="objecttype-filelogger"></a> FileLogger

Specifies Icinga 2 logging to a file.

Example:

    object FileLogger "my-debug-file" {
      severity = "debug",
      path = "/var/log/icinga2/icinga2-debug.log"
    }

Attributes:

  Name            |Description
  ----------------|----------------
  path            |**Required.** The log path.
  severity        |**Optional.** The minimum severity for this log. Can be "debug", "information", "warning" or "critical". Defaults to "information".

### <a id="objecttype-sysloglogger"></a> SyslogLogger

Specifies Icinga 2 logging to syslog.

Example:

    object SyslogLogger "my-crit-syslog" {
      severity = "critical"
    }

Attributes:

  Name            |Description
  ----------------|----------------
  severity        |**Optional.** The minimum severity for this log. Can be "debug", "information", "warning" or "critical". Defaults to "information".

### <a id="objecttype-checkcommand"></a> CheckCommand

A check command definition. Additional default command macros can be
defined here.

Example:

    object CheckCommand "check_snmp" inherits "plugin-check-command" {
      command = "$plugindir$/check_snmp -H $address$ -C $community$ -o $oid$",

      macros = {
        address = "127.0.0.1",
        community = "public",
      }
    }

Attributes:

  Name            |Description
  ----------------|----------------
  methods         |**Required.** The "execute" script method takes care of executing the check. In virtually all cases you should just inherit from the "plugin-check-command" template to take care of this setting.
  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.
  export_macros   |**Optional.** A list of macros which should be exported as environment variables prior to executing the command.
  escape_macros   |**Optional.** A list of macros which should be shell-escaped in the command.
  macros          |**Optional.** A dictionary containing macros that are specific to this command.
  timeout         |**Optional.** The command timeout in seconds. Defaults to 5 minutes.

### <a id="objecttype-notificationcommand"></a> NotificationCommand

A notification command definition.

Example:

    object NotificationCommand "mail-service-notification" inherits "plugin-notification-command" {
      command = [
        "/opt/bin/send-mail-notification",
        "$USEREMAIL$",
        "$NOTIFICATIONTYPE$ - $HOSTNAME$ - $SERVICEDESC$ - $SERVICESTATE$",
        {{{***** Icinga  *****

    Notification Type: $NOTIFICATIONTYPE$

    Service: $SERVICEDESC$
    Host: $HOSTALIAS$
    Address: $HOSTADDRESS$
    State: $SERVICESTATE$

    Date/Time: $LONGDATETIME$

    Additional Info: $SERVICEOUTPUT$

    Comment: [$NOTIFICATIONAUTHORNAME$] $NOTIFICATIONCOMMENT$}}}
      ]
    }

Attributes:

  Name            |Description
  ----------------|----------------
  methods         |**Required.** The "execute" script method takes care of executing the notification. In virtually all cases you should just inherit from the "plugin-notification-command" template to take care of this setting.
  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.
  export_macros   |**Optional.** A list of macros which should be exported as environment variables prior to executing the command.
  escape_macros   |**Optional.** A list of macros which should be shell-escaped in the command.
  macros          |**Optional.** A dictionary containing macros that are specific to this command.
  timeout         |**Optional.** The command timeout in seconds. Defaults to 5 minutes.

### <a id="objecttype-eventcommand"></a> EventCommand

An event command definition.

> **Note**
>
> Similar to Icinga 1.x event handlers.

Example:

    object EventCommand "restart-httpd-event" inherits "plugin-event-command" {
      command = "/opt/bin/restart-httpd.sh",
    }


Attributes:

  Name            |Description
  ----------------|----------------
  methods         |**Required.** The "execute" script method takes care of executing the event handler. In virtually all cases you should just inherit from the "plugin-event-command" template to take care of this setting.
  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.
  export_macros   |**Optional.** A list of macros which should be exported as environment variables prior to executing the command.
  escape_macros   |**Optional.** A list of macros which should be shell-escaped in the command.
  macros          |**Optional.** A dictionary containing macros that are specific to this command.
  timeout         |**Optional.** The command timeout in seconds. Defaults to 5 minutes.

### <a id="objecttype-perfdatawriter"></a> PerfdataWriter

Writes check result performance data to a defined path using macro
pattern.

Example:

    library "perfdata"

    object PerfdataWriter "pnp" {
      perfdata_path = "/var/spool/icinga2/perfdata/service-perfdata",

      format_template = "DATATYPE::SERVICEPERFDATA\tTIMET::$TIMET$\tHOSTNAME::$HOSTNAME$\tSERVICEDESC::$SERVICEDESC$\tSERVICEPERFDATA::$SERVICEPERFDATA$\tSERVICECHECKCOMMAND::$SERVICECHECKCOMMAND$\tHOSTSTATE::$HOSTSTATE$\tHOSTSTATETYPE::$HOSTSTATETYPE$\tSERVICESTATE::$SERVICESTATE$\tSERVICESTATETYPE::$SERVICESTATETYPE$",

      rotation_interval = 15s,
    }

Attributes:

  Name            |Description
  ----------------|----------------
  perfdata\_path  |**Optional.** Path to the service performance data file. Defaults to IcingaLocalStateDir + "/cache/icinga2/perfdata/perfdata".
  format\_template|**Optional.** Format template for the performance data file. Defaults to a template that's suitable for use with PNP4Nagios.
  rotation\_interval|**Optional.** Rotation interval for the file specified in `perfdata\_path`. Defaults to 30 seconds.

> **Note**
>
> When rotating the performance data file the current UNIX timestamp is appended to the path specified
> in `perfdata\_path` to generate a unique filename.

### <a id="objecttype-graphitewriter"></a> GraphiteWriter

Writes check result metrics and performance data to a defined
Graphite Carbon host.

Example:

    library "perfdata"

    object GraphiteWriter "graphite" {
      host = "127.0.0.1",
      port = 2003
    }

Attributes:

  Name            |Description
  ----------------|----------------
  host            |**Optional.** Graphite Carbon host address. Defaults to '127.0.0.1'.
  port            |**Optional.** Graphite Carbon port. Defaults to 2003.

### <a id="objecttype-idomysqlconnection"></a> IdoMySqlConnection

IDO DB schema compatible output into MySQL database.

Example:

    library "db_ido_mysql"

    object IdoMysqlConnection "mysql-ido" {
      host = "127.0.0.1",
      port = 3306,
      user = "icinga",
      password = "icinga",
      database = "icinga",
      table_prefix = "icinga_",
      instance_name = "icinga2",
      instance_description = "icinga2 dev instance",

      cleanup = {
        downtimehistory_age = 48h,
        logentries_age = 31d,
      }
    }

Attributes:

  Name            |Description
  ----------------|----------------
  host            |**Optional.** MySQL database host address. Defaults to "localhost".
  port            |**Optional.** MySQL database port. Defaults to 3306.
  user            |**Optional.** MySQL database user with read/write permission to the icinga database. Defaults to "icinga".
  password        |**Optional.** MySQL database user's password. Defaults to "icinga".
  database        |**Optional.** MySQL database name. Defaults to "icinga".
  table\_prefix   |**Optional.** MySQL database table prefix. Defaults to "icinga\_".
  instance\_name  |**Optional.** Unique identifier for the local Icinga 2 instance. Defaults to "default".
  instance\_description|**Optional.** Description for the Icinga 2 instance.
  cleanup         |**Optional.** Dictionary with items for historical table cleanup.

Cleanup Items:

  Name            | Description
  ----------------|----------------
  acknowledgement_age |**Optional.** Max age for acknowledgement table rows (entry_time). Defaults to 0 (never).
  commenthistory_age |**Optional.** Max age for commenthistory table rows (entry_time). Defaults to 0 (never).
  contactnotifications_age |**Optional.** Max age for contactnotifications table rows (start_time). Defaults to 0 (never).
  contactnotificationmethods_age |**Optional.** Max age for contactnotificationmethods table rows (start_time). Defaults to 0 (never).
  downtimehistory_age |**Optional.** Max age for downtimehistory table rows (entry_time). Defaults to 0 (never).
  eventhandlers_age |**Optional.** Max age for eventhandlers table rows (start_time). Defaults to 0 (never).
  externalcommands_age |**Optional.** Max age for externalcommands table rows (entry_time). Defaults to 0 (never).
  flappinghistory_age |**Optional.** Max age for flappinghistory table rows (event_time). Defaults to 0 (never).
  hostchecks_age |**Optional.** Max age for hostchecks table rows (start_time). Defaults to 0 (never).
  logentries_age |**Optional.** Max age for logentries table rows (logentry_time). Defaults to 0 (never).
  notifications_age |**Optional.** Max age for notifications table rows (start_time). Defaults to 0 (never).
  processevents_age |**Optional.** Max age for processevents table rows (event_time). Defaults to 0 (never).
  statehistory_age |**Optional.** Max age for statehistory table rows (state_time). Defaults to 0 (never).
  servicechecks_age |**Optional.** Max age for servicechecks table rows (start_time). Defaults to 0 (never).
  systemcommands_age |**Optional.** Max age for systemcommands table rows (start_time). Defaults to 0 (never).

### <a id="objecttype-livestatuslistener"></a> LiveStatusListener

Livestatus API interface available as TCP or UNIX socket.

Example:

    library "livestatus"

    object LivestatusListener "livestatus-tcp" {
      socket_type = "tcp",
      bind_host = "127.0.0.1",
      bind_port = "6558"
    }

    object LivestatusListener "livestatus-unix" {
      socket_type = "unix",
      socket_path = "/var/run/icinga2/livestatus"
    }

Attributes:

  Name            |Description
  ----------------|----------------
  socket\_type    |**Optional.** Specifies the socket type. Can be either "tcp" or "unix". Defaults to "unix".
  bind\_host      |**Optional.** Only valid when socket\_type is "tcp". Host address to listen on for connections. Defaults to "127.0.0.1".
  bind\_port      |**Optional.** Only valid when `socket\_type` is "tcp". Port to listen on for connections. Defaults to 6558.
  socket\_path    |**Optional.** Only valid when `socket\_type` is "unix". Specifies the path to the UNIX socket file. Defaults to IcingaLocalStateDir + "/run/icinga2/livestatus".

> **Note**
>
> UNIX sockets are not supported on Windows.

### <a id="objecttype-statusdatawriter"></a> StatusDataWriter

Periodically writes status data files which are used by the Classic UI and other third-party tools.

Example:

    library "compat"

    object StatusDataWriter "status" {
        status\_path = "/var/cache/icinga2/status.dat",
        objects\_path = "/var/cache/icinga2/objects.path"
    }

Attributes:

  Name            |Description
  ----------------|----------------
  status\_path    |**Optional.** Path to the status.dat file. Defaults to IcingaLocalStateDir + "/cache/icinga2/status.dat".
  objects\_path   |**Optional.** Path to the objects.cache file. Defaults to IcingaLocalStateDir + "/cache/icinga2/objects.cache".

### <a id="objecttype-externalcommandlistener"></a> ExternalCommandListener

Implements the Icinga 1.x command pipe which can be used to send commands to Icinga.

Example:

    library "compat"

    object ExternalCommandListener "external" {
        command\_path = "/var/run/icinga2/cmd/icinga2.cmd"
    }

Attributes:

  Name            |Description
  ----------------|----------------
  command\_path   |**Optional.** Path to the command pipe. Defaults to IcingaLocalStateDir + "/run/icinga2/cmd/icinga2.cmd".

### <a id="objecttype-compatlogger"></a> CompatLogger

Writes log files in a format that's compatible with Icinga 1.x.

Example:

    library "compat"

    object CompatLogger "my-log" {
      log\_dir = "/var/log/icinga2/compat",
      rotation\_method = "HOURLY"
    }

Attributes:

  Name            |Description
  ----------------|----------------
  log\_dir        |**Optional.** Path to the compat log directory. Defaults to IcingaLocalStateDir + "/log/icinga2/compat".
  rotation\_method|**Optional.** Specifies when to rotate log files. Can be one of "HOURLY", "DAILY", "WEEKLY" or "MONTHLY". Defaults to "HOURLY".

### <a id="objecttype-checkresultreader"></a> CheckResultReader

Reads Icinga 1.x check results from a directory. This functionality is provided
to help existing Icinga 1.x users and might be useful for certain cluster
scenarios.

Example:

    library "compat"

    object CheckResultReader "reader" {
      spool_dir = "/data/check-results"
    }

Attributes:

  Name            |Description
  ----------------|----------------
  spool\_dir      |**Optional.** The directory which contains the check result files. Defaults to IcingaLocalStateDir + "/lib/icinga2/spool/checkresults/".

### <a id="objecttype-checkcomponent"></a> CheckerComponent

The checker component is responsible for scheduling active checks. There are no configurable options.

Example:

    library "checker"

    object CheckerComponent "checker" { }

### <a id="objecttype-notificationcomponent"></a> NotificationComponent

The notification component is responsible for sending notifications. There are no configurable options.

Example:

    library "notification"

    object NotificationComponent "notification" { }

### <a id="objecttype-clusterlistener"></a> ClusterListener

TODO

Example:

    TODO

Attributes:

  Name            |Description
  ----------------|----------------
  cert\_path      |TODO
  key\_path       |TODO
  ca\_path        |TODO
  bind\_host      |TODO
  bind\_port      |TODO
  peers           |TODO

### <a id="objecttype-endpoint"></a> Endpoint

Endpoint objects are used to specify connection information for remote
Icinga 2 instances.

Example:

    library "cluster"

    object Endpoint "icinga-c2" {
      node = "192.168.5.46",
      service = 7777,
    }

Attributes:

  Name            |Description
  ----------------|----------------
  node            |**Required.** The hostname/IP address of the remote Icinga 2 instance.
  service         |**Required.** The service name/port of the remote Icinga 2 instance.
  config\_files   |TODO
  accept\_config  |**Optional.** A list of endpoint names from which this endpoint accepts configuration files.

### <a id="objecttype-domain"></a> Domain

TODO

Example:

    TODO

Attributes:

  Name            |Description
  ----------------|----------------
  acl             |TODO