mirror of
https://github.com/Icinga/icinga2.git
synced 2025-10-31 11:14:10 +01:00
Update documentation.
Fixes #6359 Signed-off-by: Gunnar Beutner <gunnar@beutner.name>
This commit is contained in:
Wolfgang Nieder
Gunnar Beutner
parent
24a884f79b
commit
36c71d69bd
@ -10,8 +10,8 @@ and services can be virtually anything which can be checked in some way:
|
||||
|
||||
* 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
|
||||
@ -25,12 +25,12 @@ Here is an example of a host object which defines two child services:
|
||||
}
|
||||
|
||||
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"
|
||||
}
|
||||
|
||||
@ -86,7 +86,7 @@ state the host/service switches to a `HARD` state and notifications are sent.
|
||||
|
||||
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:
|
||||
@ -275,7 +275,7 @@ the user groups are associated as attributes in `Notification` 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)
|
||||
|
||||
@ -294,7 +294,7 @@ monitoring setup.
|
||||
|
||||
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,
|
||||
@ -343,7 +343,7 @@ to the defined notifications. That way you'll save duplicated attributes in each
|
||||
|
||||
states = [ Warning, Critical, Unknown ]
|
||||
types = [ Problem, Acknowledgement, Recovery, Custom, FlappingStart,
|
||||
FlappingEnd, DowntimeStart,DowntimeEnd, DowntimeRemoved ]
|
||||
FlappingEnd, DowntimeStart, DowntimeEnd, DowntimeRemoved ]
|
||||
|
||||
period = "24x7"
|
||||
}
|
||||
@ -367,7 +367,7 @@ send notifications to all group members.
|
||||
|
||||
### <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.
|
||||
@ -419,7 +419,7 @@ command) after `30m` until `1h`.
|
||||
> 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).
|
||||
|
||||
@ -462,8 +462,8 @@ 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.
|
||||
@ -580,7 +580,7 @@ Use the `period` attribute to assign time periods to
|
||||
## <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
|
||||
@ -998,10 +998,11 @@ exceeds the maintenance, you can manually cancel the downtime.
|
||||
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
|
||||
@ -1020,10 +1021,9 @@ about a fixed downtime window between 23:00 and 24:00. After 24:00
|
||||
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.
|
||||
@ -1479,11 +1479,11 @@ enable sending commands to Icinga 2 through your web interface:
|
||||
# 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).
|
||||
@ -1609,7 +1609,7 @@ in Icinga 2 provided with the `CompatLogger` object.
|
||||
|
||||
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.
|
||||
|
||||
|
||||
@ -23,7 +23,7 @@ for specific use cases already around, for example monitoring Cisco routers.
|
||||
|
||||
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"
|
||||
@ -192,7 +192,7 @@ you want to set up certificates for additional nodes at a later time.
|
||||
|
||||
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.
|
||||
|
||||
@ -201,7 +201,7 @@ 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
|
||||
|
||||
@ -392,12 +392,12 @@ Example:
|
||||
|
||||
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
|
||||
@ -561,10 +561,10 @@ Within each DMZ there are additional check instances also serving interfaces for
|
||||
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
|
||||
|
||||
@ -13,7 +13,7 @@ the rotated performance data files.
|
||||
#### <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
|
||||
|
||||
@ -144,8 +144,8 @@ The `null` keyword can be used to specify an empty value.
|
||||
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:
|
||||
|
||||
@ -156,7 +156,7 @@ 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
|
||||
@ -166,8 +166,8 @@ removed from the dictionary.
|
||||
|
||||
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:
|
||||
|
||||
@ -233,7 +233,7 @@ string(value) | Converts the value to a string.
|
||||
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
|
||||
@ -383,7 +383,7 @@ Global constants can be set using the `const` keyword:
|
||||
|
||||
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
|
||||
@ -406,7 +406,7 @@ In this example the `assign where` condition is a boolean expression which is
|
||||
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
|
||||
@ -573,7 +573,7 @@ Attributes:
|
||||
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.
|
||||
|
||||
@ -16,7 +16,7 @@ For a more verbose output of the Icinga 2 daemon increase the
|
||||
|
||||
## <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`.
|
||||
|
||||
@ -31,7 +31,7 @@ Additionally you can enable the debug log using
|
||||
## <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%
|
||||
@ -62,7 +62,7 @@ Verify the following configuration
|
||||
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
|
||||
|
||||
@ -74,7 +74,7 @@ to `features-enabled` and that the latter is included in [icinga2.conf](#icinga2
|
||||
## <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
|
||||
|
||||
@ -16,7 +16,7 @@ Details can be found in [https://dev.icinga.org/issues/5929].
|
||||
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
|
||||
@ -130,7 +130,7 @@ could also be used.
|
||||
|
||||
### <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).
|
||||
|
||||
@ -185,10 +185,10 @@ requires an equal sign (=) between them.
|
||||
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
|
||||
|
||||
@ -220,7 +220,7 @@ These custom attributes are also used as [command parameters](#command-passing-p
|
||||
|
||||
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.
|
||||
@ -293,7 +293,7 @@ must be set using the `env` attribute in command objects.
|
||||
#### <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
|
||||
|
||||
@ -495,8 +495,8 @@ Icinga 2 doesn't support non-persistent comments.
|
||||
|
||||
### <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
|
||||
@ -614,7 +614,7 @@ object for the escalation itself.
|
||||
|
||||
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
|
||||
|
||||
@ -665,8 +665,8 @@ the value with a single flapping threshold configuration attribute.
|
||||
|
||||
### <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.
|
||||
|
||||
@ -693,7 +693,7 @@ Icinga 2 compat library provides the CompatLogger object which writes the icinga
|
||||
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.
|
||||
|
||||
@ -712,7 +712,7 @@ popular broker modules was implemented for Icinga 2:
|
||||
### <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
|
||||
|
||||
@ -128,7 +128,7 @@ Additional details can be found in the [Icinga 1.x Documentation](http://docs.ic
|
||||
|
||||
## <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.
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user