diff --git a/doc/6-object-types.md b/doc/6-object-types.md index 6d134b986..eab0a699e 100644 --- a/doc/6-object-types.md +++ b/doc/6-object-types.md @@ -3,293 +3,37 @@ This chapter provides an overview of all available object types which can be instantiated using the `object` keyword. -## Host +Additional details on configuration and runtime attributes and their +description are explained as well. -A host. +## ApiListener + +ApiListener objects are used for distributed monitoring setups +specifying the certificate files used for ssl authorization. + +The `NodeName` constant must be defined in [constants.conf](5-configuring-icinga-2.md#constants-conf). Example: - object Host "localhost" { - display_name = "The best host there is" - address = "127.0.0.1" - address6 = "::1" - - groups = [ "all-hosts" ] - - check_command = "hostalive" + 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 - ----------------|---------------- - display_name |**Optional.** A short description of the host. - 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). - 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). - comments | Dictionary | The comments for this host. - downtimes | Dictionary | The downtimes for this host. - 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). - -## HostGroup - -A group of hosts. - -> **Best Practice** -> -> Assign host group members using the [group assign](19-language-reference.md#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. - -## 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](3-monitoring-basics.md#using-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). - 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). - comments | Dictionary | The comments for this service. - downtimes | Dictionary | The downtimes for this service. - 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). - - -## ServiceGroup - -A group of services. - -> **Best Practice** -> -> Assign service group members using the [group assign](19-language-reference.md#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. - - -## 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. - zone |**Optional.** The zone this object is a member of. - -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](19-language-reference.md#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 |**Optional.** The zone this object is a member of. - - + 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`. ## CheckCommand @@ -363,13 +107,13 @@ CheckCommand: arguments = { "-X" = { value = "$x_val$" - key = "-Xnew" /* optional, set a new key identifier */ + 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 " */ 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]' ... */ + 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$" @@ -378,7 +122,7 @@ CheckCommand: skip_key = true /* don't prefix "-Y" only use "" */ 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]' ... */ + repeat_key = false /* if `value` is an array, do not repeat the key as parameter: ... 'key' 'value[0]' 'value[1]' 'value[2]' ... */ } } @@ -405,240 +149,57 @@ Argument array `repeat_key = false`: `'key' 'value[0]' 'value[1]' 'value[2]'` +## CheckerComponent -## NotificationCommand - -A notification command definition. +The checker component is responsible for scheduling active checks. There are no configurable options. Example: - object NotificationCommand "mail-service-notification" { - import "plugin-notification-command" + library "checker" - command = [ - SysconfDir + "/icinga2/scripts/mail-notification.sh" - ] + object CheckerComponent "checker" { } - 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$" - } +## 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 ----------------|---------------- - 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. - zone |**Optional.** The zone this object is a member of. - arguments |**Optional.** A dictionary of command arguments. - -Command arguments can be used the same way as for [CheckCommand objects](6-object-types.md#objecttype-checkcommand-arguments). + spool\_dir |**Optional.** The directory which contains the check result files. Defaults to LocalStateDir + "/lib/icinga2/spool/checkresults/". -## EventCommand +## CompatLogger -An event command definition. +Writes log files in a format that's compatible with Icinga 1.x. Example: - object EventCommand "restart-httpd-event" { - import "plugin-event-command" + library "compat" - 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](6-object-types.md#objecttype-checkcommand-arguments). - - -## 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](3-monitoring-basics.md#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](3-monitoring-basics.md#disable-renotification) 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: - - OK - Warning - Critical - Unknown - 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). - - -## TimePeriod - -Time periods can be used to specify when hosts/services should be checked or to limit -when notifications should be sent out. - -Example: - - object TimePeriod "24x7" { - import "legacy-timeperiod" - - display_name = "Icinga 2 24x7 TimePeriod" - - ranges = { - monday = "00:00-24:00" - tuesday = "00:00-24:00" - wednesday = "00:00-24:00" - thursday = "00:00-24:00" - friday = "00:00-24:00" - saturday = "00:00-24:00" - sunday = "00:00-24:00" - } + object CompatLogger "my-log" { + log_dir = "/var/log/icinga2/compat" + rotation_method = "HOURLY" } 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. - zone |**Optional.** The zone this object is a member of. - ranges |**Required.** A dictionary containing information which days and durations apply to this timeperiod. + 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". -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. - -## 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](4-advanced-topics.md#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. - zone |**Optional.** The zone this object is a member of. - 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. ## Dependency @@ -739,40 +300,138 @@ name you specified. This means you can define more than one object with the same `child_service_name` attributes has a different value. -## PerfdataWriter +## Endpoint -Writes check result performance data to a defined path using macro -pattern consisting of custom attributes and runtime macros. +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`. + + +## 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. + + +## 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](6-object-types.md#objecttype-checkcommand-arguments). + + +## 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 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 + object GelfWriter "gelf" { + host = "127.0.0.1" + port = 12201 } 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. + 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 @@ -807,47 +466,124 @@ Example with your custom [global constant](19-language-reference.md#constants) ` host_name_template = GraphiteEnv + ".$host.name$" service_name_template = GraphiteEnv + ".$host.name$.$service.name$" -## OpenTsdbWriter -Writes check result metrics and performance data to OpenTSDB. + +## Host + +A host. Example: - library "perfdata" + object Host NodeName { + display_name = "Local host on this node" + address = "127.0.0.1" + address6 = "::1" - object OpenTsdbWriter "opentsdb" { - host = "127.0.0.1" - port = 4242 + groups = [ "all-hosts" ] + + check_command = "hostalive" } Configuration Attributes: - Name |Description - ----------------------|---------------------- - host |**Optional.** OpenTSDB host address. Defaults to '127.0.0.1'. - port |**Optional.** OpenTSDB port. Defaults to 4242. + 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). + 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). + comments | Dictionary | The comments for this host. + downtimes | Dictionary | The downtimes for this host. + 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). -## GelfWriter -Writes event log entries to a defined GELF receiver host (Graylog2, Logstash). +## HostGroup + +A group of hosts. + +> **Best Practice** +> +> Assign host group members using the [group assign](19-language-reference.md#group-assign) rules. Example: - library "perfdata" - - object GelfWriter "gelf" { - host = "127.0.0.1" - port = 12201 + object HostGroup "my-hosts" { + display_name = "My hosts" } 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`. + Name |Description + ----------------|---------------- + display_name |**Optional.** A short description of the host group. + groups |**Optional.** An array of nested group names. + + +## IcingaStatusWriter + +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 @@ -1032,8 +768,8 @@ 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. +require the [CompatLogger](6-object-types.md#objecttype-compatlogger) feature enabled +pointing to the log files using the `compat_log_path` configuration attribute. Example: @@ -1064,6 +800,355 @@ Configuration Attributes: > > 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](3-monitoring-basics.md#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](3-monitoring-basics.md#disable-renotification) 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: + + OK + Warning + Critical + Unknown + 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. + zone |**Optional.** The zone this object is a member of. + arguments |**Optional.** A dictionary of command arguments. + +Command arguments can be used the same way as for [CheckCommand objects](6-object-types.md#objecttype-checkcommand-arguments). + + +## 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](12-distributed-monitoring-ha.md#high-availability-notifications). Defaults to "true". + +## OpenTsdbWriter + +Writes check result metrics and performance data to [OpenTSDB](http://opentsdb.net). + +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](4-advanced-topics.md#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. + zone |**Optional.** The zone this object is a member of. + 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](3-monitoring-basics.md#using-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). + 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). + comments | Dictionary | The comments for this service. + downtimes | Dictionary | The downtimes for this service. + 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). + + +## ServiceGroup + +A group of services. + +> **Best Practice** +> +> Assign service group members using the [group assign](19-language-reference.md#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. @@ -1087,113 +1172,6 @@ Configuration Attributes: update\_interval|**Optional.** The interval in which the status files are updated. Defaults to 15 seconds. -## 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". - -## 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". - - -## 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/". - - -## CheckerComponent - -The checker component is responsible for scheduling active checks. There are no configurable options. - -Example: - - library "checker" - - object CheckerComponent "checker" { } - - -## 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](#high-availability). Defaults to "true". - - -## 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". - - ## SyslogLogger Specifies Icinga 2 logging to syslog. @@ -1211,77 +1189,131 @@ Configuration Attributes: severity |**Optional.** The minimum severity for this log. Can be "debug", "notice", "information", "notice", "warning" or "critical". Defaults to "warning". +## TimePeriod -## IcingaStatusWriter - -The IcingaStatusWriter feature periodically dumps the current status -and performance data from Icinga 2 and all registered features into -a defined JSON file. +Time periods can be used to specify when hosts/services should be checked or to limit +when notifications should be sent out. Example: - object IcingaStatusWriter "status" { - status_path = LocalStateDir + "/cache/icinga2/status.json" - update_interval = 15s - } + object TimePeriod "24x7" { + import "legacy-timeperiod" -Configuration Attributes: + display_name = "Icinga 2 24x7 TimePeriod" - 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. - - -## ApiListener - -ApiListener objects are used for distributed monitoring setups -specifying the certificate files used for ssl authorization. - -The `NodeName` constant must be defined in [constants.conf](5-configuring-icinga-2.md#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`. - - -## 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 + ranges = { + monday = "00:00-24:00" + tuesday = "00:00-24:00" + wednesday = "00:00-24:00" + thursday = "00:00-24:00" + friday = "00:00-24:00" + saturday = "00:00-24:00" + sunday = "00:00-24:00" + } } 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`. + 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. + zone |**Optional.** The zone this object is a member of. + 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. + zone |**Optional.** The zone this object is a member of. + +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](19-language-reference.md#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 |**Optional.** The zone this object is a member of. ## Zone @@ -1307,4 +1339,3 @@ Configuration Attributes: 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. -