tyler.durden
/
icinga2
mirror of https://github.com/Icinga/icinga2.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Update documentation. 

Refs #5909
This commit is contained in:
Gunnar Beutner 2014-04-05 14:53:12 +02:00
parent b7cdd1b3a5
commit 226d99dc57
19 changed files with 123 additions and 140 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
doc/2.1-setting-up-icinga-2.md
View File

@ -184,10 +184,10 @@ dictionary.
assign where host.name == "localhost"
}
apply ScheduledDowntime "backup-downtime" {
apply ScheduledDowntime "backup-downtime" to Service {
import "backup-downtime"
assign where service.host == "localhost" && service.short_name == "load"
assign where host.name == "localhost" && service.short_name == "load"
}
apply Service "processes" {

8
doc/3.01-hosts-and-services.md
View File

@ -19,14 +19,14 @@ Here is an example of a host object which defines two child services:
check_command = "hostalive"
}
apply Service "ping4" {
object Service "ping4" {
host_name = "localhost"
check_command = "ping4"
assign where host.name == "my-server1"
}
apply Service "http" {
object Service "http" {
host_name = "localhost"
check_command = "http_ip"
assign where host.name == "my-server1"
}
The example host `my-server1` creates two services which belong to this host:

3
doc/3.02-commands.md
View File

@ -71,9 +71,10 @@ free disk space).
vars.address6 = "::1"
}
apply Service "disk" {
object Service "disk" {
import "generic-service"
host_name = "localhost"
check_command = "disk"
vars.wfree = 10

118
doc/3.03-custom-attributes-runtime-macros.md
View File

@ -78,12 +78,11 @@ default values for some of the latency thresholds and timeouts.
When using the `my-ping` command you can override all or some of the custom
attributes in the service definition like this:
apply Service "ping" {
object Service "ping" {
host_name = "localhost"
check_command = "my-ping"
vars.packets = 10 // Overrides the default value of 5 given in the command
assign where host.name == "my-server1"
}
If a custom attribute isn't defined anywhere an empty value is used and a warning is
@ -94,14 +93,13 @@ emitted to the Icinga 2 log.
>
> By convention every host should have an `address` custom attribute. Hosts
> which have an IPv6 address should also have an `address6` custom attribute.
> This may also be mandatory requirement for using legacy interfaces, user interfaces
> and addons.
> This may also be mandatory requirement for using user interfaces and addons.
### <a id="runtime-custom-attribute-env-vars"></a> Runtime Custom Attributes as Environment Variables
TODO
The `env` command object attribute requires a list of environment variables with values calculated
The `env` command object attribute specifies a list of environment variables with values calculated
from either runtime macros or custom attributes which should be exported as environment variables
prior to executing the command.
@ -114,36 +112,16 @@ when passing credentials to database checks:
command = PluginDir + "/check_mysql -H $address$ -d $db$",
/* default custom attribute values */
vars = {
"MYSQLUSER" = "icinga_check",
"MYSQLPASS" = "1c1ng42r0xx"
mysql_user = "icinga_check",
mysql_pass = "password"
},
env = {
"MYSQLUSER" = "$MYSQLUSER$",
"MYSQLPASS" = "$MYSQLPASS$"
MYSQLUSER = "$mysql_user$",
MYSQLPASS = "$mysql_pass$"
}
}
### <a id="configuration-macros"></a> Configuration Macros
Icinga 2 allows you to define constants which can be used in a limited
scope. For example, constant expressions can reference a pre-defined global constant
variable and calculate a value for the service check interval.
Example:
const MyCheckInterval = 10m
...
{
check_interval = MyCheckInterval / 2.5
}
More details in the chapter [Constant Expressions](#constant-expressions).
## <a id="runtime-macros"></a> Runtime Macros
Next to custom attributes there are additional runtime macros made available by Icinga 2.
@ -156,25 +134,25 @@ external commands).
The following host custom attributes are available in all commands that are executed for
hosts or services:
Name | Description
-----------------------|--------------
host.name | The name of the host object.
host.displayname | The value of the `display_name` attribute.
host.state | The host's current state. Can be one of `UNREACHABLE`, `UP` and `DOWN`.
host.stateid | The host's current state. Can be one of `0` (up), `1` (down) and `2` (unreachable).
host.statetype | The host's current state type. Can be one of `SOFT` and `HARD`.
host.attempt | The current check attempt number.
host.maxattempt | The maximum number of checks which are executed before changing to a hard state.
host.laststate | The host's previous state. Can be one of `UNREACHABLE`, `UP` and `DOWN`.
host.laststateid | The host's previous state. Can be one of `0` (up), `1` (down) and `2` (unreachable).
host.laststatetype | The host's previous state type. Can be one of `SOFT` and `HARD`.
host.laststatechange | The last state change's timestamp.
host.durationsec | The time since the last state change.
host.latency | The host's check latency.
host.executiontime | The host's check execution time.
host.output | The last check's output.
host.perfdata | The last check's performance data.
host.lastcheck | The timestamp when the last check was executed.
Name | Description
---------------------------|--------------
host.name | The name of the host object.
host.displayname | The value of the `display_name` attribute.
host.state | The host's current state. Can be one of `UNREACHABLE`, `UP` and `DOWN`.
host.stateid | The host's current state. Can be one of `0` (up), `1` (down) and `2` (unreachable).
host.statetype | The host's current state type. Can be one of `SOFT` and `HARD`.
host.attempt | The current check attempt number.
host.maxattempt | The maximum number of checks which are executed before changing to a hard state.
host.laststate | The host's previous state. Can be one of `UNREACHABLE`, `UP` and `DOWN`.
host.laststateid | The host's previous state. Can be one of `0` (up), `1` (down) and `2` (unreachable).
host.laststatetype | The host's previous state type. Can be one of `SOFT` and `HARD`.
host.laststatechange | The last state change's timestamp.
host.durationsec | The time since the last state change.
host.latency | The host's check latency.
host.executiontime | The host's check execution time.
host.output | The last check's output.
host.perfdata | The last check's performance data.
host.lastcheck | The timestamp when the last check was executed.
host.totalservices | Number of services associated with the host.
host.totalservicesok | Number of services associated with the host which are in an `OK` state.
host.totalserviceswarning | Number of services associated with the host which are in a `WARNING` state.
@ -186,28 +164,26 @@ hosts or services:
The following service macros are available in all commands that are executed for
services:
Name | Description
-----------------------|--------------
service.description | The short name of the service object.
service.displayname | The value of the `display_name` attribute.
service.checkcommand | This is an alias for the `SERVICEDISPLAYNAME` macro.
service.state | The service's current state. Can be one of `OK`, `WARNING`, `CRITICAL` and `UNKNOWN`.
service.stateid | The service's current state. Can be one of `0` (ok), `1` (warning), `2` (critical) and `3` (unknown).
service.statetype | The service's current state type. Can be one of `SOFT` and `HARD`.
service.attempt | The current check attempt number.
service.maxattempt | The maximum number of checks which are executed before changing to a hard state.
service.laststate | The service's previous state. Can be one of `OK`, `WARNING`, `CRITICAL` and `UNKNOWN`.
service.laststateid | The service's previous state. Can be one of `0` (ok), `1` (warning), `2` (critical) and `3` (unknown).
service.laststatetype | The service's previous state type. Can be one of `SOFT` and `HARD`.
service.laststatechange| The last state change's timestamp.
service.durationsec | The time since the last state change.
service.latency | The service's check latency.
service.executiontime | The service's check execution time.
service.output | The last check's output.
service.perfdata | The last check's performance data.
service.lastcheck | The timestamp when the last check was executed.
Name | Description
------------------------|--------------
service.description | The short name of the service object.
service.displayname | The value of the `display_name` attribute.
service.checkcommand | This is an alias for the `SERVICEDISPLAYNAME` macro.
service.state | The service's current state. Can be one of `OK`, `WARNING`, `CRITICAL` and `UNKNOWN`.
service.stateid | The service's current state. Can be one of `0` (ok), `1` (warning), `2` (critical) and `3` (unknown).
service.statetype | The service's current state type. Can be one of `SOFT` and `HARD`.
service.attempt | The current check attempt number.
service.maxattempt | The maximum number of checks which are executed before changing to a hard state.
service.laststate | The service's previous state. Can be one of `OK`, `WARNING`, `CRITICAL` and `UNKNOWN`.
service.laststateid | The service's previous state. Can be one of `0` (ok), `1` (warning), `2` (critical) and `3` (unknown).
service.laststatetype | The service's previous state type. Can be one of `SOFT` and `HARD`.
service.laststatechange | The last state change's timestamp.
service.durationsec | The time since the last state change.
service.latency | The service's check latency.
service.executiontime | The service's check execution time.
service.output | The last check's output.
service.perfdata | The last check's performance data.
service.lastcheck | The timestamp when the last check was executed.
### <a id="user-runtime-macros"></a> User Runtime Macros

20
doc/3.04-notifications.md
View File

@ -115,13 +115,13 @@ TODO
Use the `apply` keyword to create `Notification` objects for your services:
apply Notification "mail" {
apply Notification "mail" to Service {
import "generic-notification"
notification_command = "mail-notification"
users = [ "icingaadmin" ]
assign where service.short_name == "ping4"
assign where service.name == "ping4"
}
> **Note**
@ -193,15 +193,15 @@ If the problem does not get resolved or acknowledged preventing further notifica
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).
apply Notification "mail" {
apply Notification "mail" to Service {
import "generic-notification"
notification_command = "mail-notification"
users = [ "icingaadmin" ]
assign where service.short_name == "ping4"
assign where service.name == "ping4"
}
apply Notification "escalation-sms-2nd-level" {
apply Notification "escalation-sms-2nd-level" to Service {
import "generic-notification"
notification_command = "sms-notification"
users = [ "icinga-oncall-2nd-level" ]
@ -210,9 +210,11 @@ notified, but only for one hour (`2h` as `end` key for the `times` dictionary).
begin = 30m
end = 1h
}
assign where service.name == "ping4"
}
apply Notification "escalation-sms-1st-level" {
apply Notification "escalation-sms-1st-level" to Service {
import "generic-notification"
notification_command = "sms-notification"
users = [ "icinga-oncall-1st-level" ]
@ -221,6 +223,8 @@ notified, but only for one hour (`2h` as `end` key for the `times` dictionary).
begin = 1h
end = 2h
}
assign where service.name == "ping4"
}
> **Note**
@ -238,12 +242,14 @@ dictionary and set `begin = 15m` as key and value if you want to suppress notifi
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.
apply Notification "mail" {
apply Notification "mail" to Service {
import "generic-notification"
notification_command = "mail-notification"
users = [ "icingaadmin" ]
times.begin = 15m // delay first notification
assign where service.name == "ping4"
}
> **Note**

2
doc/3.06-groups.md
View File

@ -23,7 +23,6 @@ Then add your hosts to this hostgroup
object Host "mssql-srv2" {
groups = [ "windows" ]
vars.mssql_port = 1433
}
}
> **Best Practice**
@ -35,7 +34,6 @@ Then add your hosts to this hostgroup
template Host "windows-mssql-template" {
groups = [ "windows" ]
vars.mssql_port = 1433
}
}
object Host "mssql-srv1" {

6
doc/3.07-time-periods.md
View File

@ -63,10 +63,10 @@ create a new timeperiod named `workhours` defining a work day with
}
}
Assign the timeperiod as `notification_period` to the `Notification`
object then.
Use the `notification_period` attribute to assign time periods to
`Notification` objects:
apply Notification "mail" {
apply Notification "mail" to Host {
import "generic-notification"
notification_command = "mail-notification"

2
doc/3.09-event-handlers.md
View File

@ -12,5 +12,3 @@ events being triggered.
Common use case scenarios are a failing HTTP check requiring an immediate
restart via event command, or if an application is locked and requires
a restart upon detection.

4
doc/3.11-performance-data.md
View File

@ -58,8 +58,8 @@ You can enable the feature using
# icinga2-enable-feature graphite
The `GraphiteWriter` object expects the Graphite Carbon Cache socket listening
at `127.0.0.1` on port `2003` by default.
By default the `GraphiteWriter` object expects the Graphite Carbon Cache to listen at
`127.0.0.1` on port `2003`.
The current naming schema is

2
doc/3.13-compat-logging.md
View File

@ -5,7 +5,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. Futhermore the
`Livestatus` feature uses these logs for answering queries to
historical tables.

1
doc/3.14-check-result-files.md
View File

@ -16,4 +16,3 @@ on-demand in your Icinga 2 objects configuration.
object CheckResultReader "reader" {
spool_dir = "/data/check-results"
}

2
doc/3.15-monitoring-remote-clients.md
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 `oid` custom attribute. A service is created for all hosts which
have the `community` custom attribute set.
have the `community` custom attribute.
apply Service "uptime" {
import "generic-service"

20
doc/4.1-configuration-syntax.md
View File

@ -376,7 +376,7 @@ once they are set.
The `apply` keyword can be used to create new objects which are associated with
another group of objects.
apply Service "ping" {
apply Service "ping" to Host {
import "generic-service"
check_command = "ping4"
@ -388,15 +388,21 @@ 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
type, e.g. for the `Service` type.
Depending on the object type used in the `apply` expression additional local
variables may be available for use in the `where` condition:
Source Type | Target Type | Variables
-----------------|-------------|--------------
Service | Host | host
Dependency | Service | host, service
Notification | Service | host, service
ScheduledDowntime| Service | host, service
Source Type | Target Type | Variables
------------------|-------------|--------------
Service | Host | host
Dependency | Host | host
Dependency | Service | host, service
Notification | Host | host
Notification | Service | host, service
ScheduledDowntime | Host | host
ScheduledDowntime | Service | host, service
> **Note**
>

40
doc/4.3-object-types.md
View File

@ -19,9 +19,24 @@ Attributes:
Name |Description
----------------|----------------
display_name |**Optional.** A short description of the host.
check |**Optional.** A service that is used to determine whether the host is up or down. This must be a service short name of a service that belongs to the host.
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\_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.
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.
authorities |**Optional.** A list of Endpoints on which this host check will be executed in a cluster scenario.
domains |**Optional.** A list of Domains for this host object in a cluster scenario.
### <a id="objecttype-hostgroup"></a> HostGroup
@ -52,9 +67,8 @@ by Icinga 2.
Example:
object Service "localhost-uptime" {
object Service "uptime" {
host_name = "localhost"
name = "uptime"
display_name = "localhost Uptime"
@ -77,25 +91,9 @@ Attributes:
----------------|----------------
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).
display_name |**Optional.** A short description of the service.
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 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 service. 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 service's state changes.
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.
groups |**Optional.** The service groups this service belongs to.
authorities |**Optional.** A list of Endpoints on which this service check will be executed in a cluster scenario.
domains |**Optional.** A list of Domains for this service object in a cluster scenario.
In addition to these attributes you can also use any of the attributes which are also valid for `Host` objects.
### <a id="objecttype-servicegroup"></a> ServiceGroup

3
doc/6.01-downtimes.md
View File

@ -73,7 +73,7 @@ recurring downtimes for services.
Example:
apply ScheduledDowntime "backup-downtime" {
apply ScheduledDowntime "backup-downtime" to Service {
author = "icingaadmin"
comment = "Scheduled downtime for backup"
@ -89,4 +89,3 @@ Example:
assign where "backup" in service.groups
}

17
doc/6.05-domains.md
View File

@ -17,17 +17,20 @@ from the `icinga-node-dmz-1` endpoint.
object Host "dmz-host1" {
import "generic-host"
}
services["dmz-oracledb"] = {
templates = [ "generic-service" ]
domains = [ "dmz-db" ]
authorities = [ "icinga-node-dmz-1", "icinga-node-dmz-2"]
}
object Service "dmz-oracledb" {
import "generic-service"
host_name = "dmz-host1"
domains = [ "dmz-db" ]
authorities = [ "icinga-node-dmz-1", "icinga-node-dmz-2"]
}
object Domain "dmz-db" {
acl = {
icinga-node-dmz-1 = DomainPrivReadOnly
icinga-node-dmz-2 = DomainPrivReadWrite
"icinga-node-dmz-1" = DomainPrivReadOnly
"icinga-node-dmz-2" = DomainPrivReadWrite
}
}

2
doc/6.06-dependencies.md
View File

@ -36,7 +36,7 @@ be suppressed. This is achieved by setting the `disable_checks` attribute to `tr
assign where host.vars.address
}
apply Dependency "internet" {
apply Dependency "internet" to Service {
parent_host = "dsl-router"
disable_checks = true

7
doc/8-differences-between-icinga-1x-and-2.md
View File

@ -114,7 +114,9 @@ services) like in Icinga 1.x but directly after their type definition.
service_description ping4
}
object Service "localhost-ping4" { }
object Service "ping4" {
host_name = "localhost"
}
## <a id="differences-1x-2-templates"></a> Templates
@ -153,7 +155,7 @@ requires an equal sign (=) between them.
> **Note**
>
> 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.
> 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).
@ -212,7 +214,6 @@ TODO
> If you are planning to access custom variables as runtime macros you may access
> them with `_HOST`name as known from Icinga 1.x
## <a id="differences-1x-2-host-service-relation"></a> Host Service Relation
In Icinga 1.x a service object is associated with a host by defining the

2
doc/9-vagrant-demo-vm.md
View File

@ -21,8 +21,6 @@ The Vagrant VM is based on CentOS 6.4 and uses the official Icinga 2 RPM
packages from `packages.icinga.org`. The check plugins are installed from
EPEL providing RPMs with sources from the Monitoring Plugins project.
SSH login is available using `vagrant ssh`.
## <a id="vagrant-demo-guis"></a> Demo GUIs
In addition to installing Icinga 2 the Vagrant puppet modules also install the