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 ## Setting up Icinga 2 <a id="setting-up-icinga2"></a>
9 First off you have to install Icinga 2. The preferred way of doing this
10 is to use the official package repositories depending on which operating system
11 and distribution you are running.
13 Distribution | Repository
14 ------------------------|---------------------------
15 Debian | [Icinga Repository](https://packages.icinga.com/debian/)
16 Ubuntu | [Icinga Repository](https://packages.icinga.com/ubuntu/)
17 RHEL/CentOS | [Icinga Repository](https://packages.icinga.com/epel/)
18 openSUSE | [Icinga Repository](https://packages.icinga.com/openSUSE/)
19 SLES | [Icinga Repository](https://packages.icinga.com/SUSE/)
20 Gentoo | [Upstream](https://packages.gentoo.org/package/net-analyzer/icinga2)
21 FreeBSD | [Upstream](https://www.freshports.org/net-mgmt/icinga2)
22 OpenBSD | [Upstream](http://ports.su/net/icinga/core2,-main)
23 ArchLinux | [Upstream](https://aur.archlinux.org/packages/icinga2)
24 Alpine Linux | [Upstream](https://pkgs.alpinelinux.org/package/edge/community/x86_64/icinga2)
26 Packages for distributions other than the ones listed above may also be
27 available. Please contact your distribution packagers.
29 ### Package Repositories <a id="package-repositories"></a>
31 You need to add the Icinga repository to your package management configuration.
32 Below is a list with examples for the various distributions.
36 # wget -O - https://packages.icinga.com/icinga.key | apt-key add -
37 # echo 'deb https://packages.icinga.com/debian icinga-stretch main' >/etc/apt/sources.list.d/icinga.list
42 # wget -O - https://packages.icinga.com/icinga.key | apt-key add -
43 # echo 'deb https://packages.icinga.com/ubuntu icinga-xenial main' >/etc/apt/sources.list.d/icinga.list
48 yum install https://packages.icinga.com/epel/icinga-rpm-release-7-latest.noarch.rpm
52 yum install https://packages.icinga.com/epel/icinga-rpm-release-6-latest.noarch.rpm
56 dnf install https://packages.icinga.com/fedora/icinga-rpm-release-26-latest.noarch.rpm
60 dnf install https://packages.icinga.com/fedora/icinga-rpm-release-25-latest.noarch.rpm
64 # zypper ar https://packages.icinga.com/SUSE/ICINGA-release-11.repo
69 # zypper ar https://packages.icinga.com/SUSE/ICINGA-release.repo
74 # zypper ar https://packages.icinga.com/openSUSE/ICINGA-release.repo
80 # echo "http://dl-cdn.alpinelinux.org/alpine/edge/community" >> /etc/apk/repositories
83 #### RHEL/CentOS EPEL Repository <a id="package-repositories-rhel-epel"></a>
85 The packages for RHEL/CentOS depend on other packages which are distributed
86 as part of the [EPEL repository](https://fedoraproject.org/wiki/EPEL).
90 yum install epel-release
92 If you are using RHEL you need enable the `optional` repository and then install
93 the [EPEL rpm package](https://fedoraproject.org/wiki/EPEL#How_can_I_use_these_extra_packages.3F).
95 #### SLES Security Repository <a id="package-repositories-sles-security"></a>
97 The packages for SLES 11 depend on the `openssl1` package which is distributed
98 as part of the [SLES 11 Security Module](https://www.suse.com/communities/conversations/introducing-the-suse-linux-enterprise-11-security-module/).
100 #### SLES 12 SDK <a id="package-sles-sdk"></a>
102 Icinga 2 requires the `libboost_chrono1_54_0` package from the `SLES 12 SDK` repository. Refer to the SUSE Enterprise
103 Linux documentation for further information.
105 #### Alpine Linux Notes <a id="package-repositories-alpine-notes"></a>
107 The example provided suppose that you are running Alpine edge, which is the -dev branch and is a rolling release.
108 If you are using a stable version please "pin" the edge repository on the latest Icinga 2 package version.
109 In order to correctly manage your repository, please follow
110 [these instructions](https://wiki.alpinelinux.org/wiki/Alpine_Linux_package_management)
112 ### Installing Icinga 2 <a id="installing-icinga2"></a>
114 You can install Icinga 2 by using your distribution's package manager
115 to install the `icinga2` package.
119 # apt-get install icinga2
123 # yum install icinga2
124 # chkconfig icinga2 on
125 # service icinga2 start
127 RHEL/CentOS 7 and Fedora:
129 # yum install icinga2
130 # systemctl enable icinga2
131 # systemctl start icinga2
135 # zypper install icinga2
139 # pkg install icinga2
146 ### Enabled Features during Installation <a id="installation-enabled-features"></a>
148 The default installation will enable three features required for a basic
149 Icinga 2 installation:
151 * `checker` for executing checks
152 * `notification` for sending notifications
153 * `mainlog` for writing the `icinga2.log` file
155 You can verify that by calling `icinga2 feature list`
156 [CLI command](11-cli-commands.md#cli-command-feature) to see which features are
157 enabled and disabled.
159 # icinga2 feature list
160 Disabled features: api command compatlog debuglog gelf graphite icingastatus ido-mysql ido-pgsql influxdb livestatus opentsdb perfdata statusdata syslog
161 Enabled features: checker mainlog notification
164 ### Installation Paths <a id="installation-paths"></a>
166 By default Icinga 2 uses the following files and directories:
169 ----------------------------------------------|------------------------------------
170 /etc/icinga2 | Contains Icinga 2 configuration files.
171 /usr/lib/systemd/system/icinga2.service | The Icinga 2 Systemd service file on systems using Systemd.
172 /etc/init.d/icinga2 | The Icinga 2 init script on systems using SysVinit or OpenRC
173 /usr/sbin/icinga2 | Shell wrapper for the Icinga 2 binary.
174 /usr/lib\*/icinga2 | Libraries and the Icinga 2 binary (use `find /usr -type f -name icinga2` to locate the binary path).
175 /usr/share/doc/icinga2 | Documentation files that come with Icinga 2.
176 /usr/share/icinga2/include | The Icinga Template Library and plugin command configuration.
177 /var/run/icinga2 | PID file.
178 /var/run/icinga2/cmd | Command pipe and Livestatus socket.
179 /var/cache/icinga2 | status.dat/objects.cache, icinga2.debug files
180 /var/spool/icinga2 | Used for performance data spool files.
181 /var/lib/icinga2 | Icinga 2 state file, cluster log, local CA and configuration files (cluster, api).
182 /var/log/icinga2 | Log file location and compat/ directory for the CompatLogger feature.
184 FreeBSD uses slightly different paths:
186 By default Icinga 2 uses the following files and directories:
189 ------------------------------------|------------------------------------
190 /usr/local/etc/icinga2 | Contains Icinga 2 configuration files.
191 /usr/local/etc/rc.d/icinga2 | The Icinga 2 init script.
192 /usr/local/sbin/icinga2 | Shell wrapper for the Icinga 2 binary.
193 /usr/local/lib/icinga2 | Libraries and the Icinga 2 binary.
194 /usr/local/share/doc/icinga2 | Documentation files that come with Icinga 2.
195 /usr/local/share/icinga2/include | The Icinga Template Library and plugin command configuration.
196 /var/run/icinga2 | PID file.
197 /var/run/icinga2/cmd | Command pipe and Livestatus socket.
198 /var/cache/icinga2 | status.dat/objects.cache, icinga2.debug files
199 /var/spool/icinga2 | Used for performance data spool files.
200 /var/lib/icinga2 | Icinga 2 state file, cluster log, local CA and configuration files (cluster, api).
201 /var/log/icinga2 | Log file location and compat/ directory for the CompatLogger feature.
203 ## Setting up Check Plugins <a id="setting-up-check-plugins"></a>
205 Without plugins Icinga 2 does not know how to check external services. The
206 [Monitoring Plugins Project](https://www.monitoring-plugins.org/) provides
207 an extensive set of plugins which can be used with Icinga 2 to check whether
208 services are working properly.
210 These plugins are required to make the [example configuration](04-configuring-icinga-2.md#configuring-icinga2-overview)
213 For your convenience here is a list of package names for some of the more
214 popular operating systems/distributions:
216 OS/Distribution | Package Name | Repository | Installation Path
217 -----------------------|--------------------|---------------------------|----------------------------
218 RHEL/CentOS | nagios-plugins-all | [EPEL](https://fedoraproject.org/wiki/EPEL) | /usr/lib/nagios/plugins or /usr/lib64/nagios/plugins
219 SLES/OpenSUSE | monitoring-plugins | [server:monitoring](https://build.opensuse.org/project/repositories/server:monitoring) | /usr/lib/nagios/plugins
220 Debian/Ubuntu | monitoring-plugins | - | /usr/lib/nagios/plugins
221 FreeBSD | monitoring-plugins | - | /usr/local/libexec/nagios
222 Alpine Linux | monitoring-plugins | - | /usr/lib/monitoring-plugins
223 OS X | nagios-plugins | [MacPorts](https://www.macports.org), [Homebrew](https://brew.sh) | /opt/local/libexec or /usr/local/sbin
225 The recommended way of installing these standard plugins is to use your
226 distribution's package manager.
230 # apt-get install monitoring-plugins
234 # yum install nagios-plugins-all
236 The packages for RHEL/CentOS depend on other packages which are distributed
237 as part of the [EPEL repository](https://fedoraproject.org/wiki/EPEL). Please
238 make sure to enable this repository by following
239 [these instructions](https://fedoraproject.org/wiki/EPEL#How_can_I_use_these_extra_packages.3F).
243 # dnf install nagios-plugins-all
247 # zypper install monitoring-plugins
249 The packages for SLES/OpenSUSE depend on other packages which are distributed
250 as part of the [server:monitoring repository](https://build.opensuse.org/project/repositories/server:monitoring).
251 Please make sure to enable this repository beforehand.
255 # pkg install monitoring-plugins
259 # apk add monitoring-plugins
261 Note: For Alpine you don't need to explicitly add the `monitoring-plugins` package since it is a dependency of
262 `icinga2` and is pulled automatically.
264 Depending on which directory your plugins are installed into you may need to
265 update the global `PluginDir` constant in your [Icinga 2 configuration](04-configuring-icinga-2.md#constants-conf).
266 This constant is used by the check command definitions contained in the Icinga Template Library
267 to determine where to find the plugin binaries.
271 > Please refer to the [service monitoring](05-service-monitoring.md#service-monitoring-plugins) chapter for details about how to integrate
272 > additional check plugins into your Icinga 2 setup.
274 ## Running Icinga 2 <a id="running-icinga2"></a>
276 ### Init Script <a id="init-script"></a>
278 Icinga 2's init script is installed in `/etc/init.d/icinga2` (`/usr/local/etc/rc.d/icinga2` on FreeBSD) by default:
280 # /etc/init.d/icinga2
281 Usage: /etc/init.d/icinga2 {start|stop|restart|reload|checkconfig|status}
283 The init script supports the following actions:
285 Command | Description
286 --------------------|------------------------
287 start | The `start` action starts the Icinga 2 daemon.
288 stop | The `stop` action stops the Icinga 2 daemon.
289 restart | The `restart` action is a shortcut for running the `stop` action followed by `start`.
290 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.
291 checkconfig | The `checkconfig` action checks if the `/etc/icinga2/icinga2.conf` configuration file contains any errors.
292 status | The `status` action checks if Icinga 2 is running.
294 By default the Icinga 2 daemon is running as `icinga` user and group
295 using the init script. Using Debian packages the user and group are set to
296 `nagios` for historical reasons.
298 ### systemd Service <a id="systemd-service"></a>
300 Some distributions (e.g. Fedora, openSUSE and RHEL/CentOS 7) use systemd. The
301 Icinga 2 packages automatically install the necessary systemd unit files.
303 The Icinga 2 systemd service can be (re-)started, reloaded, stopped and also
304 queried for its current status.
306 # systemctl status icinga2
307 icinga2.service - Icinga host/service/network monitoring system
308 Loaded: loaded (/usr/lib/systemd/system/icinga2.service; disabled)
309 Active: active (running) since Mi 2014-07-23 13:39:38 CEST; 15s ago
310 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)
311 Process: 21674 ExecStartPre=/usr/sbin/icinga2-prepare-dirs /etc/sysconfig/icinga2 (code=exited, status=0/SUCCESS)
312 Main PID: 21727 (icinga2)
313 CGroup: /system.slice/icinga2.service
314 21727 /usr/sbin/icinga2 -c /etc/icinga2/icinga2.conf -d -e /var/log/icinga2/error.log -u icinga -g icinga --no-stack-rlimit
316 Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 309 Service(s).
317 Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 1 User(s).
318 Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 15 Notification(s).
319 Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 4 ScheduledDowntime(s).
320 Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 1 UserGroup(s).
321 Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 1 IcingaApplication(s).
322 Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 8 Dependency(s).
323 Jul 23 13:39:38 nbmif systemd[1]: Started Icinga host/service/network monitoring system.
325 The `systemctl` command supports the following actions:
327 Command | Description
328 --------------------|------------------------
329 start | The `start` action starts the Icinga 2 daemon.
330 stop | The `stop` action stops the Icinga 2 daemon.
331 restart | The `restart` action is a shortcut for running the `stop` action followed by `start`.
332 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.
333 status | The `status` action checks if Icinga 2 is running.
334 enable | The `enable` action enables the service being started at system boot time (similar to `chkconfig`)
338 # systemctl enable icinga2
340 # systemctl restart icinga2
341 Job for icinga2.service failed. See 'systemctl status icinga2.service' and 'journalctl -xn' for details.
343 If you're stuck with configuration errors, you can manually invoke the
344 [configuration validation](11-cli-commands.md#config-validation).
346 ### FreeBSD <a id="running-icinga2-freebsd"></a>
348 On FreeBSD you need to enable icinga2 in your rc.conf
350 # sysrc icinga2_enable=yes
352 # service icinga2 restart
355 ### SELinux <a id="running-icinga2-selinux"></a>
357 SELinux is a mandatory access control (MAC) system on Linux which adds
358 a fine-grained permission system for access to all system resources such
359 as files, devices, networks and inter-process communication.
361 Icinga 2 provides its own SELinux policy. `icinga2-selinux` is a policy package
362 for Red Hat Enterprise Linux 7 and derivatives. The package runs the targeted policy
363 which confines Icinga 2 including enabled features and running commands.
368 yum install icinga2-selinux
374 dnf install icinga2-selinux
377 Read more about SELinux in [this chapter](22-selinux.md#selinux).
379 ## Configuration Syntax Highlighting <a id="configuration-syntax-highlighting"></a>
381 Icinga 2 ships configuration examples for syntax highlighting using the `vim` and `nano` editors.
382 The RHEL and SUSE package `icinga2-common` installs these files into `/usr/share/doc/icinga2-common-[x.x.x]/syntax`
383 (where `[x.x.x]` is the version number, e.g. `2.4.3` or `2.4.4`). Sources provide these files in `tools/syntax`.
384 On Debian systems the `icinga2-common` package provides only the Nano configuration file (`/usr/share/nano/icinga2.nanorc`);
385 to obtain the Vim configuration, please install the extra package `vim-icinga2`. The files are located in `/usr/share/vim/addons`.
387 ### Configuration Syntax Highlighting using Vim <a id="configuration-syntax-highlighting-vim"></a>
389 Install the package `vim-icinga2` with your distribution's package manager.
393 # apt-get install vim-icinga2 vim-addon-manager
394 # vim-addon-manager -w install icinga2
395 Info: installing removed addon 'icinga2' to /var/lib/vim/addons
399 # yum install vim-icinga2
403 # zypper install vim-icinga2
407 # apk add icinga2-vim
409 Ensure that syntax highlighting is enabled e.g. by editing the user's `vimrc`
417 # vim /etc/icinga2/conf.d/templates.conf
419 ![Vim with syntax highlighting](images/getting-started/vim-syntax.png "Vim with Icinga 2 syntax highlighting")
422 ### Configuration Syntax Highlighting using Nano <a id="configuration-syntax-highlighting-nano"></a>
424 Install the package `nano-icinga2` with your distribution's package manager.
428 **Note:** The syntax files are installed with the `icinga2-common` package already.
432 # yum install nano-icinga2
436 # zypper install nano-icinga2
438 Copy the `/etc/nanorc` sample file to your home directory.
440 $ cp /etc/nanorc ~/.nanorc
442 Include the `icinga2.nanorc` file.
447 include "/usr/share/nano/icinga2.nanorc"
451 $ nano /etc/icinga2/conf.d/templates.conf
453 ![Nano with syntax highlighting](images/getting-started/nano-syntax.png "Nano with Icinga 2 syntax highlighting")
455 ## Setting up Icinga Web 2 <a id="setting-up-icingaweb2"></a>
457 Icinga 2 can be used with Icinga Web 2 and a number of other web interfaces.
458 This chapter explains how to set up Icinga Web 2.
460 The DB IDO (Database Icinga Data Output) modules for Icinga 2 take care of
461 exporting all configuration and status information into a database. The IDO
462 database is used by a number of projects including
463 [Icinga Web 2](02-getting-started.md#setting-up-icingaweb2), Icinga Reporting
466 There is a separate module for each database backend. At present support for
467 both MySQL and PostgreSQL is implemented.
469 Please choose whether to install [MySQL](02-getting-started.md#configuring-db-ido-mysql) or
470 [PostgreSQL](02-getting-started.md#configuring-db-ido-postgresql).
472 ### Configuring DB IDO MySQL <a id="configuring-db-ido-mysql"></a>
474 #### Installing MySQL database server <a id="installing-database-mysql-server"></a>
478 # apt-get install mysql-server mysql-client
479 # mysql_secure_installation
483 # yum install mysql-server mysql
484 # chkconfig mysqld on
485 # service mysqld start
486 # mysql_secure_installation
488 RHEL/CentOS 7 and Fedora:
490 # yum install mariadb-server mariadb
491 # systemctl enable mariadb
492 # systemctl start mariadb
493 # mysql_secure_installation
497 # zypper install mysql mysql-client
498 # chkconfig mysqld on
499 # service mysqld start
503 # pkg install mysql56-server
504 # sysrc mysql_enable=yes
505 # service mysql-server restart
506 # mysql_secure_installation
511 # rc-service mariadb setup
512 # rc-update add mariadb default
513 # rc-service mariadb start
515 #### Installing the IDO modules for MySQL <a id="installing-database-mysql-modules"></a>
517 The next step is to install the `icinga2-ido-mysql` package using your
518 distribution's package manager.
522 # apt-get install icinga2-ido-mysql
526 # yum install icinga2-ido-mysql
530 # zypper install icinga2-ido-mysql
534 On FreeBSD the IDO modules for MySQL are included with the icinga2 package
535 and located at /usr/local/share/icinga2-ido-mysql/schema/mysql.sql
539 On Alpine Linux the IDO modules for MySQL are included with the `icinga2` package
540 and located at /usr/share/icinga2-ido-mysql/schema/mysql.sql
544 > The Debian/Ubuntu packages provide a database configuration wizard by
545 > default. You can skip the automated setup and install/upgrade the
546 > database manually if you prefer that.
548 #### Setting up the MySQL database <a id="setting-up-mysql-db"></a>
550 Set up a MySQL database for Icinga 2:
554 mysql> CREATE DATABASE icinga;
555 mysql> GRANT SELECT, INSERT, UPDATE, DELETE, DROP, CREATE VIEW, INDEX, EXECUTE ON icinga.* TO 'icinga'@'localhost' IDENTIFIED BY 'icinga';
558 ![setting up the database on CentOS 7](images/getting-started/mariadb-centos7.png "Setting up the database on CentOS 7")
560 After creating the database you can import the Icinga 2 IDO schema using the
563 # mysql -u root -p icinga < /usr/share/icinga2-ido-mysql/schema/mysql.sql
566 #### Enabling the IDO MySQL module <a id="enabling-ido-mysql"></a>
568 The package provides a new configuration file that is installed in
569 `/etc/icinga2/features-available/ido-mysql.conf`. You will need to
570 update the database credentials in this file.
572 All available attributes are explained in the
573 [IdoMysqlConnection object](09-object-types.md#objecttype-idomysqlconnection)
576 You can enable the `ido-mysql` feature configuration file using
577 `icinga2 feature enable`:
579 # icinga2 feature enable ido-mysql
580 Module 'ido-mysql' was enabled.
581 Make sure to restart Icinga 2 for these changes to take effect.
583 After enabling the ido-mysql feature you have to restart Icinga 2:
585 RHEL/CentOS 7/Fedora, SLES 12, Debian Jessie/Stretch, Ubuntu Xenial:
587 # systemctl restart icinga2
589 Debian/Ubuntu, RHEL/CentOS 6 and SUSE 11:
591 # service icinga2 restart
595 # service icinga2 restart
599 # rc-service icinga2 restart
601 Continue with the [webserver setup](02-getting-started.md#icinga2-user-interface-webserver).
603 ### Configuring DB IDO PostgreSQL <a id="configuring-db-ido-postgresql"></a>
605 #### Installing PostgreSQL database server <a id="installing-database-postgresql-server"></a>
609 # apt-get install postgresql
613 # yum install postgresql-server postgresql
614 # chkconfig postgresql on
615 # service postgresql start
619 # yum install postgresql-server postgresql
620 # postgresql-setup initdb
621 # systemctl enable postgresql
622 # systemctl start postgresql
626 # zypper install postgresql postgresql-server
627 # chkconfig postgresql on
628 # service postgresql start
632 # pkg install postgresql93-server
633 # sysrc postgresql_enable=yes
634 # service postgresql start
639 # rc-update add postgresql default
640 # rc-service postgresql setup
641 # rc-service postgresql start
643 #### Installing the IDO modules for PostgreSQL <a id="installing-database-postgresql-modules"></a>
645 The next step is to install the `icinga2-ido-pgsql` package using your
646 distribution's package manager.
650 # apt-get install icinga2-ido-pgsql
654 # yum install icinga2-ido-pgsql
658 # zypper install icinga2-ido-pgsql
662 On FreeBSD the IDO modules for PostgreSQL are included with the icinga2 package
663 and located at /usr/local/share/icinga2-ido-pgsql/schema/pgsql.sql
667 On Alpine Linux the IDO modules for PostgreSQL are included with the `icinga2` package
668 and located at /usr/share/icinga2-ido-pgsql/schema/pgsql.sql
672 > Upstream Debian packages provide a database configuration wizard by default.
673 > You can skip the automated setup and install/upgrade the database manually
674 > if you prefer that.
676 #### Setting up the PostgreSQL database
678 Set up a PostgreSQL database for Icinga 2:
681 # sudo -u postgres psql -c "CREATE ROLE icinga WITH LOGIN PASSWORD 'icinga'"
682 # sudo -u postgres createdb -O icinga -E UTF8 icinga
683 # sudo -u postgres createlang plpgsql icinga
687 > When using PostgreSQL 9.x you can omit the `createlang` command.
688 > Also it is assumed here that your locale is set to utf-8, you may run into
689 > problems otherwise.
691 Locate your pg\_hba.conf (Debian: `/etc/postgresql/*/main/pg_hba.conf`,
692 RHEL/SUSE: `/var/lib/pgsql/data/pg_hba.conf`), add the icinga user with md5
693 authentication method and restart the postgresql server.
696 local icinga icinga md5
697 host icinga icinga 127.0.0.1/32 md5
698 host icinga icinga ::1/128 md5
700 # "local" is for Unix domain socket connections only
702 # IPv4 local connections:
703 host all all 127.0.0.1/32 ident
704 # IPv6 local connections:
705 host all all ::1/128 ident
707 # service postgresql restart
710 After creating the database and permissions you can import the Icinga 2 IDO
711 schema using the following command:
713 # export PGPASSWORD=icinga
714 # psql -U icinga -d icinga < /usr/share/icinga2-ido-pgsql/schema/pgsql.sql
716 ![importing the Icinga 2 IDO schema](images/getting-started/postgr-import-ido.png "Importing the Icinga 2 IDO schema on Debian Jessie")
719 #### Enabling the IDO PostgreSQL module <a id="enabling-ido-postgresql"></a>
721 The package provides a new configuration file that is installed in
722 `/etc/icinga2/features-available/ido-pgsql.conf`. You will need to update
723 the database credentials in this file.
725 All available attributes are explained in the
726 [IdoPgsqlConnection object](09-object-types.md#objecttype-idopgsqlconnection)
729 You can enable the `ido-pgsql` feature configuration file using
730 `icinga2 feature enable`:
732 # icinga2 feature enable ido-pgsql
733 Module 'ido-pgsql' was enabled.
734 Make sure to restart Icinga 2 for these changes to take effect.
736 After enabling the ido-pgsql feature you have to restart Icinga 2:
738 RHEL/CentOS 7/Fedora, SLES 12, Debian Jessie/Stretch, Ubuntu Xenial:
740 # systemctl restart icinga2
742 Debian/Ubuntu, RHEL/CentOS 6, SUSE and FreeBSD:
744 # service icinga2 restart
748 # service icinga2 restart
752 # rc-service icinga2 restart
754 Continue with the [webserver setup](02-getting-started.md#icinga2-user-interface-webserver).
756 ### Webserver <a id="icinga2-user-interface-webserver"></a>
760 # apt-get install apache2
766 # service httpd start
768 RHEL/CentOS 7, Fedora:
771 # systemctl enable httpd
772 # systemctl start httpd
776 # zypper install apache2
778 # service apache2 start
780 FreeBSD (nginx, but you could also use the apache24 package):
782 # 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
783 # sysrc php_fpm_enable=yes
784 # sysrc nginx_enable=yes
785 # sed -i '' "s/listen\ =\ 127.0.0.1:9000/listen\ =\ \/var\/run\/php5-fpm.sock/" /usr/local/etc/php-fpm.conf
786 # sed -i '' "s/;listen.owner/listen.owner/" /usr/local/etc/php-fpm.conf
787 # sed -i '' "s/;listen.group/listen.group/" /usr/local/etc/php-fpm.conf
788 # sed -i '' "s/;listen.mode/listen.mode/" /usr/local/etc/php-fpm.conf
789 # service php-fpm start
790 # service nginx start
794 # apk add apache2 php7-apache2
795 # sed -i -e "s/^#LoadModule rewrite_module/LoadModule rewrite_module/" /etc/apache2/httpd.conf
796 # rc-update add apache2 default
797 # rc-service apache2 start
799 ### Firewall Rules <a id="icinga2-user-interface-firewall-rules"></a>
803 # iptables -A INPUT -p tcp -m tcp --dport 80 -j ACCEPT
804 # service iptables save
806 RHEL/CentOS 7 specific:
808 # firewall-cmd --add-service=http
809 # firewall-cmd --permanent --add-service=http
812 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.
815 ### Setting Up Icinga 2 REST API <a id="setting-up-rest-api"></a>
817 Icinga Web 2 and other web interfaces require the [REST API](12-icinga2-api.md#icinga2-api-setup)
818 to send actions (reschedule check, etc.) and query object details.
820 You can run the CLI command `icinga2 api setup` to enable the
821 `api` [feature](11-cli-commands.md#enable-features) and set up
822 certificates as well as a new API user `root` with an auto-generated password in the
823 `/etc/icinga2/conf.d/api-users.conf` configuration file:
827 Edit the `api-users.conf` file and add a new ApiUser object. Specify the [permissions](12-icinga2-api.md#icinga2-api-permissions)
828 attribute with minimal permissions required by Icinga Web 2.
830 # vim /etc/icinga2/conf.d/api-users.conf
832 object ApiUser "icingaweb2" {
833 password = "Wijsn8Z9eRs5E25d"
834 permissions = [ "status/query", "actions/*", "objects/modify/*", "objects/query/*" ]
837 Make sure to restart Icinga 2 to activate the configuration.
839 RHEL/CentOS 7/Fedora, SLES 12, Debian Jessie/Stretch, Ubuntu Xenial:
841 # systemctl restart icinga2
843 Debian/Ubuntu, RHEL/CentOS 6 and SUSE:
845 # service icinga2 restart
849 # service icinga2 restart
853 # rc-service icinga2 restart
855 ### Installing Icinga Web 2 <a id="installing-icingaweb2"></a>
857 Please consult the [installation documentation](https://github.com/Icinga/icingaweb2/blob/master/doc/02-Installation.md)
858 for further instructions on how to install Icinga Web 2.
860 The Icinga 2 API can be defined as [command transport](https://github.com/Icinga/icingaweb2/blob/master/modules/monitoring/doc/commandtransports.md)
861 in Icinga Web 2 >= 2.4.
863 ## Addons <a id="install-addons"></a>
865 A number of additional features are available in the form of addons. A list of
866 popular addons is available in the
867 [Addons and Plugins](13-addons.md#addons) chapter.
869 ## Backup <a id="install-backup"></a>
871 Ensure to include the following in your backups:
873 * Configuration files in `/etc/icinga2`
874 * Runtime files in `/var/lib/icinga2` (the master's CA is stored here as well)
875 * Optional: IDO database backup