### <a id="installing-icinga-web"></a> 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
--------------|-------------------------------------------------------
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`.
## <a id="check-command-definitions"></a> 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 <itl>
include <plugins>
-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"`.
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:
# 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
-
### <a id="installation-enabled-features"></a> Enabled Features during Installation
The default installation will enable three features required for a basic
RHEL based distributions do not automatically set a secure root password. Do that **now**:
- # /usr/bin/mysql_secure_installation
+ # mysql_secure_installation
#### <a id="installing-database-mysql-modules"></a> Installing the IDO modules for MySQL
> **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.
#### <a id="setting-up-mysql-db"></a> Setting up the MySQL database
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:
#### <a id="enabling-ido-mysql"></a> 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`:
#### <a id="enabling-ido-postgresql"></a> 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`:
Change "www-data" to the user you're using to run queries.
-> **Note**
->
-> Packages will do that automatically. Verify that by running `id <your-webserver-user>` and skip this
-> step.
+You can verify that the user has been successfully added to the `icingacmd` group using the `id` command:
+
+ id <your-webserver-user>
## <a id="running-icinga2"></a> Running Icinga 2
# /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.
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.
### <a id="systemd-service"></a> 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
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).
## <a id="setting-up-the-user-interface"></a> 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.
#### <a id="icinga2-user-interface-webserver"></a> Webserver
# 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
#### <a id="icinga2-user-interface-firewall-rules"></a> Firewall Rules
### <a id="setting-up-icingaweb2"></a> 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`.
### <a id="install-addons"></a> 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.
#### <a id="using-apply-services"></a> 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`
#### <a id="using-apply-scheduledowntimes"></a> 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.
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
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:
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.
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.
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.
-
## <a id="constants-conf"></a> 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.
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)
`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`,
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.
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).
### <a id="templates-conf"></a> 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
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).
### <a id="timeperiods-conf"></a> 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.
### <a id="satellite-conf"></a> 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.
## <a id="cli-commands"></a> 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.
options.
# icinga2
-
icinga2 - The Icinga 2 network monitoring daemon (version: v2.1.1-299-gf695275)
-
+
Usage:
icinga2 <command> [<arguments>]
-
+
Supported commands:
* daemon (starts Icinga 2)
* feature disable (disables specified feature)
* 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
-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/>
Icinga home page: <https://www.icinga.org/>
### <a id="cli-command-feature"></a> 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 <tab>
checker --color --define --help --include --library --log-level mainlog notification --version
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
+
+
### <a id="cli-command-node"></a> CLI command: Node
Provides the functionality to install and manage master and client
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
projects / icinga2 / commitdiff