From: Gunnar Beutner Date: Sun, 25 Jan 2015 15:07:43 +0000 (+0100) Subject: Update documentation X-Git-Tag: v2.3.0~340 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=775ed474d7e676c157b1f87fba1e8f5f419b6279;p=icinga2 Update documentation --- diff --git a/doc/10-alternative-frontends.md b/doc/10-alternative-frontends.md index 4d8a4b4b2..9899260c9 100644 --- a/doc/10-alternative-frontends.md +++ b/doc/10-alternative-frontends.md @@ -62,7 +62,7 @@ Therefore you need to setup the [DB IDO feature](2-getting-started.md#configurin ### Installing Icinga Web 1.x The Icinga package repository has both Debian and RPM packages. You can install -Icinga Web using the following packages (RPMs ship an additional configuration package): +Icinga Web using the following packages: Distribution | Packages --------------|------------------------------------------------------- @@ -76,7 +76,6 @@ Details can be found in the package `README` files, for example [README.RHEL](ht The Icinga Web RPM packages install the schema files into `/usr/share/doc/icinga-web-*/schema` (`*` means package version). -The Icinga Web dist tarball ships the schema files in `etc/schema`. On SuSE-based distributions the schema files are installed in `/usr/share/doc/packages/icinga-web/schema`. diff --git a/doc/12-troubleshooting.md b/doc/12-troubleshooting.md index 9d7d717b9..a87c6a444 100644 --- a/doc/12-troubleshooting.md +++ b/doc/12-troubleshooting.md @@ -91,13 +91,13 @@ You can also filter by name and type: ## Where are the check command definitions? -Icinga 2 ships additional [plugin check command definitions](6-icinga-template-library.md#plugin-check-commands) which are +Icinga 2 features a number of built-in [check command definitions](6-icinga-template-library.md#plugin-check-commands) which are included using include include -in the [icinga2.conf](4-configuring-icinga-2.md#icinga2-conf) configuration file. These configurations will be overridden +in the [icinga2.conf](4-configuring-icinga-2.md#icinga2-conf) configuration file. These files are not considered configuration files and will be overridden on upgrade, so please send modifications as proposed patches upstream. The default include path is set to `LocalStateDir + "/share/icinga2/includes"`. diff --git a/doc/2-getting-started.md b/doc/2-getting-started.md index 6bf32cfd0..11535b24d 100644 --- a/doc/2-getting-started.md +++ b/doc/2-getting-started.md @@ -45,12 +45,13 @@ Ubuntu (PPA): RHEL/CentOS: # rpm --import http://packages.icinga.org/icinga.key - # wget http://packages.icinga.org/epel/ICINGA-release.repo -O /etc/yum.repos.d/ICINGA-release.repo + # curl -o /etc/yum.repos.d/ICINGA-release.repo http://packages.icinga.org/epel/ICINGA-release.repo # yum makecache Fedora: - # wget http://packages.icinga.org/fedora/ICINGA-release.repo -O /etc/yum.repos.d/ICINGA-release.repo + # rpm --import http://packages.icinga.org/icinga.key + # curl -o /etc/yum.repos.d/ICINGA-release.repo http://packages.icinga.org/fedora/ICINGA-release.repo # yum makecache SLES: @@ -96,13 +97,6 @@ RHEL/CentOS 7 and Fedora use [systemd](2-getting-started.md#systemd-service): # systemctl enable icinga2 # systemctl start icinga2 -Some parts of Icinga 2's functionality are available as separate packages: - - Name | Description - ------------------------|-------------------------------- - icinga2-ido-mysql | [DB IDO](2-getting-started.md#configuring-db-ido) provider module for MySQL - icinga2-ido-pgsql | [DB IDO](2-getting-started.md#configuring-db-ido) provider module for PostgreSQL - ### Enabled Features during Installation The default installation will enable three features required for a basic @@ -214,7 +208,7 @@ SUSE: RHEL based distributions do not automatically set a secure root password. Do that **now**: - # /usr/bin/mysql_secure_installation + # mysql_secure_installation #### Installing the IDO modules for MySQL @@ -236,9 +230,9 @@ SUSE: > **Note** > -> Upstream Debian packages provide a database configuration wizard by default. -> You can skip the automated setup and install/upgrade the database manually -> if you prefer that. +> The Debian/Ubuntu packages provide a database configuration wizard by +> default. You can skip the automated setup and install/upgrade the +> database manually if you prefer that. #### Setting up the MySQL database @@ -248,7 +242,6 @@ Set up a MySQL database for Icinga 2: mysql> CREATE DATABASE icinga; GRANT SELECT, INSERT, UPDATE, DELETE, DROP, CREATE VIEW, INDEX, EXECUTE ON icinga.* TO 'icinga'@'localhost' IDENTIFIED BY 'icinga'; - quit After creating the database you can import the Icinga 2 IDO schema using the following command: @@ -259,10 +252,11 @@ following command: #### Enabling the IDO MySQL module The package provides a new configuration file that is installed in -`/etc/icinga2/features-available/ido-mysql.conf`. You will need to update the -database credentials in this file. -All available attributes are listed in the -[IdoMysqlConnection object](5-object-types.md#objecttype-idomysqlconnection) configuration details. +`/etc/icinga2/features-available/ido-mysql.conf`. You will need to +update the database credentials in this file. + +All available attributes are explained in the +[IdoMysqlConnection object](5-object-types.md#objecttype-idomysqlconnection) chapter. You can enable the `ido-mysql` feature configuration file using `icinga2 feature enable`: @@ -373,10 +367,11 @@ using the following command: #### Enabling the IDO PostgreSQL module The package provides a new configuration file that is installed in -`/etc/icinga2/features-available/ido-pgsql.conf`. You will need to update the -database credentials in this file. -All available attributes are listed in the -[IdoPgsqlConnection object](5-object-types.md#objecttype-idopgsqlconnection) configuration details. +`/etc/icinga2/features-available/ido-pgsql.conf`. You will need to update +the database credentials in this file. + +All available attributes are explained in the +[IdoPgsqlConnection object](5-object-types.md#objecttype-idopgsqlconnection) chapter. You can enable the `ido-pgsql` feature configuration file using `icinga2 feature enable`: @@ -427,10 +422,9 @@ The webserver's user is different between distributions so you might have to cha Change "www-data" to the user you're using to run queries. -> **Note** -> -> Packages will do that automatically. Verify that by running `id ` and skip this -> step. +You can verify that the user has been successfully added to the `icingacmd` group using the `id` command: + + id ## Running Icinga 2 @@ -441,6 +435,8 @@ Icinga 2's init script is installed in `/etc/init.d/icinga2` by default: # /etc/init.d/icinga2 Usage: /etc/init.d/icinga2 {start|stop|restart|reload|checkconfig|status} +The init script supports the following actions: + Command | Description --------------------|------------------------ start | The `start` action starts the Icinga 2 daemon. @@ -451,15 +447,15 @@ Icinga 2's init script is installed in `/etc/init.d/icinga2` by default: status | The `status` action checks if Icinga 2 is running. By default the Icinga 2 daemon is running as `icinga` user and group -using the init script. Using Debian packages the user and group are set to `nagios` -for historical reasons. +using the init script. Using Debian packages the user and group are set to +`nagios` for historical reasons. ### systemd Service -Some distributions (e.g. Fedora, openSUSE and RHEL/CentOS 7) use systemd. The Icinga 2 -packages automatically install the necessary systemd unit files. +Some distributions (e.g. Fedora, openSUSE and RHEL/CentOS 7) use systemd. The +Icinga 2 packages automatically install the necessary systemd unit files. -The Icinga 2 systemd service can be (re)started, reloaded, stopped and also queried for its current status. +The Icinga 2 systemd service can be (re-)started, reloaded, stopped and also queried for its current status. # systemctl status icinga2 icinga2.service - Icinga host/service/network monitoring system @@ -491,19 +487,22 @@ The `systemctl` command supports the following actions: status | The `status` action checks if Icinga 2 is running. enable | The `enable` action enables the service being started at system boot time (similar to `chkconfig`) -If you're stuck with configuration errors, you can manually invoke the [configuration validation](7-cli-commands.md#config-validation). +Examples: # systemctl enable icinga2 # systemctl restart icinga2 Job for icinga2.service failed. See 'systemctl status icinga2.service' and 'journalctl -xn' for details. +If you're stuck with configuration errors, you can manually invoke the [configuration validation](7-cli-commands.md#config-validation). ## Setting up the User Interface -Icinga 2 can be used with Icinga Web 2 and a number of other web interfaces. This chapter explains how -to set up Icinga Web 2. The [Alternative Frontends](10-alternative-frontends.md#alternative-frontends) chapter can be used as a -starting point for installing some of the other web interfaces which are also available. +Icinga 2 can be used with Icinga Web 2 and a number of other web interfaces. +This chapter explains how to set up Icinga Web 2. The +[Alternative Frontends](10-alternative-frontends.md#alternative-frontends) +chapter can be used as a starting point for installing some of the other web +interfaces which are also available. #### Webserver @@ -512,17 +511,22 @@ Debian/Ubuntu: # apt-get install apache2 -RHEL/CentOS/Fedora: +RHEL/CentOS 6: # yum install httpd - # chkconfig httpd on && service httpd start - ## RHEL7 - # systemctl enable httpd && systemctl start httpd + # chkconfig httpd on + # service httpd start + +RHEL/CentOS 7/Fedora: + + # systemctl enable httpd + # systemctl start httpd SUSE: # zypper install apache2 - # chkconfig on && service apache2 start + # chkconfig on + # service apache2 start #### Firewall Rules @@ -538,30 +542,19 @@ RHEL/CentOS 7 specific: ### Setting up Icinga Web 2 -Icinga Web 2 supports `DB IDO` or `Livestatus` as backends. - -Using DB IDO as backend, you need to install and configure the -[DB IDO backend](2-getting-started.md#configuring-db-ido). - -In order to use commands in Web 2 you need to [set up the external command pipe](2-getting-started.md#setting-up-external-command-pipe). - -[Icinga Web 2](https://github.com/Icinga/icingaweb2) ships its own -web-based setup wizard which will guide you through the entire setup process. +Icinga Web 2 currently requires `DB IDO` as a backend. You need to install and configure the [DB IDO backend](2-getting-started.md#configuring-db-ido) if you +haven't already done so. -Generate the Webserver configuration and a setup token using its local cli -and proceed with the web setup when accessing `/icingaweb2` after reloading -your webserver configuration. +In order to use commands in Web 2 you will also need to [set up the external command pipe](2-getting-started.md#setting-up-external-command-pipe). -Please consult the [installation documentation](https://github.com/Icinga/icingaweb2/blob/master/doc/installation.md) -shipped with `Icinga Web 2` for further instructions on how to install -`Icinga Web 2` and to configure backends, resources and instances manually. +[Icinga Web 2](https://github.com/Icinga/icingaweb2) features a +web-based setup wizard which will guide you through the setup process. -Check the [Icinga website](https://www.icinga.org) for release announcements -and packages. +Please consult the [installation documentation](https://github.com/Icinga/icingaweb2/blob/master/doc/installation.md) for further instructions on how to install `Icinga Web 2`. ### Addons -A number of additional features are available in the form of plugins. A list of popular +A number of additional features are available in the form of addons. A list of popular addons is available in the [Addons and Plugins](9-addons-plugins.md#addons-plugins) chapter. diff --git a/doc/3-monitoring-basics.md b/doc/3-monitoring-basics.md index 6059cf660..5ef81b105 100644 --- a/doc/3-monitoring-basics.md +++ b/doc/3-monitoring-basics.md @@ -307,7 +307,7 @@ The notification is ignored for services whose host name ends with `*internal` #### Apply Services to Hosts -The sample configuration already ships a detailed example in [hosts.conf](4-configuring-icinga-2.md#hosts-conf) +The sample configuration already includes a detailed example in [hosts.conf](4-configuring-icinga-2.md#hosts-conf) and [services.conf](4-configuring-icinga-2.md#services-conf) for this use case. The example for `ssh` applies a service object to all hosts with the `address` @@ -350,7 +350,7 @@ Detailed examples can be found in the [dependencies](3-monitoring-basics.md#depe #### Apply Recurring Downtimes to Hosts and Services -The sample confituration ships an example in [downtimes.conf](4-configuring-icinga-2.md#downtimes-conf). +The sample confituration includes an example in [downtimes.conf](4-configuring-icinga-2.md#downtimes-conf). Detailed examples can be found in the [recurring downtimes](3-monitoring-basics.md#recurring-downtimes) chapter. @@ -362,7 +362,7 @@ apply rules objects based on set (array or dictionary). That way you'll save qui of a lot of duplicated apply rules by combining them into one generic generating the object name with or without a prefix. -The sample configuration already ships a detailed example in [hosts.conf](4-configuring-icinga-2.md#hosts-conf) +The sample configuration already includes a detailed example in [hosts.conf](4-configuring-icinga-2.md#hosts-conf) and [services.conf](4-configuring-icinga-2.md#services-conf) for this use case. Imagine a different example: You are monitoring your switch (hosts) with many @@ -619,7 +619,7 @@ to the defined notifications. That way you'll save duplicated attributes in each period = "24x7" } -The time period `24x7` is shipped as example configuration with Icinga 2. +The time period `24x7` is included as example configuration with Icinga 2. Use the `apply` keyword to create `Notification` objects for your services: @@ -905,7 +905,7 @@ using the `check_command` attribute. Unless you have done so already, download your check plugin and put it into the [PluginDir](4-configuring-icinga-2.md#constants-conf) directory. The following example uses the -`check_disk` plugin shipped with the Monitoring Plugins package. +`check_disk` plugin contained in the Monitoring Plugins package. The plugin path and all command arguments are made a list of double-quoted string arguments for proper shell escaping. @@ -2494,7 +2494,7 @@ skipping the external command pipe. Several clustered/distributed environments and check-aggregation addons use that method. In order to support step-by-step migration of these -environments, Icinga 2 ships the `CheckResultReader` object. +environments, Icinga 2 supports the `CheckResultReader` object. There is no feature configuration available, but it must be defined on-demand in your Icinga 2 objects configuration. diff --git a/doc/4-configuring-icinga-2.md b/doc/4-configuring-icinga-2.md index 2cf975102..d0a06403c 100644 --- a/doc/4-configuring-icinga-2.md +++ b/doc/4-configuring-icinga-2.md @@ -79,21 +79,15 @@ and their generated configuration described in You can put your own configuration files in the [conf.d](4-configuring-icinga-2.md#conf-d) directory. This directive makes sure that all of your own configuration files are included. -> **Tip** -> -> The example configuration is shipped in this directory too. You can either -> remove it entirely, or adapt the existing configuration structure with your -> own object configuration. - ## constants.conf The `constants.conf` configuration file can be used to define global constants. By default, you need to make sure to set these constants: -* The `PluginDir` constant must be pointed to your [check plugins](2-getting-started.md#setting-up-check-plugins) path. -This constant is required by the shipped -[plugin check command configuration](6-icinga-template-library.md#plugin-check-commands). +* The `PluginDir` constant must be set to the path where the [Monitoring Project plugins](2-getting-started.md#setting-up-check-plugins) are installed. +This constant is used by a number of +[built-in check command definitions](6-icinga-template-library.md#plugin-check-commands). * The `NodeName` constant defines your local node name. Should be set to FQDN which is the default if not set. This constant is required for local host configuration, monitoring remote clients and cluster setup. @@ -139,7 +133,7 @@ way of deploying Icinga 2 configuration. Further details on configuration best practice and how to build your own strategy is described in [this chapter](3-monitoring-basics.md#configuration-best-practice). -Available configuration files shipped by default: +Available configuration files which are installed by default: * [hosts.conf](4-configuring-icinga-2.md#hosts-conf) * [services.conf](4-configuring-icinga-2.md#services-conf) @@ -265,7 +259,7 @@ Service(s) | Applied on host(s) `http`, optional: `Icinga Web 2` | All hosts with custom attribute `http_vhosts` defined as dictionary `disk`, `disk /` | All hosts with custom attribute `disks` defined as dictionary -The Debian packages also ship an additional `apt` service check applied to the local host. +The Debian packages also include an additional `apt` service check applied to the local host. The command object `icinga` for the embedded health check is provided by the [Icinga Template Library (ITL)](6-icinga-template-library.md#icinga-template-library) while `http_ip`, `ssh`, `load`, `processes`, @@ -415,7 +409,7 @@ Defines the `icingaadmin` User and the `icingaadmins` UserGroup. The latter is u Notifications for check alerts are an integral part or your Icinga 2 monitoring stack. -The shipped example defines two notification apply rules for hosts and services. +The examples in this file define two notification apply rules for hosts and services. Both `apply` rules match on the same condition: They are only applied if the nested dictionary attribute `notification.mail` is set. @@ -453,12 +447,6 @@ filters can be read in [this chapter](3-monitoring-basics.md#notifications). This is the place where your own command configuration can be defined. By default only the notification commands used by the notification templates defined in [templates.conf](4-configuring-icinga-2.md#templates-conf). -> **Tip** -> -> Icinga 2 ships the most common command definitions already in the -> [Plugin Check Commands](6-icinga-template-library.md#plugin-check-commands) definitions. More details on -> that topic in the [troubleshooting section](12-troubleshooting.md#check-command-definitions). - You can freely customize these notification commands, and adapt them for your needs. Read more on that topic [here](3-monitoring-basics.md#notification-commands). @@ -508,12 +496,8 @@ and the attribute string to match with. ### templates.conf -All shipped example configuration objects use generic global templates by -default. Be it setting a default `check_command` attribute in the `generic-host` -templates for your hosts defined in [hosts.conf](4-configuring-icinga-2.md#hosts-conf), or defining -the default `states` and `types` filters for notification apply rules defined in -[notifications.conf](4-configuring-icinga-2.md#notifications-conf). - +Most of the example configuration objects use generic global templates by +default: template Host "generic-host" { max_check_attempts = 5 @@ -529,7 +513,7 @@ the default `states` and `types` filters for notification apply rules defined in retry_interval = 30s } -The `hostalive` check command is shipped with Icinga 2 in the +The `hostalive` check command is part of the [Plugin Check Commands](6-icinga-template-library.md#plugin-check-commands). @@ -586,14 +570,14 @@ to define the default value for the time ranges required for recurring downtime ### timeperiods.conf -This file ships the default timeperiod definitions for `24x7`, `9to5` +This file contains the default timeperiod definitions for `24x7`, `9to5` and `never`. Timeperiod objects are referenced by `*period` objects such as hosts, services or notifications. ### satellite.conf -Ships default templates and dependencies for [monitoring remote clients](8-monitoring-remote-systems.md#icinga2-remote-client-monitoring) +Includes default templates and dependencies for [monitoring remote clients](8-monitoring-remote-systems.md#icinga2-remote-client-monitoring) using service discovery and [config generation](8-monitoring-remote-systems.md#icinga2-remote-monitoring-master-discovery-generate-config) on the master. Can be ignored/removed on setups not using this features. diff --git a/doc/7-cli-commands.md b/doc/7-cli-commands.md index 2912e88c2..32430e953 100644 --- a/doc/7-cli-commands.md +++ b/doc/7-cli-commands.md @@ -1,6 +1,6 @@ ## Icinga 2 CLI Commands -Icinga 2 ships its own integrated CLI commands supporting bash-autocompletion. +Icinga 2 comes with a number of CLI commands which support bash autocompletion. These CLI commands will allow you to use certain functionality provided by and around the Icinga 2 daemon. @@ -12,12 +12,11 @@ Run `icinga2` without any arguments 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) @@ -59,7 +58,7 @@ options. * 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 @@ -69,9 +68,9 @@ options. -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: @@ -181,9 +180,7 @@ is returned. More details in the [configuration validation](7-cli-commands.md#co ### 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. +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 @@ -192,6 +189,13 @@ feature will only bring up all enabled features. api command debuglog graphite icingastatus ido-pgsql --library --log-level statusdata --version --color compatlog --define --help ido-mysql --include livestatus perfdata syslog +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 + + ### CLI command: Node Provides the functionality to install and manage master and client diff --git a/doc/9-addons-plugins.md b/doc/9-addons-plugins.md index 7727c7afc..6e91ae074 100644 --- a/doc/9-addons-plugins.md +++ b/doc/9-addons-plugins.md @@ -123,15 +123,12 @@ Example for a custom `my-snmp-int` check command: vars.snmp_crit = "0,600" } -You can find an existing `CheckCommand` definition for the `check_snmp_int.pl` plugin -shipped with the optional [Manubulon Plugin Check Command](6-icinga-template-library.md#snmp-manubulon-plugin-check-commands) -definitions already. - +Icinga 2 has built-in check command definitions for the [Manubulon Plugin Checks](6-icinga-template-library.md#snmp-manubulon-plugin-check-commands). For further information on your monitoring configuration read the -[monitoring basics](3-monitoring-basics.md#monitoring-basics). -You can find plugins (additional to the ones at [Monitoring Plugins](https://www.monitoring-plugins.org)) over at -[Icinga Exchange](https://exchange.icinga.org) +[Monitoring Basics](3-monitoring-basics.md#monitoring-basics) chapter. + +You can find additional plugins at the [Icinga Exchange](https://exchange.icinga.org) More details on the plugins can also be found on the Icinga Wiki at https://wiki.icinga.org