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

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.

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 NodeName 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. Defaults to 0.0.0.0.
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.
cipher_list String Optional. Cipher list that is allowed. For a list of available ciphers run openssl ciphers. Defaults to ALL:!LOW:!WEAK:!MEDIUM:!EXP:!NULL.
tls_protocolmin String Optional. Minimum TLS protocol version. Must be one of TLSv1, TLSv1.1 or TLSv1.2. Defaults to TLSv1.
access_control_allow_origin Array Optional. Specifies an array of origin URLs that may access the API. (MDN docs)
access_control_allow_credentials Boolean Optional. Indicates whether or not the actual request can be made using credentials. Defaults to true. (MDN docs)
access_control_allow_headers String Optional. 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 Optional. 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)

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

Type Location
Private key LocalStateDir + "/lib/icinga2/certs/" + NodeName + ".key"
Certificate file LocalStateDir + "/lib/icinga2/certs/" + NodeName + ".crt"
CA certificate file LocalStateDir + "/lib/icinga2/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 LocalStateDir + "/lib/icinga2/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.

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 attributes can be defined here.

Note

Icinga 2 versions < 2.6.0 require the import of the plugin-check-command template.

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 attributes 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. If the argument requires additional configuration, for example a description attribute or an optional condition, the value can be defined as dictionary specifying additional options.

Service:

vars.x_val = "My command argument value."
vars.have_x = "true"

CheckCommand:

arguments = {
  "-X" = {
    value = "$x_val$"
    key = "-Xnew"       /* optional, set a new key identifier */
    description = "My plugin requires this argument for doing X."
    required = false    /* optional, no error if not set */
    skip_key = false    /* always use "-X <value>" */
    set_if = "$have_x$" /* only set if variable defined and resolves to a numeric value. String values are not supported */
    order = -1          /* first position */
    repeat_key = true   /* if `value` is an array, repeat the key as parameter: ... 'key' 'value[0]' 'key' 'value[1]' 'key' 'value[2]' ... */
  }
  "-Y" = {
    value = "$y_val$"
    description = "My plugin requires this argument for doing Y."
    required = false    /* optional, no error if not set */
    skip_key = true     /* don't prefix "-Y" only use "<value>" */
    set_if = "$have_y$" /* only set if variable defined and resolves to a numeric value. String values are not supported */
    order = 0           /* second position */
    repeat_key = false  /* if `value` is an array, do not repeat the key as parameter: ... 'key' 'value[0]' 'value[1]' 'value[2]' ... */
  }
}
Name Type Description
value String/Function Optional argument value set by a runtime macro string or a function call.
key String Optional argument key overriding the key identifier.
description String Optional argument description.
required Boolean Required argument. Execution error if not set. Defaults to false (optional).
skip_key Boolean Use the value as argument and skip the key.
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.
order Number Set if multiple arguments require a defined argument order.
repeat_key Boolean If the argument value is an array, repeat the argument key, or not. Defaults to true (repeat).

Argument order:

..., -3, -2, -1, <un-ordered keys>, 1, 2, 3, ...

Argument array with repeat_key = true:

'key' 'value[0]' 'key' 'value[1]' 'key' 'value[2]'

Argument array with repeat_key = false:

'key' 'value[0]' 'value[1]' 'value[2]'

CheckerComponent

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

Example:

library "checker"

object CheckerComponent "checker" {
  concurrent_checks = 512
}

Configuration Attributes:

Name Type Description
concurrent_checks Number Optional. The maximum number of concurrent checks. Defaults to 512.

CheckResultReader

Reads Icinga 1.x check result files from a directory. This functionality is provided to help existing Icinga 1.x users and might be useful for migration scenarios.

Example:

library "compat"

object CheckResultReader "reader" {
  spool_dir = "/data/check-results"
}

Configuration Attributes:

Name Type Description
spool_dir String Optional. The directory which contains the check result files. Defaults to LocalStateDir + “/lib/icinga2/spool/checkresults/”.

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 "localhost!my-comment" {
  host_name = "localhost"
  author = "icingaadmin"
  text = "This is a comment."
}

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

CompatLogger

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

Example:

library "compat"

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 LocalStateDir + “/log/icinga2/compat”.
rotation_method String Optional. Specifies when to rotate log files. Can be one of “HOURLY”, “DAILY”, “WEEKLY” or “MONTHLY”. Defaults to “HOURLY”.

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.
disable_checks Boolean Optional. Whether to disable checks 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.

Downtime

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

Example:

object Downtime "localhost!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.

ElasticsearchWriter

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

Example:

library "perfdata"

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

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.

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-client1.localdomain" {
  host = "192.168.56.111"
  port = 5665
  log_duration = 1d
}

Example (disable replay log):

object Endpoint "icinga2-client1.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.

Note

Icinga 2 versions < 2.6.0 require the import of the plugin-event-command template.

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

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.

Example:

library "compat"

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:

library "perfdata"

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.

GraphiteWriter

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

Example:

library "perfdata"

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.

Additional usage examples can be found here.

Host

A host.

Example:

object Host "icinga2-client1.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 attributes 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.
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.
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
volatile Boolean Optional. The volatile setting enables always HARD state types if NOT-OK state changes occur. 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).

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.

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 attributes that are available globally.

IdoMySqlConnection

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

Example:

library "db_ido_mysql"

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. 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 60s. Defaults to 60s.
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 hostalives 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).

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.

IdoPgsqlConnection

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

Example:

library "db_ido_pgsql"

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.
table_prefix String Optional. PostgreSQL database table prefix. Defaults to icinga_.
instance_name String Optional. Unique identifier for the local Icinga 2 instance. 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 60s. Defaults to 60s.
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 hostalives 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).

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.

InfluxdbWriter

Writes check result metrics and performance data to a defined InfluxDB host. This configuration object is available as influxdb feature.

Example:

library "perfdata"

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

  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.
ssl_enable Boolean Optional. Whether to use a TLS stream. Defaults to false.
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 String Required. Host template to define the InfluxDB line protocol.
service_template String 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.

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.

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.

Examples:

library "livestatus"

object LivestatusListener "livestatus-tcp" {
  socket_type = "tcp"
  bind_host = "127.0.0.1"
  bind_port = "6558"
}

object LivestatusListener "livestatus-unix" {
  socket_type = "unix"
  socket_path = "/var/run/icinga2/cmd/livestatus"
}

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 LocalStateDir + “/log/icinga2/compat”

Note

UNIX sockets are not supported on Windows.

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

  types = [ Problem, Recovery ]
}

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 attributes that are specific to this notification object.
users Array of object names Optional. A list of user names who should be notified.
user_groups Array of object names Optional. A list of user group names who should be notified.
times Dictionary Optional. A dictionary containing begin and end attributes for the notification.
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.
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.

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.

Note

Icinga 2 versions < 2.6.0 require the import of the plugin-notification-command template.

Example:

object NotificationCommand "mail-service-notification" {
  command = [ SysconfDir + "/icinga2/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 attributes 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.

NotificationComponent

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

Example:

library "notification"

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:

library "perfdata"

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.

PerfdataWriter

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

Example:

library "perfdata"

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 LocalStateDir + “/spool/icinga2/perfdata/host-perfdata”.
service_perfdata_path String Optional. Path to the service performance data file. Defaults to LocalStateDir + “/spool/icinga2/perfdata/service-perfdata”.
host_temp_path String Optional. Path to the temporary host file. Defaults to LocalStateDir + “/spool/icinga2/tmp/host-perfdata”.
service_temp_path String Optional. Path to the temporary service file. Defaults to LocalStateDir + “/spool/icinga2/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.

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.

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.

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 attributes 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.
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.
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
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. The volatile setting enables always HARD state types if NOT-OK state changes occur. 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).
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 host 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).

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.

StatusDataWriter

Periodically writes status and configuration data files which are used by third-party tools. This configuration object is available as statusdata feature.

Example:

library "compat"

object StatusDataWriter "status" {
    status_path = "/var/cache/icinga2/status.dat"
    objects_path = "/var/cache/icinga2/objects.cache"
    update_interval = 30s
}

Configuration Attributes:

Name Type Description
status_path String Optional. Path to the status.dat file. Defaults to LocalStateDir + “/cache/icinga2/status.dat”.
objects_path String Optional. Path to the objects.cache file. Defaults to LocalStateDir + “/cache/icinga2/objects.cache”.
update_interval Duration Optional. The interval in which the status files are updated. Defaults to 15s.

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 “warning”.
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.

TimePeriod

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

Note

Icinga 2 versions < 2.6.0 require the import of the legacy-timeperiod template.

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 attributes 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.
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.
types Array Optional. A set of type filters when this notification should be triggered. By default everything is matched.
states Array Optional. A set of state filters when this notification 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.
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.