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

Deprecate the client 'bottom up' mode w/ node update-config 

This includes deprecation warnings and migration documentation.

fixes #13255
This commit is contained in:
Michael Friedrich 2016-11-23 15:33:28 +01:00
parent b028ff2c33
commit dc2992443f
23 changed files with 546 additions and 201 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

421
doc/11-cli-commands.md
View File

@ -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 <command> [<arguments>]
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 <https://dev.icinga.org/>
-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 <https://dev.icinga.org/>
Icinga home page: <https://www.icinga.org/>
@ -83,8 +85,7 @@ options.
Bash Auto-Completion (pressing `<TAB>`) 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
## <a id="cli-commands-global-options"></a> Icinga 2 CLI Global Options
### Application Type
@ -137,7 +145,7 @@ added.
## <a id="cli-command-console"></a> 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 [<arguments>]
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 <https://dev.icinga.org/>
Icinga home page: <https://www.icinga.org/>
### 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.
## <a id="cli-command-feature"></a> CLI command: Feature
The `feature enable` and `feature disable` commands can be used to enable and disable features:
# icinga2 feature disable <tab>
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 <tab>
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
## <a id="cli-command-node"></a> 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 <command> [<arguments>]
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 <https://dev.icinga.org/>
Icinga home page: <https://www.icinga.org/>
## <a id="cli-command-object"></a> 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 <command> [<arguments>]
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 <https://dev.icinga.org/>
Icinga home page: <https://www.icinga.org/>
## <a id="cli-command-pki"></a> 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 <command> [<arguments>]
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 <https://dev.icinga.org/>
Icinga home page: <https://www.icinga.org/>
## <a id="cli-command-repository"></a> 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.
## <a id="cli-command-troubleshoot"></a> 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 [<arguments>]
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 <https://dev.icinga.org/>
Icinga home page: <https://www.icinga.org/>
@ -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 <command> [<arguments>]
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 <https://dev.icinga.org/>
Icinga home page: <https://www.icinga.org/>
## <a id="enable-features"></a> 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*`:
## <a id="config-change-reload"></a> 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.

250
doc/6-distributed-monitoring.md
View File

@ -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.
### <a id="distributed-monitoring-bottom-up"></a> 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.
#### <a id="distributed-monitoring-bottom-up-migration-top-down"></a> 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 `<FQDN>.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).
## <a id="distributed-monitoring-scenarios"></a> Scenarios
The following examples should give you an idea on how to build your own

2
icinga-app/icinga.cpp
View File

@ -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 << "<command>";

19
lib/cli/clicommand.cpp
View File

@ -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 <boost/algorithm/string/join.hpp>
@ -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)

1
lib/cli/clicommand.hpp
View File

@ -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;

5
lib/cli/nodeaddcommand.cpp
View File

@ -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.
*

1
lib/cli/nodeaddcommand.hpp
View File

@ -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<std::string>& ap) const override;
};

5
lib/cli/nodeblackandwhitelistcommand.cpp
View File

@ -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
{

1
lib/cli/nodeblackandwhitelistcommand.hpp
View File

@ -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<std::string>& ap) const override;

5
lib/cli/nodelistcommand.cpp
View File

@ -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
{

1
lib/cli/nodelistcommand.hpp
View File

@ -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<std::string>& ap) const override;

5
lib/cli/noderemovecommand.cpp
View File

@ -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.
*

1
lib/cli/noderemovecommand.hpp
View File

@ -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<String> GetPositionalSuggestions(const String& word) const override;

5
lib/cli/nodesetcommand.cpp
View File

@ -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.
*

1
lib/cli/nodesetcommand.hpp
View File

@ -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<std::string>& ap) const override;

5
lib/cli/nodeupdateconfigcommand.cpp
View File

@ -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.
*

1
lib/cli/nodeupdateconfigcommand.hpp
View File

@ -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<std::string>& ap) const override;
virtual ImpersonationLevel GetImpersonationLevel(void) const override;
};

5
lib/cli/repositoryclearchangescommand.cpp
View File

@ -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.
*

1
lib/cli/repositoryclearchangescommand.hpp
View File

@ -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<std::string>& ap) const override;
};

5
lib/cli/repositorycommitcommand.cpp
View File

@ -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.
*

1
lib/cli/repositorycommitcommand.hpp
View File

@ -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;

5
lib/cli/repositoryobjectcommand.cpp
View File

@ -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
{

1
lib/cli/repositoryobjectcommand.hpp
View File

@ -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;