icinga2/doc/6-object-types.md

66 KiB

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

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

Name Description
version Timestamp when the object was created or modified. Synced throughout cluster nodes.
type Object type.
original_attributes Original values of object attributes modified at runtime.
active Object is active (e.g. a service being checked).
paused Object has been paused at runtime (e.g. IdoMysqlConnection. Defaults to false.
templates Templates imported on object compilation.
package Configuration package name this object belongs to. Local configuration is set to _etc, runtime created objects use _api.

ApiListener

ApiListener objects are used for distributed monitoring setups and API usage specifying the certificate files used for ssl authorization and additional restrictions.

The NodeName constant must be defined in constants.conf.

Example:

object ApiListener "api" {
  cert_path = SysconfDir + "/icinga2/pki/" + NodeName + ".crt"
  key_path = SysconfDir + "/icinga2/pki/" + NodeName + ".key"
  ca_path = SysconfDir + "/icinga2/pki/ca.crt"
}

Configuration Attributes:

Name Description
cert_path Required. Path to the public key.
key_path Required. Path to the private key.
ca_path Required. Path to the CA certificate file.
crl_path Optional. Path to the CRL file.
bind_host Optional. The IP address the api listener should be bound to. Defaults to 0.0.0.0.
bind_port Optional. The port the api listener should be bound to. Defaults to 5665.
accept_config Optional. Accept zone configuration. Defaults to false.
accept_commands Optional. Accept remote commands. Defaults to false.

ApiUser

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

Example:

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

Configuration Attributes:

Name Description
password Optional. Password string.
client_cn Optional. Client Common Name (CN).
permissions 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 described in the API permissions chapter.

CheckCommand

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

Example:

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

  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 Description
execute Required. The "execute" script method takes care of executing the check. In virtually all cases you should import the "plugin-check-command" template to take care of this setting.
command Required. The command. This can either be an array of individual command arguments. Alternatively a string can be specified in which case the shell interpreter (usually /bin/sh) takes care of parsing the command. When using the "arguments" attribute this must be an array. Can be specified as function for advanced implementations.
env Optional. A dictionary of macros which should be exported as environment variables prior to executing the command.
vars Optional. A dictionary containing custom attributes that are specific to this command.
timeout Optional. The command timeout in seconds. Defaults to 60 seconds.
arguments 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]' ... */
  }
}
Option Description
value Optional argument value set by a macro string or a function call.
key Optional argument key overriding the key identifier.
description Optional argument description.
required Required argument. Execution error if not set. Defaults to false (optional).
skip_key Use the value as argument and skip the key.
set_if Argument is added if the macro resolves to a defined numeric or boolean value. String values are not supported. Function calls returning a value are supported too.
order Set if multiple arguments require a defined argument order.
repeat_key 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 repeat_key = true:

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

Argument array repeat_key = false:

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

CheckerComponent

The checker component is responsible for scheduling active checks. There are no configurable options.

Example:

library "checker"

object CheckerComponent "checker" { }

CheckResultReader

Reads Icinga 1.x check results from a directory. This functionality is provided to help existing Icinga 1.x users and might be useful for certain cluster scenarios.

Example:

library "compat"

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

Configuration Attributes:

Name Description
spool_dir 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.

Example:

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

Configuration Attributes:

Name Description
host_name Required. The name of the host this comment belongs to.
service_name Optional. The short name of the service this comment belongs to. If omitted this comment object is treated as host comment.
author Required. The author's name.
text Required. The comment text.
entry_time Optional. The unix timestamp when this comment was added.
entry_type Optional. The comment type (User = 1, Downtime = 2, Flapping = 3, Acknowledgement = 4).
expire_time Optional. The comment's expire time as unix timestamp.

CompatLogger

Writes log files in a format that's compatible with Icinga 1.x.

Example:

library "compat"

object CompatLogger "my-log" {
  log_dir = "/var/log/icinga2/compat"
  rotation_method = "HOURLY"
}

Configuration Attributes:

Name Description
log_dir Optional. Path to the compat log directory. Defaults to LocalStateDir + "/log/icinga2/compat".
rotation_method Optional. Specifies when to rotate log files. Can be one of "HOURLY", "DAILY", "WEEKLY" or "MONTHLY". Defaults to "HOURLY".

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 Description
parent_host_name Required. The parent host.
parent_service_name Optional. The parent service. If omitted this dependency object is treated as host dependency.
child_host_name Required. The child host.
child_service_name Optional. The child service. If omitted this dependency object is treated as host dependency.
disable_checks Optional. Whether to disable checks when this dependency fails. Defaults to false.
disable_notifications Optional. Whether to disable notifications when this dependency fails. Defaults to true.
ignore_soft_states Optional. Whether to ignore soft states for the reachability calculation. Defaults to true.
period Optional. Time period during which this dependency is enabled.
states 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-nrpe-checks" to Service {
  parent_service_name = "nrpe-health"

  assign where service.check_command == "nrpe"
  ignore where service.name == "nrpe-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.

Example:

object Downtime "localhost!my-downtime" {
  host_name = "localhost"
  author = "icingaadmin"
  text = "This is a comment."
}

Configuration Attributes:

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

Runtime Attributes:

Name Description
trigger_time The unix timestamp when this downtime was triggered.
triggered_by The name of the downtime this downtime was triggered by.

Endpoint

Endpoint objects are used to specify connection information for remote Icinga 2 instances.

Example:

object Endpoint "icinga2b" {
  host = "192.168.5.46"
  port = 5665
}

Configuration Attributes:

Name Description
host Optional. The hostname/IP address of the remote Icinga 2 instance.
port Optional. The service name/port of the remote Icinga 2 instance. Defaults to 5665.
log_duration Optional. Duration for keeping replay logs on connection loss. Defaults to 1d.

EventCommand

An event command definition.

Example:

object EventCommand "restart-httpd-event" {
  import "plugin-event-command"

  command = "/opt/bin/restart-httpd.sh"
}

Configuration Attributes:

Name Description
execute Required. The "execute" script method takes care of executing the event handler. In virtually all cases you should import the "plugin-event-command" template to take care of this setting.
command Required. The command. This can either be an array of individual command arguments. Alternatively a string can be specified in which case the shell interpreter (usually /bin/sh) takes care of parsing the command.
env Optional. A dictionary of macros which should be exported as environment variables prior to executing the command.
vars Optional. A dictionary containing custom attributes that are specific to this command.
timeout Optional. The command timeout in seconds. Defaults to 60 seconds.
arguments Optional. A dictionary of command arguments.

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

ExternalCommandListener

Implements the Icinga 1.x command pipe which can be used to send commands to Icinga.

Example:

library "compat"

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

Configuration Attributes:

Name Description
command_path Optional. Path to the command pipe. Defaults to RunDir + "/icinga2/cmd/icinga2.cmd".

FileLogger

Specifies Icinga 2 logging to a file.

Example:

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

Configuration Attributes:

Name Description
path Required. The log path.
severity 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 (Graylog2, Logstash).

Example:

library "perfdata"

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

Configuration Attributes:

Name Description
host Optional. GELF receiver host address. Defaults to '127.0.0.1'.
port Optional. GELF receiver port. Defaults to 12201.
source Optional. Source name for this instance. Defaults to icinga2.

GraphiteWriter

Writes check result metrics and performance data to a defined Graphite Carbon host.

Example:

library "perfdata"

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

Configuration Attributes:

Name Description
host Optional. Graphite Carbon host address. Defaults to '127.0.0.1'.
port Optional. Graphite Carbon port. Defaults to 2003.
host_name_template Optional. Metric prefix for host name. Defaults to "icinga2.host.name.host.host.check_command".
service_name_template Optional. Metric prefix for service name. Defaults to "icinga2.host.name.services.service.name.service.check_command".
enable_send_thresholds Optional. Send additional threshold metrics. Defaults to false.
enable_send_metadata Optional. Send additional metadata metrics. Defaults to false.
enable_legacy_mode Optional. Enable legacy mode for schema < 2.4. Note: This will be removed in future versions.

Additional usage examples can be found here.

Host

A host.

Example:

object Host NodeName {
  display_name = "Local host on this node"
  address = "127.0.0.1"
  address6 = "::1"

  groups = [ "all-hosts" ]

  check_command = "hostalive"
}

Configuration Attributes:

Name Description
display_name Optional. A short description of the host (e.g. displayed by external interfaces instead of the name if set).
address Optional. The host's address. Available as command runtime macro $address$ if set.
address6 Optional. The host's address. Available as command runtime macro $address6$ if set.
groups Optional. A list of host groups this host belongs to.
vars Optional. A dictionary containing custom attributes that are specific to this host.
check_command Required. The name of the check command.
max_check_attempts Optional. The number of times a host is re-checked before changing into a hard state. Defaults to 3.
check_period Optional. The name of a time period which determines when this host should be checked. Not set by default.
check_interval Optional. The check interval (in seconds). This interval is used for checks when the host is in a HARD state. Defaults to 5 minutes.
retry_interval Optional. The retry interval (in seconds). This interval is used for checks when the host is in a SOFT state. Defaults to 1 minute.
enable_notifications Optional. Whether notifications are enabled. Defaults to true.
enable_active_checks Optional. Whether active checks are enabled. Defaults to true.
enable_passive_checks Optional. Whether passive checks are enabled. Defaults to true.
enable_event_handler Optional. Enables event handlers for this host. Defaults to true.
enable_flapping Optional. Whether flap detection is enabled. Defaults to false.
enable_perfdata Optional. Whether performance data processing is enabled. Defaults to true.
event_command Optional. The name of an event command that should be executed every time the host's state changes or the host is in a SOFT state.
flapping_threshold Optional. The flapping threshold in percent when a host is considered to be flapping.
volatile Optional. The volatile setting enables always HARD state types if NOT-OK state changes occur.
zone Optional. The zone this object is a member of.
command_endpoint Optional. The endpoint where commands are executed on.
notes Optional. Notes for the host.
notes_url Optional. Url for notes for the host (for example, in notification commands).
action_url Optional. Url for actions for the host (for example, an external graphing tool).
icon_image Optional. Icon image for the host. Used by external interfaces only.
icon_image_alt Optional. Icon image description for the host. Used by external interface only.

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 Number When the next check occurs (as a UNIX timestamp).
last_check Number When the last check occured (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 Number When the last state change occurred (as a UNIX timestamp).
last_hard_state_change Number 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 Number When the acknowledgement expires (as a UNIX timestamp; 0 = no expiry).
flapping_last_change Number When the last flapping change occurred (as a UNIX timestamp).
flapping Boolean Whether the host is flapping between states.
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 Number When the last UP state occurred (as a UNIX timestamp).
last_state_down Number 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 "my-hosts" {
  display_name = "My hosts"
}

Configuration Attributes:

Name Description
display_name Optional. A short description of the host group.
groups 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 Description
enable_notifications Optional. Whether notifications are globally enabled. Defaults to true.
enable_event_handlers Optional. Whether event handlers are globally enabled. Defaults to true.
enable_flapping Optional. Whether flap detection is globally enabled. Defaults to true.
enable_host_checks Optional. Whether active host checks are globally enabled. Defaults to true.
enable_service_checks Optional. Whether active service checks are globally enabled. Defaults to true.
enable_perfdata Optional. Whether performance data processing is globally enabled. Defaults to true.
vars Optional. A dictionary containing custom attributes that are available globally.

IcingaStatusWriter

Note

This feature was deprecated in 2.4 and will be removed in future releases.

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

Example:

object IcingaStatusWriter "status" {
  status_path = LocalStateDir + "/cache/icinga2/status.json"
  update_interval = 15s
}

Configuration Attributes:

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

IdoMySqlConnection

IDO database adapter for MySQL.

Example:

library "db_ido_mysql"

object IdoMysqlConnection "mysql-ido" {
  host = "127.0.0.1"
  port = 3306
  user = "icinga"
  password = "icinga"
  database = "icinga"
  table_prefix = "icinga_"
  instance_name = "icinga2"
  instance_description = "icinga2 instance"

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

  categories = DbCatConfig | DbCatState
}

Configuration Attributes:

Name Description
host Optional. MySQL database host address. Defaults to "localhost".
port Optional. MySQL database port. Defaults to 3306.
socket_path Optional. MySQL socket path.
user Optional. MySQL database user with read/write permission to the icinga database. Defaults to "icinga".
password Optional. MySQL database user's password. Defaults to "icinga".
database Optional. MySQL database name. Defaults to "icinga".
table_prefix Optional. MySQL database table prefix. Defaults to "icinga_".
instance_name Optional. Unique identifier for the local Icinga 2 instance. Defaults to "default".
instance_description Optional. Description for the Icinga 2 instance.
enable_ha Optional. Enable the high availability functionality. Only valid in a cluster setup. Defaults to "true".
failover_timeout Optional. Set the failover timeout in a HA cluster. Must not be lower than 60s. Defaults to "60s".
cleanup Optional. Dictionary with items for historical table cleanup.
categories Optional. The types of information that should be written to the database.

Cleanup Items:

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

Data Categories:

Name Description 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 Icinga Web 2
DbCatFlapping Flap detection data Icinga Web 2
DbCatCheck Check results --
DbCatLog Log messages Icinga Web 2
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

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

External interfaces like Icinga Web 2 require everything except DbCatCheck which is the default value if categories is not set.

IdoPgSqlConnection

IDO database adapter for PostgreSQL.

Example:

library "db_ido_pgsql"

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

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

  categories = DbCatConfig | DbCatState
}

Configuration Attributes:

Name Description
host Optional. PostgreSQL database host address. Defaults to "localhost".
port Optional. PostgreSQL database port. Defaults to "5432".
user Optional. PostgreSQL database user with read/write permission to the icinga database. Defaults to "icinga".
password Optional. PostgreSQL database user's password. Defaults to "icinga".
database Optional. PostgreSQL database name. Defaults to "icinga".
table_prefix Optional. PostgreSQL database table prefix. Defaults to "icinga_".
instance_name Optional. Unique identifier for the local Icinga 2 instance. Defaults to "default".
instance_description Optional. Description for the Icinga 2 instance.
enable_ha Optional. Enable the high availability functionality. Only valid in a cluster setup. Defaults to "true".
failover_timeout Optional. Set the failover timeout in a HA cluster. Must not be lower than 60s. Defaults to "60s".
cleanup Optional. Dictionary with items for historical table cleanup.
categories Optional. The types of information that should be written to the database.

Cleanup Items:

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

Data Categories:

Name Description 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 Icinga Web 2
DbCatFlapping Flap detection data Icinga Web 2
DbCatCheck Check results --
DbCatLog Log messages Icinga Web 2
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

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

External interfaces like Icinga Web 2 require everything except DbCatCheck which is the default value if categories is not set.

LiveStatusListener

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

Example:

library "livestatus"

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

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

Configuration Attributes:

Name Description
socket_type Optional. Specifies the socket type. Can be either "tcp" or "unix". Defaults to "unix".
bind_host Optional. Only valid when socket_type is "tcp". Host address to listen on for connections. Defaults to "127.0.0.1".
bind_port Optional. Only valid when socket_type is "tcp". Port to listen on for connections. Defaults to 6558.
socket_path Optional. Only valid when socket_type is "unix". Specifies the path to the UNIX socket file. Defaults to RunDir + "/icinga2/cmd/livestatus".
compat_log_path Optional. Required for historical table queries. Requires CompatLogger feature enabled. Defaults to LocalStateDir + "/log/icinga2/compat"

Note

UNIX sockets are not supported on Windows.

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 Description
host_name Required. The name of the host this notification belongs to.
service_name Optional. The short name of the service this notification belongs to. If omitted this notification object is treated as host notification.
vars Optional. A dictionary containing custom attributes that are specific to this notification object.
users Optional. A list of user names who should be notified.
user_groups Optional. A list of user group names who should be notified.
times Optional. A dictionary containing begin and end attributes for the notification.
command Required. The name of the notification command which should be executed when the notification is triggered.
interval Optional. The notification interval (in seconds). This interval is used for active notifications. Defaults to 30 minutes. If set to 0, re-notifications are disabled.
period Optional. The name of a time period which determines when this notification should be triggered. Not set by default.
zone Optional. The zone this object is a member of.
types Optional. A list of type filters when this notification should be triggered. By default everything is matched.
states 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 Number When the last notification was sent for this Notification object (as a UNIX timestamp).
next_notifcation Number 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 Number When the last notification was sent for a problem (as a UNIX timestamp).

NotificationCommand

A notification command definition.

Example:

object NotificationCommand "mail-service-notification" {
  import "plugin-notification-command"

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

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

Configuration Attributes:

Name Description
execute Required. The "execute" script method takes care of executing the notification. In virtually all cases you should import the "plugin-notification-command" template to take care of this setting.
command Required. The command. This can either be an array of individual command arguments. Alternatively a string can be specified in which case the shell interpreter (usually /bin/sh) takes care of parsing the command.
env Optional. A dictionary of macros which should be exported as environment variables prior to executing the command.
vars Optional. A dictionary containing custom attributes that are specific to this command.
timeout Optional. The command timeout in seconds. Defaults to 60 seconds.
arguments Optional. A dictionary of command arguments.

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

NotificationComponent

The notification component is responsible for sending notifications. There are no configurable options.

Example:

library "notification"

object NotificationComponent "notification" { }

Configuration Attributes:

Name Description
enable_ha Optional. Enable the high availability functionality. Only valid in a cluster setup. Defaults to "true".

OpenTsdbWriter

Writes check result metrics and performance data to OpenTSDB.

Example:

library "perfdata"

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

Configuration Attributes:

Name Description
host Optional. OpenTSDB host address. Defaults to '127.0.0.1'.
port 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.

Example:

library "perfdata"

object PerfdataWriter "pnp" {
  host_perfdata_path = "/var/spool/icinga2/perfdata/host-perfdata"

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

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

  rotation_interval = 15s
}

Configuration Attributes:

Name Description
host_perfdata_path Optional. Path to the host performance data file. Defaults to LocalStateDir + "/spool/icinga2/perfdata/host-perfdata".
service_perfdata_path Optional. Path to the service performance data file. Defaults to LocalStateDir + "/spool/icinga2/perfdata/service-perfdata".
host_temp_path Optional. Path to the temporary host file. Defaults to LocalStateDir + "/spool/icinga2/tmp/host-perfdata".
service_temp_path Optional. Path to the temporary service file. Defaults to LocalStateDir + "/spool/icinga2/tmp/service-perfdata".
host_format_template Optional. Host Format template for the performance data file. Defaults to a template that's suitable for use with PNP4Nagios.
service_format_template Optional. Service Format template for the performance data file. Defaults to a template that's suitable for use with PNP4Nagios.
rotation_interval Optional. Rotation interval for the files specified in {host,service}_perfdata_path. Defaults to 30 seconds.

When rotating the performance data file the current UNIX timestamp is appended to the path specified in host_perfdata_path and service_perfdata_path to generate a unique filename.

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 Description
host_name Required. The name of the host this scheduled downtime belongs to.
service_name Optional. The short name of the service this scheduled downtime belongs to. If omitted this downtime object is treated as host downtime.
author Required. The author of the downtime.
comment Required. A comment for the downtime.
fixed Optional. Whether this is a fixed downtime. Defaults to true.
duration Optional. How long the downtime lasts. Only has an effect for flexible (non-fixed) downtimes.
ranges Required. A dictionary containing information which days and durations apply to this timeperiod.

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

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 = "check_snmp"

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

  check_interval = 60s
  retry_interval = 15s

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

Configuration Attributes:

Name Description
display_name Optional. A short description of the service.
host_name Required. The host this service belongs to. There must be a Host object with that name.
name Required. The service name. Must be unique on a per-host basis (Similar to the service_description attribute in Icinga 1.x).
groups Optional. The service groups this service belongs to.
vars Optional. A dictionary containing custom attributes that are specific to this service.
check_command Required. The name of the check command.
max_check_attempts Optional. The number of times a service is re-checked before changing into a hard state. Defaults to 3.
check_period Optional. The name of a time period which determines when this service should be checked. Not set by default.
check_interval Optional. The check interval (in seconds). This interval is used for checks when the service is in a HARD state. Defaults to 5 minutes.
retry_interval Optional. The retry interval (in seconds). This interval is used for checks when the service is in a SOFT state. Defaults to 1 minute.
enable_notifications Optional. Whether notifications are enabled. Defaults to true.
enable_active_checks Optional. Whether active checks are enabled. Defaults to true.
enable_passive_checks Optional. Whether passive checks are enabled. Defaults to true.
enable_event_handler Optional. Enables event handlers for this host. Defaults to true.
enable_flapping Optional. Whether flap detection is enabled. Defaults to false.
enable_perfdata Optional. Whether performance data processing is enabled. Defaults to true.
event_command Optional. The name of an event command that should be executed every time the service's state changes or the service is in a SOFT state.
flapping_threshold Optional. The flapping threshold in percent when a service is considered to be flapping.
volatile Optional. The volatile setting enables always HARD state types if NOT-OK state changes occur.
zone Optional. The zone this object is a member of.
command_endpoint Optional. The endpoint where commands are executed on.
notes Optional. Notes for the service.
notes_url Optional. Url for notes for the service (for example, in notification commands).
action_url Optional. Url for actions for the service (for example, an external graphing tool).
icon_image Optional. Icon image for the service. Used by external interfaces only.
icon_image_alt 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.

Runtime Attributes:

Name Type Description
next_check Number When the next check occurs (as a UNIX timestamp).
last_check Number When the last check occured (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 Number When the last state change occurred (as a UNIX timestamp).
last_hard_state_change Number 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 Number When the acknowledgement expires (as a UNIX timestamp; 0 = no expiry).
flapping_last_change Number When the last flapping change occurred (as a UNIX timestamp).
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 Number When the last OK state occurred (as a UNIX timestamp).
last_state_warning Number When the last WARNING state occurred (as a UNIX timestamp).
last_state_critical Number When the last CRITICAL state occurred (as a UNIX timestamp).
last_state_unknown Number 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 Description
display_name Optional. A short description of the service group.
groups Optional. An array of nested group names.

StatusDataWriter

Periodically writes status data files which are used by the Classic UI and other third-party tools.

Example:

library "compat"

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

Configuration Attributes:

Name Description
status_path Optional. Path to the status.dat file. Defaults to LocalStateDir + "/cache/icinga2/status.dat".
objects_path Optional. Path to the objects.cache file. Defaults to LocalStateDir + "/cache/icinga2/objects.cache".
update_interval Optional. The interval in which the status files are updated. Defaults to 15 seconds.

SyslogLogger

Specifies Icinga 2 logging to syslog.

Example:

object SyslogLogger "crit-syslog" {
  severity = "critical"
}

Configuration Attributes:

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

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" {
  import "legacy-timeperiod"

  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" {
    import "legacy-timeperiod"

    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 within the icinga documentation.

Configuration Attributes:

Name Description
display_name Optional. A short description of the time period.
update Required. The "update" script method takes care of updating the internal representation of the time period. In virtually all cases you should import the "legacy-timeperiod" template to take care of this setting.
ranges Required. A dictionary containing information which days and durations apply to this timeperiod.

The /etc/icinga2/conf.d/timeperiods.conf file is usually used to define timeperiods including this one.

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

Runtime Attributes:

Name Type Description
last_notification Number 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 Description
display_name Optional. A short description of the user group.
groups Optional. An array of nested group names.

Zone

Zone objects are used to specify which Icinga 2 instances are located in a zone.

Example:

object Zone "config-ha-master" {
  endpoints = [ "icinga2a", "icinga2b" ]

}

object Zone "check-satellite" {
  endpoints = [ "icinga2c" ]
  parent = "config-ha-master"
}

Configuration Attributes:

Name Description
endpoints Optional. Dictionary with endpoints located in this zone.
parent Optional. The name of the parent zone.
global Optional. Whether configuration files for this zone should be synced to all endpoints. Defaults to false.

Value Types

In addition to configuration objects Icinga 2 also uses a few other types to represent its internal state. The following types are exposed via the API.

CheckResult

Name Type Description
exit_status  Number The exit status returned by the check execution.
output String The check output.
performance_data Array Array of performance data values.
check_source String Name of the node executing the check.
state Number The current state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).
command Value Array of command with shell-escaped arguments or command line string.
execution_start Number Check execution start time (as a UNIX timestamp).
execution_end Number Check execution end time (as a UNIX timestamp).
schedule_start Number Scheduled check execution start time (as a UNIX timestamp).
schedule_end Number Scheduled check execution end time (as a UNIX timestamp).
active Boolean Whether the result is from an active or passive check.
vars_before Dictionary Internal attribute used for calculations.
vars_after Dictionary Internal attribute used for calculations.

PerfdataValue

Icinga 2 parses performance data strings returned by check plugins and makes the information available to external interfaces (e.g. GraphiteWriter or the Icinga 2 API).

Name Type Description
label  String Performance data label.
value Number Normalized performance data value without unit.
counter Boolean Enabled if the original value contains c as unit. Defaults to false.
unit String Unit of measurement (seconds, bytes. percent) according to the plugin API.
crit Value Critical threshold value.
warn Value Warning threshold value.
min Value Minimum value returned by the check.
max Value Maximum value returned by the check.