# <a id="getting-started"></a> Getting Started
This tutorial is a step-by-step introduction to installing [Icinga 2](2-getting-started.md#setting-up-icinga2)
-and [Icinga Web 2](2-getting-started.md#setting-up-the-user-interface).
+and [Icinga Web 2](2-getting-started.md#setting-up-icingaweb2).
It assumes that you are familiar with the operating system you're using to install Icinga 2.
## <a id="setting-up-icinga2"></a> Setting up Icinga 2
Distribution | Repository
------------------------|---------------------------
- Debian | [debmon](http://debmon.org/packages/debmon-jessie/icinga2), [Icinga Repository](http://packages.icinga.org/debian/)
+ Debian | [debmon](https://debmon.org/packages/debmon-jessie/icinga2), [Icinga Repository](http://packages.icinga.org/debian/)
Ubuntu | [Icinga PPA](https://launchpad.net/~formorer/+archive/ubuntu/icinga), [Icinga Repository](http://packages.icinga.org/ubuntu/)
RHEL/CentOS | [Icinga Repository](http://packages.icinga.org/epel/)
openSUSE | [Icinga Repository](http://packages.icinga.org/openSUSE/), [Server Monitoring Repository](https://build.opensuse.org/package/show/server:monitoring/icinga2)
Debian (debmon):
- # wget -O - http://debmon.org/debmon/repo.key 2>/dev/null | apt-key add -
+ # wget -O - https://debmon.org/debmon/repo.key 2>/dev/null | apt-key add -
# echo 'deb http://debmon.org/debmon debmon-jessie main' >/etc/apt/sources.list.d/debmon.list
# apt-get update
# add-apt-repository ppa:formorer/icinga
# apt-get update
-RHEL/CentOS:
+RHEL/CentOS 7:
+
+ yum install https://packages.icinga.org/epel/7/release/noarch/icinga-rpm-release-7-1.el7.centos.noarch.rpm
+
+RHEL/CentOS 6:
+
+ yum install https://packages.icinga.org/epel/6/release/noarch/icinga-rpm-release-6-1.el6.noarch.rpm
+
+RHEL/CentOS 5:
- # rpm --import http://packages.icinga.org/icinga.key
- # curl -o /etc/yum.repos.d/ICINGA-release.repo http://packages.icinga.org/epel/ICINGA-release.repo
- # yum makecache
+ rpm -i http://packages.icinga.org/epel/5/release/noarch/icinga-rpm-release-5-1.el5.centos.noarch.rpm
The packages for RHEL/CentOS depend on other packages which are distributed
as part of the [EPEL repository](http://fedoraproject.org/wiki/EPEL). Please
make sure to enable this repository by following
[these instructions](http://fedoraproject.org/wiki/EPEL#How_can_I_use_these_extra_packages.3F).
-Fedora:
+Fedora 23:
+
+ dnf install https://packages.icinga.org/fedora/23/release/noarch/icinga-rpm-release-23-1.fc23.noarch.rpm
+
+Fedora 22:
- # 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
+ dnf install https://packages.icinga.org/fedora/22/release/noarch/icinga-rpm-release-22-1.fc22.noarch.rpm
+
+Fedora 21:
+
+ yum install http://packages.icinga.org/fedora/21/release/noarch/icinga-rpm-release-21-1.fc21.noarch.rpm
SLES 11:
# zypper install icinga2
+FreeBSD:
+
+ # pkg install icinga2
+
### <a id="installation-enabled-features"></a> Enabled Features during Installation
The default installation will enable three features required for a basic
/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.
+FreeBSD uses slightly different paths:
+
+By default Icinga 2 uses the following files and directories:
+
+ Path | Description
+ ------------------------------------|------------------------------------
+ /usr/local/etc/icinga2 | Contains Icinga 2 configuration files.
+ /usr/local/etc/rc.d/icinga2 | The Icinga 2 init script.
+ /usr/local/sbin/icinga2 | The Icinga 2 binary.
+ /usr/local/share/doc/icinga2 | Documentation files that come with Icinga 2.
+ /usr/local/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, icinga2.debug files
+ /var/spool/icinga2 | Used for performance data spool 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.
+
## <a id="setting-up-check-plugins"></a> Setting up Check Plugins
Without plugins Icinga 2 does not know how to check external services. The
an extensive set of plugins which can be used with Icinga 2 to check whether
services are working properly.
-The recommended way of installing these standard plugins is to use your
-distribution's package manager.
+These plugins are required to make the [example configuration](4-configuring-icinga-2.md#configuring-icinga2-overview)
+work out-of-the-box.
For your convenience here is a list of package names for some of the more
popular operating systems/distributions:
-OS/Distribution | Package Name | Installation Path
------------------------|--------------------|---------------------------
-RHEL/CentOS (EPEL) | nagios-plugins-all | /usr/lib/nagios/plugins or /usr/lib64/nagios/plugins
-Debian | nagios-plugins | /usr/lib/nagios/plugins
-FreeBSD | nagios-plugins | /usr/local/libexec/nagios
-OS X (MacPorts) | nagios-plugins | /opt/local/libexec
+OS/Distribution | Package Name | Repository | Installation Path
+-----------------------|--------------------|---------------------------|----------------------------
+RHEL/CentOS | nagios-plugins-all | [EPEL](http://fedoraproject.org/wiki/EPEL) | /usr/lib/nagios/plugins or /usr/lib64/nagios/plugins
+SLES/OpenSUSE | monitoring-plugins | [server:monitoring](https://build.opensuse.org/project/repositories/server:monitoring) | /usr/lib/nagios/plugins
+Debian/Ubuntu | nagios-plugins | - | /usr/lib/nagios/plugins
+FreeBSD | monitoring-plugins | - | /usr/local/libexec/nagios
+OS X | nagios-plugins | [MacPorts](http://www.macports.org), [Homebrew](http://brew.sh) | /opt/local/libexec or /usr/local/sbin
+
+The recommended way of installing these standard plugins is to use your
+distribution's package manager.
+
+Debian/Ubuntu:
+
+ # apt-get install nagios-plugins
+
+RHEL/CentOS:
+
+ # yum install nagios-plugins-all
+
+The packages for RHEL/CentOS depend on other packages which are distributed
+as part of the [EPEL repository](http://fedoraproject.org/wiki/EPEL). Please
+make sure to enable this repository by following
+[these instructions](http://fedoraproject.org/wiki/EPEL#How_can_I_use_these_extra_packages.3F).
+
+Fedora:
+
+ # dnf install nagios-plugins-all
+
+SLES/openSUSE:
+
+ # zypper install monitoring-plugins
+
+The packages for SLES/OpenSUSE depend on other packages which are distributed
+as part of the [server:monitoring repository](https://build.opensuse.org/project/repositories/server:monitoring).
+Please make sure to enable this repository beforehand.
+
+FreeBSD:
+
+ # pkg install monitoring-plugins
Depending on which directory your plugins are installed into you may need to
update the global `PluginDir` constant in your [Icinga 2 configuration](4-configuring-icinga-2.md#constants-conf).
This constant is used by the check command definitions contained in the Icinga Template Library
to determine where to find the plugin binaries.
-Please refer to the [plugins](14-addons-plugins.md#plugins) chapter for details about how to integrate
-additional check plugins into your Icinga 2 setup.
+> **Note**
+>
+> Please refer to the [plugins](14-addons-plugins.md#plugins) chapter for details about how to integrate
+> additional check plugins into your Icinga 2 setup.
## <a id="running-icinga2"></a> Running Icinga 2
### <a id="init-script"></a> Init Script
-Icinga 2's init script is installed in `/etc/init.d/icinga2` by default:
+Icinga 2's init script is installed in `/etc/init.d/icinga2` (`/usr/local/etc/rc.d/icinga2` on FreeBSD) by default:
# /etc/init.d/icinga2
Usage: /etc/init.d/icinga2 {start|stop|restart|reload|checkconfig|status}
If you're stuck with configuration errors, you can manually invoke the
[configuration validation](8-cli-commands.md#config-validation).
+### FreeBSD
+
+On FreeBSD you need to enable icinga2 in your rc.conf
+
+ # sysrc icinga2_enable=yes
+
+ # service icinga2 restart
## <a id="configuration-syntax-highlighting"></a> Configuration Syntax Highlighting
Icinga 2 ships configuration examples for syntax highlighting using the `vim` and `nano` editors.
-The RHEL, SUSE and Debian package `icinga2-common` install these files into
-`/usr/share/*/icinga2-common/syntax`. Sources provide these files in `tools/syntax`.
+The RHEL and SUSE package `icinga2-common` installs these files into `/usr/share/doc/icinga2-common-[x.x.x]/syntax`
+(where `[x.x.x]` is the version number, e.g. `2.4.3` or `2.4.4`). Sources provide these files in `tools/syntax`.
+On Debian systems the `icinga2-common` package provides only the Nano configuration file (`/usr/share/nano/icinga2.nanorc`);
+to obtain the Vim configuration, please install the extra package `vim-icinga2`. The files are located in `/usr/share/vim/addons`.
### <a id="configuration-syntax-highlighting-vim"></a> Configuration Syntax Highlighting using Vim
-Create a new local vim configuration storage, if not already existing.
-Edit `vim/ftdetect/icinga2.vim` if your paths to the Icinga 2 configuration
-differ.
+Install the package `vim-icinga2` with your distribution's package manager.
+
+Debian/Ubuntu:
+
+ $ apt-get install vim-icinga2 vim-addon-manager
+ $ vim-addon-manager -w install icinga2
+ Info: installing removed addon 'icinga2' to /var/lib/vim/addons
+
+RHEL/CentOS/Fedora:
+
+ $ yum install vim-icinga2
+
+SLES/openSUSE:
- $ PREFIX=~/.vim
- $ mkdir -p $PREFIX/{syntax,ftdetect}
- $ cp vim/syntax/icinga2.vim $PREFIX/syntax/
- $ cp vim/ftdetect/icinga2.vim $PREFIX/ftdetect/
+ $ zypper install vim-icinga2
+
+Ensure that syntax highlighting is enabled e.g. by editing the user's `vimrc`
+configuration file:
+
+ $ vim ~/.vimrc
+ syntax on
Test it:
$ vim /etc/icinga2/conf.d/templates.conf
+
+
+
### <a id="configuration-syntax-highlighting-nano"></a> Configuration Syntax Highlighting using Nano
-Copy the `/etc/nanorc` sample file to your home directory. Create the `/etc/nano` directory
-and copy the provided `icinga2.nanorc` into it.
+Install the package `nano-icinga2` with your distribution's package manager.
- $ cp /etc/nanorc ~/.nanorc
+Debian/Ubuntu:
+
+**Note:** The syntax files are installed with the `icinga2-common` package already.
+
+RHEL/CentOS/Fedora:
+
+ $ yum install nano-icinga2
+
+SLES/openSUSE:
+
+ $ zypper install nano-icinga2
- # mkdir -p /etc/nano
- # cp icinga2.nanorc /etc/nano/
+Copy the `/etc/nanorc` sample file to your home directory.
-Then include the icinga2.nanorc file in your ~/.nanorc by adding the following line:
+ $ cp /etc/nanorc ~/.nanorc
+
+Include the `icinga2.nanorc` file.
$ vim ~/.nanorc
## Icinga 2
- include "/etc/nano/icinga2.nanorc"
+ include "/usr/share/nano/icinga2.nanorc"
Test it:
$ nano /etc/icinga2/conf.d/templates.conf
+
-## <a id="setting-up-the-user-interface"></a> Setting up Icinga Web 2
+## <a id="setting-up-icingaweb2"></a> Setting up Icinga Web 2
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](15-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.
+This chapter explains how to set up Icinga Web 2.
The DB IDO (Database Icinga Data Output) modules for Icinga 2 take care of
exporting all configuration and status information into a database. The IDO
# chkconfig mysqld on
# service mysqld start
+FreeBSD:
+
+ # pkg install mysql56-server
+ # sysrc mysql_enable=yes
+ # service mysql-server restart
+ # mysql_secure_installation
+
#### <a id="installing-database-mysql-modules"></a> Installing the IDO modules for MySQL
The next step is to install the `icinga2-ido-mysql` package using your
# zypper install icinga2-ido-mysql
+FreeBSD:
+
+On FreeBSD the IDO modules for MySQL are included with the icinga2 package
+and located at /usr/local/share/icinga2-ido-mysql/schema/mysql.sql
> **Note**
>
# mysql -u root -p
mysql> CREATE DATABASE icinga;
- GRANT SELECT, INSERT, UPDATE, DELETE, DROP, CREATE VIEW, INDEX, EXECUTE ON icinga.* TO 'icinga'@'localhost' IDENTIFIED BY 'icinga';
+ mysql> GRANT SELECT, INSERT, UPDATE, DELETE, DROP, CREATE VIEW, INDEX, EXECUTE ON icinga.* TO 'icinga'@'localhost' IDENTIFIED BY 'icinga';
+ mysql> quit
+
+
After creating the database you can import the Icinga 2 IDO schema using the
following command:
# systemctl restart icinga2
+FreeBSD:
+
+ # service icinga2 restart
+
### <a id="configuring-db-ido-postgresql"></a> Configuring DB IDO PostgreSQL
#### <a id="installing-database-postgresql-server"></a> Installing PostgreSQL database server
RHEL/CentOS 7:
# yum install postgresql-server postgresql
- # postgresql-setup --initdb
+ # postgresql-setup initdb
# systemctl enable postgresql
# systemctl start postgresql
# chkconfig postgresql on
# service postgresql start
+FreeBSD:
+
+ # pkg install postgresql93-server
+ # sysrc postgresql_enable=yes
+ # service postgresql start
+
#### <a id="installing-database-postgresql-modules"></a> Installing the IDO modules for PostgreSQL
The next step is to install the `icinga2-ido-pgsql` package using your
# zypper install icinga2-ido-pgsql
+FreeBSD:
+
+On FreeBSD the IDO modules for PostgreSQL are included with the icinga2 package
+and located at /usr/local/share/icinga2-ido-pgsql/schema/pgsql.sql
+
> **Note**
>
> Upstream Debian packages provide a database configuration wizard by default.
Set up a PostgreSQL database for Icinga 2:
# cd /tmp
- # sudo -u postgres psql -c "CREATE ROLE icinga WITH LOGIN PASSWORD 'icinga'";
+ # sudo -u postgres psql -c "CREATE ROLE icinga WITH LOGIN PASSWORD 'icinga'"
# sudo -u postgres createdb -O icinga -E UTF8 icinga
# sudo -u postgres createlang plpgsql icinga
> **Note**
>
> When using PostgreSQL 9.x you can omit the `createlang` command.
+> Also it is assumed here that your locale is set to utf-8, you may run into
+> problems otherwise.
-Locate your pg_hba.conf (Debian: `/etc/postgresql/*/main/pg_hba.conf`,
+Locate your pg\_hba.conf (Debian: `/etc/postgresql/*/main/pg_hba.conf`,
RHEL/SUSE: `/var/lib/pgsql/data/pg_hba.conf`), add the icinga user with md5
authentication method and restart the postgresql server.
- # vim /var/lib/pgsql/data/pg_hba.conf
-
# icinga
local icinga icinga md5
host icinga icinga 127.0.0.1/32 md5
# export PGPASSWORD=icinga
# psql -U icinga -d icinga < /usr/share/icinga2-ido-pgsql/schema/pgsql.sql
+
+
#### <a id="enabling-ido-postgresql"></a> Enabling the IDO PostgreSQL module
After enabling the ido-pgsql feature you have to restart Icinga 2:
-Debian/Ubuntu, RHEL/CentOS 6 and SUSE:
+Debian/Ubuntu, RHEL/CentOS 6, SUSE and FreeBSD:
# service icinga2 restart
# chkconfig on
# service apache2 start
+FreeBSD (nginx, but you could also use the apache24 package):
+
+ # pkg install nginx php56-gettext php56-ldap php56-openssl php56-mysql php56-pdo_mysql php56-pgsql php56-pdo_pgsql php56-sockets php56-gd pecl-imagick pecl-intl
+ # sysrc php_fpm_enable=yes
+ # sysrc nginx_enable=yes
+ # sed -i '' "s/listen\ =\ 127.0.0.1:9000/listen\ =\ \/var\/run\/php5-fpm.sock/" /usr/local/etc/php-fpm.conf
+ # sed -i '' "s/;listen.owner/listen.owner/" /usr/local/etc/php-fpm.conf
+ # sed -i '' "s/;listen.group/listen.group/" /usr/local/etc/php-fpm.conf
+ # sed -i '' "s/;listen.mode/listen.mode/" /usr/local/etc/php-fpm.conf
+ # service php-fpm start
+ # service nginx start
+
### <a id="icinga2-user-interface-firewall-rules"></a> Firewall Rules
Example:
# firewall-cmd --add-service=http
# firewall-cmd --permanent --add-service=http
+FreeBSD:
+Please consult the [FreeBSD Handbook](https://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/firewalls.html) how to configure one of FreeBSD's firewalls.
+
### <a id="setting-up-external-command-pipe"></a> Setting Up External Command Pipe
# systemctl restart icinga2
+FreeBSD:
+
+ # service icinga2 restart
+
By default the command pipe file is owned by the group `icingacmd` with
read/write permissions. Add your webserver's user to the group `icingacmd` to
enable sending commands to Icinga 2 through your web interface:
# usermod -a -G icingacmd www-data
+FreeBSD:
+On FreeBSD the rw directory is owned by the group `www`. You do not need to add the
+user `icinga` to the group `www`.
+
Debian packages use `nagios` as the default user and group name. Therefore
change `icingacmd` to `nagios`.
The webserver's user is different between distributions so you might have to
change `www-data` to `wwwrun`, `www`, or `apache`.
-Change "www-data" to the user you're using to run queries.
+Change `www-data` to the user you're using to run queries.
You can verify that the user has been successfully added to the `icingacmd`
group using the `id` command:
$ id <your-webserver-user>
+
-### <a id="setting-up-icingaweb2"></a> Installing up Icinga Web 2
+### <a id="installing-icingaweb2"></a> Installing Icinga Web 2
-Please consult the [installation documentation](https://github.com/Icinga/icingaweb2/blob/master/doc/installation.md)
+Please consult the [installation documentation](https://github.com/Icinga/icingaweb2/blob/master/doc/02-Installation.md)
for further instructions on how to install Icinga Web 2.
projects / icinga2 / blobdiff