From dc2992443f14eb6c1118d5ab202d4fc8913d70bc Mon Sep 17 00:00:00 2001 From: Michael Friedrich Date: Wed, 23 Nov 2016 15:33:28 +0100 Subject: [PATCH] Deprecate the client 'bottom up' mode w/ node update-config This includes deprecation warnings and migration documentation. fixes #13255 --- doc/11-cli-commands.md | 421 ++++++++++++---------- doc/6-distributed-monitoring.md | 250 ++++++++++++- icinga-app/icinga.cpp | 2 +- lib/cli/clicommand.cpp | 19 +- lib/cli/clicommand.hpp | 1 + lib/cli/nodeaddcommand.cpp | 5 + lib/cli/nodeaddcommand.hpp | 1 + lib/cli/nodeblackandwhitelistcommand.cpp | 5 + lib/cli/nodeblackandwhitelistcommand.hpp | 1 + lib/cli/nodelistcommand.cpp | 5 + lib/cli/nodelistcommand.hpp | 1 + lib/cli/noderemovecommand.cpp | 5 + lib/cli/noderemovecommand.hpp | 1 + lib/cli/nodesetcommand.cpp | 5 + lib/cli/nodesetcommand.hpp | 1 + lib/cli/nodeupdateconfigcommand.cpp | 5 + lib/cli/nodeupdateconfigcommand.hpp | 1 + lib/cli/repositoryclearchangescommand.cpp | 5 + lib/cli/repositoryclearchangescommand.hpp | 1 + lib/cli/repositorycommitcommand.cpp | 5 + lib/cli/repositorycommitcommand.hpp | 1 + lib/cli/repositoryobjectcommand.cpp | 5 + lib/cli/repositoryobjectcommand.hpp | 1 + 23 files changed, 546 insertions(+), 201 deletions(-) diff --git a/doc/11-cli-commands.md b/doc/11-cli-commands.md index 93019e86c..75a6d1266 100644 --- a/doc/11-cli-commands.md +++ b/doc/11-cli-commands.md @@ -12,29 +12,30 @@ Run `icinga2` without any arguments to get a list of all available global options. # icinga2 - icinga2 - The Icinga 2 network monitoring daemon (version: v2.5.0) - + icinga2 - The Icinga 2 network monitoring daemon (version: v2.6.0) + Usage: icinga2 [] - + Supported commands: + * api setup (setup for api) * console (Icinga console) * daemon (starts Icinga 2) * feature disable (disables specified feature) * feature enable (enables specified feature) * feature list (lists all enabled features) - * node add (add node) - * node blacklist add (adds a new blacklist filter) - * node blacklist list (lists all blacklist filters) - * node blacklist remove (removes a blacklist filter) - * node list (lists all nodes) - * node remove (removes node) - * node set (set node attributes) + * node add (add node) (DEPRECATED) + * node blacklist add (adds a new blacklist filter) (DEPRECATED) + * node blacklist list (lists all blacklist filters) (DEPRECATED) + * node blacklist remove (removes a blacklist filter) (DEPRECATED) + * node list (lists all nodes) (DEPRECATED) + * node remove (removes node) (DEPRECATED) + * node set (set node attributes) (DEPRECATED) * node setup (set up node) - * node update-config (update node config) - * node whitelist add (adds a new whitelist filter) - * node whitelist list (lists all whitelist filters) - * node whitelist remove (removes a whitelist filter) + * node update-config (update node config) (DEPRECATED) + * node whitelist add (adds a new whitelist filter) (DEPRECATED) + * node whitelist list (lists all whitelist filters) (DEPRECATED) + * node whitelist remove (removes a whitelist filter) (DEPRECATED) * node wizard (wizard for node setup) * object list (lists all objects) * pki new-ca (sets up a new CA) @@ -43,38 +44,39 @@ options. * pki save-cert (saves another Icinga 2 instance's certificate) * pki sign-csr (signs a CSR) * pki ticket (generates a ticket) - * repository clear-changes (clear uncommitted repository changes) - * repository commit (commit repository changes) - * repository endpoint add (adds a new Endpoint object) - * repository endpoint list (lists all Endpoint objects) - * repository endpoint remove (removes a Endpoint object) - * repository host add (adds a new Host object) - * repository host list (lists all Host objects) - * repository host remove (removes a Host object) - * repository service add (adds a new Service object) - * repository service list (lists all Service objects) - * repository service remove (removes a Service object) - * repository zone add (adds a new Zone object) - * repository zone list (lists all Zone objects) - * repository zone remove (removes a Zone object) + * repository clear-changes (clear uncommitted repository changes) (DEPRECATED) + * repository commit (commit repository changes) (DEPRECATED) + * repository endpoint add (adds a new Endpoint object) (DEPRECATED) + * repository endpoint list (lists all Endpoint objects) (DEPRECATED) + * repository endpoint remove (removes a Endpoint object) (DEPRECATED) + * repository host add (adds a new Host object) (DEPRECATED) + * repository host list (lists all Host objects) (DEPRECATED) + * repository host remove (removes a Host object) (DEPRECATED) + * repository service add (adds a new Service object) (DEPRECATED) + * repository service list (lists all Service objects) (DEPRECATED) + * repository service remove (removes a Service object) (DEPRECATED) + * repository zone add (adds a new Zone object) (DEPRECATED) + * repository zone list (lists all Zone objects) (DEPRECATED) + * repository zone remove (removes a Zone object) (DEPRECATED) * troubleshoot (collect information for troubleshooting) * variable get (gets a variable) * variable list (lists all variables) - + Global options: - -h [ --help ] show this help message - -V [ --version ] show version information - --color use VT100 color codes even when stdout is not a - terminal - -D [ --define ] arg define a constant - -a [ --app ] arg application library name (default: icinga) - -l [ --library ] arg load a library - -I [ --include ] arg add include search directory - -x [ --log-level ] arg specify the log level for the console log - - Command options: - - Report bugs at + -h [ --help ] show this help message + -V [ --version ] show version information + --color use VT100 color codes even when stdout is not a + terminal + -D [ --define ] arg define a constant + -a [ --app ] arg application library name (default: icinga) + -l [ --library ] arg load a library + -I [ --include ] arg add include search directory + -x [ --log-level ] arg specify the log level for the console log. + The valid value is either debug, notice, + information (default), warning, or critical + -X [ --script-debugger ] whether to enable the script debugger + + Report bugs at Icinga home page: @@ -83,8 +85,7 @@ options. Bash Auto-Completion (pressing ``) is provided only for the corresponding context. While `--config` will suggest and auto-complete files and directories on disk, -`feature enable` will only suggest disabled features. `repository` will know -about object specific attributes, and so on. Try it yourself. +`feature enable` will only suggest disabled features. Try it yourself. RPM and Debian packages install the bash completion files into `/etc/bash_completion.d/icinga2`. @@ -103,6 +104,13 @@ Debian/Ubuntu: # apt-get install bash-completion +Ensure that the `bash-completion.d` directory is added to your shell +environment. You can manually source the icinga2 bash-completion file +into your current session and test it: + + # source /etc/bash-completion.d/icinga2 + + ## Icinga 2 CLI Global Options ### Application Type @@ -137,7 +145,7 @@ added. ## CLI command: Console -The CLI command `console` can be used to evaluate Icinga config expressions, e.g. to test +The CLI command `console` can be used to evaluate Icinga 2 config expressions, e.g. to test [functions](17-language-reference.md#functions). $ icinga2 console @@ -167,7 +175,9 @@ are required for executing config expressions and auto-completion. You can specify the API URL using the `--connect` parameter. -Although the password can be specified there process arguments on UNIX platforms are usually visible to other users (e.g. through `ps`). In order to securely specify the user credentials the console supports two environment variables: +Although the password can be specified there process arguments on UNIX platforms are +usually visible to other users (e.g. through `ps`). In order to securely specify the +user credentials the console supports two environment variables: Environment variable | Description ---------------------|------------- @@ -177,7 +187,7 @@ Although the password can be specified there process arguments on UNIX platforms Here's an example: $ ICINGA2_API_PASSWORD=icinga icinga2 console --connect 'https://root@localhost:5665/' - Icinga 2 (version: v2.4.0) + Icinga 2 (version: v2.6.0) <1> => Once connected you can inspect variables and execute other expressions by entering them at the prompt: @@ -214,9 +224,13 @@ Once connected you can inspect variables and execute other expressions by enteri <3> => -You can use the `--eval` parameter to evaluate a single expression in batch mode. Using the `--file` option you can specify a file which should be evaluated. The output format for batch mode is JSON. +You can use the `--eval` parameter to evaluate a single expression in batch mode. +Using the `--file` option you can specify a file which should be evaluated. +The output format for batch mode is JSON. -The `--syntax-only` option can be used in combination with `--eval` or `--file` to check a script for syntax errors. In this mode the script is parsed to identify syntax errors but not evaluated. +The `--syntax-only` option can be used in combination with `--eval` or `--file` +to check a script for syntax errors. In this mode the script is parsed to identify +syntax errors but not evaluated. Here's an example that retrieves the command that was used by Icinga to check the `example.localdomain` host: @@ -237,39 +251,43 @@ The CLI command `daemon` provides the functionality to start/stop Icinga 2. Furthermore it provides the [configuration validation](11-cli-commands.md#config-validation). # icinga2 daemon --help - icinga2 - The Icinga 2 network monitoring daemon (version: v2.5.0) - + icinga2 - The Icinga 2 network monitoring daemon (version: v2.6.0) + Usage: icinga2 daemon [] - + Starts Icinga 2. - + Global options: - -h [ --help ] show this help message - -V [ --version ] show version information - --color use VT100 color codes even when stdout is not a - terminal - -D [ --define ] arg define a constant - -a [ --app ] arg application library name (default: icinga) - -l [ --library ] arg load a library - -I [ --include ] arg add include search directory - -x [ --log-level ] arg specify the log level for the console log - + -h [ --help ] show this help message + -V [ --version ] show version information + --color use VT100 color codes even when stdout is not a + terminal + -D [ --define ] arg define a constant + -a [ --app ] arg application library name (default: icinga) + -l [ --library ] arg load a library + -I [ --include ] arg add include search directory + -x [ --log-level ] arg specify the log level for the console log. + The valid value is either debug, notice, + information (default), warning, or critical + -X [ --script-debugger ] whether to enable the script debugger + Command options: - -c [ --config ] arg parse a configuration file - -z [ --no-config ] start without a configuration file - -C [ --validate ] exit after validating the configuration - -e [ --errorlog ] arg log fatal errors to the specified log file (only works - in combination with --daemonize) - -d [ --daemonize ] detach from the controlling terminal - + -c [ --config ] arg parse a configuration file + -z [ --no-config ] start without a configuration file + -C [ --validate ] exit after validating the configuration + -e [ --errorlog ] arg log fatal errors to the specified log file (only + works in combination with --daemonize) + -d [ --daemonize ] detach from the controlling terminal + Report bugs at Icinga home page: + ### Config Files Using the `--config` option you can specify one or more configuration files. -Config files are processed in the order they're specified on the command-line. +Configuration files are processed in the order they're specified on the command-line. When no configuration file is specified and the `--no-config` is not used Icinga 2 automatically falls back to using the configuration file @@ -281,69 +299,78 @@ The `--validate` option can be used to check if your configuration files contain errors. If any errors are found, the exit status is 1, otherwise 0 is returned. More details in the [configuration validation](11-cli-commands.md#config-validation) chapter. - ## CLI command: Feature The `feature enable` and `feature disable` commands can be used to enable and disable features: # icinga2 feature disable - checker --color --define --help --include --library --log-level mainlog notification --version - + --app --define --include --log-level --version checker graphite mainlog + --color --help --library --script-debugger api command ido-mysql notification + # icinga2 feature enable - api command debuglog graphite icingastatus ido-pgsql --library --log-level statusdata --version - --color compatlog --define --help ido-mysql --include livestatus perfdata syslog + --app --define --include --log-level --version debuglog ido-pgsql livestatus perfdata syslog + --color --help --library --script-debugger compatlog gelf influxdb opentsdb statusdata The `feature list` command shows which features are currently enabled: # icinga2 feature list - Disabled features: agent command compatlog debuglog gelf graphite icingastatus notification perfdata statusdata syslog - Enabled features: api checker livestatus mainlog + Disabled features: compatlog debuglog gelf ido-pgsql influxdb livestatus opentsdb perfdata statusdata syslog + Enabled features: api checker command graphite ido-mysql mainlog notification ## CLI command: Node +> **Warning** +> +> This CLI command and its sub commands except for `setup` and `wizard` +> have been deprecated in v2.6 and will be +> removed in future releases. +> +> Make sure to follow the release announcements on the [Icinga website](https://www.icinga.com). + Provides the functionality to install and manage master and client nodes in a [distributed monitoring](6-distributed-monitoring.md#distributed-monitoring) scenario. - # icinga2 node --help - icinga2 - The Icinga 2 network monitoring daemon (version: v2.5.0) - + icinga2 - The Icinga 2 network monitoring daemon (version: v2.6.0) + Usage: icinga2 [] - + Supported commands: - * node add (add node) - * node blacklist add (adds a new blacklist filter) - * node blacklist list (lists all blacklist filters) - * node blacklist remove (removes a blacklist filter) - * node list (lists all nodes) - * node remove (removes node) - * node set (set node attributes) + * node add (add node) (DEPRECATED) + * node blacklist add (adds a new blacklist filter) (DEPRECATED) + * node blacklist list (lists all blacklist filters) (DEPRECATED) + * node blacklist remove (removes a blacklist filter) (DEPRECATED) + * node list (lists all nodes) (DEPRECATED) + * node remove (removes node) (DEPRECATED) + * node set (set node attributes) (DEPRECATED) * node setup (set up node) - * node update-config (update node config) - * node whitelist add (adds a new whitelist filter) - * node whitelist list (lists all whitelist filters) - * node whitelist remove (removes a whitelist filter) + * node update-config (update node config) (DEPRECATED) + * node whitelist add (adds a new whitelist filter) (DEPRECATED) + * node whitelist list (lists all whitelist filters) (DEPRECATED) + * node whitelist remove (removes a whitelist filter) (DEPRECATED) * node wizard (wizard for node setup) - + Global options: - -h [ --help ] show this help message - -V [ --version ] show version information - --color use VT100 color codes even when stdout is not a - terminal - -D [ --define ] arg define a constant - -a [ --app ] arg application library name (default: icinga) - -l [ --library ] arg load a library - -I [ --include ] arg add include search directory - -x [ --log-level ] arg specify the log level for the console log - - Command options: - + -h [ --help ] show this help message + -V [ --version ] show version information + --color use VT100 color codes even when stdout is not a + terminal + -D [ --define ] arg define a constant + -a [ --app ] arg application library name (default: icinga) + -l [ --library ] arg load a library + -I [ --include ] arg add include search directory + -x [ --log-level ] arg specify the log level for the console log. + The valid value is either debug, notice, + information (default), warning, or critical + -X [ --script-debugger ] whether to enable the script debugger + Report bugs at Icinga home page: + ## CLI command: Object The `object` CLI command can be used to list all configuration objects and their @@ -353,51 +380,51 @@ That way you can also identify which objects have been created from your [apply More information can be found in the [troubleshooting](15-troubleshooting.md#list-configuration-objects) section. # icinga2 object --help - icinga2 - The Icinga 2 network monitoring daemon (version: v2.5.0) - + icinga2 - The Icinga 2 network monitoring daemon (version: v2.6.0) + Usage: icinga2 [] - + Supported commands: * object list (lists all objects) - + Global options: - -h [ --help ] show this help message - -V [ --version ] show version information - --color use VT100 color codes even when stdout is not a - terminal - -D [ --define ] arg define a constant - -a [ --app ] arg application library name (default: icinga) - -l [ --library ] arg load a library - -I [ --include ] arg add include search directory - -x [ --log-level ] arg specify the log level for the console log - - Command options: - + -h [ --help ] show this help message + -V [ --version ] show version information + --color use VT100 color codes even when stdout is not a + terminal + -D [ --define ] arg define a constant + -a [ --app ] arg application library name (default: icinga) + -l [ --library ] arg load a library + -I [ --include ] arg add include search directory + -x [ --log-level ] arg specify the log level for the console log. + The valid value is either debug, notice, + information (default), warning, or critical + -X [ --script-debugger ] whether to enable the script debugger + Report bugs at Icinga home page: - - ## CLI command: Pki Provides the CLI commands to -* generate a new local CA +* generate a new certificate authority (CA) * generate a new CSR or self-signed certificate * sign a CSR and return a certificate * save a master certificate manually * request a signed certificate from the master * generate a new ticket for the client setup -This functionality is used by the [node setup/wizard](11-cli-commands.md#cli-command-pki) CLI commands too. +This functionality is used by the [node setup/wizard](11-cli-commands.md#cli-command-node) CLI commands. +You will need them in the [distributed monitoring chapter](6-distributed-monitoring.md#distributed-monitoring). # icinga2 pki --help - icinga2 - The Icinga 2 network monitoring daemon (version: v2.5.0) - + icinga2 - The Icinga 2 network monitoring daemon (version: v2.6.0) + Usage: icinga2 [] - + Supported commands: * pki new-ca (sets up a new CA) * pki new-cert (creates a new CSR) @@ -405,63 +432,75 @@ This functionality is used by the [node setup/wizard](11-cli-commands.md#cli-com * pki save-cert (saves another Icinga 2 instance's certificate) * pki sign-csr (signs a CSR) * pki ticket (generates a ticket) - + Global options: - -h [ --help ] show this help message - -V [ --version ] show version information - --color use VT100 color codes even when stdout is not a - terminal - -D [ --define ] arg define a constant - -a [ --app ] arg application library name (default: icinga) - -l [ --library ] arg load a library - -I [ --include ] arg add include search directory - -x [ --log-level ] arg specify the log level for the console log - - Command options: - + -h [ --help ] show this help message + -V [ --version ] show version information + --color use VT100 color codes even when stdout is not a + terminal + -D [ --define ] arg define a constant + -a [ --app ] arg application library name (default: icinga) + -l [ --library ] arg load a library + -I [ --include ] arg add include search directory + -x [ --log-level ] arg specify the log level for the console log. + The valid value is either debug, notice, + information (default), warning, or critical + -X [ --script-debugger ] whether to enable the script debugger + Report bugs at Icinga home page: - ## CLI command: Repository -This command is not supported anymore. Parts of its functionality +> **Warning** +> +> This CLI command has been deprecated in v2.6 and will be +> removed in future releases. +> +> Make sure to follow the release announcements on the [Icinga website](https://www.icinga.com). + +This command is experimental and not finished as public CLI command. Parts of its functionality are used in the [node update-config](11-cli-commands.md#cli-command-node) cli command. ## CLI command: Troubleshoot -Collects basic information like version, paths, log files and crash reports for troubleshooting purposes and prints them to a file or the console. See [troubleshooting](15-troubleshooting.md#troubleshooting-information-required). +Collects basic information like version, paths, log files and crash reports for troubleshooting +purposes and prints them to a file or the console. See [troubleshooting](15-troubleshooting.md#troubleshooting-information-required). Its output defaults to a file named `troubleshooting-[TIMESTAMP].log` so it won't overwrite older troubleshooting files. -> **Note** -> Keep in mind that this tool can not collect information from other icinga2 nodes, you will have to run it on -> each of one of you instances. -> This is only a tool to collect information to help others help you, it will not attempt to fix anything. - +Keep in mind that this tool can not collect information from other icinga2 nodes, you will have to run it on +each of one of you instances. +This is only a tool to collect information to help others help you, it will not attempt to fix anything. # icinga2 troubleshoot --help - icinga2 - The Icinga 2 network monitoring daemon (version: v2.2.0-551-g1d0f6ed) - + icinga2 - The Icinga 2 network monitoring daemon (version: v2.6.0) + Usage: icinga2 troubleshoot [] - + + Collect logs and other relevant information for troubleshooting purposes. + Global options: - -h [ --help ] show this help message - -V [ --version ] show version information - --color use VT100 color codes even when stdout is not aterminal - -D [ --define ] arg define a constant - -a [ --app ] arg application library name (default: icinga) - -l [ --library ] arg load a library - -I [ --include ] arg add include search directory - -x [ --log-level ] arg specify the log level for the console log - + -h [ --help ] show this help message + -V [ --version ] show version information + --color use VT100 color codes even when stdout is not a + terminal + -D [ --define ] arg define a constant + -a [ --app ] arg application library name (default: icinga) + -l [ --library ] arg load a library + -I [ --include ] arg add include search directory + -x [ --log-level ] arg specify the log level for the console log. + The valid value is either debug, notice, + information (default), warning, or critical + -X [ --script-debugger ] whether to enable the script debugger + Command options: - -c [ --console ] print to console instead of file - -o [ --output ] arg path to output file - --include-vars print variables to separate file - --inluce-objects print object to separate file - + -c [ --console ] print to console instead of file + -o [ --output ] arg path to output file + --include-objects Print the whole objectfile (like `object list`) + --include-vars Print all Variables (like `variable list`) + Report bugs at Icinga home page: @@ -470,32 +509,32 @@ Its output defaults to a file named `troubleshooting-[TIMESTAMP].log` so it won' Lists all configured variables (constants) in a similar fashion like [object list](11-cli-commands.md#cli-command-object). # icinga2 variable --help - icinga2 - The Icinga 2 network monitoring daemon (version: v2.5.0) - + icinga2 - The Icinga 2 network monitoring daemon (version: v2.6.0) + Usage: icinga2 [] - + Supported commands: * variable get (gets a variable) * variable list (lists all variables) - + Global options: - -h [ --help ] show this help message - -V [ --version ] show version information - --color use VT100 color codes even when stdout is not a - terminal - -D [ --define ] arg define a constant - -a [ --app ] arg application library name (default: icinga) - -l [ --library ] arg load a library - -I [ --include ] arg add include search directory - -x [ --log-level ] arg specify the log level for the console log - - Command options: - + -h [ --help ] show this help message + -V [ --version ] show version information + --color use VT100 color codes even when stdout is not a + terminal + -D [ --define ] arg define a constant + -a [ --app ] arg application library name (default: icinga) + -l [ --library ] arg load a library + -I [ --include ] arg add include search directory + -x [ --log-level ] arg specify the log level for the console log. + The valid value is either debug, notice, + information (default), warning, or critical + -X [ --script-debugger ] whether to enable the script debugger + Report bugs at Icinga home page: - ## Enabling/Disabling Features Icinga 2 provides configuration files for some commonly used features. These @@ -616,17 +655,13 @@ Example filtered by `Service` objects with the name `ping*`: ## Reload on Configuration Changes -Everytime you have changed your configuration you should first tell Icinga 2 +Every time you have changed your configuration you should first tell Icinga 2 to [validate](11-cli-commands.md#config-validation). If there are no validation errors, you can safely reload the Icinga 2 daemon. - # /etc/init.d/icinga2 reload + # systemctl reload icinga2 -> **Note** -> -> The `reload` action will send the `SIGHUP` signal to the Icinga 2 daemon -> which will validate the configuration in a separate process and not stop -> the other events like check execution, notifications, etc. -> -> Details can be found [here](22-migrating-from-icinga-1x.md#differences-1x-2-real-reload). +The `reload` action will send the `SIGHUP` signal to the Icinga 2 daemon +which will validate the configuration in a separate process and not stop +the other events like check execution, notifications, etc. diff --git a/doc/6-distributed-monitoring.md b/doc/6-distributed-monitoring.md index e97f39410..2e08ac4d6 100644 --- a/doc/6-distributed-monitoring.md +++ b/doc/6-distributed-monitoring.md @@ -512,12 +512,11 @@ checks, send notifications, etc. Two different modes are available for synchronizing the host/service object's configuration between nodes and for executing checks: -* [Top down](6-distributed-monitoring.md#distributed-monitoring-top-down): This mode sends the configuration and commands from the master to the child zones. -* [Bottom up](6-distributed-monitoring.md#distributed-monitoring-bottom-up): This mode leaves the configuration on the child nodes and requires an import on the parent nodes. +The preferred mode is the [top down](6-distributed-monitoring.md#distributed-monitoring-top-down) approach. +This mode sends the configuration and commands from the master to the child zones. -The next sections describe the differences and how to set up the two modes. -Read them carefully before you decide on one of the two options -- do not -mix them, as this will make things unnecessarily complicated. +The [bottom up](6-distributed-monitoring.md#distributed-monitoring-bottom-up) has been **deprecated in v2.6 and will be removed in future releases**. +This mode leaves the configuration files on the child nodes and requires an import on the parent nodes. **Note**: Check results are always sent from the child nodes to the parent nodes. This happens automatically and is ensured by the cluster protocol. @@ -566,6 +565,8 @@ Include the endpoint and zone configuration on **both** nodes in the file `/etc/ The endpoint configuration could look like this, for example: + [root@icinga2-client1.localdomain /]# vim /etc/icinga2/zones.conf + object Endpoint "icinga2-master1.localdomain" { host = "192.168.56.101" } @@ -581,6 +582,8 @@ is to use the client's FQDN for all object names. The `master` zone is a parent of the `icinga2-client2.localdomain` zone: + [root@icinga2-client1.localdomain /]# vim /etc/icinga2/zones.conf + object Zone "master" { endpoints = [ "icinga2-master1.localdomain" ] //array with endpoint names } @@ -594,6 +597,8 @@ The `master` zone is a parent of the `icinga2-client2.localdomain` zone: In addition, add a [global zone](6-distributed-monitoring.md#distributed-monitoring-global-zone-config-sync) for syncing check commands later: + [root@icinga2-client1.localdomain /]# vim /etc/icinga2/zones.conf + object Zone "global-templates" { global = true } @@ -725,6 +730,8 @@ Include the endpoint and zone configuration on **both** nodes in the file `/etc/ The endpoint configuration could look like this: + [root@icinga2-client1.localdomain /]# vim /etc/icinga2/zones.conf + object Endpoint "icinga2-master1.localdomain" { host = "192.168.56.101" } @@ -740,6 +747,8 @@ is to use the client's FQDN for all object names. The `master` zone is a parent of the `icinga2-client1.localdomain` zone: + [root@icinga2-client1.localdomain /]# vim /etc/icinga2/zones.conf + object Zone "master" { endpoints = [ "icinga2-master1.localdomain" ] //array with endpoint names } @@ -846,6 +855,13 @@ section where you can find detailed information on extending the setup. ### Bottom Up Import +> **Warning** +> +> This mode has been deprecated in v2.6. You are strongly advised to +> migrate your existing configuration files to the [top down mode](6-distributed-monitoring.md#distributed-monitoring-top-down). +> +> Make sure to follow the release announcements on the [Icinga website](https://www.icinga.com). + This mode requires that you manage the configuration on the client itself. Edit the configuration files in `/etc/icinga2/conf.d` or any other directory included in the `icinga2.conf` file. @@ -871,6 +887,8 @@ On the master node, you can list and import the configuration sent from all the This example shows all client services on the master node `icinga2-master1.localdomain`: [root@icinga2-master1.localdomain /]# icinga2 node list + Warning: CLI command 'node list' is DEPRECATED! Please read the Changelog. + Node 'icinga2-client1.localdomain' (last seen: Sun Aug 14 11:19:14 2016) * Host 'icinga2-client1.localdomain' * Service 'disk' @@ -902,6 +920,8 @@ in order to receive check results from the clients. Therefore you need to invoke the `node update-config` command: [root@icinga2-master1.localdomain /]# icinga2 node update-config + Warning: CLI command 'node update-config' is DEPRECATED! Please read the Changelog. + information/cli: Updating node configuration for ... @@ -941,6 +961,226 @@ and fix it. This will help with additional notification apply rules or group memberships required for Icinga Web 2 and addons. +#### Bottom Up Migration to Top Down + +The bottom up mode has been deprecated and you should be prepared to migrate +your clients to the existing [top down mode](6-distributed-monitoring.md#distributed-monitoring-top-down). + +The bottom up mode generates configuration files on the master node underneath +the `/etc/icinga2/repository.d` directory. This is achieved by running the +`node update-config` CLI command and depends on manual user interaction. + +Unless you are changing something on the client which requires to run the +CLI command the configuration files in `repository.d` remain untouched. + +The Icinga 2 client generates an object repository from local configuration +(usually included in `conf.d` by default) and syncs that to the master. The +`node update-config` CLI command parses these repository files from the `/var/lib/icinga2/api/repository` +directory and generates the `repository.d` configuration files. In addition to +that blacklist and whitelist settings are evaluated. + +Those CLI commands also hide the fact that each client needs its own `Zone` +and `Endpoint` object as described [here](6-distributed-monitoring.md#distributed-monitoring-roles). + +If you are certain that the master node has an up-to-date `repository.d` +ensure that all your clients **do not include conf.d in their icinga2.conf** +configuration file. + +**Steps on each client**: + +Comment or remove the `include recursive "conf.d"` line. + + [root@icinga2-client1.localdomain /]# vim /etc/icinga2/icinga2.conf + + //include_recursive "conf.d" + +In addition to that add a [global zone](6-distributed-monitoring.md#distributed-monitoring-global-zone-config-sync) +for syncing check commands later: + + [root@icinga2-client1.localdomain /]# vim /etc/icinga2/zones.conf + + object Zone "global-templates" { + global = true + } + +Edit the `api` feature on the client `icinga2-client2.localdomain` in +the `/etc/icinga2/features-enabled/api.conf` file and make sure to set +`accept_commands` and `accept_config` to `true`: + + [root@icinga2-client1.localdomain /]# vim /etc/icinga2/features-enabled/api.conf + + object ApiListener "api" { + //... + accept_commands = true + accept_config = true + } + +Now it is time to validate the configuration and to restart the Icinga 2 daemon +on the client host `icinga2-client1.localdomain`. + +Example on CentOS 7: + + [root@icinga2-client1.localdomain /]# icinga2 daemon -C + [root@icinga2-client1.localdomain /]# systemctl restart icinga2 + + +**Steps on the configuration master node**: + +The migration strategy will guide you to use the client(s) as +[top down command endpoint](6-distributed-monitoring.md#distributed-monitoring-top-down-command-endpoint). + +The `repository.d` directory is organised as a tree of object type directories. + + [root@icinga2-master1.localdomain /]# tree /etc/icinga2/repository.d + repository.d/ + ├── README + ├── endpoints + │   └── icinga2-client1.localdomain.conf + ├── hosts + │   ├── icinga2-client1.localdomain + │   │   ├── disk\ C%3A.conf + │   │   ├── disk.conf + │   │   ├── icinga.conf + │   │   ├── load.conf + │   │   ├── ping4.conf + │   │   ├── ping6.conf + │   │   ├── procs.conf + │   │   ├── swap.conf + │   │   └── users.conf + │   └── icinga2-client1.localdomain.conf + └── zones + └── icinga2-client1.localdomain.conf + +The `endpoints` and `zones` directories contain the required connection +information for your client. Decide whether to add the configuration +objects to your `zones.conf` file or keep them as is. + +The `hosts` directory contains a `.conf` file for the host object +and a directory with the same name as the host with service configuration +files, in this example `hosts/icinga2-client1.localdomain`. + +The simplest migration path is to merge the Zone, Endpoint, Host and Service +object configuration into one new file called `.conf`, for example +`icinga2-client2.localdomain.conf`. + +Therefore create a new file in your master's zone directory in `zones.d`. +In this example we assume that the zone is called `master`. + +Use the information provided by the configuration files `/etc/icinga2/repository.d/zones/icinga2-client1.localdomain.conf` +and `/etc/icinga2/repository.d/endpoints/icinga2-client1.localdomain.conf`. + + [root@icinga2-master1.localdomain /]# vim /etc/icinga2/zones.d/master/icinga2-client1.localdomain.conf + + object Zone "icinga2-client2.localdomain" { + endpoints = [ "icinga2-client2.localdomain" ] + parent = "master" //defined in zones.conf + } + + object Endpoint "icinga2-client2.localdomain" { + //set the host attribute if the master should connect to the client endpoint + } + +Now fetch the Host object information located in the `/etc/icinga2/repository.d/hosts/icinga2-client1.localdomain.conf` +file and adopt it for your needs. One common disadvantage of the bottom up mode is that +the host object attributes are not synced from the client to the master. Log onto your client +and manually copy the required attributes into a new host object. + +Change the `check_command` attribute to `hostalive` to just ping the host. If you want to keep the +client connection check `cluster-zone`, you need to add the `cluster_zone` custom attribute. + +In addition to that add a new custom attribute called `client_endpoint` which stores +the command endpoint information. In case you need to learn more details please refer to +the [top down command endpoint](6-distributed-monitoring.md#distributed-monitoring-top-down-command-endpoint) +chapter. + + [root@icinga2-master1.localdomain /]# vim /etc/icinga2/zones.d/master/icinga2-client1.localdomain.conf + + object Host "icinga2-client1.localdomain.conf" { + //check_command = "hostalive" + check_command = "cluster-zone" + vars.cluster_zone = name //host name must be the same as the client's zone name + + vars.client_endpoint = name //host name must be the same as the client's endpoint name + vars.os = "Linux" //added for group membership + } + +Extract the service objects from the configuration files in the +`/etc/icinga2/repository.d/hosts/icinga2-client1.localdomain` directory +and add them into the `/etc/icinga2/zones.d/master/icinga2-client1.localdomain.conf` +file. + +Best practice is to use a generic [service apply rule](3-monitoring-basics.md#using-apply) +for each service. Identify common services on your hosts and modify the apply rules for +your own needs. + +Add the services to the generic `services.conf` file in `/etc/icinga2/zones.d/master`. + +Change the `check_command` attribute to the actual `CheckCommand` object which should +be executed. This information is available on the client in the `conf.d` directory. +Make sure to also extract all required custom attributes from the client and add them +to the service object e.g. check command thresholds for [disk](10-icinga-template-library.md#plugin-check-command-disk). + +Remove the `zone` attribute from all services. Specify the `command_endpoint` attribute +for all service checks which should be run locally on the client, for example `disk`. + + [root@icinga2-master1.localdomain /]# mkdir -p /etc/icinga2/zones.d/master + [root@icinga2-master1.localdomain /]# vim /etc/icinga2/zones.d/master/services.conf + + apply Service "disk" { + check_command = "disk" //modified + vars.disk_wfree = "10%" //copied from client + vars.disk_cfree = "5%" //copied from client + + command_endpoint = host.vars.client_endpoint + + assign where host.vars.client_endpoint //create service objects for all clients with command endpoint + } + +The `ping4` service should be executed on the master node itself. That is why +you must not add the `command_endpoint` attribute here. + + [root@icinga2-master1.localdomain /]# vim /etc/icinga2/zones.d/master/services.conf + + apply Service "ping4" { + check_command = "ping4" //modified + vars.ping_wrta = 200 //copied from client + vars.ping_crta = 500 //copied from client + + assign where host.address + } + +In case you have been using custom CheckCommand definitions on your client +you must sync them again using a global zone. + +Ensure that the global zone definition is already there in your `zones.conf` +file. + + [root@icinga2-master1.localdomain /]# vim /etc/icinga2/zones.conf + + object Zone "global-templates" { + global = true + } + +Put existing CheckCommand definitions into `/etc/icinga2/zones.d/global-templates/commands.conf`. + + [root@icinga2-master1.localdomain /]# mkdir -p /etc/icinga2/zones.d/global-templates + [root@icinga2-master1.localdomain /]# vim /etc/icinga2/zones.d/global-templates/commands.conf + + object CheckCommand "my-check" { + //... + } + +Now validate the configuration and restart Icinga 2. + + [root@icinga2-master1.localdomain /]# icinga2 daemon -C + [root@icinga2-master1.localdomain /]# systemctl restart icinga2 + +In case you have additional apply rules in place and have trouble with duplicated objects please +adopt and merge them accordingly. + +If you are eager to start fresh instead you might take a look into the +[Icinga Director](https://github.com/icinga/icingaweb2-module-director). + ## Scenarios The following examples should give you an idea on how to build your own diff --git a/icinga-app/icinga.cpp b/icinga-app/icinga.cpp index dd956bb9b..3721d2436 100644 --- a/icinga-app/icinga.cpp +++ b/icinga-app/icinga.cpp @@ -321,7 +321,7 @@ int Main(void) if ((!command || vm.count("help")) && !vm.count("version")) { std::cout << "Usage:" << std::endl - << " " << argv[0] << " "; + << " " << Utility::BaseName(argv[0]) << " "; if (cmdname.IsEmpty()) std::cout << ""; diff --git a/lib/cli/clicommand.cpp b/lib/cli/clicommand.cpp index 74d129c77..cf215465f 100644 --- a/lib/cli/clicommand.cpp +++ b/lib/cli/clicommand.cpp @@ -19,6 +19,7 @@ #include "cli/clicommand.hpp" #include "base/logger.hpp" +#include "base/console.hpp" #include "base/type.hpp" #include "base/serializer.hpp" #include @@ -105,6 +106,11 @@ bool CLICommand::IsHidden(void) const return false; } +bool CLICommand::IsDeprecated(void) const +{ + return false; +} + boost::mutex& CLICommand::GetRegistryMutex(void) { static boost::mutex mtx; @@ -217,6 +223,12 @@ found_command: adesc.add(visibleDesc); adesc.add(hiddenDesc); + if (command && command->IsDeprecated()) { + std::cerr << ConsoleColorTag(Console_ForegroundRed | Console_Bold) + << "Warning: CLI command '" << cmdname << "' is DEPRECATED! Please read the Changelog." + << ConsoleColorTag(Console_Normal) << std::endl << std::endl; + } + po::store(po::command_line_parser(argc - arg_end, argv + arg_end).options(adesc).positional(positionalDesc).run(), vm); po::notify(vm); @@ -305,8 +317,11 @@ void CLICommand::ShowCommands(int argc, char **argv, po::options_description *vi if (cname.Find(aword) == 0) std::cout << cname << "\n"; } - } else - std::cout << " * " << boost::algorithm::join(vname, " ") << " (" << kv.second->GetShortDescription() << ")" << std::endl; + } else { + std::cout << " * " << boost::algorithm::join(vname, " ") + << " (" << kv.second->GetShortDescription() << ")" + << (kv.second->IsDeprecated() ? " (DEPRECATED)" : "") << std::endl; + } } if (!autocomplete) diff --git a/lib/cli/clicommand.hpp b/lib/cli/clicommand.hpp index d1adad28f..2305aac68 100644 --- a/lib/cli/clicommand.hpp +++ b/lib/cli/clicommand.hpp @@ -59,6 +59,7 @@ public: virtual int GetMinArguments(void) const; virtual int GetMaxArguments(void) const; virtual bool IsHidden(void) const; + virtual bool IsDeprecated(void) const; virtual void InitParameters(boost::program_options::options_description& visibleDesc, boost::program_options::options_description& hiddenDesc) const; virtual ImpersonationLevel GetImpersonationLevel(void) const; diff --git a/lib/cli/nodeaddcommand.cpp b/lib/cli/nodeaddcommand.cpp index cfcc330e8..6f0bae513 100644 --- a/lib/cli/nodeaddcommand.cpp +++ b/lib/cli/nodeaddcommand.cpp @@ -47,6 +47,11 @@ int NodeAddCommand::GetMinArguments(void) const return 1; } +bool NodeAddCommand::IsDeprecated(void) const +{ + return true; +} + /** * The entry point for the "node add" CLI command. * diff --git a/lib/cli/nodeaddcommand.hpp b/lib/cli/nodeaddcommand.hpp index bfa32f641..ad2958096 100644 --- a/lib/cli/nodeaddcommand.hpp +++ b/lib/cli/nodeaddcommand.hpp @@ -37,6 +37,7 @@ public: virtual String GetDescription(void) const override; virtual String GetShortDescription(void) const override; + virtual bool IsDeprecated(void) const override; virtual int GetMinArguments(void) const override; virtual int Run(const boost::program_options::variables_map& vm, const std::vector& ap) const override; }; diff --git a/lib/cli/nodeblackandwhitelistcommand.cpp b/lib/cli/nodeblackandwhitelistcommand.cpp index ec43ba819..01ceefd67 100644 --- a/lib/cli/nodeblackandwhitelistcommand.cpp +++ b/lib/cli/nodeblackandwhitelistcommand.cpp @@ -84,6 +84,11 @@ String BlackAndWhitelistCommand::GetShortDescription(void) const return description; } +bool BlackAndWhitelistCommand::IsDeprecated(void) const +{ + return true; +} + void BlackAndWhitelistCommand::InitParameters(boost::program_options::options_description& visibleDesc, boost::program_options::options_description& hiddenDesc) const { diff --git a/lib/cli/nodeblackandwhitelistcommand.hpp b/lib/cli/nodeblackandwhitelistcommand.hpp index cb34f7dbd..5c883023e 100644 --- a/lib/cli/nodeblackandwhitelistcommand.hpp +++ b/lib/cli/nodeblackandwhitelistcommand.hpp @@ -47,6 +47,7 @@ public: virtual String GetDescription(void) const override; virtual String GetShortDescription(void) const override; + virtual bool IsDeprecated(void) const override; virtual void InitParameters(boost::program_options::options_description& visibleDesc, boost::program_options::options_description& hiddenDesc) const override; virtual int Run(const boost::program_options::variables_map& vm, const std::vector& ap) const override; diff --git a/lib/cli/nodelistcommand.cpp b/lib/cli/nodelistcommand.cpp index 3074b2523..6154116c7 100644 --- a/lib/cli/nodelistcommand.cpp +++ b/lib/cli/nodelistcommand.cpp @@ -43,6 +43,11 @@ String NodeListCommand::GetShortDescription(void) const return "lists all nodes"; } +bool NodeListCommand::IsDeprecated(void) const +{ + return true; +} + void NodeListCommand::InitParameters(boost::program_options::options_description& visibleDesc, boost::program_options::options_description& hiddenDesc) const { diff --git a/lib/cli/nodelistcommand.hpp b/lib/cli/nodelistcommand.hpp index 13026e7f1..33e732b86 100644 --- a/lib/cli/nodelistcommand.hpp +++ b/lib/cli/nodelistcommand.hpp @@ -37,6 +37,7 @@ public: virtual String GetDescription(void) const override; virtual String GetShortDescription(void) const override; + virtual bool IsDeprecated(void) const override; virtual void InitParameters(boost::program_options::options_description& visibleDesc, boost::program_options::options_description& hiddenDesc) const override; virtual int Run(const boost::program_options::variables_map& vm, const std::vector& ap) const override; diff --git a/lib/cli/noderemovecommand.cpp b/lib/cli/noderemovecommand.cpp index cbdcc37b1..fa084c293 100644 --- a/lib/cli/noderemovecommand.cpp +++ b/lib/cli/noderemovecommand.cpp @@ -57,6 +57,11 @@ int NodeRemoveCommand::GetMaxArguments(void) const return -1; } +bool NodeRemoveCommand::IsDeprecated(void) const +{ + return true; +} + /** * The entry point for the "node remove" CLI command. * diff --git a/lib/cli/noderemovecommand.hpp b/lib/cli/noderemovecommand.hpp index c6a4f85ee..4371d7ef0 100644 --- a/lib/cli/noderemovecommand.hpp +++ b/lib/cli/noderemovecommand.hpp @@ -37,6 +37,7 @@ public: virtual String GetDescription(void) const override; virtual String GetShortDescription(void) const override; + virtual bool IsDeprecated(void) const override; virtual int GetMinArguments(void) const override; virtual int GetMaxArguments(void) const override; virtual std::vector GetPositionalSuggestions(const String& word) const override; diff --git a/lib/cli/nodesetcommand.cpp b/lib/cli/nodesetcommand.cpp index d786f8bed..321931e70 100644 --- a/lib/cli/nodesetcommand.cpp +++ b/lib/cli/nodesetcommand.cpp @@ -56,6 +56,11 @@ int NodeSetCommand::GetMinArguments(void) const return 1; } +bool NodeSetCommand::IsDeprecated(void) const +{ + return true; +} + /** * The entry point for the "node set" CLI command. * diff --git a/lib/cli/nodesetcommand.hpp b/lib/cli/nodesetcommand.hpp index 4e31fc9ad..2e493b717 100644 --- a/lib/cli/nodesetcommand.hpp +++ b/lib/cli/nodesetcommand.hpp @@ -38,6 +38,7 @@ public: virtual String GetDescription(void) const override; virtual String GetShortDescription(void) const override; virtual int GetMinArguments(void) const override; + virtual bool IsDeprecated(void) const override; virtual void InitParameters(boost::program_options::options_description& visibleDesc, boost::program_options::options_description& hiddenDesc) const override; virtual int Run(const boost::program_options::variables_map& vm, const std::vector& ap) const override; diff --git a/lib/cli/nodeupdateconfigcommand.cpp b/lib/cli/nodeupdateconfigcommand.cpp index c9ba63772..8e7444fa5 100644 --- a/lib/cli/nodeupdateconfigcommand.cpp +++ b/lib/cli/nodeupdateconfigcommand.cpp @@ -53,6 +53,11 @@ ImpersonationLevel NodeUpdateConfigCommand::GetImpersonationLevel(void) const return ImpersonateRoot; } +bool NodeUpdateConfigCommand::IsDeprecated(void) const +{ + return true; +} + /** * The entry point for the "node update-config" CLI command. * diff --git a/lib/cli/nodeupdateconfigcommand.hpp b/lib/cli/nodeupdateconfigcommand.hpp index 9dfcb0f55..03af2cafd 100644 --- a/lib/cli/nodeupdateconfigcommand.hpp +++ b/lib/cli/nodeupdateconfigcommand.hpp @@ -37,6 +37,7 @@ public: virtual String GetDescription(void) const override; virtual String GetShortDescription(void) const override; + virtual bool IsDeprecated(void) const override; virtual int Run(const boost::program_options::variables_map& vm, const std::vector& ap) const override; virtual ImpersonationLevel GetImpersonationLevel(void) const override; }; diff --git a/lib/cli/repositoryclearchangescommand.cpp b/lib/cli/repositoryclearchangescommand.cpp index c0ae7baff..439b170fb 100644 --- a/lib/cli/repositoryclearchangescommand.cpp +++ b/lib/cli/repositoryclearchangescommand.cpp @@ -45,6 +45,11 @@ ImpersonationLevel RepositoryClearChangesCommand::GetImpersonationLevel(void) co return ImpersonateRoot; } +bool RepositoryClearChangesCommand::IsDeprecated(void) const +{ + return true; +} + /** * The entry point for the "repository clear-changes" CLI command. * diff --git a/lib/cli/repositoryclearchangescommand.hpp b/lib/cli/repositoryclearchangescommand.hpp index ee3f48002..956927aee 100644 --- a/lib/cli/repositoryclearchangescommand.hpp +++ b/lib/cli/repositoryclearchangescommand.hpp @@ -40,6 +40,7 @@ public: virtual String GetDescription(void) const override; virtual String GetShortDescription(void) const override; + virtual bool IsDeprecated(void) const override; virtual ImpersonationLevel GetImpersonationLevel(void) const override; virtual int Run(const boost::program_options::variables_map& vm, const std::vector& ap) const override; }; diff --git a/lib/cli/repositorycommitcommand.cpp b/lib/cli/repositorycommitcommand.cpp index 57e6f750d..b796222c2 100644 --- a/lib/cli/repositorycommitcommand.cpp +++ b/lib/cli/repositorycommitcommand.cpp @@ -52,6 +52,11 @@ ImpersonationLevel RepositoryCommitCommand::GetImpersonationLevel(void) const return ImpersonateRoot; } +bool RepositoryCommitCommand::IsDeprecated(void) const +{ + return true; +} + /** * The entry point for the "repository commit" CLI command. * diff --git a/lib/cli/repositorycommitcommand.hpp b/lib/cli/repositorycommitcommand.hpp index 611d2e139..5141d6d39 100644 --- a/lib/cli/repositorycommitcommand.hpp +++ b/lib/cli/repositorycommitcommand.hpp @@ -40,6 +40,7 @@ public: virtual String GetDescription(void) const override; virtual String GetShortDescription(void) const override; + virtual bool IsDeprecated(void) const override; virtual void InitParameters(boost::program_options::options_description& visibleDesc, boost::program_options::options_description& hiddenDesc) const override; virtual ImpersonationLevel GetImpersonationLevel(void) const override; diff --git a/lib/cli/repositoryobjectcommand.cpp b/lib/cli/repositoryobjectcommand.cpp index e2768d643..db0c18e31 100644 --- a/lib/cli/repositoryobjectcommand.cpp +++ b/lib/cli/repositoryobjectcommand.cpp @@ -95,6 +95,11 @@ String RepositoryObjectCommand::GetShortDescription(void) const return description; } +bool RepositoryObjectCommand::IsDeprecated(void) const +{ + return true; +} + void RepositoryObjectCommand::InitParameters(boost::program_options::options_description& visibleDesc, boost::program_options::options_description& hiddenDesc) const { diff --git a/lib/cli/repositoryobjectcommand.hpp b/lib/cli/repositoryobjectcommand.hpp index 4bad83623..ba596d5f0 100644 --- a/lib/cli/repositoryobjectcommand.hpp +++ b/lib/cli/repositoryobjectcommand.hpp @@ -49,6 +49,7 @@ public: virtual String GetDescription(void) const override; virtual String GetShortDescription(void) const override; virtual int GetMaxArguments(void) const override; + virtual bool IsDeprecated(void) const override; virtual void InitParameters(boost::program_options::options_description& visibleDesc, boost::program_options::options_description& hiddenDesc) const override; virtual ImpersonationLevel GetImpersonationLevel(void) const override; -- 2.40.0