* Network services (HTTP, SMTP, SNMP, SSH, etc.)
* Printers
-* Switches / Routers
-* Temperature Sensors
+* Switches / routers
+* Temperature sensors
* Other local or network-accessible services
Host objects provide a mechanism to group services that are running
}
object Service "ping4" {
- host_name = "localhost"
+ host_name = "my-server1"
check_command = "ping4"
}
object Service "http" {
- host_name = "localhost"
+ host_name = "my-server1"
check_command = "http_ip"
}
The [Getting Started](#getting-started) chapter already introduced various aspects
of the Icinga 2 configuration language. If you are ready to configure additional
-hosts, services, notifications, dependencies, etc you should think about the
+hosts, services, notifications, dependencies, etc, you should think about the
requirements first and then decide for a possible strategy.
There are many ways of creating Icinga 2 configuration objects:
#### <a id="group-assign"></a> Group Membership Assign
-If there is a certain number of hosts, services or users matching a pattern
+If there is a certain number of hosts, services, or users matching a pattern
it's reasonable to assign the group object to these members.
Details on the `assign where` syntax can be found [here](#apply)
When a host or service is in a downtime, a problem has been acknowledged or
the dependency logic determined that the host/service is unreachable, no
-notirications are sent. You can configure additional type and state filters
+notifications are sent. You can configure additional type and state filters
refining the notifications being actually sent.
There are many ways of sending notifications, e.g. by e-mail, XMPP,
states = [ Warning, Critical, Unknown ]
types = [ Problem, Acknowledgement, Recovery, Custom, FlappingStart,
- FlappingEnd, DowntimeStart,DowntimeEnd, DowntimeRemoved ]
+ FlappingEnd, DowntimeStart, DowntimeEnd, DowntimeRemoved ]
period = "24x7"
}
### <a id="notification-escalations"></a> Notification Escalations
-When a problem notification is sent and a problem still exists after re-notification
+When a problem notification is sent and a problem still exists at the time of re-notification
you may want to escalate the problem to the next support level. A different approach
is to configure the default notification by email, and escalate the problem via sms
if not already solved.
> template or overriding the attribute directly in the `notifications` array
> position for `escalation-sms-2nd-level`.
-If the problem does not get resolved or acknowledged preventing further notifications
+If the problem does not get resolved nor acknowledged preventing further notifications
the `escalation-sms-1st-level` user will be escalated `1h` after the initial problem was
notified, but only for one hour (`2h` as `end` key for the `times` dictionary).
### <a id="first-notification-delay"></a> First Notification Delay
-Sometimes the problem in question should not be notified when the first notification
-happens, but a defined time duration afterwards. In Icinga 2 you can use the `times`
+Sometimes the problem in question should not be notified when the notification is due
+(the object reaching the `HARD` state) but a defined time duration afterwards. In Icinga 2 you can use the `times`
dictionary and set `begin = 15m` as key and value if you want to suppress notifications
in the first 15 minutes. Leave out the `end` key - if not set, Icinga 2 will not check against any
end time for this notification.
## <a id="commands"></a> Commands
Icinga 2 uses three different command object types to specify how
-checks should be performed, notifications should be sent and
+checks should be performed, notifications should be sent, and
events should be handled.
### <a id="command-environment-variables"></a> Environment Variables for Commands
Planned downtimes will also be taken into account for SLA reporting
tools calculating the SLAs based on the state and downtime history.
-Downtimes may overlap with their start and end times. If there
-are multiple downtimes triggered for one object, the overall downtime depth
-will be more than `1`. This is useful when you want to extend
-your maintenance window taking longer than expected.
+Multiple downtimes for a single object may overlap. This is useful
+when you want to extend your maintenance window taking longer than expected.
+If there are multiple downtimes triggered for one object, the overall downtime depth
+will be greater than `1`.
+
If the downtime was scheduled after the problem changed to a critical hard
state triggering a problem notification, and the service recovers during
all problems should be alerted again. Solution is simple -
schedule a `fixed` downtime starting at 23:00 and ending at 24:00.
-Unlike a `fixed` downtime, a `flexible` downtime end does not necessarily
-happen at the provided end time. Instead the downtime will be triggered
-by the state change in the time span defined by start and end time, but
-then last a defined duration in minutes.
+Unlike a `fixed` downtime, a `flexible` downtime will be triggered
+by the state change in the time span defined by start and end time,
+and then last for the specified duration in minutes.
Imagine the following scenario: Your service is frequently polled
by users trying to grab free deleted domains for immediate registration.
# usermod -G -a icingacmd www-data
Debian packages use `nagios` as the default user and group name. Therefore change `icingacmd` to
-`nagios`.
+`nagios`. The webserver's user is different between distributions as well.
### <a id="external-command-list"></a> External Command List
-A list of currently supported external commands can be found [here](#external-commands-list-detail)
+A list of currently supported external commands can be found [here](#external-commands-list-detail).
Detailed information on the commands and their required parameters can be found
on the [Icinga 1.x documentation](http://docs.icinga.org/latest/en/extcommands2.html).
These logs are not only used for informational representation in
external web interfaces parsing the logs, but also to generate
-SLA reports and trends in Icinga 1.x Classic UI. Futhermore the
+SLA reports and trends in Icinga 1.x Classic UI. Furthermore the
[Livestatus](#livestatus) feature uses these logs for answering queries to
historical tables.
The following example uses the [SNMP ITL](#itl-snmp) `CheckCommand` and just
overrides the `snmp_oid` custom attribute. A service is created for all hosts which
-have the `snmP-community` custom attribute.
+have the `snmp-community` custom attribute.
apply Service "uptime" {
import "generic-service"
Instead of using the default FQDN as node name you can optionally set
that value using the [NodeName](#global-constants) constant.
-This setting must be unique on each node, and must also match
+This setting must be unique for each node, and must also match
the name of the local [Endpoint](#objecttype-endpoint) object and the
SSL certificate common name.
Read further about additional [naming conventions](#cluster-naming-convention).
Not specifying the node name will make Icinga 2 using the FQDN. Make sure that all
-configured endpoint names and common names are the same.
+configured endpoint names and common names are in sync.
### <a id="cluster-naming-convention"></a> Cluster Naming Convention
Each cluster node should execute its own local cluster health check to
get an idea about network related connection problems from different
-point of views.
+points of view.
### <a id="host-multiple-cluster-nodes"></a> Host With Multiple Cluster Nodes
Special scenarios might require multiple cluster nodes running on a single host.
-By default Icinga 2 and its features will drop their runtime data below the prefix
+By default Icinga 2 and its features will place their runtime data below the prefix
`LocalStateDir`. By default packages will set that path to `/var`.
You can either set that variable as constant configuration
definition in [icinga2.conf](#icinga2-conf) or pass it as runtime variable to
departments. The customers instances will collect all results, but also send them back to
your central instance.
Additionally the customers instance on the second level in the middle prohibits you from
-sending commands to the down below department nodes. You're only allowed to receive the
+sending commands to the subjacent department nodes. You're only allowed to receive the
results, and a subset of each customers configuration too.
-Your central zone will generate global reports, aggregate alert notifications and check
+Your central zone will generate global reports, aggregate alert notifications, and check
additional dependencies (for example, the customers internet uplink and bandwidth usage).
The customers zone instances will only check a subset of local services and delegate the rest
#### <a id="addons-graphing-pnp"></a> inGraph
inGraph (https://www.netways.org/projects/ingraph/wiki) requires only the ingraph-collector
-configured pointed to the perfdata files Icinga 2's [PerfdataWriter](#performance-data) will
+configured pointing to the perfdata files Icinga 2's [PerfdataWriter](#performance-data) will
write to the performance data spool directory.
#### <a id="addons-graphing-pnp"></a> Graphite
An unordered list of key-value pairs. Keys must be unique and are
compared in a case-insensitive manner.
-Individual key-value pairs must be separated from each other with a
-comma. The comma after the last key-value pair is optional.
+Individual key-value pairs must either be comma-separated or on separate lines.
+The comma after the last key-value pair is optional.
Example:
Identifiers may not contain certain characters (e.g. space) or start
with certain characters (e.g. digits). If you want to use a dictionary
-key that is not a valid identifier you can put the key in double
+key that is not a valid identifier you can enclose the key in double
quotes.
Setting a dictionary key to null causes the key and its value to be
An ordered list of values.
-Individual array elements must be separated from each other with a
-comma. The comma after the last element is optional.
+Individual array elements must be comma-separated.
+The comma after the last element is optional.
Example:
number(value) | Converts the value to a number.
bool(value) | Converts the value to a bool.
log(value) | Writes a message to the log. Non-string values are converted to a JSON string.
-log(severity, facility, value) | Writes a message to the log. `severity` can be one of `LogDebug`, `LogNotice`, `LogInformation`, `LogWarning` and `LogCritical`. Non-string values are converted to a JSON string.
+log(severity, facility, value) | Writes a message to the log. `severity` can be one of `LogDebug`, `LogNotice`, `LogInformation`, `LogWarning`, and `LogCritical`. Non-string values are converted to a JSON string.
exit(integer) | Terminates the application.
### <a id="dictionary-operators"></a> Dictionary Operators
const VarName = "some value"
-Once defined a constant can be access from any file. Constants cannot be changed
+Once defined a constant can be accessed from any file. Constants cannot be changed
once they are set.
There is a defined set of [global constants](#global-constants) which allow
evaluated for all objects of type `Host` and a new service with name "ping"
is created for each matching host.
-The `to` keyword and the target type may be omitted if there is only target
+The `to` keyword and the target type may be omitted if there is only one target
type, e.g. for the `Service` type.
Depending on the object type used in the `apply` expression additional local
enable\_event\_handler|**Optional.** Enables event handlers for this host. Defaults to true.
enable\_flap\_detection|**Optional.** Whether flap detection is enabled. Defaults to true.
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.
+ event\_command |**Optional.** The name of an event command that should be executed every time the host's state changes and when 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.
notes |**Optional.** Notes for the host.
## <a id="troubleshooting-enable-debug-output"></a> Enable Debug Output
-Run Icinga 2 in foreground with debugging enabled Specify the console
+Run Icinga 2 in foreground with debugging enabled. Specify the console
log severity as additional parameter argument to `-x`. Default
is `debug`.
## <a id="checks-not-executed"></a> Checks are not executed
* Check the debug log if the check command gets executed
-* Verify that failed depedencies do not prevent the command execution
+* Verify that failed dependencies do not prevent the command execution
* Make sure that the plugin is executable by the Icinga 2 user (run a manual test)
# sudo -u icinga /usr/lib/nagios/plugins/check_ping -4 -H 127.0.0.1 -c 5000,100% -w 3000,80%
Total params: 1
The feature 'notification' is already enabled.
-* Does the referenced NotificationCommand work executed as Icinga user on the shell?
+* Does the referenced NotificationCommand work when executed as Icinga user on the shell?
## <a id="feature-not-working"></a> Feature is not working
## <a id="configuration-ignored"></a> Configuration is ignored
* Make sure that the line(s) are not [commented](#comments) (starting with `//` or `#`, or
-encapsulated by `/* ... */`.
+encapsulated by `/* ... */`).
* Is the configuration file included in [icinga2.conf](#icinga2-conf)?
## <a id="configuration-attribute-inheritance"></a> Configuration attributes are inherited from
For a long-term migration of your configuration you should consider re-creating
your configuration based on the Icinga 2 proposed way of doing configuration right.
-Please read the [next chapter](#differences-1x-2) to get an idea about the differences between 1.x and 2.
+Please read the [next section](#differences-1x-2) to get an idea about the differences between 1.x and 2.
## <a id="differences-1x-2"></a> Differences between Icinga 1.x and 2
### <a id="differences-1x-2-object-names"></a> Object names
-Object names must not contain a colon (`!`). Use the `display_name` attribute
+Object names must not contain an exclamation mark (`!`). Use the `display_name` attribute
to specify user-friendly names which should be shown in UIs (supported by
Icinga 1.x Classic UI and Web).
Please note that the default time value is seconds, if no duration literal
is given. `check_interval = 5` behaves the same as `check_interval = 5s`.
-All strings require double quotes in Icinga 2. Therefore a double-quote
-must be escaped with a backslash (e.g. in command line).
-If an attribute identifier starts with a number, it must be encapsulated
-with double quotes as well.
+All strings require double quotes in Icinga 2. Therefore a double quote
+must be escaped by a backslash (e.g. in command line).
+If an attribute identifier starts with a number, it must be enclosed
+in double quotes as well.
#### <a id="differences-1x-2-alias-display-name"></a> Alias vs. Display Name
In Icinga 1.x a service object is associated with a host by defining the
`host_name` attribute in the service definition. Alternate methods refer
-to `hostgroup_name` or behavior changing regular expression.
+to `hostgroup_name` or behaviour changing regular expression.
The preferred way of associating hosts with services in Icinga 2 is by
using the [apply](#using-apply) keyword.
#### <a id="differences-1x-2-runtime-macros"></a> Runtime Macros
Icinga 2 requires an object specific namespace when accessing configuration
-and stateful runtime macros. Custom attributes can be access directly.
+and stateful runtime macros. Custom attributes can be accessed directly.
Changes to user (contact) runtime macros
### <a id="differences-1x-2-commands"></a> Commands
-Unlike in Icinga 1.x there are 3 different command types in Icinga 2:
-`CheckCommand`, `NotificationCommand` and `EventCommand`.
+Unlike in Icinga 1.x there are three different command types in Icinga 2:
+`CheckCommand`, `NotificationCommand`, and `EventCommand`.
For example in Icinga 1.x it is possible to accidently use a notification
command as an event handler which might cause problems depending on which
Unlike Icinga 1.x with the 'notification_options' attribute with comma-separated
state and type filters, Icinga 2 uses two configuration attributes for that.
-All state and type filter use long names or'd with a pipe together
+All state and type filter use long names OR'd with a pipe together
notification_options w,u,c,r,f,s
### <a id="differences-1x-2-check-result-freshness"></a> Check Result Freshness
-Freshness of check results must be explicitely enabled in Icinga 1.x. The attribute
-`freshness_treshold` defines the threshold in seconds. Once the threshold is triggered, an
+Freshness of check results must be enabled explicitly in Icinga 1.x. The attribute
+`freshness_threshold` defines the threshold in seconds. Once the threshold is triggered, an
active freshness check is executed defined by the `check_command` attribute. Both check
methods (active and passive) use the same freshness check method.
in Icinga 1.x format in order to stay compatible with Classic UI and other addons.
The native Icinga 2 logging facilities are split into three configuration objects: SyslogLogger,
-FileLogger, StreamLogger. Each of them got their own severity and target configuration.
+FileLogger, StreamLogger. Each of them has their own severity and target configuration.
The Icinga 2 daemon log does not log any alerts but is considered an application log only.
### <a id="differences-1x-2-distributed-monitoring"></a> Distributed Monitoring
Icinga 1.x uses the native "obsess over host/service" method which requires the NSCA addon
-passing the slave's checkresults passively onto the master's external command pipe.
+passing the slave's check results passively onto the master's external command pipe.
While this method may be used for check load distribution, it does not provide any configuration
distribution out-of-the-box. Furthermore comments, downtimes and other stateful runtime data is
not synced between the master and slave nodes. There are addons available solving the check
## <a id="schemas"></a> Schemas
-By convention `CheckCommand`, `EventCommand` and `NotificationCommand` objects
+By convention `CheckCommand`, `EventCommand`, and `NotificationCommand` objects
are exported using a prefix. This is mandatory for unique objects in the
command tables.
projects / icinga2 / commitdiff