diff --git a/doc/2.1-setting-up-icinga-2.md b/doc/2.1-setting-up-icinga-2.md index 1db541be2..adb825924 100644 --- a/doc/2.1-setting-up-icinga-2.md +++ b/doc/2.1-setting-up-icinga-2.md @@ -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" { diff --git a/doc/3.01-hosts-and-services.md b/doc/3.01-hosts-and-services.md index 9d308ea45..eec41e50a 100644 --- a/doc/3.01-hosts-and-services.md +++ b/doc/3.01-hosts-and-services.md @@ -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: diff --git a/doc/3.02-commands.md b/doc/3.02-commands.md index b9336c859..272b7e23a 100644 --- a/doc/3.02-commands.md +++ b/doc/3.02-commands.md @@ -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 diff --git a/doc/3.03-custom-attributes-runtime-macros.md b/doc/3.03-custom-attributes-runtime-macros.md index 9103e065b..27186daad 100644 --- a/doc/3.03-custom-attributes-runtime-macros.md +++ b/doc/3.03-custom-attributes-runtime-macros.md @@ -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. ### 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$" } } -### 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). - - - ## 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. ### User Runtime Macros diff --git a/doc/3.04-notifications.md b/doc/3.04-notifications.md index 2fefea44d..56e0bae7e 100644 --- a/doc/3.04-notifications.md +++ b/doc/3.04-notifications.md @@ -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** diff --git a/doc/3.06-groups.md b/doc/3.06-groups.md index 252674947..cdf3ed074 100644 --- a/doc/3.06-groups.md +++ b/doc/3.06-groups.md @@ -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" { diff --git a/doc/3.07-time-periods.md b/doc/3.07-time-periods.md index 928d1339e..e7ce33485 100644 --- a/doc/3.07-time-periods.md +++ b/doc/3.07-time-periods.md @@ -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" diff --git a/doc/3.09-event-handlers.md b/doc/3.09-event-handlers.md index 54bddb59d..f6f0b623e 100644 --- a/doc/3.09-event-handlers.md +++ b/doc/3.09-event-handlers.md @@ -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. - - diff --git a/doc/3.11-performance-data.md b/doc/3.11-performance-data.md index df9498219..5d9fb5ab3 100644 --- a/doc/3.11-performance-data.md +++ b/doc/3.11-performance-data.md @@ -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 diff --git a/doc/3.13-compat-logging.md b/doc/3.13-compat-logging.md index 4ef9ef7a3..0028d09b7 100644 --- a/doc/3.13-compat-logging.md +++ b/doc/3.13-compat-logging.md @@ -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. diff --git a/doc/3.14-check-result-files.md b/doc/3.14-check-result-files.md index c02934ca1..b27f06cc5 100644 --- a/doc/3.14-check-result-files.md +++ b/doc/3.14-check-result-files.md @@ -16,4 +16,3 @@ on-demand in your Icinga 2 objects configuration. object CheckResultReader "reader" { spool_dir = "/data/check-results" } - diff --git a/doc/3.15-monitoring-remote-clients.md b/doc/3.15-monitoring-remote-clients.md index 3c947c494..08542d7d9 100644 --- a/doc/3.15-monitoring-remote-clients.md +++ b/doc/3.15-monitoring-remote-clients.md @@ -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" diff --git a/doc/4.1-configuration-syntax.md b/doc/4.1-configuration-syntax.md index 529a74fdb..d2d8b3ffb 100644 --- a/doc/4.1-configuration-syntax.md +++ b/doc/4.1-configuration-syntax.md @@ -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** > diff --git a/doc/4.3-object-types.md b/doc/4.3-object-types.md index 808d5138a..d2dcdaf4e 100644 --- a/doc/4.3-object-types.md +++ b/doc/4.3-object-types.md @@ -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. ### 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. ### ServiceGroup diff --git a/doc/6.01-downtimes.md b/doc/6.01-downtimes.md index 79a0ea672..6e3df04d3 100644 --- a/doc/6.01-downtimes.md +++ b/doc/6.01-downtimes.md @@ -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 } - diff --git a/doc/6.05-domains.md b/doc/6.05-domains.md index 4e16ffcae..27122ccd7 100644 --- a/doc/6.05-domains.md +++ b/doc/6.05-domains.md @@ -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 } } diff --git a/doc/6.06-dependencies.md b/doc/6.06-dependencies.md index 929a2bad0..3dbaf5579 100644 --- a/doc/6.06-dependencies.md +++ b/doc/6.06-dependencies.md @@ -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 diff --git a/doc/8-differences-between-icinga-1x-and-2.md b/doc/8-differences-between-icinga-1x-and-2.md index 846d02a0a..b475abe21 100644 --- a/doc/8-differences-between-icinga-1x-and-2.md +++ b/doc/8-differences-between-icinga-1x-and-2.md @@ -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" + } ## 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 - ## Host Service Relation In Icinga 1.x a service object is associated with a host by defining the diff --git a/doc/9-vagrant-demo-vm.md b/doc/9-vagrant-demo-vm.md index 9564aa76c..27b2ea59e 100644 --- a/doc/9-vagrant-demo-vm.md +++ b/doc/9-vagrant-demo-vm.md @@ -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`. - ## Demo GUIs In addition to installing Icinga 2 the Vagrant puppet modules also install the