1 # Getting Started <a id="getting-started"></a>
3 This tutorial is a step-by-step introduction to installing [Icinga 2](02-getting-started.md#setting-up-icinga2)
4 and [Icinga Web 2](02-getting-started.md#setting-up-icingaweb2).
5 It assumes that you are familiar with the operating system you're using to install Icinga 2.
7 In case you are upgrading an existing setup, please ensure to
8 follow the [upgrade documentation](16-upgrading-icinga-2.md#upgrading-icinga-2).
10 ## Setting up Icinga 2 <a id="setting-up-icinga2"></a>
12 First off you have to install Icinga 2. The preferred way of doing this
13 is to use the official package repositories depending on which operating system
14 and distribution you are running.
16 Distribution | Repository
17 ------------------------|---------------------------
18 Debian | [Icinga Repository](https://packages.icinga.com/debian/)
19 Ubuntu | [Icinga Repository](https://packages.icinga.com/ubuntu/)
20 RHEL/CentOS | [Icinga Repository](https://packages.icinga.com/epel/)
21 openSUSE | [Icinga Repository](https://packages.icinga.com/openSUSE/)
22 SLES | [Icinga Repository](https://packages.icinga.com/SUSE/)
23 Gentoo | [Upstream](https://packages.gentoo.org/package/net-analyzer/icinga2)
24 FreeBSD | [Upstream](https://www.freshports.org/net-mgmt/icinga2)
25 OpenBSD | [Upstream](http://ports.su/net/icinga/core2,-main)
26 ArchLinux | [Upstream](https://aur.archlinux.org/packages/icinga2)
27 Alpine Linux | [Upstream](https://pkgs.alpinelinux.org/package/edge/community/x86_64/icinga2)
29 Packages for distributions other than the ones listed above may also be
30 available. Please contact your distribution packagers.
32 ### Package Repositories <a id="package-repositories"></a>
34 You need to add the Icinga repository to your package management configuration.
35 Below is a list with examples for the various distributions.
39 # wget -O - https://packages.icinga.com/icinga.key | apt-key add -
40 # echo 'deb https://packages.icinga.com/debian icinga-stretch main' >/etc/apt/sources.list.d/icinga.list
45 # wget -O - https://packages.icinga.com/icinga.key | apt-key add -
46 # echo 'deb https://packages.icinga.com/ubuntu icinga-xenial main' >/etc/apt/sources.list.d/icinga.list
51 yum install https://packages.icinga.com/epel/icinga-rpm-release-7-latest.noarch.rpm
55 yum install https://packages.icinga.com/epel/icinga-rpm-release-6-latest.noarch.rpm
59 dnf install https://packages.icinga.com/fedora/icinga-rpm-release-26-latest.noarch.rpm
63 dnf install https://packages.icinga.com/fedora/icinga-rpm-release-25-latest.noarch.rpm
67 # zypper ar https://packages.icinga.com/SUSE/ICINGA-release-11.repo
72 # zypper ar https://packages.icinga.com/SUSE/ICINGA-release.repo
77 # zypper ar https://packages.icinga.com/openSUSE/ICINGA-release.repo
83 # echo "http://dl-cdn.alpinelinux.org/alpine/edge/community" >> /etc/apk/repositories
86 #### RHEL/CentOS EPEL Repository <a id="package-repositories-rhel-epel"></a>
88 The packages for RHEL/CentOS depend on other packages which are distributed
89 as part of the [EPEL repository](https://fedoraproject.org/wiki/EPEL).
93 yum install epel-release
95 If you are using RHEL you need to enable the `optional` repository and then install
96 the [EPEL rpm package](https://fedoraproject.org/wiki/EPEL#How_can_I_use_these_extra_packages.3F).
98 #### SLES Security Repository <a id="package-repositories-sles-security"></a>
100 The packages for SLES 11 depend on the `openssl1` package which is distributed
101 as part of the [SLES 11 Security Module](https://www.suse.com/communities/conversations/introducing-the-suse-linux-enterprise-11-security-module/).
103 #### SLES 12 SDK <a id="package-sles-sdk"></a>
105 Icinga 2 requires the `libboost_chrono1_54_0` package from the `SLES 12 SDK` repository. Refer to the SUSE Enterprise
106 Linux documentation for further information.
108 #### Alpine Linux Notes <a id="package-repositories-alpine-notes"></a>
110 The example provided assumes that you are running Alpine edge, which is the -dev branch and is a rolling release.
111 If you are using a stable version please "pin" the edge repository on the latest Icinga 2 package version.
112 In order to correctly manage your repository, please follow
113 [these instructions](https://wiki.alpinelinux.org/wiki/Alpine_Linux_package_management)
115 ### Installing Icinga 2 <a id="installing-icinga2"></a>
117 You can install Icinga 2 by using your distribution's package manager
118 to install the `icinga2` package.
122 # apt-get install icinga2
126 # yum install icinga2
127 # chkconfig icinga2 on
128 # service icinga2 start
130 RHEL/CentOS 7 and Fedora:
132 # yum install icinga2
133 # systemctl enable icinga2
134 # systemctl start icinga2
138 # zypper install icinga2
142 # pkg install icinga2
149 ### Enabled Features during Installation <a id="installation-enabled-features"></a>
151 The default installation will enable three features required for a basic
152 Icinga 2 installation:
154 * `checker` for executing checks
155 * `notification` for sending notifications
156 * `mainlog` for writing the `icinga2.log` file
158 You can verify that by calling `icinga2 feature list`
159 [CLI command](11-cli-commands.md#cli-command-feature) to see which features are
160 enabled and disabled.
162 # icinga2 feature list
163 Disabled features: api command compatlog debuglog gelf graphite icingastatus ido-mysql ido-pgsql influxdb livestatus opentsdb perfdata statusdata syslog
164 Enabled features: checker mainlog notification
167 ### Installation Paths <a id="installation-paths"></a>
169 By default Icinga 2 uses the following files and directories:
172 ----------------------------------------------|------------------------------------
173 /etc/icinga2 | Contains Icinga 2 configuration files.
174 /usr/lib/systemd/system/icinga2.service | The Icinga 2 Systemd service file on systems using Systemd.
175 /etc/systemd/system/icinga2.service.d/limits.conf | On distributions with Systemd >227, additional service limits are required.
176 /etc/init.d/icinga2 | The Icinga 2 init script on systems using SysVinit or OpenRC.
177 /usr/sbin/icinga2 | Shell wrapper for the Icinga 2 binary.
178 /usr/lib\*/icinga2 | Libraries and the Icinga 2 binary (use `find /usr -type f -name icinga2` to locate the binary path).
179 /usr/share/doc/icinga2 | Documentation files that come with Icinga 2.
180 /usr/share/icinga2/include | The Icinga Template Library and plugin command configuration.
181 /var/lib/icinga2 | Icinga 2 state file, cluster log, master CA, node certificates and configuration files (cluster, api).
182 /var/run/icinga2 | PID file.
183 /var/run/icinga2/cmd | Command pipe and Livestatus socket.
184 /var/cache/icinga2 | status.dat/objects.cache, icinga2.debug files.
185 /var/spool/icinga2 | Used for performance data spool files.
186 /var/log/icinga2 | Log file location and compat/ directory for the CompatLogger feature.
188 FreeBSD uses slightly different paths:
190 By default Icinga 2 uses the following files and directories:
193 ------------------------------------|------------------------------------
194 /usr/local/etc/icinga2 | Contains Icinga 2 configuration files.
195 /usr/local/etc/rc.d/icinga2 | The Icinga 2 init script.
196 /usr/local/sbin/icinga2 | Shell wrapper for the Icinga 2 binary.
197 /usr/local/lib/icinga2 | Libraries and the Icinga 2 binary.
198 /usr/local/share/doc/icinga2 | Documentation files that come with Icinga 2.
199 /usr/local/share/icinga2/include | The Icinga Template Library and plugin command configuration.
200 /var/lib/icinga2 | Icinga 2 state file, cluster log, master CA, node certificates and configuration files (cluster, api).
201 /var/run/icinga2 | PID file.
202 /var/run/icinga2/cmd | Command pipe and Livestatus socket.
203 /var/cache/icinga2 | status.dat/objects.cache, icinga2.debug files.
204 /var/spool/icinga2 | Used for performance data spool files.
205 /var/log/icinga2 | Log file location and compat/ directory for the CompatLogger feature.
207 ## Setting up Check Plugins <a id="setting-up-check-plugins"></a>
209 Without plugins Icinga 2 does not know how to check external services. The
210 [Monitoring Plugins Project](https://www.monitoring-plugins.org/) provides
211 an extensive set of plugins which can be used with Icinga 2 to check whether
212 services are working properly.
214 These plugins are required to make the [example configuration](04-configuring-icinga-2.md#configuring-icinga2-overview)
217 For your convenience here is a list of package names for some of the more
218 popular operating systems/distributions:
220 OS/Distribution | Package Name | Repository | Installation Path
221 -----------------------|--------------------|---------------------------|----------------------------
222 RHEL/CentOS | nagios-plugins-all | [EPEL](https://fedoraproject.org/wiki/EPEL) | /usr/lib/nagios/plugins or /usr/lib64/nagios/plugins
223 SLES/OpenSUSE | monitoring-plugins | [server:monitoring](https://build.opensuse.org/project/repositories/server:monitoring) | /usr/lib/nagios/plugins
224 Debian/Ubuntu | monitoring-plugins | - | /usr/lib/nagios/plugins
225 FreeBSD | monitoring-plugins | - | /usr/local/libexec/nagios
226 Alpine Linux | monitoring-plugins | - | /usr/lib/monitoring-plugins
227 OS X | nagios-plugins | [MacPorts](https://www.macports.org), [Homebrew](https://brew.sh) | /opt/local/libexec or /usr/local/sbin
229 The recommended way of installing these standard plugins is to use your
230 distribution's package manager.
234 # apt-get install monitoring-plugins
238 # yum install nagios-plugins-all
240 The packages for RHEL/CentOS depend on other packages which are distributed
241 as part of the [EPEL repository](https://fedoraproject.org/wiki/EPEL). Please
242 make sure to enable this repository by following
243 [these instructions](https://fedoraproject.org/wiki/EPEL#How_can_I_use_these_extra_packages.3F).
247 # dnf install nagios-plugins-all
251 # zypper install monitoring-plugins
253 The packages for SLES/OpenSUSE depend on other packages which are distributed
254 as part of the [server:monitoring repository](https://build.opensuse.org/project/repositories/server:monitoring).
255 Please make sure to enable this repository beforehand.
259 # pkg install monitoring-plugins
263 # apk add monitoring-plugins
265 Note: For Alpine you don't need to explicitly add the `monitoring-plugins` package since it is a dependency of
266 `icinga2` and is pulled automatically.
268 Depending on which directory your plugins are installed into you may need to
269 update the global `PluginDir` constant in your [Icinga 2 configuration](04-configuring-icinga-2.md#constants-conf).
270 This constant is used by the check command definitions contained in the Icinga Template Library
271 to determine where to find the plugin binaries.
275 > Please refer to the [service monitoring](05-service-monitoring.md#service-monitoring-plugins) chapter for details about how to integrate
276 > additional check plugins into your Icinga 2 setup.
278 ## Running Icinga 2 <a id="running-icinga2"></a>
280 ### Init Script <a id="init-script"></a>
282 Icinga 2's init script is installed in `/etc/init.d/icinga2` (`/usr/local/etc/rc.d/icinga2` on FreeBSD) by default:
284 # /etc/init.d/icinga2
285 Usage: /etc/init.d/icinga2 {start|stop|restart|reload|checkconfig|status}
287 The init script supports the following actions:
289 Command | Description
290 --------------------|------------------------
291 start | The `start` action starts the Icinga 2 daemon.
292 stop | The `stop` action stops the Icinga 2 daemon.
293 restart | The `restart` action is a shortcut for running the `stop` action followed by `start`.
294 reload | The `reload` action sends the `HUP` signal to Icinga 2 which causes it to restart. Unlike the `restart` action `reload` does not wait until Icinga 2 has restarted.
295 checkconfig | The `checkconfig` action checks if the `/etc/icinga2/icinga2.conf` configuration file contains any errors.
296 status | The `status` action checks if Icinga 2 is running.
298 By default, the Icinga 2 daemon is running as `icinga` user and group
299 using the init script. Using Debian packages the user and group are set to
300 `nagios` for historical reasons.
302 ### Systemd Service <a id="systemd-service"></a>
304 Some distributions (e.g. Fedora, openSUSE and RHEL/CentOS 7) use Systemd. The
305 Icinga 2 packages automatically install the necessary Systemd unit files.
307 The Icinga 2 Systemd service can be (re-)started, reloaded, stopped and also
308 queried for its current status.
310 # systemctl status icinga2
311 icinga2.service - Icinga host/service/network monitoring system
312 Loaded: loaded (/usr/lib/systemd/system/icinga2.service; disabled)
313 Active: active (running) since Mi 2014-07-23 13:39:38 CEST; 15s ago
314 Process: 21692 ExecStart=/usr/sbin/icinga2 -c ${ICINGA2_CONFIG_FILE} -d -e ${ICINGA2_ERROR_LOG} -u ${ICINGA2_USER} -g ${ICINGA2_GROUP} (code=exited, status=0/SUCCESS)
315 Process: 21674 ExecStartPre=/usr/sbin/icinga2-prepare-dirs /etc/sysconfig/icinga2 (code=exited, status=0/SUCCESS)
316 Main PID: 21727 (icinga2)
317 CGroup: /system.slice/icinga2.service
318 21727 /usr/sbin/icinga2 -c /etc/icinga2/icinga2.conf -d -e /var/log/icinga2/error.log -u icinga -g icinga --no-stack-rlimit
320 Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 309 Service(s).
321 Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 1 User(s).
322 Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 15 Notification(s).
323 Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 4 ScheduledDowntime(s).
324 Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 1 UserGroup(s).
325 Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 1 IcingaApplication(s).
326 Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 8 Dependency(s).
327 Jul 23 13:39:38 nbmif systemd[1]: Started Icinga host/service/network monitoring system.
329 The `systemctl` command supports the following actions:
331 Command | Description
332 --------------------|------------------------
333 start | The `start` action starts the Icinga 2 daemon.
334 stop | The `stop` action stops the Icinga 2 daemon.
335 restart | The `restart` action is a shortcut for running the `stop` action followed by `start`.
336 reload | The `reload` action sends the `HUP` signal to Icinga 2 which causes it to restart. Unlike the `restart` action `reload` does not wait until Icinga 2 has restarted.
337 status | The `status` action checks if Icinga 2 is running.
338 enable | The `enable` action enables the service being started at system boot time (similar to `chkconfig`)
342 # systemctl enable icinga2
344 # systemctl restart icinga2
345 Job for icinga2.service failed. See 'systemctl status icinga2.service' and 'journalctl -xn' for details.
347 If you're stuck with configuration errors, you can manually invoke the
348 [configuration validation](11-cli-commands.md#config-validation).
352 > If you are running into fork errors with Systemd enabled distributions,
353 > please check the [troubleshooting chapter](15-troubleshooting.md#check-fork-errors).
355 ### FreeBSD <a id="running-icinga2-freebsd"></a>
357 On FreeBSD you need to enable icinga2 in your rc.conf
359 # sysrc icinga2_enable=yes
361 # service icinga2 restart
364 ### SELinux <a id="running-icinga2-selinux"></a>
366 SELinux is a mandatory access control (MAC) system on Linux which adds
367 a fine-grained permission system for access to all system resources such
368 as files, devices, networks and inter-process communication.
370 Icinga 2 provides its own SELinux policy. `icinga2-selinux` is a policy package
371 for Red Hat Enterprise Linux 7 and derivatives. The package runs the targeted policy
372 which confines Icinga 2 including enabled features and running commands.
377 yum install icinga2-selinux
383 dnf install icinga2-selinux
386 Read more about SELinux in [this chapter](22-selinux.md#selinux).
388 ## Configuration Syntax Highlighting <a id="configuration-syntax-highlighting"></a>
390 Icinga 2 ships configuration examples for syntax highlighting using the `vim` and `nano` editors.
391 The RHEL and SUSE package `icinga2-common` installs these files into `/usr/share/doc/icinga2-common-[x.x.x]/syntax`
392 (where `[x.x.x]` is the version number, e.g. `2.4.3` or `2.4.4`). Sources provide these files in `tools/syntax`.
393 On Debian systems the `icinga2-common` package provides only the Nano configuration file (`/usr/share/nano/icinga2.nanorc`);
394 to obtain the Vim configuration, please install the extra package `vim-icinga2`. The files are located in `/usr/share/vim/addons`.
396 ### Configuration Syntax Highlighting using Vim <a id="configuration-syntax-highlighting-vim"></a>
398 Install the package `vim-icinga2` with your distribution's package manager.
402 # apt-get install vim-icinga2 vim-addon-manager
403 # vim-addon-manager -w install icinga2
404 Info: installing removed addon 'icinga2' to /var/lib/vim/addons
408 # yum install vim-icinga2
412 # zypper install vim-icinga2
416 # apk add icinga2-vim
418 Ensure that syntax highlighting is enabled e.g. by editing the user's `vimrc`
426 # vim /etc/icinga2/conf.d/templates.conf
428 ![Vim with syntax highlighting](images/getting-started/vim-syntax.png "Vim with Icinga 2 syntax highlighting")
431 ### Configuration Syntax Highlighting using Nano <a id="configuration-syntax-highlighting-nano"></a>
433 Install the package `nano-icinga2` with your distribution's package manager.
437 **Note:** The syntax files are installed with the `icinga2-common` package already.
441 # yum install nano-icinga2
445 # zypper install nano-icinga2
447 Copy the `/etc/nanorc` sample file to your home directory.
449 $ cp /etc/nanorc ~/.nanorc
451 Include the `icinga2.nanorc` file.
456 include "/usr/share/nano/icinga2.nanorc"
460 $ nano /etc/icinga2/conf.d/templates.conf
462 ![Nano with syntax highlighting](images/getting-started/nano-syntax.png "Nano with Icinga 2 syntax highlighting")
464 ## Setting up Icinga Web 2 <a id="setting-up-icingaweb2"></a>
466 Icinga 2 can be used with Icinga Web 2 and a number of other web interfaces.
467 This chapter explains how to set up Icinga Web 2.
469 The DB IDO (Database Icinga Data Output) modules for Icinga 2 take care of
470 exporting all configuration and status information into a database. The IDO
471 database is used by a number of projects including
472 [Icinga Web 2](02-getting-started.md#setting-up-icingaweb2), Icinga Reporting
475 There is a separate module for each database backend. At present support for
476 both MySQL and PostgreSQL has been implemented.
478 Please choose whether to install [MySQL](02-getting-started.md#configuring-db-ido-mysql) or
479 [PostgreSQL](02-getting-started.md#configuring-db-ido-postgresql).
481 ### Configuring DB IDO MySQL <a id="configuring-db-ido-mysql"></a>
483 #### Installing MySQL database server <a id="installing-database-mysql-server"></a>
487 # apt-get install mysql-server mysql-client
488 # mysql_secure_installation
492 # yum install mysql-server mysql
493 # chkconfig mysqld on
494 # service mysqld start
495 # mysql_secure_installation
497 RHEL/CentOS 7 and Fedora:
499 # yum install mariadb-server mariadb
500 # systemctl enable mariadb
501 # systemctl start mariadb
502 # mysql_secure_installation
506 # zypper install mysql mysql-client
507 # chkconfig mysqld on
508 # service mysqld start
512 # pkg install mysql56-server
513 # sysrc mysql_enable=yes
514 # service mysql-server restart
515 # mysql_secure_installation
520 # rc-service mariadb setup
521 # rc-update add mariadb default
522 # rc-service mariadb start
524 #### Installing the IDO modules for MySQL <a id="installing-database-mysql-modules"></a>
526 The next step is to install the `icinga2-ido-mysql` package using your
527 distribution's package manager.
531 # apt-get install icinga2-ido-mysql
535 # yum install icinga2-ido-mysql
539 # zypper install icinga2-ido-mysql
543 On FreeBSD the IDO modules for MySQL are included with the icinga2 package
544 and located at /usr/local/share/icinga2-ido-mysql/schema/mysql.sql
548 On Alpine Linux the IDO modules for MySQL are included with the `icinga2` package
549 and located at /usr/share/icinga2-ido-mysql/schema/mysql.sql
553 > The Debian/Ubuntu packages provide a database configuration wizard by
554 > default. You can skip the automated setup and install/upgrade the
555 > database manually if you prefer that.
557 #### Setting up the MySQL database <a id="setting-up-mysql-db"></a>
559 Set up a MySQL database for Icinga 2:
563 mysql> CREATE DATABASE icinga;
564 mysql> GRANT SELECT, INSERT, UPDATE, DELETE, DROP, CREATE VIEW, INDEX, EXECUTE ON icinga.* TO 'icinga'@'localhost' IDENTIFIED BY 'icinga';
567 ![setting up the database on CentOS 7](images/getting-started/mariadb-centos7.png "Setting up the database on CentOS 7")
569 After creating the database you can import the Icinga 2 IDO schema using the
572 # mysql -u root -p icinga < /usr/share/icinga2-ido-mysql/schema/mysql.sql
575 #### Enabling the IDO MySQL module <a id="enabling-ido-mysql"></a>
577 The package provides a new configuration file that is installed in
578 `/etc/icinga2/features-available/ido-mysql.conf`. You will need to
579 update the database credentials in this file.
581 All available attributes are explained in the
582 [IdoMysqlConnection object](09-object-types.md#objecttype-idomysqlconnection)
585 You can enable the `ido-mysql` feature configuration file using
586 `icinga2 feature enable`:
588 # icinga2 feature enable ido-mysql
589 Module 'ido-mysql' was enabled.
590 Make sure to restart Icinga 2 for these changes to take effect.
592 After enabling the ido-mysql feature you have to restart Icinga 2:
594 RHEL/CentOS 7/Fedora, SLES 12, Debian Jessie/Stretch, Ubuntu Xenial:
596 # systemctl restart icinga2
598 Debian/Ubuntu, RHEL/CentOS 6 and SUSE 11:
600 # service icinga2 restart
604 # service icinga2 restart
608 # rc-service icinga2 restart
610 Continue with the [webserver setup](02-getting-started.md#icinga2-user-interface-webserver).
612 ### Configuring DB IDO PostgreSQL <a id="configuring-db-ido-postgresql"></a>
614 #### Installing PostgreSQL database server <a id="installing-database-postgresql-server"></a>
618 # apt-get install postgresql
622 # yum install postgresql-server postgresql
623 # chkconfig postgresql on
624 # service postgresql start
628 # yum install postgresql-server postgresql
629 # postgresql-setup initdb
630 # systemctl enable postgresql
631 # systemctl start postgresql
635 # zypper install postgresql postgresql-server
636 # chkconfig postgresql on
637 # service postgresql start
641 # pkg install postgresql93-server
642 # sysrc postgresql_enable=yes
643 # service postgresql start
648 # rc-update add postgresql default
649 # rc-service postgresql setup
650 # rc-service postgresql start
652 #### Installing the IDO modules for PostgreSQL <a id="installing-database-postgresql-modules"></a>
654 The next step is to install the `icinga2-ido-pgsql` package using your
655 distribution's package manager.
659 # apt-get install icinga2-ido-pgsql
663 # yum install icinga2-ido-pgsql
667 # zypper install icinga2-ido-pgsql
671 On FreeBSD the IDO modules for PostgreSQL are included with the icinga2 package
672 and located at /usr/local/share/icinga2-ido-pgsql/schema/pgsql.sql
676 On Alpine Linux the IDO modules for PostgreSQL are included with the `icinga2` package
677 and located at /usr/share/icinga2-ido-pgsql/schema/pgsql.sql
681 > Upstream Debian packages provide a database configuration wizard by default.
682 > You can skip the automated setup and install/upgrade the database manually
683 > if you prefer that.
685 #### Setting up the PostgreSQL database
687 Set up a PostgreSQL database for Icinga 2:
690 # sudo -u postgres psql -c "CREATE ROLE icinga WITH LOGIN PASSWORD 'icinga'"
691 # sudo -u postgres createdb -O icinga -E UTF8 icinga
692 # sudo -u postgres createlang plpgsql icinga
696 > When using PostgreSQL 9.x you can omit the `createlang` command.
697 > Also it is assumed here that your locale is set to utf-8, you may run into
698 > problems otherwise.
700 Locate your pg\_hba.conf (Debian: `/etc/postgresql/*/main/pg_hba.conf`,
701 RHEL/SUSE: `/var/lib/pgsql/data/pg_hba.conf`), add the icinga user with md5
702 authentication method and restart the postgresql server.
705 local icinga icinga md5
706 host icinga icinga 127.0.0.1/32 md5
707 host icinga icinga ::1/128 md5
709 # "local" is for Unix domain socket connections only
711 # IPv4 local connections:
712 host all all 127.0.0.1/32 ident
713 # IPv6 local connections:
714 host all all ::1/128 ident
716 # service postgresql restart
719 After creating the database and permissions you can import the Icinga 2 IDO
720 schema using the following command:
722 # export PGPASSWORD=icinga
723 # psql -U icinga -d icinga < /usr/share/icinga2-ido-pgsql/schema/pgsql.sql
725 ![importing the Icinga 2 IDO schema](images/getting-started/postgr-import-ido.png "Importing the Icinga 2 IDO schema on Debian Jessie")
728 #### Enabling the IDO PostgreSQL module <a id="enabling-ido-postgresql"></a>
730 The package provides a new configuration file that is installed in
731 `/etc/icinga2/features-available/ido-pgsql.conf`. You will need to update
732 the database credentials in this file.
734 All available attributes are explained in the
735 [IdoPgsqlConnection object](09-object-types.md#objecttype-idopgsqlconnection)
738 You can enable the `ido-pgsql` feature configuration file using
739 `icinga2 feature enable`:
741 # icinga2 feature enable ido-pgsql
742 Module 'ido-pgsql' was enabled.
743 Make sure to restart Icinga 2 for these changes to take effect.
745 After enabling the ido-pgsql feature you have to restart Icinga 2:
747 RHEL/CentOS 7/Fedora, SLES 12, Debian Jessie/Stretch, Ubuntu Xenial:
749 # systemctl restart icinga2
751 Debian/Ubuntu, RHEL/CentOS 6, SUSE and FreeBSD:
753 # service icinga2 restart
757 # service icinga2 restart
761 # rc-service icinga2 restart
763 Continue with the [webserver setup](02-getting-started.md#icinga2-user-interface-webserver).
765 ### Webserver <a id="icinga2-user-interface-webserver"></a>
769 # apt-get install apache2
775 # service httpd start
777 RHEL/CentOS 7, Fedora:
780 # systemctl enable httpd
781 # systemctl start httpd
785 # zypper install apache2
787 # service apache2 start
789 FreeBSD (nginx, but you could also use the apache24 package):
791 # 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
792 # sysrc php_fpm_enable=yes
793 # sysrc nginx_enable=yes
794 # sed -i '' "s/listen\ =\ 127.0.0.1:9000/listen\ =\ \/var\/run\/php5-fpm.sock/" /usr/local/etc/php-fpm.conf
795 # sed -i '' "s/;listen.owner/listen.owner/" /usr/local/etc/php-fpm.conf
796 # sed -i '' "s/;listen.group/listen.group/" /usr/local/etc/php-fpm.conf
797 # sed -i '' "s/;listen.mode/listen.mode/" /usr/local/etc/php-fpm.conf
798 # service php-fpm start
799 # service nginx start
803 # apk add apache2 php7-apache2
804 # sed -i -e "s/^#LoadModule rewrite_module/LoadModule rewrite_module/" /etc/apache2/httpd.conf
805 # rc-update add apache2 default
806 # rc-service apache2 start
808 ### Firewall Rules <a id="icinga2-user-interface-firewall-rules"></a>
812 # iptables -A INPUT -p tcp -m tcp --dport 80 -j ACCEPT
813 # service iptables save
815 RHEL/CentOS 7 specific:
817 # firewall-cmd --add-service=http
818 # firewall-cmd --permanent --add-service=http
821 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.
824 ### Setting Up Icinga 2 REST API <a id="setting-up-rest-api"></a>
826 Icinga Web 2 and other web interfaces require the [REST API](12-icinga2-api.md#icinga2-api-setup)
827 to send actions (reschedule check, etc.) and query object details.
829 You can run the CLI command `icinga2 api setup` to enable the
830 `api` [feature](11-cli-commands.md#enable-features) and set up
831 certificates as well as a new API user `root` with an auto-generated password in the
832 `/etc/icinga2/conf.d/api-users.conf` configuration file:
836 Edit the `api-users.conf` file and add a new ApiUser object. Specify the [permissions](12-icinga2-api.md#icinga2-api-permissions)
837 attribute with minimal permissions required by Icinga Web 2.
839 # vim /etc/icinga2/conf.d/api-users.conf
841 object ApiUser "icingaweb2" {
842 password = "Wijsn8Z9eRs5E25d"
843 permissions = [ "status/query", "actions/*", "objects/modify/*", "objects/query/*" ]
846 Make sure to restart Icinga 2 to activate the configuration.
848 RHEL/CentOS 7/Fedora, SLES 12, Debian Jessie/Stretch, Ubuntu Xenial:
850 # systemctl restart icinga2
852 Debian/Ubuntu, RHEL/CentOS 6 and SUSE:
854 # service icinga2 restart
858 # service icinga2 restart
862 # rc-service icinga2 restart
864 ### Installing Icinga Web 2 <a id="installing-icingaweb2"></a>
866 Please consult the [installation documentation](https://github.com/Icinga/icingaweb2/blob/master/doc/02-Installation.md)
867 for further instructions on how to install Icinga Web 2.
869 The Icinga 2 API can be defined as [command transport](https://github.com/Icinga/icingaweb2/blob/master/modules/monitoring/doc/commandtransports.md)
870 in Icinga Web 2 >= 2.4.
872 ## Addons <a id="install-addons"></a>
874 A number of additional features are available in the form of addons. A list of
875 popular addons is available in the
876 [Addons and Plugins](13-addons.md#addons) chapter.
878 ## Backup <a id="install-backup"></a>
880 Ensure to include the following in your backups:
882 * Configuration files in `/etc/icinga2`
883 * Certificate files in `/var/lib/icinga2/ca` (Master CA key pair) and `/var/lib/icinga2/certs` (node certificates)
884 * Runtime files in `/var/lib/icinga2`
885 * Optional: IDO database backup