Skip to content

Object Types

This chapter provides an overview of all available config object types which can be instantiated using the object keyword.

Additional details on configuration and runtime attributes and their description are explained here too.

The attributes need to have a specific type value. Many of them are explained in this chapter already. You should note that the Timestamp type is a Number. In addition to that Object name is an object reference to an existing object name as String type.

Overview

Common Runtime Attributes

Configuration objects share these runtime attributes which cannot be modified by the user. You can access these attributes using the Icinga 2 API.

Name Type Description
version Number Timestamp when the object was created or modified. Synced throughout cluster nodes.
type String Object type.
original_attributes Dictionary Original values of object attributes modified at runtime.
active Boolean Object is active (e.g. a service being checked).
paused Boolean Object has been paused at runtime (e.g. IdoMysqlConnection. Defaults to false.
templates Array Templates imported on object compilation.
package String Configuration package name this object belongs to. Local configuration is set to _etc, runtime created objects use _api.
source_location Dictionary Location information where the configuration files are stored.
name String Object name. Might be used in apply rules.

Monitoring Objects

ApiUser

ApiUser objects are used for authentication against the Icinga 2 API.

Example:

object ApiUser "root" {
  password = "mysecretapipassword"
  permissions = [ "*" ]
}

Configuration Attributes:

Name Type Description
password String Optional. Password string. Note: This attribute is hidden in API responses.
client_cn String Optional. Client Common Name (CN).
permissions Array Required. Array of permissions. Either as string or dictionary with the keys permission and filter. The latter must be specified as function.

Available permissions are explained in the API permissions chapter.

CheckCommand

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

Example:

object CheckCommand "http" {
  command = [ PluginDir + "/check_http" ]

  arguments = {
    "-H" = "$http_vhost$"
    "-I" = "$http_address$"
    "-u" = "$http_uri$"
    "-p" = "$http_port$"
    "-S" = {
      set_if = "$http_ssl$"
    }
    "--sni" = {
      set_if = "$http_sni$"
    }
    "-a" = {
      value = "$http_auth_pair$"
      description = "Username:password on sites with basic authentication"
    }
    "--no-body" = {
      set_if = "$http_ignore_body$"
    }
    "-r" = "$http_expect_body_regex$"
    "-w" = "$http_warn_time$"
    "-c" = "$http_critical_time$"
    "-e" = "$http_expect$"
  }

  vars.http_address = "$address$"
  vars.http_ssl = false
  vars.http_sni = false
}

Configuration Attributes:

Name Type Description
command Array 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. When using the “arguments” attribute this must be an array. Can be specified as function for advanced implementations.
env Dictionary Optional. A dictionary of macros which should be exported as environment variables prior to executing the command.
vars Dictionary Optional. A dictionary containing custom variables that are specific to this command.
timeout Duration Optional. The command timeout in seconds. Defaults to 1m.
arguments Dictionary Optional. A dictionary of command arguments.

CheckCommand Arguments

Command arguments can be defined as key-value-pairs in the arguments dictionary. Best practice is to assign a dictionary as value which provides additional details such as the description next to the value.

  arguments = {
    "--parameter" = {
      description = "..."
      value = "..."
    }
  }

All available argument value entries are shown below:

Name Type Description
value String/Function Optional argument value set by a runtime macro string or a function call. More details.
description String Optional argument description. More details.
required Boolean Required argument. Execution error if not set. Defaults to false (optional). More details.
skip_key Boolean Use the value as argument and skip the key. More details.
set_if String/Function Argument is added if the runtime macro string resolves to a defined numeric or boolean value. String values are not supported. Function calls returning a value are supported too. More details.
order Number Set if multiple arguments require a defined argument order. The syntax is ..., -3, -2, -1, <un-ordered keys>, 1, 2, 3, .... More details.
repeat_key Boolean If the argument value is an array, repeat the argument key, or not. Defaults to true (repeat). More details.
key String Optional argument key overriding the key identifier. More details.
separator String Key-value separator. If given, e.g. =, appears between key and value like --key=value instead of the regular --key value.

value and description are commonly used, the other entries allow to build more advanced CheckCommand objects and arguments.

Please continue reading here for advanced usage and examples for command arguments.

Dependency

Dependency objects are used to specify dependencies between hosts and services. Dependencies can be defined as Host-to-Host, Service-to-Service, Service-to-Host, or Host-to-Service relations.

Best Practice

Rather than creating a Dependency object for a specific host or service it is usually easier to just create a Dependency template and use the apply keyword to assign the dependency to a number of hosts or services. Use the to keyword to set the specific target type for Host or Service. Check the dependencies chapter for detailed examples.

Service-to-Service Example:

object Dependency "webserver-internet" {
  parent_host_name = "internet"
  parent_service_name = "ping4"

  child_host_name = "webserver"
  child_service_name = "ping4"

  states = [ OK, Warning ]

  disable_checks = true
}

Host-to-Host Example:

object Dependency "webserver-internet" {
  parent_host_name = "internet"

  child_host_name = "webserver"

  states = [ Up ]

  disable_checks = true
}

Configuration Attributes:

Name Type Description
parent_host_name Object name Required. The parent host.
parent_service_name Object name Optional. The parent service. If omitted, this dependency object is treated as host dependency.
child_host_name Object name Required. The child host.
child_service_name Object name Optional. The child service. If omitted, this dependency object is treated as host dependency.
redundancy_group String Optional. Puts the dependency into a group of mutually redundant ones.
disable_checks Boolean Optional. Whether to disable checks (i.e., don’t schedule active checks and drop passive results) when this dependency fails. Defaults to false.
disable_notifications Boolean Optional. Whether to disable notifications when this dependency fails. Defaults to true.
ignore_soft_states Boolean Optional. Whether to ignore soft states for the reachability calculation. Defaults to true.
period Object name Optional. Time period object during which this dependency is enabled.
states Array Optional. A list of state 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

When using apply rules for dependencies, you can leave out certain attributes which will be automatically determined by Icinga 2.

Service-to-Host Dependency Example:

apply Dependency "internet" to Service {
  parent_host_name = "dsl-router"
  disable_checks = true

  assign where host.name != "dsl-router"
}

This example sets all service objects matching the assign condition into a dependency relation to the parent host object dsl-router as implicit child services.

Service-to-Service-on-the-same-Host Dependency Example:

apply Dependency "disable-agent-checks" to Service {
  parent_service_name = "agent-health"

  assign where service.check_command == "ssh"
  ignore where service.name == "agent-health"
}

This example omits the parent_host_name attribute and Icinga 2 automatically sets its value to the name of the host object matched by the apply rule condition. All services where apply matches are made implicit child services in this dependency relation.

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.

Endpoint

Endpoint objects are used to specify connection information for remote Icinga 2 instances. More details can be found in the distributed monitoring chapter.

Example:

object Endpoint "icinga2-agent1.localdomain" {
  host = "192.168.56.111"
  port = 5665
  log_duration = 1d
}

Example (disable replay log):

object Endpoint "icinga2-agent1.localdomain" {
  host = "192.168.5.111"
  port = 5665
  log_duration = 0
}

Configuration Attributes:

Name Type Description
host String Optional. The hostname/IP address of the remote Icinga 2 instance.
port Number Optional. The service name/port of the remote Icinga 2 instance. Defaults to 5665.
log_duration Duration Optional. Duration for keeping replay logs on connection loss. Defaults to 1d (86400 seconds). Attribute is specified in seconds. If log_duration is set to 0, replaying logs is disabled. You could also specify the value in human readable format like 10m for 10 minutes or 1h for one hour.

Endpoint objects cannot currently be created with the API.

EventCommand

An event command definition.

Example:

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

Configuration Attributes:

Name Type Description
command Array 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. When using the “arguments” attribute this must be an array. Can be specified as function for advanced implementations.
env Dictionary Optional. A dictionary of macros which should be exported as environment variables prior to executing the command.
vars Dictionary Optional. A dictionary containing custom variables that are specific to this command.
timeout Duration Optional. The command timeout in seconds. Defaults to 1m.
arguments Dictionary Optional. A dictionary of command arguments.

Command arguments can be used the same way as for CheckCommand objects.

More advanced examples for event command usage can be found here.

Host

A host.

Example:

object Host "icinga2-agent1.localdomain" {
  display_name = "Linux Client 1"
  address = "192.168.56.111"
  address6 = "2a00:1450:4001:815::2003"

  groups = [ "linux-servers" ]

  check_command = "hostalive"
}

Configuration Attributes:

Name Type Description
display_name String Optional. A short description of the host (e.g. displayed by external interfaces instead of the name if set).
address String Optional. The host’s IPv4 address. Available as command runtime macro $address$ if set.
address6 String Optional. The host’s IPv6 address. Available as command runtime macro $address6$ if set.
groups Array of object names Optional. A list of host groups this host belongs to.
vars Dictionary Optional. A dictionary containing custom variables that are specific to this host.
check_command Object name Required. The name of the check command.
max_check_attempts Number Optional. The number of times a host is re-checked before changing into a hard state. Defaults to 3.
check_period Object name Optional. The name of a time period which determines when this host should be checked. Not set by default (effectively 24x7).
check_timeout Duration Optional. Check command timeout in seconds. Overrides the CheckCommand’s timeout attribute.
check_interval Duration Optional. The check interval (in seconds). This interval is used for checks when the host is in a HARD state. Defaults to 5m.
retry_interval Duration Optional. The retry interval (in seconds). This interval is used for checks when the host is in a SOFT state. Defaults to 1m. Note: This does not affect the scheduling after a passive check result.
enable_notifications Boolean Optional. Whether notifications are enabled. Defaults to true.
enable_active_checks Boolean Optional. Whether active checks are enabled. Defaults to true.
enable_passive_checks Boolean Optional. Whether passive checks are enabled. Defaults to true.
enable_event_handler Boolean Optional. Enables event handlers for this host. Defaults to true.
enable_flapping Boolean Optional. Whether flap detection is enabled. Defaults to false.
enable_perfdata Boolean Optional. Whether performance data processing is enabled. Defaults to true.
event_command Object name Optional. The name of an event command that should be executed every time the host’s state changes or the host is in a SOFT state.
flapping_threshold_high Number Optional. Flapping upper bound in percent for a host to be considered flapping. Default 30.0
flapping_threshold_low Number Optional. Flapping lower bound in percent for a host to be considered not flapping. Default 25.0
flapping_ignore_states Array Optional. A list of states that should be ignored during flapping calculation. By default no state is ignored.
volatile Boolean Optional. Treat all state changes as HARD changes. See here for details. Defaults to false.
zone Object name Optional. The zone this object is a member of. Please read the distributed monitoring chapter for details.
command_endpoint Object name Optional. The endpoint where commands are executed on.
notes String Optional. Notes for the host.
notes_url String Optional. URL for notes for the host (for example, in notification commands).
action_url String Optional. URL for actions for the host (for example, an external graphing tool).
icon_image String Optional. Icon image for the host. Used by external interfaces only.
icon_image_alt String Optional. Icon image description for the host. Used by external interface only.

The actual check interval might deviate slightly from the configured values due to the fact that Icinga tries to evenly distribute all checks over a certain period of time, i.e. to avoid load spikes.

Best Practice

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

Runtime Attributes:

Name Type Description
next_check Timestamp When the next check occurs (as a UNIX timestamp).
last_check Timestamp When the last check occurred (as a UNIX timestamp).
check_attempt Number The current check attempt number.
state_type Number The current state type (0 = SOFT, 1 = HARD).
last_state_type Number The previous state type (0 = SOFT, 1 = HARD).
last_reachable Boolean Whether the host was reachable when the last check occurred.
last_check_result CheckResult The current check result.
last_state_change Timestamp When the last state change occurred (as a UNIX timestamp).
last_hard_state_change Timestamp When the last hard state change occurred (as a UNIX timestamp).
acknowledgement Number The acknowledgement type (0 = NONE, 1 = NORMAL, 2 = STICKY).
acknowledgement_expiry Timestamp When the acknowledgement expires (as a UNIX timestamp; 0 = no expiry).
downtime_depth Number Whether the host has one or more active downtimes.
flapping_last_change Timestamp When the last flapping change occurred (as a UNIX timestamp).
flapping Boolean Whether the host is flapping between states.
flapping_current Number Current flapping value in percent (see flapping_thresholds)
state Number The current state (0 = UP, 1 = DOWN).
last_state Number The previous state (0 = UP, 1 = DOWN).
last_hard_state Number The last hard state (0 = UP, 1 = DOWN).
last_state_up Timestamp When the last UP state occurred (as a UNIX timestamp).
last_state_down Timestamp When the last DOWN state occurred (as a UNIX timestamp).
last_state_unreachable Timestamp When the host was unreachable the last time (as a UNIX timestamp).
previous_state_change Timestamp Previous timestamp of last_state_change before processing a new check result.
severity Number Severity calculated value.
problem Boolean Whether the host is considered in a problem state type (NOT-UP).
handled Boolean Whether the host problem is handled (downtime or acknowledgement).
next_update Timestamp When the next check update is to be expected.

HostGroup

A group of hosts.

Best Practice

Assign host group members using the group assign rules.

Example:

object HostGroup "linux-servers" {
  display_name = "Linux Servers"

  assign where host.vars.os == "Linux"
}

Configuration Attributes:

Name Type Description
display_name String Optional. A short description of the host group.
groups Array of object names Optional. An array of nested group names.

Notification

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

Best Practice

Rather than creating a Notification object for a specific host or service it is usually easier to just create a Notification template and use the apply keyword to assign the notification to a number of hosts or services. Use the to keyword to set the specific target type for Host or Service. Check the notifications chapter for detailed examples.

Example:

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

  command = "mail-notification"

  users = [ "user1", "user2" ] // reference to User objects

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

Configuration Attributes:

Name Type Description
host_name Object name Required. The name of the host this notification belongs to.
service_name Object name Optional. The short name of the service this notification belongs to. If omitted, this notification object is treated as host notification.
vars Dictionary Optional. A dictionary containing custom variables that are specific to this notification object.
users Array of object names Required. A list of user names who should be notified. Optional. if the user_groups attribute is set.
user_groups Array of object names Required. A list of user group names who should be notified. Optional. if the users attribute is set.
times Dictionary Optional. A dictionary containing begin and end attributes for the notification. If end is set to 0, Notifications are disabled permanently. Please read the notification delay chapter for details.
command Object name Required. The name of the notification command which should be executed when the notification is triggered.
interval Duration Optional. The notification interval (in seconds). This interval is used for active notifications. Defaults to 30 minutes. If set to 0, re-notifications are disabled.
period Object name Optional. The name of a time period which determines when this notification should be triggered. Not set by default (effectively 24x7).
zone Object name Optional. The zone this object is a member of. Please read the distributed monitoring chapter for details.
types Array Optional. A list of type filters when this notification should be triggered. By default everything is matched.
states Array Optional. A list of state filters when this notification should be triggered. By default everything is matched. Note that the states filter is ignored for notifications of type Acknowledgement!

Available notification state filters for Service:

OK
Warning
Critical
Unknown

Available notification state filters for Host:

Up
Down

Available notification type filters:

DowntimeStart
DowntimeEnd
DowntimeRemoved
Custom
Acknowledgement
Problem
Recovery
FlappingStart
FlappingEnd

Runtime Attributes:

Name Type Description
last_notification Timestamp When the last notification was sent for this Notification object (as a UNIX timestamp).
next_notification Timestamp When the next notification is going to be sent for this assuming the associated host/service is still in a non-OK state (as a UNIX timestamp).
notification_number Number The notification number.
last_problem_notification Timestamp When the last notification was sent for a problem (as a UNIX timestamp).

NotificationCommand

A notification command definition.

Example:

object NotificationCommand "mail-service-notification" {
  command = [ ConfigDir + "/scripts/mail-service-notification.sh" ]

  arguments += {
    "-4" = {
      required = true
      value = "$notification_address$"
    }
    "-6" = "$notification_address6$"
    "-b" = "$notification_author$"
    "-c" = "$notification_comment$"
    "-d" = {
      required = true
      value = "$notification_date$"
    }
    "-e" = {
      required = true
      value = "$notification_servicename$"
    }
    "-f" = {
      value = "$notification_from$"
      description = "Set from address. Requires GNU mailutils (Debian/Ubuntu) or mailx (RHEL/SUSE)"
    }
    "-i" = "$notification_icingaweb2url$"
    "-l" = {
      required = true
      value = "$notification_hostname$"
    }
    "-n" = {
      required = true
      value = "$notification_hostdisplayname$"
    }
    "-o" = {
      required = true
      value = "$notification_serviceoutput$"
    }
    "-r" = {
      required = true
      value = "$notification_useremail$"
    }
    "-s" = {
      required = true
      value = "$notification_servicestate$"
    }
    "-t" = {
      required = true
      value = "$notification_type$"
    }
    "-u" = {
      required = true
      value = "$notification_servicedisplayname$"
    }
    "-v" = "$notification_logtosyslog$"
  }

  vars += {
    notification_address = "$address$"
    notification_address6 = "$address6$"
    notification_author = "$notification.author$"
    notification_comment = "$notification.comment$"
    notification_type = "$notification.type$"
    notification_date = "$icinga.long_date_time$"
    notification_hostname = "$host.name$"
    notification_hostdisplayname = "$host.display_name$"
    notification_servicename = "$service.name$"
    notification_serviceoutput = "$service.output$"
    notification_servicestate = "$service.state$"
    notification_useremail = "$user.email$"
    notification_servicedisplayname = "$service.display_name$"
  }
}

Configuration Attributes:

Name Type Description
command Array 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. When using the “arguments” attribute this must be an array. Can be specified as function for advanced implementations.
env Dictionary Optional. A dictionary of macros which should be exported as environment variables prior to executing the command.
vars Dictionary Optional. A dictionary containing custom variables that are specific to this command.
timeout Duration Optional. The command timeout in seconds. Defaults to 1m.
arguments Dictionary Optional. A dictionary of command arguments.

Command arguments can be used the same way as for CheckCommand objects.

More details on specific attributes can be found in this chapter.

ScheduledDowntime

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

Best Practice

Rather than creating a ScheduledDowntime object for a specific host or 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 hosts or services. Use the to keyword to set the specific target type for Host or Service. Check the recurring downtimes example for details.

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

Configuration Attributes:

Name Type Description
host_name Object name Required. The name of the host this scheduled downtime belongs to.
service_name Object name Optional. The short name of the service this scheduled downtime belongs to. If omitted, this downtime object is treated as host downtime.
author String Required. The author of the downtime.
comment String Required. A comment for the downtime.
fixed Boolean Optional. Whether this is a fixed downtime. Defaults to true.
duration Duration Optional. How long the downtime lasts. Only has an effect for flexible (non-fixed) downtimes.
ranges Dictionary Required. A dictionary containing information which days and durations apply to this timeperiod.
child_options String Optional. Schedule child downtimes. DowntimeNoChildren does not do anything, DowntimeTriggeredChildren schedules child downtimes triggered by this downtime, DowntimeNonTriggeredChildren schedules non-triggered downtimes. Defaults to DowntimeNoChildren.

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.

See also time zone handling.

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. Check the apply chapter for details.

Example:

object Service "uptime" {
  host_name = "localhost"

  display_name = "localhost Uptime"

  check_command = "snmp"

  vars.snmp_community = "public"
  vars.snmp_oid = "DISMAN-EVENT-MIB::sysUpTimeInstance"

  check_interval = 60s
  retry_interval = 15s

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

Configuration Attributes:

Name Type Description
display_name String Optional. A short description of the service.
host_name Object name Required. The host this service belongs to. There must be a Host object with that name.
groups Array of object names Optional. The service groups this service belongs to.
vars Dictionary Optional. A dictionary containing custom variables that are specific to this service.
check_command Object name Required. The name of the check command.
max_check_attempts Number Optional. The number of times a service is re-checked before changing into a hard state. Defaults to 3.
check_period Object name Optional. The name of a time period which determines when this service should be checked. Not set by default (effectively 24x7).
check_timeout Duration Optional. Check command timeout in seconds. Overrides the CheckCommand’s timeout attribute.
check_interval Duration Optional. The check interval (in seconds). This interval is used for checks when the service is in a HARD state. Defaults to 5m.
retry_interval Duration Optional. The retry interval (in seconds). This interval is used for checks when the service is in a SOFT state. Defaults to 1m. Note: This does not affect the scheduling after a passive check result.
enable_notifications Boolean Optional. Whether notifications are enabled. Defaults to true.
enable_active_checks Boolean Optional. Whether active checks are enabled. Defaults to true.
enable_passive_checks Boolean Optional. Whether passive checks are enabled. Defaults to true.
enable_event_handler Boolean Optional. Enables event handlers for this host. Defaults to true.
enable_flapping Boolean Optional. Whether flap detection is enabled. Defaults to false.
flapping_threshold_high Number Optional. Flapping upper bound in percent for a service to be considered flapping. 30.0
flapping_threshold_low Number Optional. Flapping lower bound in percent for a service to be considered not flapping. 25.0
flapping_ignore_states Array Optional. A list of states that should be ignored during flapping calculation. By default no state is ignored.
enable_perfdata Boolean Optional. Whether performance data processing is enabled. Defaults to true.
event_command Object name Optional. The name of an event command that should be executed every time the service’s state changes or the service is in a SOFT state.
volatile Boolean Optional. Treat all state changes as HARD changes. See here for details. Defaults to false.
zone Object name Optional. The zone this object is a member of. Please read the distributed monitoring chapter for details.
command_endpoint Object name Optional. The endpoint where commands are executed on.
notes String Optional. Notes for the service.
notes_url String Optional. URL for notes for the service (for example, in notification commands).
action_url String Optional. URL for actions for the service (for example, an external graphing tool).
icon_image String Optional. Icon image for the service. Used by external interfaces only.
icon_image_alt String Optional. Icon image description for the service. Used by external interface only.

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.

The actual check interval might deviate slightly from the configured values due to the fact that Icinga tries to evenly distribute all checks over a certain period of time, i.e. to avoid load spikes.

Runtime Attributes:

Name Type Description
next_check Timestamp When the next check occurs (as a UNIX timestamp).
last_check Timestamp When the last check occurred (as a UNIX timestamp).
check_attempt Number The current check attempt number.
state_type Number The current state type (0 = SOFT, 1 = HARD).
last_state_type Number The previous state type (0 = SOFT, 1 = HARD).
last_reachable Boolean Whether the service was reachable when the last check occurred.
last_check_result CheckResult The current check result.
last_state_change Timestamp When the last state change occurred (as a UNIX timestamp).
last_hard_state_change Timestamp When the last hard state change occurred (as a UNIX timestamp).
acknowledgement Number The acknowledgement type (0 = NONE, 1 = NORMAL, 2 = STICKY).
acknowledgement_expiry Timestamp When the acknowledgement expires (as a UNIX timestamp; 0 = no expiry).
acknowledgement_last_change Timestamp When the acknowledgement has been set/cleared
downtime_depth Number Whether the service has one or more active downtimes.
flapping_last_change Timestamp When the last flapping change occurred (as a UNIX timestamp).
flapping_current Number Current flapping value in percent (see flapping_thresholds)
flapping Boolean Whether the service is flapping between states.
state Number The current state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).
last_state Number The previous state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).
last_hard_state Number The last hard state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).
last_state_ok Timestamp When the last OK state occurred (as a UNIX timestamp).
last_state_warning Timestamp When the last WARNING state occurred (as a UNIX timestamp).
last_state_critical Timestamp When the last CRITICAL state occurred (as a UNIX timestamp).
last_state_unknown Timestamp When the last UNKNOWN state occurred (as a UNIX timestamp).
last_state_unreachable Timestamp When the service was unreachable the last time (as a UNIX timestamp).
previous_state_change Timestamp Previous timestamp of last_state_change before processing a new check result.
severity Number Severity calculated value.
problem Boolean Whether the service is considered in a problem state type (NOT-OK).
handled Boolean Whether the service problem is handled (downtime or acknowledgement).
next_update Timestamp When the next check update is to be expected.

ServiceGroup

A group of services.

Best Practice

Assign service group members using the group assign rules.

Example:

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

Configuration Attributes:

Name Type Description
display_name String Optional. A short description of the service group.
groups Array of object names Optional. An array of nested group names.

TimePeriod

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

Examples:

object TimePeriod "nonworkhours" {
  display_name = "Icinga 2 TimePeriod for non working hours"

  ranges = {
    monday = "00:00-8:00,17:00-24:00"
    tuesday = "00:00-8:00,17:00-24:00"
    wednesday = "00:00-8:00,17:00-24:00"
    thursday = "00:00-8:00,17:00-24:00"
    friday = "00:00-8:00,16:00-24:00"
    saturday = "00:00-24:00"
    sunday = "00:00-24:00"
  }
}

object TimePeriod "exampledays" {
    display_name = "Icinga 2 TimePeriod for random example days"

    ranges = {
        //We still believe in Santa, no peeking!
        //Applies every 25th of December every year
        "december 25" = "00:00-24:00"

        //Any point in time can be specified,
        //but you still have to use a range
        "2038-01-19" = "03:13-03:15"

        //Evey 3rd day from the second monday of February
        //to 8th of November
        "monday 2 february - november 8 / 3" = "00:00-24:00"
    }
}

Additional examples can be found here.

Configuration Attributes:

Name Type Description
display_name String Optional. A short description of the time period.
ranges Dictionary Required. A dictionary containing information which days and durations apply to this timeperiod.
prefer_includes Boolean Optional. Whether to prefer timeperiods includes or excludes. Default to true.
excludes Array of object names Optional. An array of timeperiods, which should exclude from your timerange.
includes Array of object names Optional. An array of timeperiods, which should include into your timerange

Runtime Attributes:

Name Type Description
is_inside Boolean Whether we’re currently inside this timeperiod.

See also time zone handling.

User

A user.

Example:

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

  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

Configuration Attributes:

Name Type Description
display_name String Optional. A short description of the user.
email String Optional. An email string for this user. Useful for notification commands.
pager String Optional. A pager string for this user. Useful for notification commands.
vars Dictionary Optional. A dictionary containing custom variables that are specific to this user.
groups Array of object names Optional. An array of group names.
enable_notifications Boolean Optional. Whether notifications are enabled for this user. Defaults to true.
period Object name Optional. The name of a time period which determines when a notification for this user should be triggered. Not set by default (effectively 24x7).
types Array Optional. A set of type filters when a notification for this user should be triggered. By default everything is matched.
states Array Optional. A set of state filters when a notification for this should be triggered. By default everything is matched.

Runtime Attributes:

Name Type Description
last_notification Timestamp When the last notification was sent for this user (as a UNIX timestamp).

UserGroup

A user group.

Best Practice

Assign user group members using the group assign rules.

Example:

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

Configuration Attributes:

Name Type Description
display_name String Optional. A short description of the user group.
groups Array of object names Optional. An array of nested group names.

Zone

Zone objects are used to specify which Icinga 2 instances are located in a zone. Please read the distributed monitoring chapter for additional details. Example:

object Zone "master" {
  endpoints = [ "icinga2-master1.localdomain", "icinga2-master2.localdomain" ]

}

object Zone "satellite" {
  endpoints = [ "icinga2-satellite1.localdomain" ]
  parent = "master"
}

Configuration Attributes:

Name Type Description
endpoints Array of object names Optional. Array of endpoint names located in this zone.
parent Object name Optional. The name of the parent zone. (Do not specify a global zone)
global Boolean Optional. Whether configuration files for this zone should be synced to all endpoints. Defaults to false.

Zone objects cannot currently be created with the API.

Runtime Objects

These objects are generated at runtime by the daemon from API actions. Downtime objects are also created by ScheduledDowntime objects.

Comment

Comments created at runtime are represented as objects. Note: This is for reference only. You can create comments with the add-comment API action.

Example:

object Comment "my-comment" {
  host_name = "localhost"
  author = "icingaadmin"
  text = "This is a comment."
  entry_time = 1234567890
}

Configuration Attributes:

Name Type Description
host_name Object name Required. The name of the host this comment belongs to.
service_name Object name Optional. The short name of the service this comment belongs to. If omitted, this comment object is treated as host comment.
author String Required. The author’s name.
text String Required. The comment text.
entry_time Timestamp Optional. The UNIX timestamp when this comment was added. If omitted, the entry time is volatile!
entry_type Number Optional. The comment type (User = 1, Downtime = 2, Flapping = 3, Acknowledgement = 4).
expire_time Timestamp Optional. The comment’s expire time as UNIX timestamp.
persistent Boolean Optional. Only evaluated for entry_type Acknowledgement. true does not remove the comment when the acknowledgement is removed.

Downtime

Downtimes created at runtime are represented as objects. You can create downtimes with the schedule-downtime API action.

Example:

object Downtime "my-downtime" {
  host_name = "localhost"
  author = "icingaadmin"
  comment = "This is a downtime."
  start_time = 1505312869
  end_time = 1505312924
}

Configuration Attributes:

Name Type Description
host_name Object name Required. The name of the host this downtime belongs to.
service_name Object name Optional. The short name of the service this downtime belongs to. If omitted, this downtime object is treated as host downtime.
author String Required. The author’s name.
comment String Required. The comment text.
start_time Timestamp Required. The start time as UNIX timestamp.
end_time Timestamp Required. The end time as UNIX timestamp.
duration Number Optional. The duration as number.
entry_time Timestamp Optional. The UNIX timestamp when this downtime was added.
fixed Boolean Optional. Whether the downtime is fixed (true) or flexible (false). Defaults to flexible. Details in the advanced topics chapter.
triggers Array of object names Optional. List of downtimes which should be triggered by this downtime.

Runtime Attributes:

Name Type Description
trigger_time Timestamp The UNIX timestamp when this downtime was triggered.
triggered_by Object name The name of the downtime this downtime was triggered by.

Features

ApiListener

ApiListener objects are used for distributed monitoring setups and API usage specifying the certificate files used for ssl authorization and additional restrictions. This configuration object is available as api feature.

The TicketSalt constant must be defined in constants.conf.

Example:

object ApiListener "api" {
  accept_commands = true
  accept_config = true

  ticket_salt = TicketSalt
}

Configuration Attributes:

Name Type Description
cert_path String Deprecated. Path to the public key.
key_path String Deprecated. Path to the private key.
ca_path String Deprecated. Path to the CA certificate file.
ticket_salt String Optional. Private key for CSR auto-signing. Required for a signing master instance.
crl_path String Optional. Path to the CRL file.
bind_host String Optional. The IP address the api listener should be bound to. If not specified, the ApiListener is bound to :: and listens for both IPv4 and IPv6 connections or to 0.0.0.0 if IPv6 is not supported by the operating system.
bind_port Number Optional. The port the api listener should be bound to. Defaults to 5665.
accept_config Boolean Optional. Accept zone configuration. Defaults to false.
accept_commands Boolean Optional. Accept remote commands. Defaults to false.
max_anonymous_clients Number Optional. Limit the number of anonymous client connections (not configured endpoints and signing requests).
cipher_list String Optional. Cipher list that is allowed. For a list of available ciphers run openssl ciphers. Defaults to ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384:DHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256.
tls_protocolmin String Optional. Minimum TLS protocol version. Since v2.11, only TLSv1.2 is supported. Defaults to TLSv1.2.
tls_handshake_timeout Number Deprecated. TLS Handshake timeout. Defaults to 10s.
connect_timeout Number Optional. Timeout for establishing new connections. Affects both incoming and outgoing connections. Within this time, the TCP and TLS handshakes must complete and either a HTTP request or an Icinga cluster connection must be initiated. Defaults to 15s.
access_control_allow_origin Array Optional. Specifies an array of origin URLs that may access the API. (MDN docs)
access_control_allow_credentials Boolean Deprecated. Indicates whether or not the actual request can be made using credentials. Defaults to true. (MDN docs)
access_control_allow_headers String Deprecated. Used in response to a preflight request to indicate which HTTP headers can be used when making the actual request. Defaults to Authorization. (MDN docs)
access_control_allow_methods String Deprecated. Used in response to a preflight request to indicate which HTTP methods can be used when making the actual request. Defaults to GET, POST, PUT, DELETE. (MDN docs)
environment String Optional. Used as suffix in TLS SNI extension name; default from constant ApiEnvironment, which is empty.

The attributes access_control_allow_credentials, access_control_allow_headers and access_control_allow_methods are controlled by Icinga 2 and are not changeable by config any more.

The ApiListener type expects its certificate files to be in the following locations:

Type Location
Private key DataDir + "/certs/" + NodeName + ".key"
Certificate file DataDir + "/certs/" + NodeName + ".crt"
CA certificate file DataDir + "/certs/ca.crt"

If the deprecated attributes cert_path, key_path and/or ca_path are specified Icinga 2 copies those files to the new location in DataDir + "/certs" unless the file(s) there are newer.

Please check the upgrading chapter for more details.

While Icinga 2 and the underlying OpenSSL library use sane and secure defaults, the attributes cipher_list and tls_protocolmin can be used to increase communication security. A good source for a more secure configuration is provided by the Mozilla Wiki. Ensure to use the same configuration for both attributes on all endpoints to avoid communication problems which requires to use cipher_list compatible with the endpoint using the oldest version of the OpenSSL library. If using other tools to connect to the API ensure also compatibility with them as this setting affects not only inter-cluster communcation but also the REST API.

CheckerComponent

The checker component is responsible for scheduling active checks. This configuration object is available as checker feature.

Example:

object CheckerComponent "checker" { }

In order to limit the concurrent checks on a master/satellite endpoint, use MaxConcurrentChecks constant. This also applies to an agent as command endpoint where the checker feature is disabled.

CompatLogger

Writes log files in a format that’s compatible with Icinga 1.x. This configuration object is available as compatlog feature.

Note

This feature is DEPRECATED and may be removed in future releases. Check the roadmap.

Example:

object CompatLogger "compatlog" {
  log_dir = "/var/log/icinga2/compat"
  rotation_method = "DAILY"
}

Configuration Attributes:

Name Type Description
log_dir String Optional. Path to the compat log directory. Defaults to LogDir + “/compat”.
rotation_method String Optional. Specifies when to rotate log files. Can be one of “HOURLY”, “DAILY”, “WEEKLY” or “MONTHLY”. Defaults to “HOURLY”.

ElasticsearchWriter

Writes check result metrics and performance data to an Elasticsearch instance. This configuration object is available as elasticsearch feature.

Example:

object ElasticsearchWriter "elasticsearch" {
  host = "127.0.0.1"
  port = 9200
  index = "icinga2"

  enable_send_perfdata = true

  flush_threshold = 1024
  flush_interval = 10
}

The index is rotated daily, as is recommended by Elastic, meaning the index will be renamed to $index-$d.$M.$y.

Configuration Attributes:

Name Type Description
host String Required. Elasticsearch host address. Defaults to 127.0.0.1.
port Number Required. Elasticsearch port. Defaults to 9200.
index String Required. Elasticsearch index name. Defaults to icinga2.
enable_send_perfdata Boolean Optional. Send parsed performance data metrics for check results. Defaults to false.
flush_interval Duration Optional. How long to buffer data points before transferring to Elasticsearch. Defaults to 10s.
flush_threshold Number Optional. How many data points to buffer before forcing a transfer to Elasticsearch. Defaults to 1024.
username String Optional. Basic auth username if Elasticsearch is hidden behind an HTTP proxy.
password String Optional. Basic auth password if Elasticsearch is hidden behind an HTTP proxy.
enable_tls Boolean Optional. Whether to use a TLS stream. Defaults to false. Requires an HTTP proxy.
insecure_noverify Boolean Optional. Disable TLS peer verification.
ca_path String Optional. Path to CA certificate to validate the remote host. Requires enable_tls set to true.
cert_path String Optional. Path to host certificate to present to the remote host for mutual verification. Requires enable_tls set to true.
key_path String Optional. Path to host key to accompany the cert_path. Requires enable_tls set to true.
enable_ha Boolean Optional. Enable the high availability functionality. Only valid in a cluster setup. Defaults to false.

Note: If flush_threshold is set too low, this will force the feature to flush all data to Elasticsearch too often. Experiment with the setting, if you are processing more than 1024 metrics per second or similar.

Basic auth is supported with the username and password attributes. This requires an HTTP proxy (Nginx, etc.) in front of the Elasticsearch instance. Check this blogpost for an example.

TLS for the HTTP proxy can be enabled with enable_tls. In addition to that you can specify the certificates with the ca_path, cert_path and cert_key attributes.

ExternalCommandListener

Implements the Icinga 1.x command pipe which can be used to send commands to Icinga. This configuration object is available as command feature.

Note

This feature is DEPRECATED and may be removed in future releases. Check the roadmap.

Example:

object ExternalCommandListener "command" {
    command_path = "/var/run/icinga2/cmd/icinga2.cmd"
}

Configuration Attributes:

Name Type Description
command_path String Optional. Path to the command pipe. Defaults to RunDir + “/icinga2/cmd/icinga2.cmd”.

FileLogger

Specifies Icinga 2 logging to a file. This configuration object is available as mainlog and debuglog logging feature.

Example:

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

Configuration Attributes:

Name Type Description
path String Required. The log path.
severity String Optional. The minimum severity for this log. Can be “debug”, “notice”, “information”, “warning” or “critical”. Defaults to “information”.

GelfWriter

Writes event log entries to a defined GELF receiver host (Graylog, Logstash). This configuration object is available as gelf feature.

Example:

object GelfWriter "gelf" {
  host = "127.0.0.1"
  port = 12201
}

Configuration Attributes:

Name Type Description
host String Optional. GELF receiver host address. Defaults to 127.0.0.1.
port Number Optional. GELF receiver port. Defaults to 12201.
source String Optional. Source name for this instance. Defaults to icinga2.
enable_send_perfdata Boolean Optional. Enable performance data for ‘CHECK RESULT’ events.
enable_ha Boolean Optional. Enable the high availability functionality. Only valid in a cluster setup. Defaults to false.
enable_tls Boolean Optional. Whether to use a TLS stream. Defaults to false.
insecure_noverify Boolean Optional. Disable TLS peer verification.
ca_path String Optional. Path to CA certificate to validate the remote host. Requires enable_tls set to true.
cert_path String Optional. Path to host certificate to present to the remote host for mutual verification. Requires enable_tls set to true.
key_path String Optional. Path to host key to accompany the cert_path. Requires enable_tls set to true.

GraphiteWriter

Writes check result metrics and performance data to a defined Graphite Carbon host. This configuration object is available as graphite feature.

Example:

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

Configuration Attributes:

Name Type Description
host String Optional. Graphite Carbon host address. Defaults to 127.0.0.1.
port Number Optional. Graphite Carbon port. Defaults to 2003.
host_name_template String Optional. Metric prefix for host name. Defaults to icinga2.$host.name$.host.$host.check_command$.
service_name_template String Optional. Metric prefix for service name. Defaults to icinga2.$host.name$.services.$service.name$.$service.check_command$.
enable_send_thresholds Boolean Optional. Send additional threshold metrics. Defaults to false.
enable_send_metadata Boolean Optional. Send additional metadata metrics. Defaults to false.
enable_ha Boolean Optional. Enable the high availability functionality. Only valid in a cluster setup. Defaults to false.

Additional usage examples can be found here.

IcingaApplication

The IcingaApplication object is required to start Icinga 2. The object name must be app. If the object configuration is missing, Icinga 2 will automatically create an IcingaApplication object.

Example:

object IcingaApplication "app" {
  enable_perfdata = false
}

Configuration Attributes:

Name Type Description
enable_notifications Boolean Optional. Whether notifications are globally enabled. Defaults to true.
enable_event_handlers Boolean Optional. Whether event handlers are globally enabled. Defaults to true.
enable_flapping Boolean Optional. Whether flap detection is globally enabled. Defaults to true.
enable_host_checks Boolean Optional. Whether active host checks are globally enabled. Defaults to true.
enable_service_checks Boolean Optional. Whether active service checks are globally enabled. Defaults to true.
enable_perfdata Boolean Optional. Whether performance data processing is globally enabled. Defaults to true.
vars Dictionary Optional. A dictionary containing custom variables that are available globally.
environment String Optional. Specify the Icinga environment. This overrides the Environment constant specified in the configuration or on the CLI with --define. Defaults to empty.

IcingaDB

The IcingaDB object implements the Icinga DB feature.

Example:

object IcingaDB "icingadb" {
  //host = "127.0.0.1"
  //port = 6380
  //password = "xxx"
}

Configuration Attributes:

Name Type Description
host String Optional. Redis host. Defaults to 127.0.0.1.
port Number Optional. Redis port. Defaults to 6380 since the Redis server provided by the icingadb-redis package listens on that port.
path String Optional. Redis unix socket path. Can be used instead of host and port attributes.
password String Optional. Redis auth password.
enable_tls Boolean Optional. Whether to use TLS.
cert_path String Optional. Path to the certificate.
key_path String Optional. Path to the private key.
ca_path String Optional. Path to the CA certificate to use instead of the system’s root CAs.
crl_path String Optional. Path to the CRL file.
cipher_list String Optional. Cipher list that is allowed. For a list of available ciphers run openssl ciphers. Defaults to ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384:DHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256.
tls_protocolmin String Optional. Minimum TLS protocol version. Defaults to TLSv1.2.
insecure_noverify Boolean Optional. Whether not to verify the peer.
connect_timeout Number Optional. Timeout for establishing new connections. Within this time, the TCP, TLS (if enabled) and Redis handshakes must complete. Defaults to 15s.

IdoMySqlConnection

Note

This feature is DEPRECATED and may be removed in future releases. Check the roadmap.

IDO database adapter for MySQL. This configuration object is available as ido-mysql feature.

Example:

object IdoMysqlConnection "mysql-ido" {
  host = "127.0.0.1"
  port = 3306
  user = "icinga"
  password = "icinga"
  database = "icinga"

  cleanup = {
    downtimehistory_age = 48h
    contactnotifications_age = 31d
  }
}

Configuration Attributes:

Name Type Description
host String Optional. MySQL database host address. Defaults to localhost.
port Number Optional. MySQL database port. Defaults to 3306.
socket_path String Optional. MySQL socket path.
user String Optional. MySQL database user with read/write permission to the icinga database. Defaults to icinga.
password String Optional. MySQL database user’s password. Defaults to icinga.
database String Optional. MySQL database name. Defaults to icinga.
enable_ssl Boolean Optional. Use SSL. Defaults to false. Change to true in case you want to use any of the SSL options.
ssl_key String Optional. MySQL SSL client key file path.
ssl_cert String Optional. MySQL SSL certificate file path.
ssl_ca String Optional. MySQL SSL certificate authority certificate file path.
ssl_capath String Optional. MySQL SSL trusted SSL CA certificates in PEM format directory path.
ssl_cipher String Optional. MySQL SSL list of allowed ciphers.
table_prefix String Optional. MySQL database table prefix. Defaults to icinga_.
instance_name String Optional. Unique identifier for the local Icinga 2 instance, used for multiple Icinga 2 clusters writing to the same database. Defaults to default.
instance_description String Optional. Description for the Icinga 2 instance.
enable_ha Boolean Optional. Enable the high availability functionality. Only valid in a cluster setup. Defaults to true.
failover_timeout Duration Optional. Set the failover timeout in a HA cluster. Must not be lower than 30s. Defaults to 30s.
cleanup Dictionary Optional. Dictionary with items for historical table cleanup.
categories Array Optional. Array of information types that should be written to the database.

Cleanup Items:

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

Supported units

Supported suffixes include ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Check the language reference.

Data Categories:

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

The default value for categories includes everything required by Icinga Web 2 in the table above.

In addition to the category flags listed above the DbCatEverything flag may be used as a shortcut for listing all flags.

Runtime Attributes:

Name Type Description
last_failover Timestamp When the last failover happened for this connection (only available with enable_ha = true.

IdoPgsqlConnection

Note

This feature is DEPRECATED and may be removed in future releases. Check the roadmap.

IDO database adapter for PostgreSQL. This configuration object is available as ido-pgsql feature.

Example:

object IdoPgsqlConnection "pgsql-ido" {
  host = "127.0.0.1"
  port = 5432
  user = "icinga"
  password = "icinga"
  database = "icinga"

  cleanup = {
    downtimehistory_age = 48h
    contactnotifications_age = 31d
  }
}

Configuration Attributes:

Name Type Description
host String Optional. PostgreSQL database host address. Defaults to localhost.
port Number Optional. PostgreSQL database port. Defaults to 5432.
user String Optional. PostgreSQL database user with read/write permission to the icinga database. Defaults to icinga.
password String Optional. PostgreSQL database user’s password. Defaults to icinga.
database String Optional. PostgreSQL database name. Defaults to icinga.
ssl_mode String Optional. Enable SSL connection mode. Value must be set according to the sslmode setting: prefer, require, verify-ca, verify-full, allow, disable.
ssl_key String Optional. PostgreSQL SSL client key file path.
ssl_cert String Optional. PostgreSQL SSL certificate file path.
ssl_ca String Optional. PostgreSQL SSL certificate authority certificate file path.
table_prefix String Optional. PostgreSQL database table prefix. Defaults to icinga_.
instance_name String Optional. Unique identifier for the local Icinga 2 instance, used for multiple Icinga 2 clusters writing to the same database. Defaults to default.
instance_description String Optional. Description for the Icinga 2 instance.
enable_ha Boolean Optional. Enable the high availability functionality. Only valid in a cluster setup. Defaults to true.
failover_timeout Duration Optional. Set the failover timeout in a HA cluster. Must not be lower than 30s. Defaults to 30s.
cleanup Dictionary Optional. Dictionary with items for historical table cleanup.
categories Array Optional. Array of information types that should be written to the database.

Cleanup Items:

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

Supported units

Supported suffixes include ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Check the language reference.

Data Categories:

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

The default value for categories includes everything required by Icinga Web 2 in the table above.

In addition to the category flags listed above the DbCatEverything flag may be used as a shortcut for listing all flags.

Runtime Attributes:

Name Type Description
last_failover Timestamp When the last failover happened for this connection (only available with enable_ha = true.

InfluxdbWriter

Writes check result metrics and performance data to a defined InfluxDB v1 host. This configuration object is available as influxdb feature. For InfluxDB v2 support see the Influxdb2Writer below.

Example:

object InfluxdbWriter "influxdb" {
  host = "127.0.0.1"
  port = 8086
  database = "icinga2"
  username = "icinga2"
  password = "icinga2"

  basic_auth = {
     username = "icinga"
     password = "icinga"
  }

  flush_threshold = 1024
  flush_interval = 10s

  host_template = {
    measurement = "$host.check_command$"
    tags = {
      hostname = "$host.name$"
    }
  }
  service_template = {
    measurement = "$service.check_command$"
    tags = {
      hostname = "$host.name$"
      service = "$service.name$"
    }
  }
}

Configuration Attributes:

Name Type Description
host String Required. InfluxDB host address. Defaults to 127.0.0.1.
port Number Required. InfluxDB HTTP port. Defaults to 8086.
database String Required. InfluxDB database name. Defaults to icinga2.
username String Optional. InfluxDB user name. Defaults to none.
password String Optional. InfluxDB user password. Defaults to none.
basic_auth Dictionary Optional. Username and password for HTTP basic authentication.
ssl_enable Boolean Optional. Whether to use a TLS stream. Defaults to false.
ssl_insecure_noverify Boolean Optional. Disable TLS peer verification.
ssl_ca_cert String Optional. Path to CA certificate to validate the remote host.
ssl_cert String Optional. Path to host certificate to present to the remote host for mutual verification.
ssl_key String Optional. Path to host key to accompany the ssl_cert.
host_template Dictionary Required. Host template to define the InfluxDB line protocol.
service_template Dictionary Required. Service template to define the influxDB line protocol.
enable_send_thresholds Boolean Optional. Whether to send warn, crit, min & max tagged data.
enable_send_metadata Boolean Optional. Whether to send check metadata e.g. states, execution time, latency etc.
flush_interval Duration Optional. How long to buffer data points before transferring to InfluxDB. Defaults to 10s.
flush_threshold Number Optional. How many data points to buffer before forcing a transfer to InfluxDB. Defaults to 1024.
enable_ha Boolean Optional. Enable the high availability functionality. Only valid in a cluster setup. Defaults to false.

Note: If flush_threshold is set too low, this will always force the feature to flush all data to InfluxDB. Experiment with the setting, if you are processing more than 1024 metrics per second or similar.

Influxdb2Writer

Writes check result metrics and performance data to a defined InfluxDB v2 host. This configuration object is available as influxdb feature. For InfluxDB v1 support see the InfluxdbWriter above.

Example:

object Influxdb2Writer "influxdb2" {
  host = "127.0.0.1"
  port = 8086
  organization = "monitoring"
  bucket = "icinga2"
  auth_token = "ABCDEvwxyz0189-_"

  flush_threshold = 1024
  flush_interval = 10s

  host_template = {
    measurement = "$host.check_command$"
    tags = {
      hostname = "$host.name$"
    }
  }
  service_template = {
    measurement = "$service.check_command$"
    tags = {
      hostname = "$host.name$"
      service = "$service.name$"
    }
  }
}

Configuration Attributes:

Name Type Description
host String Required. InfluxDB host address. Defaults to 127.0.0.1.
port Number Required. InfluxDB HTTP port. Defaults to 8086.
organization String Required. InfluxDB organization name.
bucket String Required. InfluxDB bucket name.
auth_token String Required. InfluxDB authentication token.
ssl_enable Boolean Optional. Whether to use a TLS stream. Defaults to false.
ssl_insecure_noverify Boolean Optional. Disable TLS peer verification.
ssl_ca_cert String Optional. Path to CA certificate to validate the remote host.
ssl_cert String Optional. Path to host certificate to present to the remote host for mutual verification.
ssl_key String Optional. Path to host key to accompany the ssl_cert.
host_template Dictionary Required. Host template to define the InfluxDB line protocol.
service_template Dictionary Required. Service template to define the influxDB line protocol.
enable_send_thresholds Boolean Optional. Whether to send warn, crit, min & max tagged data.
enable_send_metadata Boolean Optional. Whether to send check metadata e.g. states, execution time, latency etc.
flush_interval Duration Optional. How long to buffer data points before transferring to InfluxDB. Defaults to 10s.
flush_threshold Number Optional. How many data points to buffer before forcing a transfer to InfluxDB. Defaults to 1024.
enable_ha Boolean Optional. Enable the high availability functionality. Only valid in a cluster setup. Defaults to false.

Note: If flush_threshold is set too low, this will always force the feature to flush all data to InfluxDB. Experiment with the setting, if you are processing more than 1024 metrics per second or similar.

JournaldLogger

Specifies Icinga 2 logging to the systemd journal using its native interface. This configuration object is available as journald logging feature.

Resulting journal records have fields as described in journal fields, and an additional custom field ICINGA2_FACILITY with the detailed message origin (e.g. “ApiListener”).

Example:

object JournaldLogger "journald" {
  severity = "warning"
}

Configuration Attributes:

Name Type Description
severity String Optional. The minimum syslog compatible severity for this log. Can be “debug”, “notice”, “information”, “warning” or “critical”. Defaults to “information”.
facility String Optional. Defines the syslog compatible facility to use for journal entries. This can be a facility constant like FacilityDaemon. Defaults to FacilityUser.
identifier String Optional. Defines the syslog compatible identifier (also known as “tag”) to use for journal entries. If not given, systemd’s default behavior is used and usually results in “icinga2”.

Facility Constants are the same as for SyslogLogger.

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. This configuration object is available as livestatus feature.

Note

This feature is DEPRECATED and may be removed in future releases. Check the roadmap.

Examples:

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

Configuration Attributes:

Name Type Description
socket_type String Optional. Specifies the socket type. Can be either tcp or unix. Defaults to unix.
bind_host String Optional. Only valid when socket_type is set to tcp. Host address to listen on for connections. Defaults to 127.0.0.1.
bind_port Number Optional. Only valid when socket_type is set to tcp. Port to listen on for connections. Defaults to 6558.
socket_path String Optional. Only valid when socket_type is set to unix. Specifies the path to the UNIX socket file. Defaults to RunDir + “/icinga2/cmd/livestatus”.
compat_log_path String Optional. Path to Icinga 1.x log files. Required for historical table queries. Requires CompatLogger feature enabled. Defaults to LogDir + “/compat”

Note

UNIX sockets are not supported on Windows.

NotificationComponent

The notification component is responsible for sending notifications. This configuration object is available as notification feature.

Example:

object NotificationComponent "notification" { }

Configuration Attributes:

Name Type Description
enable_ha Boolean Optional. Enable the high availability functionality. Only valid in a cluster setup. Disabling this currently only affects reminder notifications. Defaults to “true”.

OpenTsdbWriter

Writes check result metrics and performance data to OpenTSDB. This configuration object is available as opentsdb feature.

Example:

object OpenTsdbWriter "opentsdb" {
  host = "127.0.0.1"
  port = 4242
}

Configuration Attributes:

Name Type Description
host String Optional. OpenTSDB host address. Defaults to 127.0.0.1.
port Number Optional. OpenTSDB port. Defaults to 4242.
enable_ha Boolean Optional. Enable the high availability functionality. Only valid in a cluster setup. Defaults to false.
enable_generic_metrics Boolean Optional. Re-use metric names to store different perfdata values for a particular check. Use tags to distinguish perfdata instead of metric name. Defaults to false.
host_template Dictionary Optional. Specify additional tags to be included with host metrics. This requires a sub-dictionary named tags. Also specify a naming prefix by setting metric. More information can be found in OpenTSDB custom tags and OpenTSDB Metric Prefix. More information can be found in OpenTSDB custom tags. Defaults to an empty Dictionary.
service_template Dictionary Optional. Specify additional tags to be included with service metrics. This requires a sub-dictionary named tags. Also specify a naming prefix by setting metric. More information can be found in OpenTSDB custom tags and OpenTSDB Metric Prefix. Defaults to an empty Dictionary.

PerfdataWriter

Writes check result performance data to a defined path using macro pattern consisting of custom variables and runtime macros. This configuration object is available as perfdata feature.

Example:

object PerfdataWriter "perfdata" {
  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
}

Configuration Attributes:

Name Type Description
host_perfdata_path String Optional. Path to the host performance data file. Defaults to SpoolDir + “/perfdata/host-perfdata”.
service_perfdata_path String Optional. Path to the service performance data file. Defaults to SpoolDir + “/perfdata/service-perfdata”.
host_temp_path String Optional. Path to the temporary host file. Defaults to SpoolDir + “/tmp/host-perfdata”.
service_temp_path String Optional. Path to the temporary service file. Defaults to SpoolDir + “/tmp/service-perfdata”.
host_format_template String Optional. Host Format template for the performance data file. Defaults to a template that’s suitable for use with PNP4Nagios.
service_format_template String Optional. Service Format template for the performance data file. Defaults to a template that’s suitable for use with PNP4Nagios.
rotation_interval Duration Optional. Rotation interval for the files specified in {host,service}_perfdata_path. Defaults to 30s.
enable_ha Boolean Optional. Enable the high availability functionality. Only valid in a cluster setup. Defaults to false.

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.

SyslogLogger

Specifies Icinga 2 logging to syslog. This configuration object is available as syslog logging feature.

Example:

object SyslogLogger "syslog" {
  severity = "warning"
}

Configuration Attributes:

Name Type Description
severity String Optional. The minimum severity for this log. Can be “debug”, “notice”, “information”, “warning” or “critical”. Defaults to “information”.
facility String Optional. Defines the facility to use for syslog entries. This can be a facility constant like FacilityDaemon. Defaults to FacilityUser.

Facility Constants:

Name Facility Description
FacilityAuth LOG_AUTH The authorization system.
FacilityAuthPriv LOG_AUTHPRIV The same as FacilityAuth, but logged to a file readable only by selected individuals.
FacilityCron LOG_CRON The cron daemon.
FacilityDaemon LOG_DAEMON System daemons that are not provided for explicitly by other facilities.
FacilityFtp LOG_FTP The file transfer protocol daemons.
FacilityKern LOG_KERN Messages generated by the kernel. These cannot be generated by any user processes.
FacilityLocal0 LOG_LOCAL0 Reserved for local use.
FacilityLocal1 LOG_LOCAL1 Reserved for local use.
FacilityLocal2 LOG_LOCAL2 Reserved for local use.
FacilityLocal3 LOG_LOCAL3 Reserved for local use.
FacilityLocal4 LOG_LOCAL4 Reserved for local use.
FacilityLocal5 LOG_LOCAL5 Reserved for local use.
FacilityLocal6 LOG_LOCAL6 Reserved for local use.
FacilityLocal7 LOG_LOCAL7 Reserved for local use.
FacilityLpr LOG_LPR The line printer spooling system.
FacilityMail LOG_MAIL The mail system.
FacilityNews LOG_NEWS The network news system.
FacilitySyslog LOG_SYSLOG Messages generated internally by syslogd.
FacilityUser LOG_USER Messages generated by user processes. This is the default facility identifier if none is specified.
FacilityUucp LOG_UUCP The UUCP system.

WindowsEventLogLogger

Specifies Icinga 2 logging to the Windows Event Log. This configuration object is available as windowseventlog logging feature.

Example:

object WindowsEventLogLogger "windowseventlog" {
  severity = "information"
}

Configuration Attributes:

Name Type Description
severity String Optional. The minimum severity for this log. Can be “debug”, “notice”, “information”, “warning” or “critical”. Defaults to “information”.