Object Types ¶
This chapter provides an overview of all available config object types which can be
instantiated using the object
keyword.
Additional details on configuration and runtime attributes and their description are explained here too.
The attributes need to have a specific type value. Many of them are
explained in this chapter already.
You should note that the Timestamp
type is a Number
.
In addition to that Object name
is an object reference to
an existing object name as String
type.
Overview ¶
- Monitoring Objects such as host, service, etc.
- Runtime Objects generated by Icinga itself.
- Features available via
icinga2 feature
CLI command.
Common Runtime Attributes ¶
Configuration objects share these runtime attributes which cannot be modified by the user. You can access these attributes using the Icinga 2 API.
Name | Type | Description |
---|---|---|
version | Number | Timestamp when the object was created or modified. Synced throughout cluster nodes. |
type | String | Object type. |
original_attributes | Dictionary | Original values of object attributes modified at runtime. |
active | Boolean | Object is active (e.g. a service being checked). |
paused | Boolean | Object has been paused at runtime (e.g. IdoMysqlConnection. Defaults to false . |
templates | Array | Templates imported on object compilation. |
package | String | Configuration package name this object belongs to. Local configuration is set to _etc , runtime created objects use _api . |
source_location | Dictionary | Location information where the configuration files are stored. |
name | String | Object name. Might be used in apply rules. |
Monitoring Objects ¶
ApiUser ¶
ApiUser objects are used for authentication against the Icinga 2 API.
Example:
object ApiUser "root" {
password = "mysecretapipassword"
permissions = [ "*" ]
}
Configuration Attributes:
Name | Type | Description |
---|---|---|
password | String | Optional. Password string. Note: This attribute is hidden in API responses. |
client_cn | String | Optional. Client Common Name (CN). |
permissions | Array | Required. Array of permissions. Either as string or dictionary with the keys permission and filter . The latter must be specified as function. |
Available permissions are explained in the API permissions chapter.
CheckCommand ¶
A check command definition. Additional default command custom variables can be defined here.
Example:
object CheckCommand "http" {
command = [ PluginDir + "/check_http" ]
arguments = {
"-H" = "$http_vhost$"
"-I" = "$http_address$"
"-u" = "$http_uri$"
"-p" = "$http_port$"
"-S" = {
set_if = "$http_ssl$"
}
"--sni" = {
set_if = "$http_sni$"
}
"-a" = {
value = "$http_auth_pair$"
description = "Username:password on sites with basic authentication"
}
"--no-body" = {
set_if = "$http_ignore_body$"
}
"-r" = "$http_expect_body_regex$"
"-w" = "$http_warn_time$"
"-c" = "$http_critical_time$"
"-e" = "$http_expect$"
}
vars.http_address = "$address$"
vars.http_ssl = false
vars.http_sni = false
}
Configuration Attributes:
Name | Type | Description |
---|---|---|
command | Array | Required. The command. This can either be an array of individual command arguments. Alternatively a string can be specified in which case the shell interpreter (usually /bin/sh) takes care of parsing the command. When using the “arguments” attribute this must be an array. Can be specified as function for advanced implementations. |
env | Dictionary | Optional. A dictionary of macros which should be exported as environment variables prior to executing the command. |
vars | Dictionary | Optional. A dictionary containing custom variables that are specific to this command. |
timeout | Duration | Optional. The command timeout in seconds. Defaults to 1m . |
arguments | Dictionary | Optional. A dictionary of command arguments. |
CheckCommand Arguments ¶
Command arguments can be defined as key-value-pairs in the arguments
dictionary. Best practice is to assign a dictionary as value which
provides additional details such as the description
next to the value
.
arguments = {
"--parameter" = {
description = "..."
value = "..."
}
}
All available argument value entries are shown below:
Name | Type | Description |
---|---|---|
value | String/Function | Optional argument value set by a runtime macro string or a function call. More details. |
description | String | Optional argument description. More details. |
required | Boolean | Required argument. Execution error if not set. Defaults to false (optional). More details. |
skip_key | Boolean | Use the value as argument and skip the key. More details. |
set_if | String/Function | Argument is added if the runtime macro string resolves to a defined numeric or boolean value. String values are not supported. Function calls returning a value are supported too. More details. |
order | Number | Set if multiple arguments require a defined argument order. The syntax is ..., -3, -2, -1, <un-ordered keys>, 1, 2, 3, ... . More details. |
repeat_key | Boolean | If the argument value is an array, repeat the argument key, or not. Defaults to true (repeat). More details. |
key | String | Optional argument key overriding the key identifier. More details. |
separator | String | Key-value separator. If given, e.g. = , appears between key and value like --key=value instead of the regular --key value . |
value
and description
are commonly used, the other entries allow
to build more advanced CheckCommand objects and arguments.
Please continue reading here for advanced usage and examples for command arguments.
Dependency ¶
Dependency objects are used to specify dependencies between hosts and services. Dependencies can be defined as Host-to-Host, Service-to-Service, Service-to-Host, or Host-to-Service relations.
Best Practice
Rather than creating a
Dependency
object for a specific host or service it is usually easier to just create aDependency
template and use theapply
keyword to assign the dependency to a number of hosts or services. Use theto
keyword to set the specific target type forHost
orService
. Check the dependencies chapter for detailed examples.
Service-to-Service Example:
object Dependency "webserver-internet" {
parent_host_name = "internet"
parent_service_name = "ping4"
child_host_name = "webserver"
child_service_name = "ping4"
states = [ OK, Warning ]
disable_checks = true
}
Host-to-Host Example:
object Dependency "webserver-internet" {
parent_host_name = "internet"
child_host_name = "webserver"
states = [ Up ]
disable_checks = true
}
Configuration Attributes:
Name | Type | Description |
---|---|---|
parent_host_name | Object name | Required. The parent host. |
parent_service_name | Object name | Optional. The parent service. If omitted, this dependency object is treated as host dependency. |
child_host_name | Object name | Required. The child host. |
child_service_name | Object name | Optional. The child service. If omitted, this dependency object is treated as host dependency. |
redundancy_group | String | Optional. Puts the dependency into a group of mutually redundant ones. |
disable_checks | Boolean | Optional. Whether to disable checks (i.e., don’t schedule active checks and drop passive results) when this dependency fails. Defaults to false. |
disable_notifications | Boolean | Optional. Whether to disable notifications when this dependency fails. Defaults to true. |
ignore_soft_states | Boolean | Optional. Whether to ignore soft states for the reachability calculation. Defaults to true. |
period | Object name | Optional. Time period object during which this dependency is enabled. |
states | Array | Optional. A list of state filters when this dependency should be OK. Defaults to [ OK, Warning ] for services and [ Up ] for hosts. |
Available state filters:
OK
Warning
Critical
Unknown
Up
Down
When using apply rules for dependencies, you can leave out certain attributes which will be automatically determined by Icinga 2.
Service-to-Host Dependency Example:
apply Dependency "internet" to Service {
parent_host_name = "dsl-router"
disable_checks = true
assign where host.name != "dsl-router"
}
This example sets all service objects matching the assign condition into a dependency relation to
the parent host object dsl-router
as implicit child services.
Service-to-Service-on-the-same-Host Dependency Example:
apply Dependency "disable-agent-checks" to Service {
parent_service_name = "agent-health"
assign where service.check_command == "ssh"
ignore where service.name == "agent-health"
}
This example omits the parent_host_name
attribute and Icinga 2 automatically sets its value to the name of the
host object matched by the apply rule condition. All services where apply matches are made implicit child services
in this dependency relation.
Dependency objects have composite names, i.e. their names are based on the child_host_name
and child_service_name
attributes and the
name you specified. This means you can define more than one object with the same (short) name as long as one of the child_host_name
and
child_service_name
attributes has a different value.
Endpoint ¶
Endpoint objects are used to specify connection information for remote Icinga 2 instances. More details can be found in the distributed monitoring chapter.
Example:
object Endpoint "icinga2-agent1.localdomain" {
host = "192.168.56.111"
port = 5665
log_duration = 1d
}
Example (disable replay log):
object Endpoint "icinga2-agent1.localdomain" {
host = "192.168.5.111"
port = 5665
log_duration = 0
}
Configuration Attributes:
Name | Type | Description |
---|---|---|
host | String | Optional. The hostname/IP address of the remote Icinga 2 instance. |
port | Number | Optional. The service name/port of the remote Icinga 2 instance. Defaults to 5665 . |
log_duration | Duration | Optional. Duration for keeping replay logs on connection loss. Defaults to 1d (86400 seconds). Attribute is specified in seconds. If log_duration is set to 0, replaying logs is disabled. You could also specify the value in human readable format like 10m for 10 minutes or 1h for one hour. |
Endpoint objects cannot currently be created with the API.
EventCommand ¶
An event command definition.
Example:
object EventCommand "restart-httpd-event" {
command = "/opt/bin/restart-httpd.sh"
}
Configuration Attributes:
Name | Type | Description |
---|---|---|
command | Array | Required. The command. This can either be an array of individual command arguments. Alternatively a string can be specified in which case the shell interpreter (usually /bin/sh) takes care of parsing the command. When using the “arguments” attribute this must be an array. Can be specified as function for advanced implementations. |
env | Dictionary | Optional. A dictionary of macros which should be exported as environment variables prior to executing the command. |
vars | Dictionary | Optional. A dictionary containing custom variables that are specific to this command. |
timeout | Duration | Optional. The command timeout in seconds. Defaults to 1m . |
arguments | Dictionary | Optional. A dictionary of command arguments. |
Command arguments can be used the same way as for CheckCommand objects.
More advanced examples for event command usage can be found here.
Host ¶
A host.
Example:
object Host "icinga2-agent1.localdomain" {
display_name = "Linux Client 1"
address = "192.168.56.111"
address6 = "2a00:1450:4001:815::2003"
groups = [ "linux-servers" ]
check_command = "hostalive"
}
Configuration Attributes:
Name | Type | Description |
---|---|---|
display_name | String | Optional. A short description of the host (e.g. displayed by external interfaces instead of the name if set). |
address | String | Optional. The host’s IPv4 address. Available as command runtime macro $address$ if set. |
address6 | String | Optional. The host’s IPv6 address. Available as command runtime macro $address6$ if set. |
groups | Array of object names | Optional. A list of host groups this host belongs to. |
vars | Dictionary | Optional. A dictionary containing custom variables that are specific to this host. |
check_command | Object name | Required. The name of the check command. |
max_check_attempts | Number | Optional. The number of times a host is re-checked before changing into a hard state. Defaults to 3. |
check_period | Object name | Optional. The name of a time period which determines when this host should be checked. Not set by default (effectively 24x7). |
check_timeout | Duration | Optional. Check command timeout in seconds. Overrides the CheckCommand’s timeout attribute. |
check_interval | Duration | Optional. The check interval (in seconds). This interval is used for checks when the host is in a HARD state. Defaults to 5m . |
retry_interval | Duration | Optional. The retry interval (in seconds). This interval is used for checks when the host is in a SOFT state. Defaults to 1m . Note: This does not affect the scheduling after a passive check result. |
enable_notifications | Boolean | Optional. Whether notifications are enabled. Defaults to true. |
enable_active_checks | Boolean | Optional. Whether active checks are enabled. Defaults to true. |
enable_passive_checks | Boolean | Optional. Whether passive checks are enabled. Defaults to true. |
enable_event_handler | Boolean | Optional. Enables event handlers for this host. Defaults to true. |
enable_flapping | Boolean | Optional. Whether flap detection is enabled. Defaults to false. |
enable_perfdata | Boolean | Optional. Whether performance data processing is enabled. Defaults to true. |
event_command | Object name | Optional. The name of an event command that should be executed every time the host’s state changes or the host is in a SOFT state. |
flapping_threshold_high | Number | Optional. Flapping upper bound in percent for a host to be considered flapping. Default 30.0 |
flapping_threshold_low | Number | Optional. Flapping lower bound in percent for a host to be considered not flapping. Default 25.0 |
flapping_ignore_states | Array | Optional. A list of states that should be ignored during flapping calculation. By default no state is ignored. |
volatile | Boolean | Optional. Treat all state changes as HARD changes. See here for details. Defaults to false . |
zone | Object name | Optional. The zone this object is a member of. Please read the distributed monitoring chapter for details. |
command_endpoint | Object name | Optional. The endpoint where commands are executed on. |
notes | String | Optional. Notes for the host. |
notes_url | String | Optional. URL for notes for the host (for example, in notification commands). |
action_url | String | Optional. URL for actions for the host (for example, an external graphing tool). |
icon_image | String | Optional. Icon image for the host. Used by external interfaces only. |
icon_image_alt | String | Optional. Icon image description for the host. Used by external interface only. |
The actual check interval might deviate slightly from the configured values due to the fact that Icinga tries to evenly distribute all checks over a certain period of time, i.e. to avoid load spikes.
Best Practice
The
address
andaddress6
attributes are required for running commands using the$address$
and$address6$
runtime macros.
Runtime Attributes:
Name | Type | Description |
---|---|---|
next_check | Timestamp | When the next check occurs (as a UNIX timestamp). |
last_check | Timestamp | When the last check occurred (as a UNIX timestamp). |
check_attempt | Number | The current check attempt number. |
state_type | Number | The current state type (0 = SOFT, 1 = HARD). |
last_state_type | Number | The previous state type (0 = SOFT, 1 = HARD). |
last_reachable | Boolean | Whether the host was reachable when the last check occurred. |
last_check_result | CheckResult | The current check result. |
last_state_change | Timestamp | When the last state change occurred (as a UNIX timestamp). |
last_hard_state_change | Timestamp | When the last hard state change occurred (as a UNIX timestamp). |
acknowledgement | Number | The acknowledgement type (0 = NONE, 1 = NORMAL, 2 = STICKY). |
acknowledgement_expiry | Timestamp | When the acknowledgement expires (as a UNIX timestamp; 0 = no expiry). |
downtime_depth | Number | Whether the host has one or more active downtimes. |
flapping_last_change | Timestamp | When the last flapping change occurred (as a UNIX timestamp). |
flapping | Boolean | Whether the host is flapping between states. |
flapping_current | Number | Current flapping value in percent (see flapping_thresholds) |
state | Number | The current state (0 = UP, 1 = DOWN). |
last_state | Number | The previous state (0 = UP, 1 = DOWN). |
last_hard_state | Number | The last hard state (0 = UP, 1 = DOWN). |
last_state_up | Timestamp | When the last UP state occurred (as a UNIX timestamp). |
last_state_down | Timestamp | When the last DOWN state occurred (as a UNIX timestamp). |
last_state_unreachable | Timestamp | When the host was unreachable the last time (as a UNIX timestamp). |
previous_state_change | Timestamp | Previous timestamp of last_state_change before processing a new check result. |
severity | Number | Severity calculated value. |
problem | Boolean | Whether the host is considered in a problem state type (NOT-UP). |
handled | Boolean | Whether the host problem is handled (downtime or acknowledgement). |
next_update | Timestamp | When the next check update is to be expected. |
HostGroup ¶
A group of hosts.
Best Practice
Assign host group members using the group assign rules.
Example:
object HostGroup "linux-servers" {
display_name = "Linux Servers"
assign where host.vars.os == "Linux"
}
Configuration Attributes:
Name | Type | Description |
---|---|---|
display_name | String | Optional. A short description of the host group. |
groups | Array of object names | Optional. An array of nested group names. |
Notification ¶
Notification objects are used to specify how users should be notified in case of host and service state changes and other events.
Best Practice
Rather than creating a
Notification
object for a specific host or service it is usually easier to just create aNotification
template and use theapply
keyword to assign the notification to a number of hosts or services. Use theto
keyword to set the specific target type forHost
orService
. Check the notifications chapter for detailed examples.
Example:
object Notification "localhost-ping-notification" {
host_name = "localhost"
service_name = "ping4"
command = "mail-notification"
users = [ "user1", "user2" ] // reference to User objects
types = [ Problem, Recovery ]
states = [ Critical, Warning, OK ]
}
Configuration Attributes:
Name | Type | Description |
---|---|---|
host_name | Object name | Required. The name of the host this notification belongs to. |
service_name | Object name | Optional. The short name of the service this notification belongs to. If omitted, this notification object is treated as host notification. |
vars | Dictionary | Optional. A dictionary containing custom variables that are specific to this notification object. |
users | Array of object names | Required. A list of user names who should be notified. Optional. if the user_groups attribute is set. |
user_groups | Array of object names | Required. A list of user group names who should be notified. Optional. if the users attribute is set. |
times | Dictionary | Optional. A dictionary containing begin and end attributes for the notification. If end is set to 0, Notifications are disabled permanently. Please read the notification delay chapter for details. |
command | Object name | Required. The name of the notification command which should be executed when the notification is triggered. |
interval | Duration | Optional. The notification interval (in seconds). This interval is used for active notifications. Defaults to 30 minutes. If set to 0, re-notifications are disabled. |
period | Object name | Optional. The name of a time period which determines when this notification should be triggered. Not set by default (effectively 24x7). |
zone | Object name | Optional. The zone this object is a member of. Please read the distributed monitoring chapter for details. |
types | Array | Optional. A list of type filters when this notification should be triggered. By default everything is matched. |
states | Array | Optional. A list of state filters when this notification should be triggered. By default everything is matched. Note that the states filter is ignored for notifications of type Acknowledgement! |
Available notification state filters for Service:
OK
Warning
Critical
Unknown
Available notification state filters for Host:
Up
Down
Available notification type filters:
DowntimeStart
DowntimeEnd
DowntimeRemoved
Custom
Acknowledgement
Problem
Recovery
FlappingStart
FlappingEnd
Runtime Attributes:
Name | Type | Description |
---|---|---|
last_notification | Timestamp | When the last notification was sent for this Notification object (as a UNIX timestamp). |
next_notification | Timestamp | When the next notification is going to be sent for this assuming the associated host/service is still in a non-OK state (as a UNIX timestamp). |
notification_number | Number | The notification number. |
last_problem_notification | Timestamp | When the last notification was sent for a problem (as a UNIX timestamp). |
NotificationCommand ¶
A notification command definition.
Example:
object NotificationCommand "mail-service-notification" {
command = [ ConfigDir + "/scripts/mail-service-notification.sh" ]
arguments += {
"-4" = {
required = true
value = "$notification_address$"
}
"-6" = "$notification_address6$"
"-b" = "$notification_author$"
"-c" = "$notification_comment$"
"-d" = {
required = true
value = "$notification_date$"
}
"-e" = {
required = true
value = "$notification_servicename$"
}
"-f" = {
value = "$notification_from$"
description = "Set from address. Requires GNU mailutils (Debian/Ubuntu) or mailx (RHEL/SUSE)"
}
"-i" = "$notification_icingaweb2url$"
"-l" = {
required = true
value = "$notification_hostname$"
}
"-n" = {
required = true
value = "$notification_hostdisplayname$"
}
"-o" = {
required = true
value = "$notification_serviceoutput$"
}
"-r" = {
required = true
value = "$notification_useremail$"
}
"-s" = {
required = true
value = "$notification_servicestate$"
}
"-t" = {
required = true
value = "$notification_type$"
}
"-u" = {
required = true
value = "$notification_servicedisplayname$"
}
"-v" = "$notification_logtosyslog$"
}
vars += {
notification_address = "$address$"
notification_address6 = "$address6$"
notification_author = "$notification.author$"
notification_comment = "$notification.comment$"
notification_type = "$notification.type$"
notification_date = "$icinga.long_date_time$"
notification_hostname = "$host.name$"
notification_hostdisplayname = "$host.display_name$"
notification_servicename = "$service.name$"
notification_serviceoutput = "$service.output$"
notification_servicestate = "$service.state$"
notification_useremail = "$user.email$"
notification_servicedisplayname = "$service.display_name$"
}
}
Configuration Attributes:
Name | Type | Description |
---|---|---|
command | Array | Required. The command. This can either be an array of individual command arguments. Alternatively a string can be specified in which case the shell interpreter (usually /bin/sh) takes care of parsing the command. When using the “arguments” attribute this must be an array. Can be specified as function for advanced implementations. |
env | Dictionary | Optional. A dictionary of macros which should be exported as environment variables prior to executing the command. |
vars | Dictionary | Optional. A dictionary containing custom variables that are specific to this command. |
timeout | Duration | Optional. The command timeout in seconds. Defaults to 1m . |
arguments | Dictionary | Optional. A dictionary of command arguments. |
Command arguments can be used the same way as for CheckCommand objects.
More details on specific attributes can be found in this chapter.
ScheduledDowntime ¶
ScheduledDowntime objects can be used to set up recurring downtimes for hosts/services.
Best Practice
Rather than creating a
ScheduledDowntime
object for a specific host or service it is usually easier to just create aScheduledDowntime
template and use theapply
keyword to assign the scheduled downtime to a number of hosts or services. Use theto
keyword to set the specific target type forHost
orService
. Check the recurring downtimes example for details.
Example:
object ScheduledDowntime "some-downtime" {
host_name = "localhost"
service_name = "ping4"
author = "icingaadmin"
comment = "Some comment"
fixed = false
duration = 30m
ranges = {
"sunday" = "02:00-03:00"
}
}
Configuration Attributes:
Name | Type | Description |
---|---|---|
host_name | Object name | Required. The name of the host this scheduled downtime belongs to. |
service_name | Object name | Optional. The short name of the service this scheduled downtime belongs to. If omitted, this downtime object is treated as host downtime. |
author | String | Required. The author of the downtime. |
comment | String | Required. A comment for the downtime. |
fixed | Boolean | Optional. Whether this is a fixed downtime. Defaults to true . |
duration | Duration | Optional. How long the downtime lasts. Only has an effect for flexible (non-fixed) downtimes. |
ranges | Dictionary | Required. A dictionary containing information which days and durations apply to this timeperiod. |
child_options | String | Optional. Schedule child downtimes. DowntimeNoChildren does not do anything, DowntimeTriggeredChildren schedules child downtimes triggered by this downtime, DowntimeNonTriggeredChildren schedules non-triggered downtimes. Defaults to DowntimeNoChildren . |
ScheduledDowntime objects have composite names, i.e. their names are based
on the host_name
and service_name
attributes and the
name you specified. This means you can define more than one object
with the same (short) name as long as one of the host_name
and
service_name
attributes has a different value.
See also time zone handling.
Service ¶
Service objects describe network services and how they should be checked by Icinga 2.
Best Practice
Rather than creating a
Service
object for a specific host it is usually easier to just create aService
template and use theapply
keyword to assign the service to a number of hosts. Check the apply chapter for details.
Example:
object Service "uptime" {
host_name = "localhost"
display_name = "localhost Uptime"
check_command = "snmp"
vars.snmp_community = "public"
vars.snmp_oid = "DISMAN-EVENT-MIB::sysUpTimeInstance"
check_interval = 60s
retry_interval = 15s
groups = [ "all-services", "snmp" ]
}
Configuration Attributes:
Name | Type | Description |
---|---|---|
display_name | String | Optional. A short description of the service. |
host_name | Object name | Required. The host this service belongs to. There must be a Host object with that name. |
groups | Array of object names | Optional. The service groups this service belongs to. |
vars | Dictionary | Optional. A dictionary containing custom variables that are specific to this service. |
check_command | Object name | Required. The name of the check command. |
max_check_attempts | Number | Optional. The number of times a service is re-checked before changing into a hard state. Defaults to 3. |
check_period | Object name | Optional. The name of a time period which determines when this service should be checked. Not set by default (effectively 24x7). |
check_timeout | Duration | Optional. Check command timeout in seconds. Overrides the CheckCommand’s timeout attribute. |
check_interval | Duration | Optional. The check interval (in seconds). This interval is used for checks when the service is in a HARD state. Defaults to 5m . |
retry_interval | Duration | Optional. The retry interval (in seconds). This interval is used for checks when the service is in a SOFT state. Defaults to 1m . Note: This does not affect the scheduling after a passive check result. |
enable_notifications | Boolean | Optional. Whether notifications are enabled. Defaults to true . |
enable_active_checks | Boolean | Optional. Whether active checks are enabled. Defaults to true . |
enable_passive_checks | Boolean | Optional. Whether passive checks are enabled. Defaults to true . |
enable_event_handler | Boolean | Optional. Enables event handlers for this host. Defaults to true . |
enable_flapping | Boolean | Optional. Whether flap detection is enabled. Defaults to false . |
flapping_threshold_high | Number | Optional. Flapping upper bound in percent for a service to be considered flapping. 30.0 |
flapping_threshold_low | Number | Optional. Flapping lower bound in percent for a service to be considered not flapping. 25.0 |
flapping_ignore_states | Array | Optional. A list of states that should be ignored during flapping calculation. By default no state is ignored. |
enable_perfdata | Boolean | Optional. Whether performance data processing is enabled. Defaults to true . |
event_command | Object name | Optional. The name of an event command that should be executed every time the service’s state changes or the service is in a SOFT state. |
volatile | Boolean | Optional. Treat all state changes as HARD changes. See here for details. Defaults to false . |
zone | Object name | Optional. The zone this object is a member of. Please read the distributed monitoring chapter for details. |
command_endpoint | Object name | Optional. The endpoint where commands are executed on. |
notes | String | Optional. Notes for the service. |
notes_url | String | Optional. URL for notes for the service (for example, in notification commands). |
action_url | String | Optional. URL for actions for the service (for example, an external graphing tool). |
icon_image | String | Optional. Icon image for the service. Used by external interfaces only. |
icon_image_alt | String | Optional. Icon image description for the service. Used by external interface only. |
Service objects have composite names, i.e. their names are based on the host_name attribute and the name you specified. This means
you can define more than one object with the same (short) name as long as the host_name
attribute has a different value.
The actual check interval might deviate slightly from the configured values due to the fact that Icinga tries to evenly distribute all checks over a certain period of time, i.e. to avoid load spikes.
Runtime Attributes:
Name | Type | Description |
---|---|---|
next_check | Timestamp | When the next check occurs (as a UNIX timestamp). |
last_check | Timestamp | When the last check occurred (as a UNIX timestamp). |
check_attempt | Number | The current check attempt number. |
state_type | Number | The current state type (0 = SOFT, 1 = HARD). |
last_state_type | Number | The previous state type (0 = SOFT, 1 = HARD). |
last_reachable | Boolean | Whether the service was reachable when the last check occurred. |
last_check_result | CheckResult | The current check result. |
last_state_change | Timestamp | When the last state change occurred (as a UNIX timestamp). |
last_hard_state_change | Timestamp | When the last hard state change occurred (as a UNIX timestamp). |
acknowledgement | Number | The acknowledgement type (0 = NONE, 1 = NORMAL, 2 = STICKY). |
acknowledgement_expiry | Timestamp | When the acknowledgement expires (as a UNIX timestamp; 0 = no expiry). |
acknowledgement_last_change | Timestamp | When the acknowledgement has been set/cleared |
downtime_depth | Number | Whether the service has one or more active downtimes. |
flapping_last_change | Timestamp | When the last flapping change occurred (as a UNIX timestamp). |
flapping_current | Number | Current flapping value in percent (see flapping_thresholds) |
flapping | Boolean | Whether the service is flapping between states. |
state | Number | The current state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN). |
last_state | Number | The previous state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN). |
last_hard_state | Number | The last hard state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN). |
last_state_ok | Timestamp | When the last OK state occurred (as a UNIX timestamp). |
last_state_warning | Timestamp | When the last WARNING state occurred (as a UNIX timestamp). |
last_state_critical | Timestamp | When the last CRITICAL state occurred (as a UNIX timestamp). |
last_state_unknown | Timestamp | When the last UNKNOWN state occurred (as a UNIX timestamp). |
last_state_unreachable | Timestamp | When the service was unreachable the last time (as a UNIX timestamp). |
previous_state_change | Timestamp | Previous timestamp of last_state_change before processing a new check result. |
severity | Number | Severity calculated value. |
problem | Boolean | Whether the service is considered in a problem state type (NOT-OK). |
handled | Boolean | Whether the service problem is handled (downtime or acknowledgement). |
next_update | Timestamp | When the next check update is to be expected. |
ServiceGroup ¶
A group of services.
Best Practice
Assign service group members using the group assign rules.
Example:
object ServiceGroup "snmp" {
display_name = "SNMP services"
}
Configuration Attributes:
Name | Type | Description |
---|---|---|
display_name | String | Optional. A short description of the service group. |
groups | Array of object names | Optional. An array of nested group names. |
TimePeriod ¶
Time periods can be used to specify when hosts/services should be checked or to limit when notifications should be sent out.
Examples:
object TimePeriod "nonworkhours" {
display_name = "Icinga 2 TimePeriod for non working hours"
ranges = {
monday = "00:00-8:00,17:00-24:00"
tuesday = "00:00-8:00,17:00-24:00"
wednesday = "00:00-8:00,17:00-24:00"
thursday = "00:00-8:00,17:00-24:00"
friday = "00:00-8:00,16:00-24:00"
saturday = "00:00-24:00"
sunday = "00:00-24:00"
}
}
object TimePeriod "exampledays" {
display_name = "Icinga 2 TimePeriod for random example days"
ranges = {
//We still believe in Santa, no peeking!
//Applies every 25th of December every year
"december 25" = "00:00-24:00"
//Any point in time can be specified,
//but you still have to use a range
"2038-01-19" = "03:13-03:15"
//Evey 3rd day from the second monday of February
//to 8th of November
"monday 2 february - november 8 / 3" = "00:00-24:00"
}
}
Additional examples can be found here.
Configuration Attributes:
Name | Type | Description |
---|---|---|
display_name | String | Optional. A short description of the time period. |
ranges | Dictionary | Required. A dictionary containing information which days and durations apply to this timeperiod. |
prefer_includes | Boolean | Optional. Whether to prefer timeperiods includes or excludes . Default to true. |
excludes | Array of object names | Optional. An array of timeperiods, which should exclude from your timerange. |
includes | Array of object names | Optional. An array of timeperiods, which should include into your timerange |
Runtime Attributes:
Name | Type | Description |
---|---|---|
is_inside | Boolean | Whether we’re currently inside this timeperiod. |
See also time zone handling.
User ¶
A user.
Example:
object User "icingaadmin" {
display_name = "Icinga 2 Admin"
groups = [ "icingaadmins" ]
email = "icinga@localhost"
pager = "icingaadmin@localhost.localdomain"
period = "24x7"
states = [ OK, Warning, Critical, Unknown ]
types = [ Problem, Recovery ]
vars.additional_notes = "This is the Icinga 2 Admin account."
}
Available notification state filters:
OK
Warning
Critical
Unknown
Up
Down
Available notification type filters:
DowntimeStart
DowntimeEnd
DowntimeRemoved
Custom
Acknowledgement
Problem
Recovery
FlappingStart
FlappingEnd
Configuration Attributes:
Name | Type | Description |
---|---|---|
display_name | String | Optional. A short description of the user. |
String | Optional. An email string for this user. Useful for notification commands. | |
pager | String | Optional. A pager string for this user. Useful for notification commands. |
vars | Dictionary | Optional. A dictionary containing custom variables that are specific to this user. |
groups | Array of object names | Optional. An array of group names. |
enable_notifications | Boolean | Optional. Whether notifications are enabled for this user. Defaults to true. |
period | Object name | Optional. The name of a time period which determines when a notification for this user should be triggered. Not set by default (effectively 24x7). |
types | Array | Optional. A set of type filters when a notification for this user should be triggered. By default everything is matched. |
states | Array | Optional. A set of state filters when a notification for this should be triggered. By default everything is matched. |
Runtime Attributes:
Name | Type | Description |
---|---|---|
last_notification | Timestamp | When the last notification was sent for this user (as a UNIX timestamp). |
UserGroup ¶
A user group.
Best Practice
Assign user group members using the group assign rules.
Example:
object UserGroup "icingaadmins" {
display_name = "Icinga 2 Admin Group"
}
Configuration Attributes:
Name | Type | Description |
---|---|---|
display_name | String | Optional. A short description of the user group. |
groups | Array of object names | Optional. An array of nested group names. |
Zone ¶
Zone objects are used to specify which Icinga 2 instances are located in a zone. Please read the distributed monitoring chapter for additional details. Example:
object Zone "master" {
endpoints = [ "icinga2-master1.localdomain", "icinga2-master2.localdomain" ]
}
object Zone "satellite" {
endpoints = [ "icinga2-satellite1.localdomain" ]
parent = "master"
}
Configuration Attributes:
Name | Type | Description |
---|---|---|
endpoints | Array of object names | Optional. Array of endpoint names located in this zone. |
parent | Object name | Optional. The name of the parent zone. (Do not specify a global zone) |
global | Boolean | Optional. Whether configuration files for this zone should be synced to all endpoints. Defaults to false . |
Zone objects cannot currently be created with the API.
Runtime Objects ¶
These objects are generated at runtime by the daemon from API actions. Downtime objects are also created by ScheduledDowntime objects.
Comment ¶
Comments created at runtime are represented as objects. Note: This is for reference only. You can create comments with the add-comment API action.
Example:
object Comment "my-comment" {
host_name = "localhost"
author = "icingaadmin"
text = "This is a comment."
entry_time = 1234567890
}
Configuration Attributes:
Name | Type | Description |
---|---|---|
host_name | Object name | Required. The name of the host this comment belongs to. |
service_name | Object name | Optional. The short name of the service this comment belongs to. If omitted, this comment object is treated as host comment. |
author | String | Required. The author’s name. |
text | String | Required. The comment text. |
entry_time | Timestamp | Optional. The UNIX timestamp when this comment was added. If omitted, the entry time is volatile! |
entry_type | Number | Optional. The comment type (User = 1, Downtime = 2, Flapping = 3, Acknowledgement = 4). |
expire_time | Timestamp | Optional. The comment’s expire time as UNIX timestamp. |
persistent | Boolean | Optional. Only evaluated for entry_type Acknowledgement. true does not remove the comment when the acknowledgement is removed. |
Downtime ¶
Downtimes created at runtime are represented as objects. You can create downtimes with the schedule-downtime API action.
Example:
object Downtime "my-downtime" {
host_name = "localhost"
author = "icingaadmin"
comment = "This is a downtime."
start_time = 1505312869
end_time = 1505312924
}
Configuration Attributes:
Name | Type | Description |
---|---|---|
host_name | Object name | Required. The name of the host this downtime belongs to. |
service_name | Object name | Optional. The short name of the service this downtime belongs to. If omitted, this downtime object is treated as host downtime. |
author | String | Required. The author’s name. |
comment | String | Required. The comment text. |
start_time | Timestamp | Required. The start time as UNIX timestamp. |
end_time | Timestamp | Required. The end time as UNIX timestamp. |
duration | Number | Optional. The duration as number. |
entry_time | Timestamp | Optional. The UNIX timestamp when this downtime was added. |
fixed | Boolean | Optional. Whether the downtime is fixed (true) or flexible (false). Defaults to flexible. Details in the advanced topics chapter. |
triggers | Array of object names | Optional. List of downtimes which should be triggered by this downtime. |
Runtime Attributes:
Name | Type | Description |
---|---|---|
trigger_time | Timestamp | The UNIX timestamp when this downtime was triggered. |
triggered_by | Object name | The name of the downtime this downtime was triggered by. |
Features ¶
ApiListener ¶
ApiListener objects are used for distributed monitoring setups and API usage specifying the certificate files used for ssl authorization and additional restrictions. This configuration object is available as api feature.
The TicketSalt
constant must be defined in constants.conf.
Example:
object ApiListener "api" {
accept_commands = true
accept_config = true
ticket_salt = TicketSalt
}
Configuration Attributes:
Name | Type | Description |
---|---|---|
cert_path | String | Deprecated. Path to the public key. |
key_path | String | Deprecated. Path to the private key. |
ca_path | String | Deprecated. Path to the CA certificate file. |
ticket_salt | String | Optional. Private key for CSR auto-signing. Required for a signing master instance. |
crl_path | String | Optional. Path to the CRL file. |
bind_host | String | Optional. The IP address the api listener should be bound to. If not specified, the ApiListener is bound to :: and listens for both IPv4 and IPv6 connections or to 0.0.0.0 if IPv6 is not supported by the operating system. |
bind_port | Number | Optional. The port the api listener should be bound to. Defaults to 5665 . |
accept_config | Boolean | Optional. Accept zone configuration. Defaults to false . |
accept_commands | Boolean | Optional. Accept remote commands. Defaults to false . |
max_anonymous_clients | Number | Optional. Limit the number of anonymous client connections (not configured endpoints and signing requests). |
cipher_list | String | Optional. Cipher list that is allowed. For a list of available ciphers run openssl ciphers . Defaults to ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384:DHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256 . |
tls_protocolmin | String | Optional. Minimum TLS protocol version. Since v2.11, only TLSv1.2 is supported. Defaults to TLSv1.2 . |
tls_handshake_timeout | Number | Deprecated. TLS Handshake timeout. Defaults to 10s . |
connect_timeout | Number | Optional. Timeout for establishing new connections. Affects both incoming and outgoing connections. Within this time, the TCP and TLS handshakes must complete and either a HTTP request or an Icinga cluster connection must be initiated. Defaults to 15s . |
access_control_allow_origin | Array | Optional. Specifies an array of origin URLs that may access the API. (MDN docs) |
access_control_allow_credentials | Boolean | Deprecated. Indicates whether or not the actual request can be made using credentials. Defaults to true . (MDN docs) |
access_control_allow_headers | String | Deprecated. Used in response to a preflight request to indicate which HTTP headers can be used when making the actual request. Defaults to Authorization . (MDN docs) |
access_control_allow_methods | String | Deprecated. Used in response to a preflight request to indicate which HTTP methods can be used when making the actual request. Defaults to GET, POST, PUT, DELETE . (MDN docs) |
environment | String | Optional. Used as suffix in TLS SNI extension name; default from constant ApiEnvironment , which is empty. |
The attributes access_control_allow_credentials
, access_control_allow_headers
and access_control_allow_methods
are controlled by Icinga 2 and are not changeable by config any more.
The ApiListener type expects its certificate files to be in the following locations:
Type | Location |
---|---|
Private key | DataDir + "/certs/" + NodeName + ".key" |
Certificate file | DataDir + "/certs/" + NodeName + ".crt" |
CA certificate file | DataDir + "/certs/ca.crt" |
If the deprecated attributes cert_path
, key_path
and/or ca_path
are specified Icinga 2
copies those files to the new location in DataDir + "/certs"
unless the
file(s) there are newer.
Please check the upgrading chapter for more details.
While Icinga 2 and the underlying OpenSSL library use sane and secure defaults, the attributes
cipher_list
and tls_protocolmin
can be used to increase communication security. A good source
for a more secure configuration is provided by the Mozilla Wiki.
Ensure to use the same configuration for both attributes on all endpoints to avoid communication problems which
requires to use cipher_list
compatible with the endpoint using the oldest version of the OpenSSL library. If using
other tools to connect to the API ensure also compatibility with them as this setting affects not only inter-cluster
communcation but also the REST API.
CheckerComponent ¶
The checker component is responsible for scheduling active checks. This configuration object is available as checker feature.
Example:
object CheckerComponent "checker" { }
In order to limit the concurrent checks on a master/satellite endpoint, use MaxConcurrentChecks constant. This also applies to an agent as command endpoint where the checker feature is disabled.
CompatLogger ¶
Writes log files in a format that’s compatible with Icinga 1.x. This configuration object is available as compatlog feature.
Note
This feature is DEPRECATED and may be removed in future releases. Check the roadmap.
Example:
object CompatLogger "compatlog" {
log_dir = "/var/log/icinga2/compat"
rotation_method = "DAILY"
}
Configuration Attributes:
Name | Type | Description |
---|---|---|
log_dir | String | Optional. Path to the compat log directory. Defaults to LogDir + “/compat”. |
rotation_method | String | Optional. Specifies when to rotate log files. Can be one of “HOURLY”, “DAILY”, “WEEKLY” or “MONTHLY”. Defaults to “HOURLY”. |
ElasticsearchWriter ¶
Writes check result metrics and performance data to an Elasticsearch instance. This configuration object is available as elasticsearch feature.
Example:
object ElasticsearchWriter "elasticsearch" {
host = "127.0.0.1"
port = 9200
index = "icinga2"
enable_send_perfdata = true
flush_threshold = 1024
flush_interval = 10
}
The index is rotated daily, as is recommended by Elastic, meaning the index will be renamed to $index-$d.$M.$y
.
Configuration Attributes:
Name | Type | Description |
---|---|---|
host | String | Required. Elasticsearch host address. Defaults to 127.0.0.1 . |
port | Number | Required. Elasticsearch port. Defaults to 9200 . |
index | String | Required. Elasticsearch index name. Defaults to icinga2 . |
enable_send_perfdata | Boolean | Optional. Send parsed performance data metrics for check results. Defaults to false . |
flush_interval | Duration | Optional. How long to buffer data points before transferring to Elasticsearch. Defaults to 10s . |
flush_threshold | Number | Optional. How many data points to buffer before forcing a transfer to Elasticsearch. Defaults to 1024 . |
username | String | Optional. Basic auth username if Elasticsearch is hidden behind an HTTP proxy. |
password | String | Optional. Basic auth password if Elasticsearch is hidden behind an HTTP proxy. |
enable_tls | Boolean | Optional. Whether to use a TLS stream. Defaults to false . Requires an HTTP proxy. |
insecure_noverify | Boolean | Optional. Disable TLS peer verification. |
ca_path | String | Optional. Path to CA certificate to validate the remote host. Requires enable_tls set to true . |
cert_path | String | Optional. Path to host certificate to present to the remote host for mutual verification. Requires enable_tls set to true . |
key_path | String | Optional. Path to host key to accompany the cert_path. Requires enable_tls set to true . |
enable_ha | Boolean | Optional. Enable the high availability functionality. Only valid in a cluster setup. Defaults to false . |
Note: If flush_threshold
is set too low, this will force the feature to flush all data to Elasticsearch too often.
Experiment with the setting, if you are processing more than 1024 metrics per second or similar.
Basic auth is supported with the username
and password
attributes. This requires an
HTTP proxy (Nginx, etc.) in front of the Elasticsearch instance. Check this blogpost
for an example.
TLS for the HTTP proxy can be enabled with enable_tls
. In addition to that
you can specify the certificates with the ca_path
, cert_path
and cert_key
attributes.
ExternalCommandListener ¶
Implements the Icinga 1.x command pipe which can be used to send commands to Icinga. This configuration object is available as command feature.
Note
This feature is DEPRECATED and may be removed in future releases. Check the roadmap.
Example:
object ExternalCommandListener "command" {
command_path = "/var/run/icinga2/cmd/icinga2.cmd"
}
Configuration Attributes:
Name | Type | Description |
---|---|---|
command_path | String | Optional. Path to the command pipe. Defaults to RunDir + “/icinga2/cmd/icinga2.cmd”. |
FileLogger ¶
Specifies Icinga 2 logging to a file.
This configuration object is available as mainlog
and debuglog
logging feature.
Example:
object FileLogger "debug-file" {
severity = "debug"
path = "/var/log/icinga2/debug.log"
}
Configuration Attributes:
Name | Type | Description |
---|---|---|
path | String | Required. The log path. |
severity | String | Optional. The minimum severity for this log. Can be “debug”, “notice”, “information”, “warning” or “critical”. Defaults to “information”. |
GelfWriter ¶
Writes event log entries to a defined GELF receiver host (Graylog, Logstash). This configuration object is available as gelf feature.
Example:
object GelfWriter "gelf" {
host = "127.0.0.1"
port = 12201
}
Configuration Attributes:
Name | Type | Description |
---|---|---|
host | String | Optional. GELF receiver host address. Defaults to 127.0.0.1 . |
port | Number | Optional. GELF receiver port. Defaults to 12201 . |
source | String | Optional. Source name for this instance. Defaults to icinga2 . |
enable_send_perfdata | Boolean | Optional. Enable performance data for ‘CHECK RESULT’ events. |
enable_ha | Boolean | Optional. Enable the high availability functionality. Only valid in a cluster setup. Defaults to false . |
enable_tls | Boolean | Optional. Whether to use a TLS stream. Defaults to false . |
insecure_noverify | Boolean | Optional. Disable TLS peer verification. |
ca_path | String | Optional. Path to CA certificate to validate the remote host. Requires enable_tls set to true . |
cert_path | String | Optional. Path to host certificate to present to the remote host for mutual verification. Requires enable_tls set to true . |
key_path | String | Optional. Path to host key to accompany the cert_path. Requires enable_tls set to true . |
GraphiteWriter ¶
Writes check result metrics and performance data to a defined Graphite Carbon host. This configuration object is available as graphite feature.
Example:
object GraphiteWriter "graphite" {
host = "127.0.0.1"
port = 2003
}
Configuration Attributes:
Name | Type | Description |
---|---|---|
host | String | Optional. Graphite Carbon host address. Defaults to 127.0.0.1 . |
port | Number | Optional. Graphite Carbon port. Defaults to 2003 . |
host_name_template | String | Optional. Metric prefix for host name. Defaults to icinga2.$host.name$.host.$host.check_command$ . |
service_name_template | String | Optional. Metric prefix for service name. Defaults to icinga2.$host.name$.services.$service.name$.$service.check_command$ . |
enable_send_thresholds | Boolean | Optional. Send additional threshold metrics. Defaults to false . |
enable_send_metadata | Boolean | Optional. Send additional metadata metrics. Defaults to false . |
enable_ha | Boolean | Optional. Enable the high availability functionality. Only valid in a cluster setup. Defaults to false . |
Additional usage examples can be found here.
IcingaApplication ¶
The IcingaApplication object is required to start Icinga 2.
The object name must be app
. If the object configuration
is missing, Icinga 2 will automatically create an IcingaApplication
object.
Example:
object IcingaApplication "app" {
enable_perfdata = false
}
Configuration Attributes:
Name | Type | Description |
---|---|---|
enable_notifications | Boolean | Optional. Whether notifications are globally enabled. Defaults to true. |
enable_event_handlers | Boolean | Optional. Whether event handlers are globally enabled. Defaults to true. |
enable_flapping | Boolean | Optional. Whether flap detection is globally enabled. Defaults to true. |
enable_host_checks | Boolean | Optional. Whether active host checks are globally enabled. Defaults to true. |
enable_service_checks | Boolean | Optional. Whether active service checks are globally enabled. Defaults to true. |
enable_perfdata | Boolean | Optional. Whether performance data processing is globally enabled. Defaults to true. |
vars | Dictionary | Optional. A dictionary containing custom variables that are available globally. |
environment | String | Optional. Specify the Icinga environment. This overrides the Environment constant specified in the configuration or on the CLI with --define . Defaults to empty. |
IcingaDB ¶
The IcingaDB
object implements the Icinga DB feature.
Example:
object IcingaDB "icingadb" {
//host = "127.0.0.1"
//port = 6380
//password = "xxx"
}
Configuration Attributes:
Name | Type | Description |
---|---|---|
host | String | Optional. Redis host. Defaults to 127.0.0.1 . |
port | Number | Optional. Redis port. Defaults to 6380 since the Redis server provided by the icingadb-redis package listens on that port. |
path | String | Optional. Redis unix socket path. Can be used instead of host and port attributes. |
password | String | Optional. Redis auth password. |
enable_tls | Boolean | Optional. Whether to use TLS. |
cert_path | String | Optional. Path to the certificate. |
key_path | String | Optional. Path to the private key. |
ca_path | String | Optional. Path to the CA certificate to use instead of the system’s root CAs. |
crl_path | String | Optional. Path to the CRL file. |
cipher_list | String | Optional. Cipher list that is allowed. For a list of available ciphers run openssl ciphers . Defaults to ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384:DHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256 . |
tls_protocolmin | String | Optional. Minimum TLS protocol version. Defaults to TLSv1.2 . |
insecure_noverify | Boolean | Optional. Whether not to verify the peer. |
connect_timeout | Number | Optional. Timeout for establishing new connections. Within this time, the TCP, TLS (if enabled) and Redis handshakes must complete. Defaults to 15s . |
IdoMySqlConnection ¶
Note
This feature is DEPRECATED and may be removed in future releases. Check the roadmap.
IDO database adapter for MySQL. This configuration object is available as ido-mysql feature.
Example:
object IdoMysqlConnection "mysql-ido" {
host = "127.0.0.1"
port = 3306
user = "icinga"
password = "icinga"
database = "icinga"
cleanup = {
downtimehistory_age = 48h
contactnotifications_age = 31d
}
}
Configuration Attributes:
Name | Type | Description |
---|---|---|
host | String | Optional. MySQL database host address. Defaults to localhost . |
port | Number | Optional. MySQL database port. Defaults to 3306 . |
socket_path | String | Optional. MySQL socket path. |
user | String | Optional. MySQL database user with read/write permission to the icinga database. Defaults to icinga . |
password | String | Optional. MySQL database user’s password. Defaults to icinga . |
database | String | Optional. MySQL database name. Defaults to icinga . |
enable_ssl | Boolean | Optional. Use SSL. Defaults to false. Change to true in case you want to use any of the SSL options. |
ssl_key | String | Optional. MySQL SSL client key file path. |
ssl_cert | String | Optional. MySQL SSL certificate file path. |
ssl_ca | String | Optional. MySQL SSL certificate authority certificate file path. |
ssl_capath | String | Optional. MySQL SSL trusted SSL CA certificates in PEM format directory path. |
ssl_cipher | String | Optional. MySQL SSL list of allowed ciphers. |
table_prefix | String | Optional. MySQL database table prefix. Defaults to icinga_ . |
instance_name | String | Optional. Unique identifier for the local Icinga 2 instance, used for multiple Icinga 2 clusters writing to the same database. Defaults to default . |
instance_description | String | Optional. Description for the Icinga 2 instance. |
enable_ha | Boolean | Optional. Enable the high availability functionality. Only valid in a cluster setup. Defaults to true . |
failover_timeout | Duration | Optional. Set the failover timeout in a HA cluster. Must not be lower than 30s. Defaults to 30s . |
cleanup | Dictionary | Optional. Dictionary with items for historical table cleanup. |
categories | Array | Optional. Array of information types that should be written to the database. |
Cleanup Items:
Name | Type | Description |
---|---|---|
acknowledgements_age | Duration | Optional. Max age for acknowledgements table rows (entry_time). Defaults to 0 (never). |
commenthistory_age | Duration | Optional. Max age for commenthistory table rows (entry_time). Defaults to 0 (never). |
contactnotifications_age | Duration | Optional. Max age for contactnotifications table rows (start_time). Defaults to 0 (never). |
contactnotificationmethods_age | Duration | Optional. Max age for contactnotificationmethods table rows (start_time). Defaults to 0 (never). |
downtimehistory_age | Duration | Optional. Max age for downtimehistory table rows (entry_time). Defaults to 0 (never). |
eventhandlers_age | Duration | Optional. Max age for eventhandlers table rows (start_time). Defaults to 0 (never). |
externalcommands_age | Duration | Optional. Max age for externalcommands table rows (entry_time). Defaults to 0 (never). |
flappinghistory_age | Duration | Optional. Max age for flappinghistory table rows (event_time). Defaults to 0 (never). |
hostchecks_age | Duration | Optional. Max age for hostchecks table rows (start_time). Defaults to 0 (never). |
logentries_age | Duration | Optional. Max age for logentries table rows (logentry_time). Defaults to 0 (never). |
notifications_age | Duration | Optional. Max age for notifications table rows (start_time). Defaults to 0 (never). |
processevents_age | Duration | Optional. Max age for processevents table rows (event_time). Defaults to 0 (never). |
statehistory_age | Duration | Optional. Max age for statehistory table rows (state_time). Defaults to 0 (never). |
servicechecks_age | Duration | Optional. Max age for servicechecks table rows (start_time). Defaults to 0 (never). |
systemcommands_age | Duration | Optional. Max age for systemcommands table rows (start_time). Defaults to 0 (never). |
Supported units
Supported suffixes include ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Check the language reference.
Data Categories:
Name | Description | Required by |
---|---|---|
DbCatConfig | Configuration data | Icinga Web 2 |
DbCatState | Current state data | Icinga Web 2 |
DbCatAcknowledgement | Acknowledgements | Icinga Web 2 |
DbCatComment | Comments | Icinga Web 2 |
DbCatDowntime | Downtimes | Icinga Web 2 |
DbCatEventHandler | Event handler data | Icinga Web 2 |
DbCatExternalCommand | External commands | – |
DbCatFlapping | Flap detection data | Icinga Web 2 |
DbCatCheck | Check results | – |
DbCatLog | Log messages | – |
DbCatNotification | Notifications | Icinga Web 2 |
DbCatProgramStatus | Program status data | Icinga Web 2 |
DbCatRetention | Retention data | Icinga Web 2 |
DbCatStateHistory | Historical state data | Icinga Web 2 |
The default value for categories
includes everything required
by Icinga Web 2 in the table above.
In addition to the category flags listed above the DbCatEverything
flag may be used as a shortcut for listing all flags.
Runtime Attributes:
Name | Type | Description |
---|---|---|
last_failover | Timestamp | When the last failover happened for this connection (only available with enable_ha = true . |
IdoPgsqlConnection ¶
Note
This feature is DEPRECATED and may be removed in future releases. Check the roadmap.
IDO database adapter for PostgreSQL. This configuration object is available as ido-pgsql feature.
Example:
object IdoPgsqlConnection "pgsql-ido" {
host = "127.0.0.1"
port = 5432
user = "icinga"
password = "icinga"
database = "icinga"
cleanup = {
downtimehistory_age = 48h
contactnotifications_age = 31d
}
}
Configuration Attributes:
Name | Type | Description |
---|---|---|
host | String | Optional. PostgreSQL database host address. Defaults to localhost . |
port | Number | Optional. PostgreSQL database port. Defaults to 5432 . |
user | String | Optional. PostgreSQL database user with read/write permission to the icinga database. Defaults to icinga . |
password | String | Optional. PostgreSQL database user’s password. Defaults to icinga . |
database | String | Optional. PostgreSQL database name. Defaults to icinga . |
ssl_mode | String | Optional. Enable SSL connection mode. Value must be set according to the sslmode setting: prefer , require , verify-ca , verify-full , allow , disable . |
ssl_key | String | Optional. PostgreSQL SSL client key file path. |
ssl_cert | String | Optional. PostgreSQL SSL certificate file path. |
ssl_ca | String | Optional. PostgreSQL SSL certificate authority certificate file path. |
table_prefix | String | Optional. PostgreSQL database table prefix. Defaults to icinga_ . |
instance_name | String | Optional. Unique identifier for the local Icinga 2 instance, used for multiple Icinga 2 clusters writing to the same database. Defaults to default . |
instance_description | String | Optional. Description for the Icinga 2 instance. |
enable_ha | Boolean | Optional. Enable the high availability functionality. Only valid in a cluster setup. Defaults to true . |
failover_timeout | Duration | Optional. Set the failover timeout in a HA cluster. Must not be lower than 30s. Defaults to 30s . |
cleanup | Dictionary | Optional. Dictionary with items for historical table cleanup. |
categories | Array | Optional. Array of information types that should be written to the database. |
Cleanup Items:
Name | Type | Description |
---|---|---|
acknowledgements_age | Duration | Optional. Max age for acknowledgements table rows (entry_time). Defaults to 0 (never). |
commenthistory_age | Duration | Optional. Max age for commenthistory table rows (entry_time). Defaults to 0 (never). |
contactnotifications_age | Duration | Optional. Max age for contactnotifications table rows (start_time). Defaults to 0 (never). |
contactnotificationmethods_age | Duration | Optional. Max age for contactnotificationmethods table rows (start_time). Defaults to 0 (never). |
downtimehistory_age | Duration | Optional. Max age for downtimehistory table rows (entry_time). Defaults to 0 (never). |
eventhandlers_age | Duration | Optional. Max age for eventhandlers table rows (start_time). Defaults to 0 (never). |
externalcommands_age | Duration | Optional. Max age for externalcommands table rows (entry_time). Defaults to 0 (never). |
flappinghistory_age | Duration | Optional. Max age for flappinghistory table rows (event_time). Defaults to 0 (never). |
hostchecks_age | Duration | Optional. Max age for hostchecks table rows (start_time). Defaults to 0 (never). |
logentries_age | Duration | Optional. Max age for logentries table rows (logentry_time). Defaults to 0 (never). |
notifications_age | Duration | Optional. Max age for notifications table rows (start_time). Defaults to 0 (never). |
processevents_age | Duration | Optional. Max age for processevents table rows (event_time). Defaults to 0 (never). |
statehistory_age | Duration | Optional. Max age for statehistory table rows (state_time). Defaults to 0 (never). |
servicechecks_age | Duration | Optional. Max age for servicechecks table rows (start_time). Defaults to 0 (never). |
systemcommands_age | Duration | Optional. Max age for systemcommands table rows (start_time). Defaults to 0 (never). |
Supported units
Supported suffixes include ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Check the language reference.
Data Categories:
Name | Description | Required by |
---|---|---|
DbCatConfig | Configuration data | Icinga Web 2 |
DbCatState | Current state data | Icinga Web 2 |
DbCatAcknowledgement | Acknowledgements | Icinga Web 2 |
DbCatComment | Comments | Icinga Web 2 |
DbCatDowntime | Downtimes | Icinga Web 2 |
DbCatEventHandler | Event handler data | Icinga Web 2 |
DbCatExternalCommand | External commands | – |
DbCatFlapping | Flap detection data | Icinga Web 2 |
DbCatCheck | Check results | – |
DbCatLog | Log messages | – |
DbCatNotification | Notifications | Icinga Web 2 |
DbCatProgramStatus | Program status data | Icinga Web 2 |
DbCatRetention | Retention data | Icinga Web 2 |
DbCatStateHistory | Historical state data | Icinga Web 2 |
The default value for categories
includes everything required
by Icinga Web 2 in the table above.
In addition to the category flags listed above the DbCatEverything
flag may be used as a shortcut for listing all flags.
Runtime Attributes:
Name | Type | Description |
---|---|---|
last_failover | Timestamp | When the last failover happened for this connection (only available with enable_ha = true . |
InfluxdbWriter ¶
Writes check result metrics and performance data to a defined InfluxDB v1 host. This configuration object is available as influxdb feature. For InfluxDB v2 support see the Influxdb2Writer below.
Example:
object InfluxdbWriter "influxdb" {
host = "127.0.0.1"
port = 8086
database = "icinga2"
username = "icinga2"
password = "icinga2"
basic_auth = {
username = "icinga"
password = "icinga"
}
flush_threshold = 1024
flush_interval = 10s
host_template = {
measurement = "$host.check_command$"
tags = {
hostname = "$host.name$"
}
}
service_template = {
measurement = "$service.check_command$"
tags = {
hostname = "$host.name$"
service = "$service.name$"
}
}
}
Configuration Attributes:
Name | Type | Description |
---|---|---|
host | String | Required. InfluxDB host address. Defaults to 127.0.0.1 . |
port | Number | Required. InfluxDB HTTP port. Defaults to 8086 . |
database | String | Required. InfluxDB database name. Defaults to icinga2 . |
username | String | Optional. InfluxDB user name. Defaults to none . |
password | String | Optional. InfluxDB user password. Defaults to none . |
basic_auth | Dictionary | Optional. Username and password for HTTP basic authentication. |
ssl_enable | Boolean | Optional. Whether to use a TLS stream. Defaults to false . |
ssl_insecure_noverify | Boolean | Optional. Disable TLS peer verification. |
ssl_ca_cert | String | Optional. Path to CA certificate to validate the remote host. |
ssl_cert | String | Optional. Path to host certificate to present to the remote host for mutual verification. |
ssl_key | String | Optional. Path to host key to accompany the ssl_cert. |
host_template | Dictionary | Required. Host template to define the InfluxDB line protocol. |
service_template | Dictionary | Required. Service template to define the influxDB line protocol. |
enable_send_thresholds | Boolean | Optional. Whether to send warn, crit, min & max tagged data. |
enable_send_metadata | Boolean | Optional. Whether to send check metadata e.g. states, execution time, latency etc. |
flush_interval | Duration | Optional. How long to buffer data points before transferring to InfluxDB. Defaults to 10s . |
flush_threshold | Number | Optional. How many data points to buffer before forcing a transfer to InfluxDB. Defaults to 1024 . |
enable_ha | Boolean | Optional. Enable the high availability functionality. Only valid in a cluster setup. Defaults to false . |
Note: If flush_threshold
is set too low, this will always force the feature to flush all data
to InfluxDB. Experiment with the setting, if you are processing more than 1024 metrics per second
or similar.
Influxdb2Writer ¶
Writes check result metrics and performance data to a defined InfluxDB v2 host. This configuration object is available as influxdb feature. For InfluxDB v1 support see the InfluxdbWriter above.
Example:
object Influxdb2Writer "influxdb2" {
host = "127.0.0.1"
port = 8086
organization = "monitoring"
bucket = "icinga2"
auth_token = "ABCDEvwxyz0189-_"
flush_threshold = 1024
flush_interval = 10s
host_template = {
measurement = "$host.check_command$"
tags = {
hostname = "$host.name$"
}
}
service_template = {
measurement = "$service.check_command$"
tags = {
hostname = "$host.name$"
service = "$service.name$"
}
}
}
Configuration Attributes:
Name | Type | Description |
---|---|---|
host | String | Required. InfluxDB host address. Defaults to 127.0.0.1 . |
port | Number | Required. InfluxDB HTTP port. Defaults to 8086 . |
organization | String | Required. InfluxDB organization name. |
bucket | String | Required. InfluxDB bucket name. |
auth_token | String | Required. InfluxDB authentication token. |
ssl_enable | Boolean | Optional. Whether to use a TLS stream. Defaults to false . |
ssl_insecure_noverify | Boolean | Optional. Disable TLS peer verification. |
ssl_ca_cert | String | Optional. Path to CA certificate to validate the remote host. |
ssl_cert | String | Optional. Path to host certificate to present to the remote host for mutual verification. |
ssl_key | String | Optional. Path to host key to accompany the ssl_cert. |
host_template | Dictionary | Required. Host template to define the InfluxDB line protocol. |
service_template | Dictionary | Required. Service template to define the influxDB line protocol. |
enable_send_thresholds | Boolean | Optional. Whether to send warn, crit, min & max tagged data. |
enable_send_metadata | Boolean | Optional. Whether to send check metadata e.g. states, execution time, latency etc. |
flush_interval | Duration | Optional. How long to buffer data points before transferring to InfluxDB. Defaults to 10s . |
flush_threshold | Number | Optional. How many data points to buffer before forcing a transfer to InfluxDB. Defaults to 1024 . |
enable_ha | Boolean | Optional. Enable the high availability functionality. Only valid in a cluster setup. Defaults to false . |
Note: If flush_threshold
is set too low, this will always force the feature to flush all data
to InfluxDB. Experiment with the setting, if you are processing more than 1024 metrics per second
or similar.
JournaldLogger ¶
Specifies Icinga 2 logging to the systemd journal using its native interface.
This configuration object is available as journald
logging feature.
Resulting journal records have fields as described in
journal fields,
and an additional custom field ICINGA2_FACILITY
with the detailed message origin (e.g. “ApiListener”).
Example:
object JournaldLogger "journald" {
severity = "warning"
}
Configuration Attributes:
Name | Type | Description |
---|---|---|
severity | String | Optional. The minimum syslog compatible severity for this log. Can be “debug”, “notice”, “information”, “warning” or “critical”. Defaults to “information”. |
facility | String | Optional. Defines the syslog compatible facility to use for journal entries. This can be a facility constant like FacilityDaemon . Defaults to FacilityUser . |
identifier | String | Optional. Defines the syslog compatible identifier (also known as “tag”) to use for journal entries. If not given, systemd’s default behavior is used and usually results in “icinga2”. |
Facility Constants are the same as for SyslogLogger.
LiveStatusListener ¶
Livestatus API interface available as TCP or UNIX socket. Historical table queries
require the CompatLogger feature enabled
pointing to the log files using the compat_log_path
configuration attribute.
This configuration object is available as livestatus feature.
Note
This feature is DEPRECATED and may be removed in future releases. Check the roadmap.
Examples:
object LivestatusListener "livestatus-tcp" {
socket_type = "tcp"
bind_host = "127.0.0.1"
bind_port = "6558"
}
object LivestatusListener "livestatus-unix" {
socket_type = "unix"
socket_path = "/var/run/icinga2/cmd/livestatus"
}
Configuration Attributes:
Name | Type | Description |
---|---|---|
socket_type | String | Optional. Specifies the socket type. Can be either tcp or unix . Defaults to unix . |
bind_host | String | Optional. Only valid when socket_type is set to tcp . Host address to listen on for connections. Defaults to 127.0.0.1 . |
bind_port | Number | Optional. Only valid when socket_type is set to tcp . Port to listen on for connections. Defaults to 6558 . |
socket_path | String | Optional. Only valid when socket_type is set to unix . Specifies the path to the UNIX socket file. Defaults to RunDir + “/icinga2/cmd/livestatus”. |
compat_log_path | String | Optional. Path to Icinga 1.x log files. Required for historical table queries. Requires CompatLogger feature enabled. Defaults to LogDir + “/compat” |
Note
UNIX sockets are not supported on Windows.
NotificationComponent ¶
The notification component is responsible for sending notifications. This configuration object is available as notification feature.
Example:
object NotificationComponent "notification" { }
Configuration Attributes:
Name | Type | Description |
---|---|---|
enable_ha | Boolean | Optional. Enable the high availability functionality. Only valid in a cluster setup. Disabling this currently only affects reminder notifications. Defaults to “true”. |
OpenTsdbWriter ¶
Writes check result metrics and performance data to OpenTSDB. This configuration object is available as opentsdb feature.
Example:
object OpenTsdbWriter "opentsdb" {
host = "127.0.0.1"
port = 4242
}
Configuration Attributes:
Name | Type | Description |
---|---|---|
host | String | Optional. OpenTSDB host address. Defaults to 127.0.0.1 . |
port | Number | Optional. OpenTSDB port. Defaults to 4242 . |
enable_ha | Boolean | Optional. Enable the high availability functionality. Only valid in a cluster setup. Defaults to false . |
enable_generic_metrics | Boolean | Optional. Re-use metric names to store different perfdata values for a particular check. Use tags to distinguish perfdata instead of metric name. Defaults to false . |
host_template | Dictionary | Optional. Specify additional tags to be included with host metrics. This requires a sub-dictionary named tags . Also specify a naming prefix by setting metric . More information can be found in OpenTSDB custom tags and OpenTSDB Metric Prefix. More information can be found in OpenTSDB custom tags. Defaults to an empty Dictionary . |
service_template | Dictionary | Optional. Specify additional tags to be included with service metrics. This requires a sub-dictionary named tags . Also specify a naming prefix by setting metric . More information can be found in OpenTSDB custom tags and OpenTSDB Metric Prefix. Defaults to an empty Dictionary . |
PerfdataWriter ¶
Writes check result performance data to a defined path using macro pattern consisting of custom variables and runtime macros. This configuration object is available as perfdata feature.
Example:
object PerfdataWriter "perfdata" {
host_perfdata_path = "/var/spool/icinga2/perfdata/host-perfdata"
service_perfdata_path = "/var/spool/icinga2/perfdata/service-perfdata"
host_format_template = "DATATYPE::HOSTPERFDATA\tTIMET::$icinga.timet$\tHOSTNAME::$host.name$\tHOSTPERFDATA::$host.perfdata$\tHOSTCHECKCOMMAND::$host.check_command$\tHOSTSTATE::$host.state$\tHOSTSTATETYPE::$host.state_type$"
service_format_template = "DATATYPE::SERVICEPERFDATA\tTIMET::$icinga.timet$\tHOSTNAME::$host.name$\tSERVICEDESC::$service.name$\tSERVICEPERFDATA::$service.perfdata$\tSERVICECHECKCOMMAND::$service.check_command$\tHOSTSTATE::$host.state$\tHOSTSTATETYPE::$host.state_type$\tSERVICESTATE::$service.state$\tSERVICESTATETYPE::$service.state_type$"
rotation_interval = 15s
}
Configuration Attributes:
Name | Type | Description |
---|---|---|
host_perfdata_path | String | Optional. Path to the host performance data file. Defaults to SpoolDir + “/perfdata/host-perfdata”. |
service_perfdata_path | String | Optional. Path to the service performance data file. Defaults to SpoolDir + “/perfdata/service-perfdata”. |
host_temp_path | String | Optional. Path to the temporary host file. Defaults to SpoolDir + “/tmp/host-perfdata”. |
service_temp_path | String | Optional. Path to the temporary service file. Defaults to SpoolDir + “/tmp/service-perfdata”. |
host_format_template | String | Optional. Host Format template for the performance data file. Defaults to a template that’s suitable for use with PNP4Nagios. |
service_format_template | String | Optional. Service Format template for the performance data file. Defaults to a template that’s suitable for use with PNP4Nagios. |
rotation_interval | Duration | Optional. Rotation interval for the files specified in {host,service}_perfdata_path . Defaults to 30s . |
enable_ha | Boolean | Optional. Enable the high availability functionality. Only valid in a cluster setup. Defaults to false . |
When rotating the performance data file the current UNIX timestamp is appended to the path specified
in host_perfdata_path
and service_perfdata_path
to generate a unique filename.
SyslogLogger ¶
Specifies Icinga 2 logging to syslog.
This configuration object is available as syslog
logging feature.
Example:
object SyslogLogger "syslog" {
severity = "warning"
}
Configuration Attributes:
Name | Type | Description |
---|---|---|
severity | String | Optional. The minimum severity for this log. Can be “debug”, “notice”, “information”, “warning” or “critical”. Defaults to “information”. |
facility | String | Optional. Defines the facility to use for syslog entries. This can be a facility constant like FacilityDaemon . Defaults to FacilityUser . |
Facility Constants:
Name | Facility | Description |
---|---|---|
FacilityAuth | LOG_AUTH | The authorization system. |
FacilityAuthPriv | LOG_AUTHPRIV | The same as FacilityAuth , but logged to a file readable only by selected individuals. |
FacilityCron | LOG_CRON | The cron daemon. |
FacilityDaemon | LOG_DAEMON | System daemons that are not provided for explicitly by other facilities. |
FacilityFtp | LOG_FTP | The file transfer protocol daemons. |
FacilityKern | LOG_KERN | Messages generated by the kernel. These cannot be generated by any user processes. |
FacilityLocal0 | LOG_LOCAL0 | Reserved for local use. |
FacilityLocal1 | LOG_LOCAL1 | Reserved for local use. |
FacilityLocal2 | LOG_LOCAL2 | Reserved for local use. |
FacilityLocal3 | LOG_LOCAL3 | Reserved for local use. |
FacilityLocal4 | LOG_LOCAL4 | Reserved for local use. |
FacilityLocal5 | LOG_LOCAL5 | Reserved for local use. |
FacilityLocal6 | LOG_LOCAL6 | Reserved for local use. |
FacilityLocal7 | LOG_LOCAL7 | Reserved for local use. |
FacilityLpr | LOG_LPR | The line printer spooling system. |
FacilityMail | LOG_MAIL | The mail system. |
FacilityNews | LOG_NEWS | The network news system. |
FacilitySyslog | LOG_SYSLOG | Messages generated internally by syslogd. |
FacilityUser | LOG_USER | Messages generated by user processes. This is the default facility identifier if none is specified. |
FacilityUucp | LOG_UUCP | The UUCP system. |
WindowsEventLogLogger ¶
Specifies Icinga 2 logging to the Windows Event Log.
This configuration object is available as windowseventlog
logging feature.
Example:
object WindowsEventLogLogger "windowseventlog" {
severity = "information"
}
Configuration Attributes:
Name | Type | Description |
---|---|---|
severity | String | Optional. The minimum severity for this log. Can be “debug”, “notice”, “information”, “warning” or “critical”. Defaults to “information”. |