icinga2/doc/4.3-object-types.md

Object Types

Host

A host.

Example:

object Host "localhost" {
  display_name = "The best host there is"
  address = "127.0.0.1"
  address6 = "::1"

  groups = [ "all-hosts" ]

  check_command = "hostalive"
}

Attributes:

Name	Description
display_name	Optional. A short description of the host.
address	Optional. The host's address. Available as command runtime macro $address$ if set.
address6	Optional. The host's address. Available as command runtime macro $address6$ if set.
groups	Optional. A list of host groups this host belongs to.
vars	Optional. A dictionary containing custom attributes that are specific to this host.
check_command	Required. The name of the check command.
max_check_attempts	Optional. The number of times a host 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 host should be checked. Not set by default.
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.
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.
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 host. 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 host's state changes.
flapping_threshold	Optional. The flapping threshold in percent when a host is considered to be flapping.
volatile	Optional. The volatile setting enables always HARD state types if NOT-OK state changes occur.
authorities	Optional. A list of Endpoints on which this host check will be executed in a cluster scenario.
domains	Optional. A list of Domains for this host object in a cluster scenario.
notes	Optional. Notes for the host.
notes_url	Optional. Url for notes for the host (for example, in notification commands).
action_url	Optional. Url for actions for the host (for example, an external graphing tool).
icon_image	Optional. Icon image for the host. Required for external interfaces only.
icon_image_alt	Optional. Icon image description for the host. Required for external interface only.

Best Practice

The address and address6 attributes are required for running commands using the $address$ and $address6 runtime macros.

Unlike Icinga 1.x the statusmap_image and 2d_coords attributes are custom attributes only in Icinga 2.

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.
groups	Optional. An array of nested group names.

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 use the apply keyword to assign the service to a number of hosts.

Example:

object Service "uptime" {
  host_name = "localhost"

  display_name = "localhost Uptime"

  check_command = "check_snmp"

  vars.community = "public"
  vars.oid = "DISMAN-EVENT-MIB::sysUpTimeInstance"

  check_interval = 60s
  retry_interval = 15s

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

Attributes:

Name	Description
host_name	Required. The host this service belongs to. There must be a Host object with that name.
name	Required. The service name. Must be unique on a per-host basis (Similar to the service_description attribute in Icinga 1.x).
groups	Optional. The service groups this service belongs to.

In addition to these attributes you can also use any of the attributes except the address and address6 which are also valid for Host objects.

Service objects have composite names, i.e. their names are based on the host_name attribute and the name you specified. This means you can define more than one object with the same (short) name as long as the host_name attribute has a different value.

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.
groups	Optional. An array of nested group names.

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 use the apply keyword to assign the notification to a number of services.

Example:

object Notification "localhost-ping-notification" {
  host_name = "localhost"
  service_name = "ping4"

  command = "mail-notification"

  users = [ "user1", "user2" ]

  types = [ Problem, Recovery ]
}

Attributes:

Name	Description
host_name	Required. The name of the host this notification belongs to.
service_name	Required. The short name of the service this notification belongs to.
vars	Optional. A dictionary containing custom attributes 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.
command	Required. The name of the notification command which should be executed when the notification is triggered.
interval	Optional. The notification interval (in seconds). This interval is used for active notifications. Defaults to 30 minutes.
period	Optional. The name of a time period which determines when this notification should be triggered. Not set by default.
types	Optional. A list of type filters when this notification should be triggered. By default everything is matched.
states	Optional. A list of type filters when this notification should be triggered. By default everything is matched.

Available notification state filters:

OK
Warning
Critical
Unknown
Up
Down

Available notification type filters:

DowntimeStart
DowntimeEnd
DowntimeRemoved
Custom
Acknowledgement
Problem
Recovery
FlappingStart
FlappingEnd

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 use the apply keyword to assign the dependency to a number of services.

Example:

object Dependency "webserver-internet" {
  child_host_name = "webserver"
  child_service_name = "ping4"

  parent_host_name = "internet"
  parent_service_name = "ping4"

  state_filter = [ OK, Warning ]

  disable_checks = true
}

Attributes:

Name	Description
parent_host_name	Required. The parent host.
parent_service_name	Optional. The parent service. When not specified the host's check service is used.
child_host_name	Required. The child host.
child_service_name	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 list of type filters when this dependency should be OK. Defaults to [ OK, Warning ] for services and [ Up ] for hosts.

Available state filters:

OK
Warning
Critical
Unknown
Up
Down

Dependency objects have composite names, i.e. their names are based on the child_host_name and child_service_name attributes and the 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 child_service_name attributes has a different value.

User

A user.

Example:

object User "icingaadmin" {
  display_name = "Icinga 2 Admin"
  groups = [ "icingaadmins" ]
  email = "icinga@localhost"
  pager = "icingaadmin@localhost.localdomain"

  notification_period = "24x7"

  states = [ OK, Warning, Critical, Unknown ]
  types = [ Problem, Recovery ]

  vars.additional_notes = "This is the Icinga 2 Admin account."
}

Available notification state filters:

OK
Warning
Critical
Unknown
Up
Down

Available notification type filters:

DowntimeStart
DowntimeEnd
DowntimeRemoved
Custom
Acknowledgement
Problem
Recovery
FlappingStart
FlappingEnd

Attributes:

Name	Description
display_name	Optional. A short description of the user.
email	Optional. An email string for this user. Useful for notification commands.
pager	Optional. A pager string for this user. Useful for notification commands.
vars	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.
period	Optional. The name of a time period which determines when this notification should be triggered. Not set by default.
types	Optional. A set of type filters when this notification should be triggered. By default everything is matched.
states	Optional. A set of state 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.
groups	Optional. An array of nested group names.

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" {
  import "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 import 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 use the apply keyword to assign the scheduled downtime to a number of services.

Example:

object ScheduledDowntime "some-downtime" {
  host_name = "localhost"
  service_name = "ping4"

  author = "icingaadmin"
  comment = "Some comment"

  fixed = false
  duration = 30m

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

Attributes:

Name	Description
host_name	Required. The name of the host this notification belongs to.
service_name	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.

ScheduledDowntime objects have composite names, i.e. their names are based on the host_name and service_name attributes and the name you specified. This means you can define more than one object with the same (short) name as long as one of the host_name and service_name attributes has a different value.

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

CheckCommand

A check command definition. Additional default command custom attributes can be defined here.

Example:

object CheckCommand "check_snmp" {
  import "plugin-check-command"

  command = [
    PluginDir + "/check_snmp",
"-H", "$address$",
"-C", "$community$",
"-o", "$oid$"
  ]

  vars.address = "127.0.0.1"
  vars.community = "public"
}

Attributes:

Name	Description
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.
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.
env	Optional. A dictionary of macros which should be exported as environment variables prior to executing the command.
vars	Optional. A dictionary containing custom attributes 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" {
  import "plugin-notification-command"

  command = [
    SysconfDir + "/icinga2/scripts/mail-notification.sh"
  ]

  env = {
    "NOTIFICATIONTYPE" = "$notification.type$"
    "SERVICEDESC" = "$service.name$"
    "HOSTALIAS" = "$host.display_name$",
    "HOSTADDRESS" = "$address$",
    "SERVICESTATE" = "$service.state$",
    "LONGDATETIME" = "$icinga.long_date_time$",
    "SERVICEOUTPUT" = "$service.output$",
    "NOTIFICATIONAUTHORNAME" = "$notification.author$",
    "NOTIFICATIONCOMMENT" = "$notification.comment$",
    "HOSTDISPLAYNAME" = "$host.display_name$",
    "SERVICEDISPLAYNAME" = "$service.display_name$",
    "USEREMAIL" = "$user.email$"
  }
}

Attributes:

Name	Description
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.
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.
env	Optional. A dictionary of macros which should be exported as environment variables prior to executing the command.
vars	Optional. A dictionary containing custom attributes that are specific to this command.
timeout	Optional. The command timeout in seconds. Defaults to 5 minutes.

EventCommand

An event command definition.

Example:

object EventCommand "restart-httpd-event" {
  import "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 import 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.
env	Optional. A dictionary of macros which should be exported as environment variables prior to executing the command.
vars	Optional. A dictionary containing custom attributes 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" {
  host_perfdata_path = "/var/spool/icinga2/perfdata/host-perfdata"

  service_perfdata_path = "/var/spool/icinga2/perfdata/service-perfdata"

  host_format_template = "DATATYPE::HOSTPERFDATA\tTIMET::$icinga.timet$\tHOSTNAME::$host.name$\tHOSTPERFDATA::$host.perfdata$\tHOSTCHECKCOMMAND::$host.check_command$\tHOSTSTATE::$host.state$\tHOSTSTATETYPE::$host.state_type$"
  service_format_template = "DATATYPE::SERVICEPERFDATA\tTIMET::$icinga.timet$\tHOSTNAME::$host.name$\tSERVICEDESC::$service.name$\tSERVICEPERFDATA::$service.perfdata$\tSERVICECHECKCOMMAND::$service.check_command$\tHOSTSTATE::$host.state$\tHOSTSTATETYPE::$host.state_type$\tSERVICESTATE::$service.state$\tSERVICESTATETYPE::$service.state_type$"

  rotation_interval = 15s
}

Attributes:

Name	Description
host_perfdata_path	Optional. Path to the host performance data file. Defaults to LocalStateDir + "/spool/icinga2/perfdata/host-perfdata".
service_perfdata_path	Optional. Path to the service performance data file. Defaults to LocalStateDir + "/spool/icinga2/perfdata/service-perfdata".
host_temp_path	Optional. Path to the temporary host file. Defaults to LocalStateDir + "/spool/icinga2/tmp/host-perfdata".
service_temp_path	Optional. Path to the temporary service file. Defaults to LocalStateDir + "/spool/icinga2/tmp/service-perfdata".
host_format_template	Optional. Host Format template for the performance data file. Defaults to a template that's suitable for use with PNP4Nagios.
service_format_template	Optional. Service 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 files specified in {host,service}\_perfdata\_path. Defaults to 30 seconds.

When rotating the performance data file the current UNIX timestamp is appended to the path specified in host_perfdata\_path and service_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 hostalives 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 hostalives 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 LocalStateDir + "/run/icinga2/cmd/livestatus".
compat_log_path	Optional. Required for historical table queries. Requires CompatLogger feature enabled. Defaults to LocalStateDir + "/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 LocalStateDir + "/cache/icinga2/status.dat".
objects_path	Optional. Path to the objects.cache file. Defaults to LocalStateDir + "/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 LocalStateDir + "/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 LocalStateDir + "/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 LocalStateDir + "/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 = LocalStateDir + "/cache/icinga2/status.json"
  update_interval = 15s
}

Attributes:

Name	Description
status_path	Optional. Path to cluster status file. Defaults to LocalStateDir + "/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	Equivalent to DomainPrivRead.
DomainPrivReadWrite	Equivalent to DomainPrivRead | DomainPrivCheckResult | DomainPrivCommand.