icinga2/doc/4.3-object-types.md

Object Types

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. The templates attribute can be used to specify an array of templates that should be inherited by the service. The new service's name is "hostname:service" - where "service" is the dictionary key in the services dictionary. The dictionary key is used as the service's short name.
macros	Optional. A dictionary containing macros that are specific to this host.

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.

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	Optional. The flapping threshold in percent when a service is considered to be flapping.
volatile	Optional. The volatile setting enables always HARD state types if NOT-OK state changes occur.
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. The templates attribute can be used to specify an array of templates that should be inherited by the notification object. The new notification object's name is "hostname:service:notification" - where "notification" is the dictionary key in the notifications dictionary.

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.

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	Optional. A dictionary containing begin and end attributes for the notification.
notification_command	Required. The name of the notification command which should be executed when the notification is triggered.
notification_interval	Optional. The notification interval (in seconds). This interval is used for active notifications. Defaults to 5 minutes.
notification_period	Optional. The name of a time period which determines when this notification should be triggered. Not set by default.
notification_type_filter	Optional. A set of state filters when this notification should be triggered. By default everything is matched.
notification_state_filter	Optional. A set of type filters when this notification should be triggered. By default everything is matched.

Available notification type and state filters:

StateFilterOK
StateFilterWarning
StateFilterCritical
StateFilterUnknown

NotificationFilterDowntimeStart
NotificationFilterDowntimeEnd
NotificationFilterDowntimeRemoved
NotificationFilterCustom
NotificationFilterAcknowledgement
NotificationFilterProblem
NotificationFilterRecovery
NotificationFilterFlappingStart
NotificationFilterFlappingEnd

Note

In order to notify on problem states, you will need the type filter NotificationFilterProblem.

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.",
  }
}

Available notification type and state filters:

StateFilterOK
StateFilterWarning
StateFilterCritical
StateFilterUnknown

NotificationFilterDowntimeStart
NotificationFilterDowntimeEnd
NotificationFilterDowntimeRemoved
NotificationFilterCustom
NotificationFilterAcknowledgement
NotificationFilterProblem
NotificationFilterRecovery
NotificationFilterFlappingStart
NotificationFilterFlappingEnd

Note

In order to notify on problem states, you will need the type filter NotificationFilterProblem.

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	Optional. An array of group names.
enable_notifications	Optional. Whether notifications are enabled for this user.
notification_period	Optional. The name of a time period which determines when this notification should be triggered. Not set by default.
notification_type_filter	Optional. A set of state filters when this notification should be triggered. By default everything is matched.
notification_state_filter	Optional. A set of type filters when this notification should be triggered. By default everything is matched.

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.

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	Required. A dictionary containing information which days and durations apply to this timeperiod.

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

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".

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".

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".

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.

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.

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.

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.

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.

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).

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.

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".

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".

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".

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/".

CheckerComponent

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

Example:

library "checker"

object CheckerComponent "checker" { }

NotificationComponent

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

Example:

library "notification"

object NotificationComponent "notification" { }

ClusterListener

ClusterListener objects are used to specify remote cluster node peers and the certificate files used for ssl authorization.

Example:

library "cluster"

object ClusterListener "cluster" {
  ca_path = "/etc/icinga2/ca/ca.crt",
  cert_path = "/etc/icinga2/ca/icinga-node-1.crt",
  key_path = "/etc/icinga2/ca/icinga-node-1.key",

  bind_port = 8888,

  peers = [ "icinga-node-2" ]
}

Attributes:

Name	Description
cert_path	Required. Path to the public key.
key_path	Required. Path to the private key.
ca_path	Required. Path to the CA certificate file.
bind_host	Optional. The IP address the cluster listener should be bound to.
bind_port	Optional. The port the cluster listener should be bound to.
peers	Optional. A list of

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	Optional. A list of configuration files sent to remote peers (wildcards possible).
accept_config	Optional. A list of endpoint names from which this endpoint accepts configuration files.

Domain

TODO

Example:

TODO

Attributes:

Name	Description
acl	TODO