Update documentation.

Fixes #6359

Signed-off-by: Gunnar Beutner <gunnar@beutner.name>
This commit is contained in:
Wolfgang Nieder 2014-05-29 16:54:57 +02:00 committed by Gunnar Beutner
parent 24a884f79b
commit 36c71d69bd
7 changed files with 61 additions and 61 deletions

View File

@ -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.

View File

@ -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

View File

@ -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

View File

@ -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.

View File

@ -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

View File

@ -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

View File

@ -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.