Merge pull request #7093 from Icinga/feature/docs-2-11

Docs: Update version specific changes for 2.11
This commit is contained in:
Michael Friedrich 2019-04-08 14:52:58 +02:00 committed by GitHub
commit e69e72d6af
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
7 changed files with 74 additions and 104 deletions

View File

@ -2273,54 +2273,13 @@ defaults can always be overwritten locally.
>
> This example requires the `mail` binary installed on the Icinga 2
> master.
#### Notification Commands in 2.7 <a id="notification-command-2-7"></a>
Icinga 2 v2.7.0 introduced new notification scripts which support both
environment variables and command line parameters.
Therefore the `NotificationCommand` objects inside the [commands.conf](04-configuring-icinga-2.md#commands-conf)
and `Notification` apply rules inside the [notifications.conf](04-configuring-icinga-2.md#notifications-conf)
configuration files have been updated. Your configuration needs to be
updated next to the notification scripts themselves.
> **Note**
>
> Several parameters have been changed. Please review the notification
> script parameters and configuration objects before updating your production
> environment.
The safest way is to incorporate the configuration updates from
v2.7.0 inside the [commands.conf](04-configuring-icinga-2.md#commands-conf) and [notifications.conf](04-configuring-icinga-2.md#notifications-conf)
configuration files.
A quick-fix is shown below:
```
@@ -5,7 +5,8 @@ object NotificationCommand "mail-host-notification" {
env = {
NOTIFICATIONTYPE = "$notification.type$"
- HOSTALIAS = "$host.display_name$"
+ HOSTNAME = "$host.name$"
+ HOSTDISPLAYNAME = "$host.display_name$"
HOSTADDRESS = "$address$"
HOSTSTATE = "$host.state$"
LONGDATETIME = "$icinga.long_date_time$"
@@ -22,8 +23,9 @@ object NotificationCommand "mail-service-notification" {
env = {
NOTIFICATIONTYPE = "$notification.type$"
- SERVICEDESC = "$service.name$"
- HOSTALIAS = "$host.display_name$"
+ SERVICENAME = "$service.name$"
+ HOSTNAME = "$host.name$"
+ HOSTDISPLAYNAME = "$host.display_name$"
HOSTADDRESS = "$address$"
SERVICESTATE = "$service.state$"
LONGDATETIME = "$icinga.long_date_time$"
```
> Depending on the distribution, you need a local mail transfer
> agent (MTA) such as Postfix, Exim or Sendmail in order
> to send emails.
>
> These tools virtually provide the `mail` binary executed
> by the notification scripts below.
#### mail-host-notification <a id="mail-host-notification"></a>

View File

@ -203,15 +203,15 @@ Prior to upgrading, make sure to plan a maintenance window.
The Icinga project aims to allow the following compatibility:
```
master (2.9) >= satellite (2.8) >= clients (2.7)
master (2.11) >= satellite (2.10) >= clients (2.9)
```
Older client versions may work, but there's no guarantee. Always keep in mind that
older versions are out of support and can contain bugs.
In terms of an upgrade, ensure that the master is upgraded first, then
involved satellites, and last the Icinga 2 clients. If you are on v2.8
currently, first upgrade the master instance(s) to 2.9, and then proceed
involved satellites, and last the Icinga 2 clients. If you are on v2.10
currently, first upgrade the master instance(s) to 2.11, and then proceed
with the satellites. Things are getting easier with any sort of automation
tool (Puppet, Ansible, etc.).
@ -332,7 +332,7 @@ and sign the request.
> **Note**
>
> Icinga 2 v2.8 adds the possibility to forward signing requests on a satellite
> Icinga 2 v2.8 added the possibility to forward signing requests on a satellite
> to the master node. This is called `CA Proxy` in blog posts and design drafts.
> This functionality helps with the setup of [three level clusters](#06-distributed-monitoring.md#distributed-monitoring-scenarios-master-satellite-client)
> and more.
@ -2561,7 +2561,7 @@ with automating setups (setup, certificates, configuration).
### Certificate Auto-Renewal <a id="distributed-monitoring-certificate-auto-renewal"></a>
Icinga 2 v2.8+ adds the possibility that nodes request certificate updates
Icinga 2 v2.8+ added the possibility that nodes request certificate updates
on their own. If their expiration date is soon enough, they automatically
renew their already signed certificate by sending a signing request to the
parent node. You'll also see a message in the logs if certificate renewal
@ -2955,9 +2955,9 @@ Pass the following details to the `node setup` CLI command:
> **Note**
>
> The `master_host` parameter is deprecated and will be removed in 2.10.0. Please use `--parent_host` instead.
> The `master_host` parameter is deprecated and will be removed. Please use `--parent_host` instead.
Example for Icinga 2 v2.9:
Example:
```
[root@icinga2-client1.localdomain /]# icinga2 node setup --ticket ead2d570e18c78abf285d6b85524970a0f69c22d \

View File

@ -722,7 +722,7 @@ to connect to the REST API.
```
$ ICINGA2_API_PASSWORD=icinga icinga2 console --connect 'https://root@localhost:5665/'
Icinga 2 (version: v2.8.1-373-g4bea6d25c)
Icinga 2 (version: v2.11.0)
<1> => globals.state_to_string(1)
"Warning"
<2> => state_to_string(2)

View File

@ -13,7 +13,7 @@ options.
```
# icinga2
icinga2 - The Icinga 2 network monitoring daemon (version: v2.8.0)
icinga2 - The Icinga 2 network monitoring daemon (version: v2.11.0)
Usage:
icinga2 <command> [<arguments>]
@ -141,7 +141,7 @@ More details in the [Icinga 2 API](12-icinga2-api.md#icinga2-api-setup) chapter.
```
# icinga2 api --help
icinga2 - The Icinga 2 network monitoring daemon (version: v2.8.0)
icinga2 - The Icinga 2 network monitoring daemon (version: v2.11.0)
Usage:
icinga2 <command> [<arguments>]
@ -176,7 +176,7 @@ chapter. This CLI command is available since v2.8.
```
# icinga2 ca --help
icinga2 - The Icinga 2 network monitoring daemon (version: v2.8.0)
icinga2 - The Icinga 2 network monitoring daemon (version: v2.11.0)
Usage:
icinga2 <command> [<arguments>]
@ -210,7 +210,7 @@ e.g. to test [functions](17-language-reference.md#functions) in your local sandb
```
$ icinga2 console
Icinga 2 (version: v2.8.0)
Icinga 2 (version: v2.11.0)
<1> => function test(name) {
<1> .. log("Hello " + name)
<1> .. }
@ -225,7 +225,7 @@ Further usage examples can be found in the [library reference](18-library-refere
```
# icinga2 console --help
icinga2 - The Icinga 2 network monitoring daemon (version: v2.8.0)
icinga2 - The Icinga 2 network monitoring daemon (version: v2.11.0)
Usage:
icinga2 console [<arguments>]
@ -293,7 +293,7 @@ Here's an example:
```
$ ICINGA2_API_PASSWORD=icinga icinga2 console --connect 'https://root@localhost:5665/'
Icinga 2 (version: v2.8.0)
Icinga 2 (version: v2.11.0)
<1> =>
```
@ -362,7 +362,7 @@ Furthermore it allows to run the [configuration validation](11-cli-commands.md#c
```
# icinga2 daemon --help
icinga2 - The Icinga 2 network monitoring daemon (version: v2.8.0)
icinga2 - The Icinga 2 network monitoring daemon (version: v2.11.0)
Usage:
icinga2 daemon [<arguments>]
@ -443,7 +443,7 @@ nodes in a [distributed monitoring](06-distributed-monitoring.md#distributed-mon
```
# icinga2 node --help
icinga2 - The Icinga 2 network monitoring daemon (version: v2.8.0)
icinga2 - The Icinga 2 network monitoring daemon (version: v2.11.0)
Usage:
icinga2 <command> [<arguments>]
@ -486,7 +486,7 @@ More information can be found in the [troubleshooting](15-troubleshooting.md#tro
```
# icinga2 object --help
icinga2 - The Icinga 2 network monitoring daemon (version: v2.7.1-196-g23e8a6253; debug)
icinga2 - The Icinga 2 network monitoring daemon (version: v2.11.0)
Usage:
icinga2 <command> [<arguments>]
@ -528,7 +528,7 @@ You will need them in the [distributed monitoring chapter](06-distributed-monito
```
# icinga2 pki --help
icinga2 - The Icinga 2 network monitoring daemon (version: v2.8.0)
icinga2 - The Icinga 2 network monitoring daemon (version: v2.11.0)
Usage:
icinga2 <command> [<arguments>]
@ -572,7 +572,7 @@ This is only a tool to collect information to help others help you, it will not
```
# icinga2 troubleshoot --help
icinga2 - The Icinga 2 network monitoring daemon (version: v2.8.0)
icinga2 - The Icinga 2 network monitoring daemon (version: v2.11.0)
Usage:
icinga2 troubleshoot [<arguments>]
@ -609,7 +609,7 @@ Lists all configured variables (constants) in a similar fashion like [object lis
```
# icinga2 variable --help
icinga2 - The Icinga 2 network monitoring daemon (version: v2.8.0; debug)
icinga2 - The Icinga 2 network monitoring daemon (version: v2.11.0)
Usage:
icinga2 <command> [<arguments>]

View File

@ -1,6 +1,7 @@
# Upgrading Icinga 2 <a id="upgrading-icinga-2"></a>
Upgrading Icinga 2 is usually quite straightforward. Ordinarily the only manual steps involved
Upgrading Icinga 2 is usually quite straightforward.
Ordinarily the only manual steps involved
are scheme updates for the IDO database.
Specific version upgrades are described below. Please note that version

View File

@ -480,7 +480,7 @@ once they are set.
Icinga 2 provides a number of special global constants. These include directory paths, global configuration
and runtime parameters for the application version and (build) platform.
Directory paths:
#### Directory Path Constants <a id="icinga-constants-director-path"></a>
Constant | Description
--------------------|-------------------
@ -492,7 +492,7 @@ SpoolDir |**Read-only.** Spool directory for certain data outputs. Us
InitRunDir |**Read-only.** Directory for PID files and sockets in daemon mode. Usually set to `/run/icinga2`.
ZonesDir |**Read-only.** Contains the path of the zones.d directory. Defaults to `ConfigDir + "/zones.d"`.
Global configuration:
#### Global Configuration Constants <a id="icinga-constants-global-config"></a>
Constant | Description
--------------------|-------------------
@ -506,7 +506,7 @@ MaxConcurrentChecks |**Read-write.** The number of max checks run simultaneously
ApiBindHost |**Read-write.** Overrides the default value for the ApiListener `bind_host` attribute. Not set by default.
ApiBindPort |**Read-write.** Overrides the default value for the ApiListener `bind_port` attribute. Not set by default.
Application runtime details:
#### Application Runtime Constants <a id="icinga-constants-application-runtime"></a>
Constant | Description
--------------------|-------------------
@ -519,6 +519,8 @@ BuildCompilerVersion|**Read-only.** The version of the compiler Icinga was built
BuildHostName |**Read-only.** The name of the host Icinga was built on, e.g. `acheron`.
ApplicationVersion |**Read-only.** The application version, e.g. `2.9.0`.
#### Additional Constants <a id="icinga-constants-additional"></a>
Writable constants can be specified on the CLI using the `--define/-D` parameter.
> **Note for v2.10+**
@ -546,15 +548,23 @@ SysconfDir |**Read-only.** Contains the path of the sysconf directory.
LocalStateDir |**Read-only.** Contains the path of the local state directory. Defaults to `PrefixDir + "/var"`.
RunDir |**Read-only.** Contains the path of the run directory. Defaults to `LocalStateDir + "/run"`.
#### Advanced Constants and Variables <a id="icinga-constants-advanced"></a>
Advanced runtime constants. Please only use them if advised by support or developers.
Variable | Description
---------------------------|-------------------
EventEngine |**Read-write.** The name of the socket event engine, can be `poll` or `epoll`. The epoll interface is only supported on Linux.
AttachDebugger |**Read-write.** Whether to attach a debugger when Icinga 2 crashes. Defaults to `false`.
ICINGA2\_RLIMIT\_FILES |**Read-write.** Defines the resource limit for RLIMIT_NOFILE that should be set at start-up. Value cannot be set lower than the default `16 * 1024`. 0 disables the setting. Set in Icinga 2 sysconfig.
ICINGA2\_RLIMIT\_PROCESSES |**Read-write.** Defines the resource limit for RLIMIT_NPROC that should be set at start-up. Value cannot be set lower than the default `16 * 1024`. 0 disables the setting. Set in Icinga 2 sysconfig.
ICINGA2\_RLIMIT\_STACK |**Read-write.** Defines the resource limit for RLIMIT_STACK that should be set at start-up. Value cannot be set lower than the default `256 * 1024`. 0 disables the setting. Set in Icinga 2 sysconfig.
Advanced sysconfig environment variables, defined in `/etc/sysconfig/icinga2` (RHEL/SLES) or `/etc/default/icinga2` (Debian/Ubuntu).
Variable | Description
---------------------------|-------------------
ICINGA2\_RLIMIT\_FILES |**Read-write.** Defines the resource limit for `RLIMIT_NOFILE` that should be set at start-up. Value cannot be set lower than the default `16 * 1024`. 0 disables the setting. Set in Icinga 2 sysconfig.
ICINGA2\_RLIMIT\_PROCESSES |**Read-write.** Defines the resource limit for `RLIMIT_NPROC` that should be set at start-up. Value cannot be set lower than the default `16 * 1024`. 0 disables the setting. Set in Icinga 2 sysconfig.
ICINGA2\_RLIMIT\_STACK |**Read-write.** Defines the resource limit for `RLIMIT_STACK` that should be set at start-up. Value cannot be set lower than the default `256 * 1024`. 0 disables the setting. Set in Icinga 2 sysconfig.
## Apply <a id="apply"></a>
@ -1229,4 +1239,4 @@ object Host "localhost" {
vars.@include = "some cmdb export field"
}
```
```

View File

@ -32,7 +32,7 @@ Example for string values:
```
$ icinga2 console
Icinga 2 (version: v2.7.0)
Icinga 2 (version: v2.11.0)
<1> => host.vars.os_type = "Linux/Unix"
null
<2> => regex("^Linux", host.vars.os_type)
@ -45,7 +45,7 @@ Example for an array of string values:
```
$ icinga2 console
Icinga 2 (version: v2.7.0)
Icinga 2 (version: v2.11.0)
<1> => host.vars.databases = [ "db-prod1", "db-prod2", "db-dev" ]
null
<2> => regex("^db-prod\\d+", host.vars.databases, MatchAny)
@ -74,7 +74,7 @@ Example for string values:
```
$ icinga2 console
Icinga 2 (version: v2.7.0)
Icinga 2 (version: v2.11.0)
<1> => var name = "db-prod-sfo-657"
null
<2> => match("*prod-sfo*", name)
@ -87,7 +87,7 @@ Example for an array of string values:
```
$ icinga2 console
Icinga 2 (version: v2.7.0-28)
Icinga 2 (version: v2.11.0-28)
<1> => host.vars.application_types = [ "web-wp", "web-rt", "db-local" ]
null
<2> => match("web-*", host.vars.application_types, MatchAll)
@ -116,7 +116,7 @@ Example for a single IP address:
```
$ icinga2 console
Icinga 2 (version: v2.7.0)
Icinga 2 (version: v2.11.0)
<1> => host.address = "192.168.56.101"
null
<2> => cidr_match("192.168.56.0/24", host.address)
@ -129,7 +129,7 @@ Example for an array of IP addresses:
```
$ icinga2 console
Icinga 2 (version: v2.7.0)
Icinga 2 (version: v2.11.0)
<1> => host.vars.vhost_ips = [ "192.168.56.101", "192.168.56.102", "10.0.10.99" ]
null
<2> => cidr_match("192.168.56.0/24", host.vars.vhost_ips, MatchAll)
@ -162,7 +162,7 @@ Example:
```
$ icinga2 console
Icinga 2 (version: v2.7.0)
Icinga 2 (version: v2.11.0)
<1> => range(5)
[ 0.000000, 1.000000, 2.000000, 3.000000, 4.000000 ]
<2> => range(2,4)
@ -190,7 +190,7 @@ Example:
```
$ icinga2 console
Icinga 2 (version: v2.7.0)
Icinga 2 (version: v2.11.0)
<1> => host.groups = [ "linux-servers", "db-servers" ]
null
<2> => host.groups.len()
@ -220,7 +220,7 @@ Returns an array containing all unique elements from the specified arrays.
Example:
```
$ icinga2 console
Icinga 2 (version: v2.7.0)
Icinga 2 (version: v2.11.0)
<1> => var dev_notification_groups = [ "devs", "slack" ]
null
<2> => var host_notification_groups = [ "slack", "noc" ]
@ -244,7 +244,7 @@ Example:
```
$ icinga2 console
Icinga 2 (version: v2.7.0)
Icinga 2 (version: v2.11.0)
<1> => var dev_notification_groups = [ "devs", "slack" ]
null
<2> => var host_notification_groups = [ "slack", "noc" ]
@ -270,7 +270,7 @@ Example:
```
$ icinga2 console
Icinga 2 (version: v2.7.0)
Icinga 2 (version: v2.11.0)
<1> => host.vars.disks["/"] = {}
null
<2> => host.vars.disks["/var"] = {}
@ -302,7 +302,7 @@ Example:
```
$ icinga2 console
Icinga 2 (version: v2.7.0)
Icinga 2 (version: v2.11.0)
<1> => 5.to_string()
"5"
<2> => false.to_string()
@ -331,7 +331,7 @@ Example:
```
$ icinga2 console
Icinga 2 (version: v2.7.0)
Icinga 2 (version: v2.11.0)
<1> => number(false)
0.000000
<2> => number("78")
@ -352,7 +352,7 @@ Example:
```
$ icinga2 console
Icinga 2 (version: v2.7.0)
Icinga 2 (version: v2.11.0)
<1> => bool(1)
true
<2> => bool(0)
@ -371,7 +371,7 @@ Returns a random value between 0 and RAND\_MAX (as defined in stdlib.h).
```
$ icinga2 console
Icinga 2 (version: v2.7.0)
Icinga 2 (version: v2.11.0)
<1> => random()
1263171996.000000
<2> => random()
@ -403,7 +403,7 @@ Example:
```
$ icinga2 console
Icinga 2 (version: v2.7.0)
Icinga 2 (version: v2.11.0)
<1> => log(LogCritical, "Console", "First line")
critical/Console: First line
null
@ -428,7 +428,7 @@ Example:
```
$ icinga2 console
Icinga 2 (version: v2.7.0)
Icinga 2 (version: v2.11.0)
<1> => typeof(3) == Number
true
<2> => typeof("str") == String
@ -455,7 +455,7 @@ Example:
```
$ icinga2 console
Icinga 2 (version: v2.7.0)
Icinga 2 (version: v2.11.0)
<1> => get_time()
1480072135.633008
<2> => get_time()
@ -476,7 +476,7 @@ Example:
```
$ icinga2 console
Icinga 2 (version: v2.7.0)
Icinga 2 (version: v2.11.0)
<1> => var pd = "'time'=1480074205.197363;;;"
null
<2> => parse_performance_data(pd)
@ -527,7 +527,7 @@ Example:
```
$ icinga2 console
Icinga 2 (version: v2.7.0)
Icinga 2 (version: v2.11.0)
<1> => var path = "/etc/icinga2/scripts/xmpp-notification.pl"
null
<2> => dirname(path)
@ -548,7 +548,7 @@ Example:
```
$ icinga2 console
Icinga 2 (version: v2.7.0)
Icinga 2 (version: v2.11.0)
<1> => var path = "/etc/icinga2/scripts/xmpp-notification.pl"
null
<2> => basename(path)
@ -569,7 +569,7 @@ Example:
```
$ icinga2 console
Icinga 2 (version: v2.7.0)
Icinga 2 (version: v2.11.0)
<1> => var path = "/etc/icinga2/scripts/xmpp-notification.pl"
null
<2> => path_exists(path)
@ -593,7 +593,7 @@ and `GlobDirectory` constants. The default value is `GlobFile | GlobDirectory`.
```
$ icinga2 console
Icinga 2 (version: v2.7.0)
Icinga 2 (version: v2.11.0)
<1> => var pathSpec = "/etc/icinga2/conf.d/*.conf"
null
<2> => glob(pathSpec)
@ -617,7 +617,7 @@ and `GlobDirectory` constants. The default value is `GlobFile | GlobDirectory`.
```
$ icinga2 console
Icinga 2 (version: v2.7.0)
Icinga 2 (version: v2.11.0)
<1> => var path = "/etc/icinga2/zones.d/"
null
<2> => var pattern = "*.conf"
@ -640,7 +640,7 @@ Example:
```
$ icinga2 console
Icinga 2 (version: v2.7.0)
Icinga 2 (version: v2.11.0)
<1> => escape_shell_arg("'$host.name$' '$service.name$'")
"''\\''$host.name$'\\'' '\\''$service.name$'\\'''"
```
@ -659,7 +659,7 @@ Example:
```
$ icinga2 console
Icinga 2 (version: v2.7.0)
Icinga 2 (version: v2.11.0)
<1> => escape_shell_cmd("/bin/echo 'shell test' $ENV")
"/bin/echo 'shell test' \\$ENV"
```
@ -788,7 +788,7 @@ which fetches the `disk` service object from the current Icinga 2 node:
```
$ ICINGA2_API_PASSWORD=icinga icinga2 console --connect 'https://root@localhost:5665/'
Icinga 2 (version: v2.7.0)
Icinga 2 (version: v2.11.0)
<1> => get_service(NodeName, "disk")
<2> => get_service(NodeName, "disk").__name
@ -815,7 +815,7 @@ which fetches all service objects from the current Icinga 2 node:
```
$ ICINGA2_API_PASSWORD=icinga icinga2 console --connect 'https://root@localhost:5665/'
Icinga 2 (version: v2.7.0)
Icinga 2 (version: v2.11.0)
<1> => get_services(NodeName).map(s => s.name)
[ "disk", "disk /", "http", "icinga", "load", "ping4", "ping6", "procs", "ssh", "users" ]
@ -1912,4 +1912,4 @@ Example:
```
var s = DateTime(2016, 4, 21).to_string() /* Sets s to "2016-04-21 00:00:00 +0200". */
```
```