From a56561beecc00c466debfbf3655e4fa22417946d Mon Sep 17 00:00:00 2001 From: Michael Friedrich Date: Sun, 2 Nov 2014 21:46:02 +0100 Subject: [PATCH] Docs: Add cli commands fixes #7356 --- doc/2-getting-started.md | 453 +++++++++++++++++++++++++---- doc/5-monitoring-remote-systems.md | 6 +- doc/7-configuring-icinga-2.md | 10 + 3 files changed, 407 insertions(+), 62 deletions(-) diff --git a/doc/2-getting-started.md b/doc/2-getting-started.md index 3d9010792..8b8d45154 100644 --- a/doc/2-getting-started.md +++ b/doc/2-getting-started.md @@ -117,19 +117,16 @@ Icinga 2 installation: * `checker` for executing checks * `notification` for sending notifications -* `mainlog` for writing the `icinga2.log ` file +* `mainlog` for writing the `icinga2.log` file -Verify that by calling `icinga2 feature enable` without any additional parameters -and enable the missing features, if any. +You can verify that by calling `icinga2 feature list` [cli command](#cli-command-feature) +to see which features are enabled and disabled. - # icinga2 feature enable - Syntax: icinga2 feature enable - Example: icinga2 feature enable checker notification mainlog - Enables the specified feature(s). - - Available features: api checker command compatlog debuglog graphite icingastatus ido-mysql ido-pgsql livestatus mainlog notification perfdata statusdata syslog + # icinga2 feature list + Disabled features: api command compatlog debuglog graphite icingastatus ido-mysql ido-pgsql livestatus notification perfdata statusdata syslog Enabled features: checker mainlog notification + ### Installation Paths By default Icinga 2 uses the following files and directories: @@ -138,15 +135,14 @@ By default Icinga 2 uses the following files and directories: ------------------------------------|------------------------------------ /etc/icinga2 | Contains Icinga 2 configuration files. /etc/init.d/icinga2 | The Icinga 2 init script. - /usr/bin/icinga2-* | Migration and certificate build scripts. - /usr/sbin/icinga2* | The Icinga 2 binary and feature enable/disable scripts. + /usr/sbin/icinga2* | The Icinga 2 binary. /usr/share/doc/icinga2 | Documentation files that come with Icinga 2. /usr/share/icinga2/include | The Icinga Template Library and plugin command configuration. /var/run/icinga2 | PID file. /var/run/icinga2/cmd | Command pipe and Livestatus socket. - /var/cache/icinga2 | status.dat/objects.cache. + /var/cache/icinga2 | status.dat/objects.cache, icinga2.debug files /var/spool/icinga2 | Used for performance data spool files. - /var/lib/icinga2 | Icinga 2 state file, cluster feature replay log and configuration files. + /var/lib/icinga2 | Icinga 2 state file, cluster log, local CA and configuration files. /var/log/icinga2 | Log file location and compat/ directory for the CompatLogger feature. ## Setting up Check Plugins @@ -1290,48 +1286,124 @@ If you're stuck with configuration errors, you can manually invoke the [configur # systemctl restart icinga2 Job for icinga2.service failed. See 'systemctl status icinga2.service' and 'journalctl -xn' for details. -### Command-line Options - $ icinga2 --help - icinga2 - The Icinga 2 network monitoring daemon. - Supported options: - --help show this help message - -V [ --version ] show version information - -l [ --library ] arg load a library - -I [ --include ] arg add include search directory - -D [ --define] args define a constant - -c [ --config ] arg parse a configuration file - -C [ --validate ] exit after validating the configuration - -x [ --debug ] arg enable debugging with severity level specified - -d [ --daemonize ] detach from the controlling terminal - -e [ --errorlog ] arg log fatal errors to the specified log file (only works - in combination with --daemonize) - -u [ --user ] arg user to run Icinga as - -g [ --group ] arg group to run Icinga as +### Icinga 2 CLI Commands - Report bugs at - Icinga home page: +Icinga 2 ships its own integrated cli commands supporting bash-autocompletion. +These cli commands will allow you to use certain functionality +provided by and around the Icinga 2 daemon. > **Note** > -> The cli command `repository` only supports basic configuration manipulation (add, remove). Future -> versions will support more options (set, etc.). Please check the Icinga 2 development roadmap -> for that. +> The cli commands are available in Icinga 2 starting with *2.2*. + +Each cli command provides its own help and usage information, so please +make sure to always run them withthe `--help` parameter. + +Run `icinga2` without any arguments (or using `--help`) to get a list of +all available global options. + + # icinga2 + + icinga2 - The Icinga 2 network monitoring daemon (version: v2.1.1-299-gf695275) + + Usage: + icinga2 [] + + Supported commands: + * 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 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 wizard (wizard for node setup) + * object list (lists all objects) + * pki new-ca (sets up a new CA) + * pki new-cert (creates a new CSR) + * pki request (requests a certificate) + * 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) + * 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 + -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 + Icinga home page: + + +#### Icinga 2 CLI Bash Autocompletion + +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. +RPM and Debian packages install the bash completion files into +`/etc/bash_completion.d/icinga2`. -#### Libraries +You will need to install the `bash-completion` package if not already installed. + +RHEL/CentOS/Fedora: + # yum install bash-completion + +SUSE: + # zypper install bash-completion + +Debian/Ubuntu: + # apt-get install bash-completion + +#### Icinga 2 CLI Global Options + +##### Libraries Instead of loading libraries using the [`library` config directive](#library) you can also use the `--library` command-line option. -#### Constants +##### Constants [Global constants](#global-constants) can be set using the `--define` command-line option. -#### Config Include Path +##### Config Include Path When including files you can specify that the include search path should be checked. You can do this by putting your configuration file name in angle @@ -1346,7 +1418,43 @@ is the only search directory. Using the `--include` command-line option additional search directories can be added. -#### Config Files + + +#### Cli command: Daemon + +The cli command `daemon` provides the functionality to start/stop Icinga 2. +Furthermore it provides the [configuration validation](#config-validation). + + # icinga2 daemon --help + icinga2 - The Icinga 2 network monitoring daemon (version: v2.1.1-299-gf695275) + + 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 + -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: + -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. @@ -1355,46 +1463,271 @@ When no configuration file is specified and the `--no-config` is not used Icinga 2 automatically falls back to using the configuration file `SysconfDir + "/icinga2/icinga2.conf"` (where SysconfDir is usually `/etc`). -#### Config Validation +##### Config Validation 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. +is returned. More details in the [configuration validation](#config-validation) chapter. + + +#### Cli command: Feature + +The cli commands for `enable` and `disable` feature support bash auto-completion +and will only suggest features for the corresponding context. Like disabling a +feature will only bring up all enabled features. + + # icinga2 feature disable + checker --color --define --help --include --library --log-level mainlog notification --version + + # 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 + +#### Cli command: Node + +Provides the functionality to install and manage master and client +nodes in a [remote monitoring ](#icinga2-remote-client-monitoring) or +[distributed cluster](#distributed-monitoring-high-availability) scenario. + + + # icinga2 node --help + icinga2 - The Icinga 2 network monitoring daemon (version: v2.1.1-299-gf695275) + + 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 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 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 + -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 + Icinga home page: + + +#### Cli command: Object + +The `object` cli command can be used to list all configuration objects and their +attributes. The command also shows where each of the attributes was modified. +That way you can also identify which objects have been created from your [apply rules](#apply). + +More information can be found in the [troubleshooting](#list-configuration-objects) section. + + # icinga2 object --help + icinga2 - The Icinga 2 network monitoring daemon (version: v2.1.1-299-gf695275) + + 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 + -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 + Icinga home page: + + + +#### Cli command: Pki + +Provides the cli commands to + +* generate a new local 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](#cli-command-pki) cli commands too. + + # icinga2 pki --help + icinga2 - The Icinga 2 network monitoring daemon (version: v2.1.1-299-gf695275) + + Usage: + icinga2 [] + + Supported commands: + * pki new-ca (sets up a new CA) + * pki new-cert (creates a new CSR) + * pki request (requests a certificate) + * 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 + -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 + Icinga home page: + + +#### Cli command: Repository + +Provides the functionality to manage the Icinga 2 configuration repository in +`/etc/icinga2/repository.d`. All changes are logged and must be committed or +cleared after review. + + +> **Note** +> +> The cli command `repository` only supports basic configuration manipulation (add, remove) +> and a limited set of objects required for the [remote client] integration. Future +> versions will support more options (set, etc.). +> +> Please check the Icinga 2 development roadmap for updates. + + + # icinga2 repository --help + icinga2 - The Icinga 2 network monitoring daemon (version: v2.1.1-299-gf695275) + + Usage: + icinga2 [] + + Supported commands: + * 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) + + 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 + -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 + Icinga home page: + + + +#### Cli command: Variable + +Lists all configured variables (constants) in a similar fasion like [object list](#cli-command-object). + + # icinga2 variable --help + icinga2 - The Icinga 2 network monitoring daemon (version: v2.1.1-299-gf695275) + + 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 + -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 + Icinga home page: + + + + ### Enabling/Disabling Features Icinga 2 provides configuration files for some commonly used features. These are installed in the `/etc/icinga2/features-available` directory and can be -enabled and disabled using the `icinga2 feature enable` and `icinga2 feature disable` tools, -respectively. - -The `icinga2 feature enable` tool creates symlinks in the `/etc/icinga2/features-enabled` -directory which is included by default in the example configuration file. +enabled and disabled using the `icinga2 feature enable` and `icinga2 feature disable` +[cli commands](#cli-command-feature), respectively. -You can view a list of available feature configuration files: +The `icinga2 feature enable` cli command creates symlinks in the +`/etc/icinga2/features-enabled` directory which is included by default +in the example configuration file. - # icinga2 feature enable - Syntax: icinga2 feature enable - Enables the specified feature. +You can view a list of enabled and disabled features: - Available features: statusdata + # icinga2 feature list + Disabled features: api command compatlog debuglog graphite icingastatus ido-mysql ido-pgsql livestatus notification perfdata statusdata syslog + Enabled features: checker mainlog notification Using the `icinga2 feature enable` command you can enable features: - # icinga2 feature enable statusdata - Module 'statusdata' was enabled. - Make sure to restart Icinga 2 for these changes to take effect. + # icinga2 feature enable graphite + Enabling feature graphite. Make sure to restart Icinga 2 for these changes to take effect. + You can disable features using the `icinga2 feature disable` command: - # icinga2 feature disable statusdata - Module 'statusdata' was disabled. - Make sure to restart Icinga 2 for these changes to take effect. + # icinga2 feature disable ido-mysql livestatus + Disabling feature ido-mysql. Make sure to restart Icinga 2 for these changes to take effect. + Disabling feature livestatus. Make sure to restart Icinga 2 for these changes to take effect. + The `icinga2 feature enable` and `icinga2 feature disable` commands do not restart Icinga 2. You will need to restart Icinga 2 using the init script after enabling or disabling features. + + ### Configuration Validation Once you've edited the configuration files make sure to tell Icinga 2 to validate @@ -1444,8 +1777,9 @@ Or manually passing the `-C` argument: If you encouter errors during configuration validation, please make sure to read the [troubleshooting](#troubleshooting) chapter. -You can also use the cli command `icinga2 object list` after validation passes -to analyze object attributes, inheritance or created objects by apply rules. +You can also use the [cli command](#cli-command-object) `icinga2 object list` +after validation passes to analyze object attributes, inheritance or created +objects by apply rules. Find more on troubleshooting with `object list` in [this chapter](#list-configuration-objects). Example filtered by `Service` objects with the name `ping*`: @@ -1475,6 +1809,7 @@ Example filtered by `Service` objects with the name `ping*`: % = modified in '/etc/icinga2/conf.d/services.conf', lines 18:3-18:19 + ### Reload on Configuration Changes Everytime you have changed your configuration you should first tell Icinga 2 diff --git a/doc/5-monitoring-remote-systems.md b/doc/5-monitoring-remote-systems.md index 7862a5873..df90283bf 100644 --- a/doc/5-monitoring-remote-systems.md +++ b/doc/5-monitoring-remote-systems.md @@ -76,7 +76,7 @@ Your master setup requires the following * Enabled API feature, and a local Endpoint and Zone object configuration * Firewall ACLs for the communication port (default 5665) -You can use the cli command `icinga2 node wizard` for setting up a new node +You can use the [cli command](#cli-command-node) `node wizard` for setting up a new node on the master. The command must be run as root, all Icinga 2 specific files will be updated to the icinga user the daemon is running as (certificate files for example). @@ -142,7 +142,7 @@ The setup wizard does not automatically restart Icinga 2. ## Client Setup for Remote Monitoring Icinga 2 can be installed on Linux/Unix and Windows. While -[Linux/Unix](#icinga2-remote-monitoring-client-linux) will be using the CLI command +[Linux/Unix](#icinga2-remote-monitoring-client-linux) will be using the [cli command](#cli-command-node) `node wizard` for a guided setup, you will need to use the graphical installer for Windows based client setup. @@ -633,7 +633,7 @@ Before you start deploying, keep the following things in mind: ### Manual SSL Certificate Generation -Icinga 2 ships cli commands assisting with CA and node certificate creation +Icinga 2 ships [cli commands](#cli-command-pki) assisting with CA and node certificate creation for your Icinga 2 distributed setup. > **Note** diff --git a/doc/7-configuring-icinga-2.md b/doc/7-configuring-icinga-2.md index 521339718..a0c2e3d22 100644 --- a/doc/7-configuring-icinga-2.md +++ b/doc/7-configuring-icinga-2.md @@ -639,6 +639,7 @@ Attributes: event\_command |**Optional.** The name of an event command that should be executed every time the host's state changes or the host is in a `SOFT` state. flapping\_threshold|**Optional.** The flapping threshold in percent when a host is considered to be flapping. volatile |**Optional.** The volatile setting enables always `HARD` state types if `NOT-OK` state changes occur. + zone |**Optional.** The zone this object is a member of. notes |**Optional.** Notes for the host. notes_url |**Optional.** Url for notes for the host (for example, in notification commands). action_url |**Optional.** Url for actions for the host (for example, an external graphing tool). @@ -725,6 +726,7 @@ Attributes: event\_command |**Optional.** The name of an event command that should be executed every time the service's state changes or the service is in a `SOFT` state. flapping\_threshold|**Optional.** The flapping threshold in percent when a service is considered to be flapping. volatile |**Optional.** The volatile setting enables always `HARD` state types if `NOT-OK` state changes occur. + zone |**Optional.** The zone this object is a member of. notes |**Optional.** Notes for the service. notes_url |**Optional.** Url for notes for the service (for example, in notification commands). action_url |**Optional.** Url for actions for the service (for example, an external graphing tool). @@ -811,6 +813,7 @@ Attributes: period |**Optional.** The name of a time period which determines when a notification for this user should be triggered. Not set by default. types |**Optional.** A set of type filters when this notification should be triggered. By default everything is matched. states |**Optional.** A set of state filters when this notification should be triggered. By default everything is matched. + zone |**Optional.** The zone this object is a member of. ### UserGroup @@ -833,6 +836,7 @@ Attributes: ----------------|---------------- display_name |**Optional.** A short description of the user group. groups |**Optional.** An array of nested group names. + zone |**Optional.** The zone this object is a member of. @@ -887,6 +891,7 @@ Attributes: env |**Optional.** A dictionary of macros which should be exported as environment variables prior to executing the command. vars |**Optional.** A dictionary containing custom attributes that are specific to this command. timeout |**Optional.** The command timeout in seconds. Defaults to 60 seconds. + zone |**Optional.** The zone this object is a member of. arguments |**Optional.** A dictionary of command arguments. @@ -972,6 +977,7 @@ Attributes: env |**Optional.** A dictionary of macros which should be exported as environment variables prior to executing the command. vars |**Optional.** A dictionary containing custom attributes that are specific to this command. timeout |**Optional.** The command timeout in seconds. Defaults to 60 seconds. + zone |**Optional.** The zone this object is a member of. arguments |**Optional.** A dictionary of command arguments. Command arguments can be used the same way as for `CheckCommand` objects. @@ -1043,6 +1049,7 @@ Attributes: command | **Required.** The name of the notification command which should be executed when the notification is triggered. interval | **Optional.** The notification interval (in seconds). This interval is used for active notifications. Defaults to 30 minutes. If set to 0, [re-notifications](#disable-renotification) are disabled. period | **Optional.** The name of a time period which determines when this notification should be triggered. Not set by default. + zone |**Optional.** The zone this object is a member of. types | **Optional.** A list of type filters when this notification should be triggered. By default everything is matched. states | **Optional.** A list of state filters when this notification should be triggered. By default everything is matched. @@ -1098,6 +1105,7 @@ Attributes: ----------------|---------------- display_name |**Optional.** A short description of the time period. methods |**Required.** The "update" script method takes care of updating the internal representation of the time period. In virtually all cases you should import the "legacy-timeperiod" template to take care of this setting. + zone |**Optional.** The zone this object is a member of. ranges |**Required.** A dictionary containing information which days and durations apply to this timeperiod. The `/etc/icinga2/conf.d/timeperiods.conf` file is usually used to define @@ -1143,6 +1151,7 @@ Attributes: comment |**Required.** A comment for the downtime. fixed |**Optional.** Whether this is a fixed downtime. Defaults to true. duration |**Optional.** How long the downtime lasts. Only has an effect for flexible (non-fixed) downtimes. + zone |**Optional.** The zone this object is a member of. ranges |**Required.** A dictionary containing information which days and durations apply to this timeperiod. ScheduledDowntime objects have composite names, i.e. their names are based @@ -1203,6 +1212,7 @@ Attributes: disable_checks |**Optional.** Whether to disable checks when this dependency fails. Defaults to false. disable_notifications |**Optional.** Whether to disable notifications when this dependency fails. Defaults to true. period |**Optional.** Time period during which this dependency is enabled. + zone |**Optional.** The zone this object is a member of. states |**Optional.** A list of state filters when this dependency should be OK. Defaults to [ OK, Warning ] for services and [ Up ] for hosts. Available state filters: -- 2.40.0