108 KiB

Raw Blame History

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

Monitoring Objects such as host, service, etc.
Runtime Objects generated by Icinga itself.
Features available via icinga2 feature CLI command.

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.

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).
last_in_downtime	Boolean	Whether the host was in a downtime when the last check occurred.
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.

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.
name	String	Required. The service name. Must be unique on a per-host basis. For advanced usage in apply rules only.
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).
last_in_downtime	Boolean	Whether the service was in a downtime when the last check occurred.
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.

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

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

108 KiB Raw Blame History

Object Types

Overview

Common Runtime Attributes

Monitoring Objects

ApiUser

CheckCommand

CheckCommand Arguments

Dependency

Endpoint

EventCommand

Host

HostGroup

Notification

NotificationCommand

ScheduledDowntime

Service

ServiceGroup

TimePeriod

User

UserGroup

Zone

Runtime Objects

Comment

Downtime

Features

ApiListener

CheckerComponent

CompatLogger

ElasticsearchWriter

ExternalCommandListener

FileLogger

GelfWriter

GraphiteWriter

IcingaApplication

IcingaDB

IdoMySqlConnection

IdoPgsqlConnection

InfluxdbWriter

Influxdb2Writer

JournaldLogger

LiveStatusListener

NotificationComponent

OpenTsdbWriter

PerfdataWriter

SyslogLogger

WindowsEventLogLogger

108 KiB

Raw Blame History