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" ],

  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.
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.
dependencies	Optional. Inline definition of dependencies. Each dictionary item specifies a dependency. The templates attribute can be used to specify an array of templates that should be inherited by the dependency object. The new dependency object's name is "hostname:service:dependency" - where "dependency" is the dictionary key in the dependencies dictionary.
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,

  groups = [ "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 minute.
enable_notifications	Optional. Whether notifications are enabled. Defaults to true.
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.
enable_flap_detection	Optional. Whether flap detection is enabled. Defaults to true.
enable_perfdata	Optional. Whether performance data processing is enabled. 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.
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.
dependencies	Optional. Inline definition of dependencies. Each dictionary item specifies a dependency. The templates attribute can be used to specify an array of templates that should be inherited by the dependency object. The new dependency object's name is "hostname:service:dependency" - where "dependency" is the dictionary key in the dependencies dictionary.
authorities	Optional. A list of Endpoints on which this service check will be executed in a cluster scenario.
domains	Optional. A list of Domains for this service object in a cluster scenario.

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.

Dependency

Dependency objects are used to specify dependencies between hosts and services.

Best Practice

Rather than creating a Dependency object for a specific service it is usually easier to just create a Dependency template and using the dependencies attribute in the Service object to associate these templates with a service.

Example:

object Dependency "webserver-internet" {
  child_host = "webserver",
  child_service = "ping4",

  parent_host = "internet",
  parent_service = "ping4",

  state_filter = (StateFilterOK),

  disable_checks = true
}

Attributes:

Name	Description
parent_host	Required. The parent host.
parent_service	Optional. The parent service. When not specified the host's check service is used.
child_host	Required. The child host.
child_service	Optional. The child service. When not specified the host's check service is used.
disable_checks	Optional. Whether to disable checks when this dependency fails. Defaults to false.
disable_notifications	Optional. Whether to disable notifications when this dependency fails. Defaults to true.
period	Optional. Time period during which this dependency is enabled.
state_filter	Optional. A set of type filters when this dependency should be OK. Defaults to (StateFilterOK

Available state filters:

StateFilterOK
StateFilterWarning
StateFilterCritical
StateFilterUnknown

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.

ScheduledDowntime

ScheduledDowntime objects can be used to set up recurring downtimes for services.

Best Practice

Rather than creating a ScheduledDowntime object for a specific service it is usually easier to just create a ScheduledDowntime template and using the scheduled_downtimes attribute in the Service object to associate these templates with a service.

Example:

object ScheduledDowntime "some-downtime" {
  host = "localhost",
  service = "ping4",

  author = "icingaadmin",
  comment = "Some comment",

  fixed = false,
  duration = 30m,

  ranges = {
    "sunday" = "02:00-03:00"
  }
}

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.
author	Required. The author of the downtime.
comment	Required. A comment for the downtime.
fixed	Optional. Whether this is a fixed downtime. Defaults to true.
duration	Optional. How long the downtime lasts. Only has an effect for flexible (non-fixed) downtimes.
ranges	Required. A dictionary containing information which days and durations apply to this timeperiod.

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 = [ (IcingaSysconfDir + "/icinga2/scripts/mail-notification.sh") ],

  export_macros = [
    "NOTIFICATIONTYPE",
    "SERVICEDESC",
    "HOSTALIAS",
    "HOSTADDRESS",
    "SERVICESTATE",
    "LONGDATETIME",
    "SERVICEOUTPUT",
    "NOTIFICATIONAUTHORNAME",
    "NOTIFICATIONCOMMENT",
    "HOSTDISPLAYNAME",
    "SERVICEDISPLAYNAME",
    "USEREMAIL"
  ]
}

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 + "/spool/icinga2/perfdata/perfdata".
temp_path	Optional. Path to the temporary file. Defaults to IcingaLocalStateDir + "/spool/icinga2/tmp/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 database adapter for MySQL.

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

  categories = (DbCatConfig | DbCatState)
}

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.
categories	Optional. The types of information that should be written to the database.

Cleanup Items:

Name	Description
acknowledgements_age	Optional. Max age for acknowledgements 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).

Data Categories:

Name	Description
DbCatConfig	Configuration data
DbCatState	Current state data
DbCatAcknowledgement	Acknowledgements
DbCatComment	Comments
DbCatDowntime	Downtimes
DbCatEventHandler	Event handler data
DbCatExternalCommand	External commands
DbCatFlapping	Flap detection data
DbCatCheck	Check results
DbCatLog	Log messages
DbCatNotification	Notifications
DbCatProgramStatus	Program status data
DbCatRetention	Retention data
DbCatStateHistory	Historical state data

Multiple categories can be combined using the | operator. In addition to the category flags listed above the DbCatEverything flag may be used as a shortcut for listing all flags.

IdoPgSqlConnection

IDO database adapter for PostgreSQL.

Example:

library "db_ido_pgsql"

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

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

  categories = (DbCatConfig | DbCatState)
}

Attributes:

Name	Description
host	Optional. PostgreSQL database host address. Defaults to "localhost".
port	Optional. PostgreSQL database port. Defaults to "5432".
user	Optional. PostgreSQL database user with read/write permission to the icinga database. Defaults to "icinga".
password	Optional. PostgreSQL database user's password. Defaults to "icinga".
database	Optional. PostgreSQL database name. Defaults to "icinga".
table_prefix	Optional. PostgreSQL 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.
categories	Optional. The types of information that should be written to the database.

Cleanup Items:

Name	Description
acknowledgements_age	Optional. Max age for acknowledgements 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).

Data Categories:

Name	Description
DbCatConfig	Configuration data
DbCatState	Current state data
DbCatAcknowledgement	Acknowledgements
DbCatComment	Comments
DbCatDowntime	Downtimes
DbCatEventHandler	Event handler data
DbCatExternalCommand	External commands
DbCatFlapping	Flap detection data
DbCatCheck	Check results
DbCatLog	Log messages
DbCatNotification	Notifications
DbCatProgramStatus	Program status data
DbCatRetention	Retention data
DbCatStateHistory	Historical state data

Multiple categories can be combined using the | operator. In addition to the category flags listed above the DbCatEverything flag may be used as a shortcut for listing all flags.

LiveStatusListener

Livestatus API interface available as TCP or UNIX socket. Historical table queries require the CompatLogger feature enabled pointing to the log files using the compat_log_path configuration attribute.

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/cmd/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/cmd/livestatus".
compat_log_path	Optional. Required for historical table queries. Requires CompatLogger feature enabled. Defaults to IcingaLocalStateDir + "/log/icinga2/compat"

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",
    update\_interval = 30s
}

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".
update_interval	Optional. The interval in which the status files are updated. Defaults to 15 seconds.

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" { }

IcingaStatusWriter

The IcingaStatusWriter feature periodically dumps the current status and performance data from Icinga 2 and all registered features into a defined JSON file.

Example:

object IcingaStatusWriter "status" {
  status_path = (IcingaLocalStateDir + "/cache/icinga2/status.json"),
  update_interval = 15s
}

Attributes:

Name	Description
status_path	Optional. Path to cluster status file. Defaults to IcingaLocalStateDir + "/cache/icinga2/status.json"
update_interval	Optional. The interval in which the status files are updated. Defaults to 15 seconds.

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.
crl_path	Optional. Path to the CRL 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" {
  host = "192.168.5.46",
  port = 7777,

  config_files = [ "/etc/icinga2/cluster.d/*" ],

  config_files_recursive = [
    "/etc/icinga2/cluster2",
    { path = "/etc/icinga2/cluster3", pattern = "*.myconf" }
  ]
}

Attributes:

Name	Description
host	Required. The hostname/IP address of the remote Icinga 2 instance.
port	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).
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".
accept_config	Optional. A list of endpoint names from which this endpoint accepts configuration files.

Domain

A Service object can be restricted using the domains attribute array specifying endpoint privileges.

A Domain object specifices the ACLs applied for each Endpoint.

Example:

object Domain "dmz-1" {
  acl = {
    node1 = (DomainPrivCheckResult),
    node2 = (DomainPrivReadWrite)
  }
}

Attributes:

Name	Description
acl	Required. Dictionary with items for Domain ACLs.

Domain ACLs:

Name	Description
DomainPrivRead	Endpoint reads local messages and relays them to remote nodes.
DomainPrivCheckResult	Endpoint accepts check result messages from remote nodes.
DomainPrivCommand	Endpoint accepts command messages from remote nodes.
DomainPrevReadOnly	Endpoint reads local messages and relays them to remote nodes.
DomainPrivReadWrite	Combination of (DomainPrivRead