From 863af5afb4d49f683a497ba503c0a2cb159b6f0d Mon Sep 17 00:00:00 2001 From: Michael Friedrich Date: Mon, 8 Apr 2019 14:08:14 +0200 Subject: [PATCH] Docs: Update version specific changes for 2.11 - Notification commands 2.7 dropped, reference to MTAs added - Sysconfig variable locations - Version bumps --- doc/03-monitoring-basics.md | 53 ++++------------------------- doc/06-distributed-monitoring.md | 14 ++++---- doc/08-advanced-topics.md | 2 +- doc/11-cli-commands.md | 24 ++++++------- doc/16-upgrading-icinga-2.md | 3 +- doc/17-language-reference.md | 24 +++++++++---- doc/18-library-reference.md | 58 ++++++++++++++++---------------- 7 files changed, 74 insertions(+), 104 deletions(-) diff --git a/doc/03-monitoring-basics.md b/doc/03-monitoring-basics.md index 3c44b67c5..539987726 100644 --- a/doc/03-monitoring-basics.md +++ b/doc/03-monitoring-basics.md @@ -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 - -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 diff --git a/doc/06-distributed-monitoring.md b/doc/06-distributed-monitoring.md index 7064e6fb7..00a91157b 100644 --- a/doc/06-distributed-monitoring.md +++ b/doc/06-distributed-monitoring.md @@ -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 -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 \ diff --git a/doc/08-advanced-topics.md b/doc/08-advanced-topics.md index a7acb9591..f0f154525 100644 --- a/doc/08-advanced-topics.md +++ b/doc/08-advanced-topics.md @@ -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) diff --git a/doc/11-cli-commands.md b/doc/11-cli-commands.md index 886dff5ea..5b58c4c52 100644 --- a/doc/11-cli-commands.md +++ b/doc/11-cli-commands.md @@ -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 [] @@ -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 [] @@ -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 [] @@ -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 [] @@ -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 [] @@ -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 [] @@ -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 [] @@ -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 [] @@ -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 [] @@ -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 [] diff --git a/doc/16-upgrading-icinga-2.md b/doc/16-upgrading-icinga-2.md index 2b6d3a340..8ff710ec1 100644 --- a/doc/16-upgrading-icinga-2.md +++ b/doc/16-upgrading-icinga-2.md @@ -1,6 +1,7 @@ # Upgrading Icinga 2 -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 diff --git a/doc/17-language-reference.md b/doc/17-language-reference.md index 740d775d2..9a6060238 100644 --- a/doc/17-language-reference.md +++ b/doc/17-language-reference.md @@ -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 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 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 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 + 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 + 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 @@ -1229,4 +1239,4 @@ object Host "localhost" { vars.@include = "some cmdb export field" } -``` \ No newline at end of file +``` diff --git a/doc/18-library-reference.md b/doc/18-library-reference.md index 9b560eda1..91f2fff74 100644 --- a/doc/18-library-reference.md +++ b/doc/18-library-reference.md @@ -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". */ -``` \ No newline at end of file +```