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/systemd/system/icinga2.service.d/limits.conf | On distributions with Systemd >227, additional service limits are required.
173 /etc/init.d/icinga2 | The Icinga 2 init script on systems using SysVinit or OpenRC
174 /usr/sbin/icinga2 | Shell wrapper for the Icinga 2 binary.
175 /usr/lib\*/icinga2 | Libraries and the Icinga 2 binary (use `find /usr -type f -name icinga2` to locate the binary path).
176 /usr/share/doc/icinga2 | Documentation files that come with Icinga 2.
177 /usr/share/icinga2/include | The Icinga Template Library and plugin command configuration.
178 /var/lib/icinga2 | Icinga 2 state file, cluster log, master CA, node certificates and configuration files (cluster, api).
179 /var/run/icinga2 | PID file.
180 /var/run/icinga2/cmd | Command pipe and Livestatus socket.
181 /var/cache/icinga2 | status.dat/objects.cache, icinga2.debug files
182 /var/spool/icinga2 | Used for performance data spool files.
183 /var/log/icinga2 | Log file location and compat/ directory for the CompatLogger feature.
185 FreeBSD uses slightly different paths:
187 By default Icinga 2 uses the following files and directories:
190 ------------------------------------|------------------------------------
191 /usr/local/etc/icinga2 | Contains Icinga 2 configuration files.
192 /usr/local/etc/rc.d/icinga2 | The Icinga 2 init script.
193 /usr/local/sbin/icinga2 | Shell wrapper for the Icinga 2 binary.
194 /usr/local/lib/icinga2 | Libraries and the Icinga 2 binary.
195 /usr/local/share/doc/icinga2 | Documentation files that come with Icinga 2.
196 /usr/local/share/icinga2/include | The Icinga Template Library and plugin command configuration.
197 /var/lib/icinga2 | Icinga 2 state file, cluster log, master CA, node certificates and configuration files (cluster, api).
198 /var/run/icinga2 | PID file.
199 /var/run/icinga2/cmd | Command pipe and Livestatus socket.
200 /var/cache/icinga2 | status.dat/objects.cache, icinga2.debug files
201 /var/spool/icinga2 | Used for performance data spool files.
202 /var/log/icinga2 | Log file location and compat/ directory for the CompatLogger feature.
204 ## Setting up Check Plugins <a id="setting-up-check-plugins"></a>
206 Without plugins Icinga 2 does not know how to check external services. The
207 [Monitoring Plugins Project](https://www.monitoring-plugins.org/) provides
208 an extensive set of plugins which can be used with Icinga 2 to check whether
209 services are working properly.
211 These plugins are required to make the [example configuration](04-configuring-icinga-2.md#configuring-icinga2-overview)
214 For your convenience here is a list of package names for some of the more
215 popular operating systems/distributions:
217 OS/Distribution | Package Name | Repository | Installation Path
218 -----------------------|--------------------|---------------------------|----------------------------
219 RHEL/CentOS | nagios-plugins-all | [EPEL](https://fedoraproject.org/wiki/EPEL) | /usr/lib/nagios/plugins or /usr/lib64/nagios/plugins
220 SLES/OpenSUSE | monitoring-plugins | [server:monitoring](https://build.opensuse.org/project/repositories/server:monitoring) | /usr/lib/nagios/plugins
221 Debian/Ubuntu | monitoring-plugins | - | /usr/lib/nagios/plugins
222 FreeBSD | monitoring-plugins | - | /usr/local/libexec/nagios
223 Alpine Linux | monitoring-plugins | - | /usr/lib/monitoring-plugins
224 OS X | nagios-plugins | [MacPorts](https://www.macports.org), [Homebrew](https://brew.sh) | /opt/local/libexec or /usr/local/sbin
226 The recommended way of installing these standard plugins is to use your
227 distribution's package manager.
231 # apt-get install monitoring-plugins
235 # yum install nagios-plugins-all
237 The packages for RHEL/CentOS depend on other packages which are distributed
238 as part of the [EPEL repository](https://fedoraproject.org/wiki/EPEL). Please
239 make sure to enable this repository by following
240 [these instructions](https://fedoraproject.org/wiki/EPEL#How_can_I_use_these_extra_packages.3F).
244 # dnf install nagios-plugins-all
248 # zypper install monitoring-plugins
250 The packages for SLES/OpenSUSE depend on other packages which are distributed
251 as part of the [server:monitoring repository](https://build.opensuse.org/project/repositories/server:monitoring).
252 Please make sure to enable this repository beforehand.
256 # pkg install monitoring-plugins
260 # apk add monitoring-plugins
262 Note: For Alpine you don't need to explicitly add the `monitoring-plugins` package since it is a dependency of
263 `icinga2` and is pulled automatically.
265 Depending on which directory your plugins are installed into you may need to
266 update the global `PluginDir` constant in your [Icinga 2 configuration](04-configuring-icinga-2.md#constants-conf).
267 This constant is used by the check command definitions contained in the Icinga Template Library
268 to determine where to find the plugin binaries.
272 > Please refer to the [service monitoring](05-service-monitoring.md#service-monitoring-plugins) chapter for details about how to integrate
273 > additional check plugins into your Icinga 2 setup.
275 ## Running Icinga 2 <a id="running-icinga2"></a>
277 ### Init Script <a id="init-script"></a>
279 Icinga 2's init script is installed in `/etc/init.d/icinga2` (`/usr/local/etc/rc.d/icinga2` on FreeBSD) by default:
281 # /etc/init.d/icinga2
282 Usage: /etc/init.d/icinga2 {start|stop|restart|reload|checkconfig|status}
284 The init script supports the following actions:
286 Command | Description
287 --------------------|------------------------
288 start | The `start` action starts the Icinga 2 daemon.
289 stop | The `stop` action stops the Icinga 2 daemon.
290 restart | The `restart` action is a shortcut for running the `stop` action followed by `start`.
291 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.
292 checkconfig | The `checkconfig` action checks if the `/etc/icinga2/icinga2.conf` configuration file contains any errors.
293 status | The `status` action checks if Icinga 2 is running.
295 By default the Icinga 2 daemon is running as `icinga` user and group
296 using the init script. Using Debian packages the user and group are set to
297 `nagios` for historical reasons.
299 ### Systemd Service <a id="systemd-service"></a>
301 Some distributions (e.g. Fedora, openSUSE and RHEL/CentOS 7) use Systemd. The
302 Icinga 2 packages automatically install the necessary Systemd unit files.
304 The Icinga 2 Systemd service can be (re-)started, reloaded, stopped and also
305 queried for its current status.
307 # systemctl status icinga2
308 icinga2.service - Icinga host/service/network monitoring system
309 Loaded: loaded (/usr/lib/systemd/system/icinga2.service; disabled)
310 Active: active (running) since Mi 2014-07-23 13:39:38 CEST; 15s ago
311 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)
312 Process: 21674 ExecStartPre=/usr/sbin/icinga2-prepare-dirs /etc/sysconfig/icinga2 (code=exited, status=0/SUCCESS)
313 Main PID: 21727 (icinga2)
314 CGroup: /system.slice/icinga2.service
315 21727 /usr/sbin/icinga2 -c /etc/icinga2/icinga2.conf -d -e /var/log/icinga2/error.log -u icinga -g icinga --no-stack-rlimit
317 Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 309 Service(s).
318 Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 1 User(s).
319 Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 15 Notification(s).
320 Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 4 ScheduledDowntime(s).
321 Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 1 UserGroup(s).
322 Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 1 IcingaApplication(s).
323 Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 8 Dependency(s).
324 Jul 23 13:39:38 nbmif systemd[1]: Started Icinga host/service/network monitoring system.
326 The `systemctl` command supports the following actions:
328 Command | Description
329 --------------------|------------------------
330 start | The `start` action starts the Icinga 2 daemon.
331 stop | The `stop` action stops the Icinga 2 daemon.
332 restart | The `restart` action is a shortcut for running the `stop` action followed by `start`.
333 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.
334 status | The `status` action checks if Icinga 2 is running.
335 enable | The `enable` action enables the service being started at system boot time (similar to `chkconfig`)
339 # systemctl enable icinga2
341 # systemctl restart icinga2
342 Job for icinga2.service failed. See 'systemctl status icinga2.service' and 'journalctl -xn' for details.
344 If you're stuck with configuration errors, you can manually invoke the
345 [configuration validation](11-cli-commands.md#config-validation).
349 > If you are running into fork errors with Systemd enabled distributions,
350 > please check the [troubleshooting chapter](15-troubleshooting.md#check-fork-errors).
352 ### FreeBSD <a id="running-icinga2-freebsd"></a>
354 On FreeBSD you need to enable icinga2 in your rc.conf
356 # sysrc icinga2_enable=yes
358 # service icinga2 restart
361 ### SELinux <a id="running-icinga2-selinux"></a>
363 SELinux is a mandatory access control (MAC) system on Linux which adds
364 a fine-grained permission system for access to all system resources such
365 as files, devices, networks and inter-process communication.
367 Icinga 2 provides its own SELinux policy. `icinga2-selinux` is a policy package
368 for Red Hat Enterprise Linux 7 and derivatives. The package runs the targeted policy
369 which confines Icinga 2 including enabled features and running commands.
374 yum install icinga2-selinux
380 dnf install icinga2-selinux
383 Read more about SELinux in [this chapter](22-selinux.md#selinux).
385 ## Configuration Syntax Highlighting <a id="configuration-syntax-highlighting"></a>
387 Icinga 2 ships configuration examples for syntax highlighting using the `vim` and `nano` editors.
388 The RHEL and SUSE package `icinga2-common` installs these files into `/usr/share/doc/icinga2-common-[x.x.x]/syntax`
389 (where `[x.x.x]` is the version number, e.g. `2.4.3` or `2.4.4`). Sources provide these files in `tools/syntax`.
390 On Debian systems the `icinga2-common` package provides only the Nano configuration file (`/usr/share/nano/icinga2.nanorc`);
391 to obtain the Vim configuration, please install the extra package `vim-icinga2`. The files are located in `/usr/share/vim/addons`.
393 ### Configuration Syntax Highlighting using Vim <a id="configuration-syntax-highlighting-vim"></a>
395 Install the package `vim-icinga2` with your distribution's package manager.
399 # apt-get install vim-icinga2 vim-addon-manager
400 # vim-addon-manager -w install icinga2
401 Info: installing removed addon 'icinga2' to /var/lib/vim/addons
405 # yum install vim-icinga2
409 # zypper install vim-icinga2
413 # apk add icinga2-vim
415 Ensure that syntax highlighting is enabled e.g. by editing the user's `vimrc`
423 # vim /etc/icinga2/conf.d/templates.conf
425 ![Vim with syntax highlighting](images/getting-started/vim-syntax.png "Vim with Icinga 2 syntax highlighting")
428 ### Configuration Syntax Highlighting using Nano <a id="configuration-syntax-highlighting-nano"></a>
430 Install the package `nano-icinga2` with your distribution's package manager.
434 **Note:** The syntax files are installed with the `icinga2-common` package already.
438 # yum install nano-icinga2
442 # zypper install nano-icinga2
444 Copy the `/etc/nanorc` sample file to your home directory.
446 $ cp /etc/nanorc ~/.nanorc
448 Include the `icinga2.nanorc` file.
453 include "/usr/share/nano/icinga2.nanorc"
457 $ nano /etc/icinga2/conf.d/templates.conf
459 ![Nano with syntax highlighting](images/getting-started/nano-syntax.png "Nano with Icinga 2 syntax highlighting")
461 ## Setting up Icinga Web 2 <a id="setting-up-icingaweb2"></a>
463 Icinga 2 can be used with Icinga Web 2 and a number of other web interfaces.
464 This chapter explains how to set up Icinga Web 2.
466 The DB IDO (Database Icinga Data Output) modules for Icinga 2 take care of
467 exporting all configuration and status information into a database. The IDO
468 database is used by a number of projects including
469 [Icinga Web 2](02-getting-started.md#setting-up-icingaweb2), Icinga Reporting
472 There is a separate module for each database backend. At present support for
473 both MySQL and PostgreSQL is implemented.
475 Please choose whether to install [MySQL](02-getting-started.md#configuring-db-ido-mysql) or
476 [PostgreSQL](02-getting-started.md#configuring-db-ido-postgresql).
478 ### Configuring DB IDO MySQL <a id="configuring-db-ido-mysql"></a>
480 #### Installing MySQL database server <a id="installing-database-mysql-server"></a>
484 # apt-get install mysql-server mysql-client
485 # mysql_secure_installation
489 # yum install mysql-server mysql
490 # chkconfig mysqld on
491 # service mysqld start
492 # mysql_secure_installation
494 RHEL/CentOS 7 and Fedora:
496 # yum install mariadb-server mariadb
497 # systemctl enable mariadb
498 # systemctl start mariadb
499 # mysql_secure_installation
503 # zypper install mysql mysql-client
504 # chkconfig mysqld on
505 # service mysqld start
509 # pkg install mysql56-server
510 # sysrc mysql_enable=yes
511 # service mysql-server restart
512 # mysql_secure_installation
517 # rc-service mariadb setup
518 # rc-update add mariadb default
519 # rc-service mariadb start
521 #### Installing the IDO modules for MySQL <a id="installing-database-mysql-modules"></a>
523 The next step is to install the `icinga2-ido-mysql` package using your
524 distribution's package manager.
528 # apt-get install icinga2-ido-mysql
532 # yum install icinga2-ido-mysql
536 # zypper install icinga2-ido-mysql
540 On FreeBSD the IDO modules for MySQL are included with the icinga2 package
541 and located at /usr/local/share/icinga2-ido-mysql/schema/mysql.sql
545 On Alpine Linux the IDO modules for MySQL are included with the `icinga2` package
546 and located at /usr/share/icinga2-ido-mysql/schema/mysql.sql
550 > The Debian/Ubuntu packages provide a database configuration wizard by
551 > default. You can skip the automated setup and install/upgrade the
552 > database manually if you prefer that.
554 #### Setting up the MySQL database <a id="setting-up-mysql-db"></a>
556 Set up a MySQL database for Icinga 2:
560 mysql> CREATE DATABASE icinga;
561 mysql> GRANT SELECT, INSERT, UPDATE, DELETE, DROP, CREATE VIEW, INDEX, EXECUTE ON icinga.* TO 'icinga'@'localhost' IDENTIFIED BY 'icinga';
564 ![setting up the database on CentOS 7](images/getting-started/mariadb-centos7.png "Setting up the database on CentOS 7")
566 After creating the database you can import the Icinga 2 IDO schema using the
569 # mysql -u root -p icinga < /usr/share/icinga2-ido-mysql/schema/mysql.sql
572 #### Enabling the IDO MySQL module <a id="enabling-ido-mysql"></a>
574 The package provides a new configuration file that is installed in
575 `/etc/icinga2/features-available/ido-mysql.conf`. You will need to
576 update the database credentials in this file.
578 All available attributes are explained in the
579 [IdoMysqlConnection object](09-object-types.md#objecttype-idomysqlconnection)
582 You can enable the `ido-mysql` feature configuration file using
583 `icinga2 feature enable`:
585 # icinga2 feature enable ido-mysql
586 Module 'ido-mysql' was enabled.
587 Make sure to restart Icinga 2 for these changes to take effect.
589 After enabling the ido-mysql feature you have to restart Icinga 2:
591 RHEL/CentOS 7/Fedora, SLES 12, Debian Jessie/Stretch, Ubuntu Xenial:
593 # systemctl restart icinga2
595 Debian/Ubuntu, RHEL/CentOS 6 and SUSE 11:
597 # service icinga2 restart
601 # service icinga2 restart
605 # rc-service icinga2 restart
607 Continue with the [webserver setup](02-getting-started.md#icinga2-user-interface-webserver).
609 ### Configuring DB IDO PostgreSQL <a id="configuring-db-ido-postgresql"></a>
611 #### Installing PostgreSQL database server <a id="installing-database-postgresql-server"></a>
615 # apt-get install postgresql
619 # yum install postgresql-server postgresql
620 # chkconfig postgresql on
621 # service postgresql start
625 # yum install postgresql-server postgresql
626 # postgresql-setup initdb
627 # systemctl enable postgresql
628 # systemctl start postgresql
632 # zypper install postgresql postgresql-server
633 # chkconfig postgresql on
634 # service postgresql start
638 # pkg install postgresql93-server
639 # sysrc postgresql_enable=yes
640 # service postgresql start
645 # rc-update add postgresql default
646 # rc-service postgresql setup
647 # rc-service postgresql start
649 #### Installing the IDO modules for PostgreSQL <a id="installing-database-postgresql-modules"></a>
651 The next step is to install the `icinga2-ido-pgsql` package using your
652 distribution's package manager.
656 # apt-get install icinga2-ido-pgsql
660 # yum install icinga2-ido-pgsql
664 # zypper install icinga2-ido-pgsql
668 On FreeBSD the IDO modules for PostgreSQL are included with the icinga2 package
669 and located at /usr/local/share/icinga2-ido-pgsql/schema/pgsql.sql
673 On Alpine Linux the IDO modules for PostgreSQL are included with the `icinga2` package
674 and located at /usr/share/icinga2-ido-pgsql/schema/pgsql.sql
678 > Upstream Debian packages provide a database configuration wizard by default.
679 > You can skip the automated setup and install/upgrade the database manually
680 > if you prefer that.
682 #### Setting up the PostgreSQL database
684 Set up a PostgreSQL database for Icinga 2:
687 # sudo -u postgres psql -c "CREATE ROLE icinga WITH LOGIN PASSWORD 'icinga'"
688 # sudo -u postgres createdb -O icinga -E UTF8 icinga
689 # sudo -u postgres createlang plpgsql icinga
693 > When using PostgreSQL 9.x you can omit the `createlang` command.
694 > Also it is assumed here that your locale is set to utf-8, you may run into
695 > problems otherwise.
697 Locate your pg\_hba.conf (Debian: `/etc/postgresql/*/main/pg_hba.conf`,
698 RHEL/SUSE: `/var/lib/pgsql/data/pg_hba.conf`), add the icinga user with md5
699 authentication method and restart the postgresql server.
702 local icinga icinga md5
703 host icinga icinga 127.0.0.1/32 md5
704 host icinga icinga ::1/128 md5
706 # "local" is for Unix domain socket connections only
708 # IPv4 local connections:
709 host all all 127.0.0.1/32 ident
710 # IPv6 local connections:
711 host all all ::1/128 ident
713 # service postgresql restart
716 After creating the database and permissions you can import the Icinga 2 IDO
717 schema using the following command:
719 # export PGPASSWORD=icinga
720 # psql -U icinga -d icinga < /usr/share/icinga2-ido-pgsql/schema/pgsql.sql
722 ![importing the Icinga 2 IDO schema](images/getting-started/postgr-import-ido.png "Importing the Icinga 2 IDO schema on Debian Jessie")
725 #### Enabling the IDO PostgreSQL module <a id="enabling-ido-postgresql"></a>
727 The package provides a new configuration file that is installed in
728 `/etc/icinga2/features-available/ido-pgsql.conf`. You will need to update
729 the database credentials in this file.
731 All available attributes are explained in the
732 [IdoPgsqlConnection object](09-object-types.md#objecttype-idopgsqlconnection)
735 You can enable the `ido-pgsql` feature configuration file using
736 `icinga2 feature enable`:
738 # icinga2 feature enable ido-pgsql
739 Module 'ido-pgsql' was enabled.
740 Make sure to restart Icinga 2 for these changes to take effect.
742 After enabling the ido-pgsql feature you have to restart Icinga 2:
744 RHEL/CentOS 7/Fedora, SLES 12, Debian Jessie/Stretch, Ubuntu Xenial:
746 # systemctl restart icinga2
748 Debian/Ubuntu, RHEL/CentOS 6, SUSE and FreeBSD:
750 # service icinga2 restart
754 # service icinga2 restart
758 # rc-service icinga2 restart
760 Continue with the [webserver setup](02-getting-started.md#icinga2-user-interface-webserver).
762 ### Webserver <a id="icinga2-user-interface-webserver"></a>
766 # apt-get install apache2
772 # service httpd start
774 RHEL/CentOS 7, Fedora:
777 # systemctl enable httpd
778 # systemctl start httpd
782 # zypper install apache2
784 # service apache2 start
786 FreeBSD (nginx, but you could also use the apache24 package):
788 # 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
789 # sysrc php_fpm_enable=yes
790 # sysrc nginx_enable=yes
791 # sed -i '' "s/listen\ =\ 127.0.0.1:9000/listen\ =\ \/var\/run\/php5-fpm.sock/" /usr/local/etc/php-fpm.conf
792 # sed -i '' "s/;listen.owner/listen.owner/" /usr/local/etc/php-fpm.conf
793 # sed -i '' "s/;listen.group/listen.group/" /usr/local/etc/php-fpm.conf
794 # sed -i '' "s/;listen.mode/listen.mode/" /usr/local/etc/php-fpm.conf
795 # service php-fpm start
796 # service nginx start
800 # apk add apache2 php7-apache2
801 # sed -i -e "s/^#LoadModule rewrite_module/LoadModule rewrite_module/" /etc/apache2/httpd.conf
802 # rc-update add apache2 default
803 # rc-service apache2 start
805 ### Firewall Rules <a id="icinga2-user-interface-firewall-rules"></a>
809 # iptables -A INPUT -p tcp -m tcp --dport 80 -j ACCEPT
810 # service iptables save
812 RHEL/CentOS 7 specific:
814 # firewall-cmd --add-service=http
815 # firewall-cmd --permanent --add-service=http
818 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.
821 ### Setting Up Icinga 2 REST API <a id="setting-up-rest-api"></a>
823 Icinga Web 2 and other web interfaces require the [REST API](12-icinga2-api.md#icinga2-api-setup)
824 to send actions (reschedule check, etc.) and query object details.
826 You can run the CLI command `icinga2 api setup` to enable the
827 `api` [feature](11-cli-commands.md#enable-features) and set up
828 certificates as well as a new API user `root` with an auto-generated password in the
829 `/etc/icinga2/conf.d/api-users.conf` configuration file:
833 Edit the `api-users.conf` file and add a new ApiUser object. Specify the [permissions](12-icinga2-api.md#icinga2-api-permissions)
834 attribute with minimal permissions required by Icinga Web 2.
836 # vim /etc/icinga2/conf.d/api-users.conf
838 object ApiUser "icingaweb2" {
839 password = "Wijsn8Z9eRs5E25d"
840 permissions = [ "status/query", "actions/*", "objects/modify/*", "objects/query/*" ]
843 Make sure to restart Icinga 2 to activate the configuration.
845 RHEL/CentOS 7/Fedora, SLES 12, Debian Jessie/Stretch, Ubuntu Xenial:
847 # systemctl restart icinga2
849 Debian/Ubuntu, RHEL/CentOS 6 and SUSE:
851 # service icinga2 restart
855 # service icinga2 restart
859 # rc-service icinga2 restart
861 ### Installing Icinga Web 2 <a id="installing-icingaweb2"></a>
863 Please consult the [installation documentation](https://github.com/Icinga/icingaweb2/blob/master/doc/02-Installation.md)
864 for further instructions on how to install Icinga Web 2.
866 The Icinga 2 API can be defined as [command transport](https://github.com/Icinga/icingaweb2/blob/master/modules/monitoring/doc/commandtransports.md)
867 in Icinga Web 2 >= 2.4.
869 ## Addons <a id="install-addons"></a>
871 A number of additional features are available in the form of addons. A list of
872 popular addons is available in the
873 [Addons and Plugins](13-addons.md#addons) chapter.
875 ## Backup <a id="install-backup"></a>
877 Ensure to include the following in your backups:
879 * Configuration files in `/etc/icinga2`
880 * Certificate files in `/var/lib/icinga2/ca` (Master CA key pair) and `/var/lib/icinga2/certs` (node certificates)
881 * Runtime files in `/var/lib/icinga2`
882 * Optional: IDO database backup