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 AlpineLinux | [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
78 #### RHEL/CentOS EPEL Repository <a id="package-repositories-rhel-epel"></a>
80 The packages for RHEL/CentOS depend on other packages which are distributed
81 as part of the [EPEL repository](https://fedoraproject.org/wiki/EPEL).
85 yum install epel-release
87 If you are using RHEL you need enable the `optional` repository and then install
88 the [EPEL rpm package](https://fedoraproject.org/wiki/EPEL#How_can_I_use_these_extra_packages.3F).
90 #### SLES Security Repository <a id="package-repositories-sles-security"></a>
92 The packages for SLES 11 depend on the `openssl1` package which is distributed
93 as part of the [SLES 11 Security Module](https://www.suse.com/communities/conversations/introducing-the-suse-linux-enterprise-11-security-module/).
95 #### SLES 12 SDK <a id="package-sles-sdk"></a>
97 Icinga 2 requires the `libboost_chrono1_54_0` package from the `SLES 12 SDK` repository. Refer to the SUSE Enterprise
98 Linux documentation for further information.
100 ### Installing Icinga 2 <a id="installing-icinga2"></a>
102 You can install Icinga 2 by using your distribution's package manager
103 to install the `icinga2` package.
107 # apt-get install icinga2
111 # yum install icinga2
112 # chkconfig icinga2 on
113 # service icinga2 start
115 RHEL/CentOS 7 and Fedora:
117 # yum install icinga2
118 # systemctl enable icinga2
119 # systemctl start icinga2
123 # zypper install icinga2
127 # pkg install icinga2
129 ### Enabled Features during Installation <a id="installation-enabled-features"></a>
131 The default installation will enable three features required for a basic
132 Icinga 2 installation:
134 * `checker` for executing checks
135 * `notification` for sending notifications
136 * `mainlog` for writing the `icinga2.log` file
138 You can verify that by calling `icinga2 feature list`
139 [CLI command](11-cli-commands.md#cli-command-feature) to see which features are
140 enabled and disabled.
142 # icinga2 feature list
143 Disabled features: api command compatlog debuglog gelf graphite icingastatus ido-mysql ido-pgsql influxdb livestatus opentsdb perfdata statusdata syslog
144 Enabled features: checker mainlog notification
147 ### Installation Paths <a id="installation-paths"></a>
149 By default Icinga 2 uses the following files and directories:
152 ----------------------------------------------|------------------------------------
153 /etc/icinga2 | Contains Icinga 2 configuration files.
154 /usr/lib/systemd/system/icinga2.service | The Icinga 2 Systemd service file on systems using Systemd.
155 /etc/init.d/icinga2 | The Icinga 2 init script on systems using SysVinit.
156 /usr/sbin/icinga2 | Shell wrapper for the Icinga 2 binary.
157 /usr/lib\*/icinga2 | Libraries and the Icinga 2 binary (use `find /usr -type f -name icinga2` to locate the binary path).
158 /usr/share/doc/icinga2 | Documentation files that come with Icinga 2.
159 /usr/share/icinga2/include | The Icinga Template Library and plugin command configuration.
160 /var/run/icinga2 | PID file.
161 /var/run/icinga2/cmd | Command pipe and Livestatus socket.
162 /var/cache/icinga2 | status.dat/objects.cache, icinga2.debug files
163 /var/spool/icinga2 | Used for performance data spool files.
164 /var/lib/icinga2 | Icinga 2 state file, cluster log, local CA and configuration files (cluster, api).
165 /var/log/icinga2 | Log file location and compat/ directory for the CompatLogger feature.
167 FreeBSD uses slightly different paths:
169 By default Icinga 2 uses the following files and directories:
172 ------------------------------------|------------------------------------
173 /usr/local/etc/icinga2 | Contains Icinga 2 configuration files.
174 /usr/local/etc/rc.d/icinga2 | The Icinga 2 init script.
175 /usr/local/sbin/icinga2 | Shell wrapper for the Icinga 2 binary.
176 /usr/local/lib/icinga2 | Libraries and the Icinga 2 binary.
177 /usr/local/share/doc/icinga2 | Documentation files that come with Icinga 2.
178 /usr/local/share/icinga2/include | The Icinga Template Library and plugin command configuration.
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/lib/icinga2 | Icinga 2 state file, cluster log, local CA and configuration files (cluster, api).
184 /var/log/icinga2 | Log file location and compat/ directory for the CompatLogger feature.
186 ## Setting up Check Plugins <a id="setting-up-check-plugins"></a>
188 Without plugins Icinga 2 does not know how to check external services. The
189 [Monitoring Plugins Project](https://www.monitoring-plugins.org/) provides
190 an extensive set of plugins which can be used with Icinga 2 to check whether
191 services are working properly.
193 These plugins are required to make the [example configuration](04-configuring-icinga-2.md#configuring-icinga2-overview)
196 For your convenience here is a list of package names for some of the more
197 popular operating systems/distributions:
199 OS/Distribution | Package Name | Repository | Installation Path
200 -----------------------|--------------------|---------------------------|----------------------------
201 RHEL/CentOS | nagios-plugins-all | [EPEL](https://fedoraproject.org/wiki/EPEL) | /usr/lib/nagios/plugins or /usr/lib64/nagios/plugins
202 SLES/OpenSUSE | monitoring-plugins | [server:monitoring](https://build.opensuse.org/project/repositories/server:monitoring) | /usr/lib/nagios/plugins
203 Debian/Ubuntu | monitoring-plugins | - | /usr/lib/nagios/plugins
204 FreeBSD | monitoring-plugins | - | /usr/local/libexec/nagios
205 OS X | nagios-plugins | [MacPorts](https://www.macports.org), [Homebrew](https://brew.sh) | /opt/local/libexec or /usr/local/sbin
207 The recommended way of installing these standard plugins is to use your
208 distribution's package manager.
212 # apt-get install monitoring-plugins
216 # yum install nagios-plugins-all
218 The packages for RHEL/CentOS depend on other packages which are distributed
219 as part of the [EPEL repository](https://fedoraproject.org/wiki/EPEL). Please
220 make sure to enable this repository by following
221 [these instructions](https://fedoraproject.org/wiki/EPEL#How_can_I_use_these_extra_packages.3F).
225 # dnf install nagios-plugins-all
229 # zypper install monitoring-plugins
231 The packages for SLES/OpenSUSE depend on other packages which are distributed
232 as part of the [server:monitoring repository](https://build.opensuse.org/project/repositories/server:monitoring).
233 Please make sure to enable this repository beforehand.
237 # pkg install monitoring-plugins
239 Depending on which directory your plugins are installed into you may need to
240 update the global `PluginDir` constant in your [Icinga 2 configuration](04-configuring-icinga-2.md#constants-conf).
241 This constant is used by the check command definitions contained in the Icinga Template Library
242 to determine where to find the plugin binaries.
246 > Please refer to the [service monitoring](05-service-monitoring.md#service-monitoring-plugins) chapter for details about how to integrate
247 > additional check plugins into your Icinga 2 setup.
249 ## Running Icinga 2 <a id="running-icinga2"></a>
251 ### Init Script <a id="init-script"></a>
253 Icinga 2's init script is installed in `/etc/init.d/icinga2` (`/usr/local/etc/rc.d/icinga2` on FreeBSD) by default:
255 # /etc/init.d/icinga2
256 Usage: /etc/init.d/icinga2 {start|stop|restart|reload|checkconfig|status}
258 The init script supports the following actions:
260 Command | Description
261 --------------------|------------------------
262 start | The `start` action starts the Icinga 2 daemon.
263 stop | The `stop` action stops the Icinga 2 daemon.
264 restart | The `restart` action is a shortcut for running the `stop` action followed by `start`.
265 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.
266 checkconfig | The `checkconfig` action checks if the `/etc/icinga2/icinga2.conf` configuration file contains any errors.
267 status | The `status` action checks if Icinga 2 is running.
269 By default the Icinga 2 daemon is running as `icinga` user and group
270 using the init script. Using Debian packages the user and group are set to
271 `nagios` for historical reasons.
273 ### systemd Service <a id="systemd-service"></a>
275 Some distributions (e.g. Fedora, openSUSE and RHEL/CentOS 7) use systemd. The
276 Icinga 2 packages automatically install the necessary systemd unit files.
278 The Icinga 2 systemd service can be (re-)started, reloaded, stopped and also
279 queried for its current status.
281 # systemctl status icinga2
282 icinga2.service - Icinga host/service/network monitoring system
283 Loaded: loaded (/usr/lib/systemd/system/icinga2.service; disabled)
284 Active: active (running) since Mi 2014-07-23 13:39:38 CEST; 15s ago
285 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)
286 Process: 21674 ExecStartPre=/usr/sbin/icinga2-prepare-dirs /etc/sysconfig/icinga2 (code=exited, status=0/SUCCESS)
287 Main PID: 21727 (icinga2)
288 CGroup: /system.slice/icinga2.service
289 21727 /usr/sbin/icinga2 -c /etc/icinga2/icinga2.conf -d -e /var/log/icinga2/error.log -u icinga -g icinga --no-stack-rlimit
291 Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 309 Service(s).
292 Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 1 User(s).
293 Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 15 Notification(s).
294 Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 4 ScheduledDowntime(s).
295 Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 1 UserGroup(s).
296 Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 1 IcingaApplication(s).
297 Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 8 Dependency(s).
298 Jul 23 13:39:38 nbmif systemd[1]: Started Icinga host/service/network monitoring system.
300 The `systemctl` command supports the following actions:
302 Command | Description
303 --------------------|------------------------
304 start | The `start` action starts the Icinga 2 daemon.
305 stop | The `stop` action stops the Icinga 2 daemon.
306 restart | The `restart` action is a shortcut for running the `stop` action followed by `start`.
307 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.
308 status | The `status` action checks if Icinga 2 is running.
309 enable | The `enable` action enables the service being started at system boot time (similar to `chkconfig`)
313 # systemctl enable icinga2
315 # systemctl restart icinga2
316 Job for icinga2.service failed. See 'systemctl status icinga2.service' and 'journalctl -xn' for details.
318 If you're stuck with configuration errors, you can manually invoke the
319 [configuration validation](11-cli-commands.md#config-validation).
323 On FreeBSD you need to enable icinga2 in your rc.conf
325 # sysrc icinga2_enable=yes
327 # service icinga2 restart
329 ## Configuration Syntax Highlighting <a id="configuration-syntax-highlighting"></a>
331 Icinga 2 ships configuration examples for syntax highlighting using the `vim` and `nano` editors.
332 The RHEL and SUSE package `icinga2-common` installs these files into `/usr/share/doc/icinga2-common-[x.x.x]/syntax`
333 (where `[x.x.x]` is the version number, e.g. `2.4.3` or `2.4.4`). Sources provide these files in `tools/syntax`.
334 On Debian systems the `icinga2-common` package provides only the Nano configuration file (`/usr/share/nano/icinga2.nanorc`);
335 to obtain the Vim configuration, please install the extra package `vim-icinga2`. The files are located in `/usr/share/vim/addons`.
337 ### Configuration Syntax Highlighting using Vim <a id="configuration-syntax-highlighting-vim"></a>
339 Install the package `vim-icinga2` with your distribution's package manager.
343 $ apt-get install vim-icinga2 vim-addon-manager
344 $ vim-addon-manager -w install icinga2
345 Info: installing removed addon 'icinga2' to /var/lib/vim/addons
349 $ yum install vim-icinga2
353 $ zypper install vim-icinga2
355 Ensure that syntax highlighting is enabled e.g. by editing the user's `vimrc`
363 $ vim /etc/icinga2/conf.d/templates.conf
365 ![Vim with syntax highlighting](images/getting-started/vim-syntax.png "Vim with Icinga 2 syntax highlighting")
368 ### Configuration Syntax Highlighting using Nano <a id="configuration-syntax-highlighting-nano"></a>
370 Install the package `nano-icinga2` with your distribution's package manager.
374 **Note:** The syntax files are installed with the `icinga2-common` package already.
378 $ yum install nano-icinga2
382 $ zypper install nano-icinga2
384 Copy the `/etc/nanorc` sample file to your home directory.
386 $ cp /etc/nanorc ~/.nanorc
388 Include the `icinga2.nanorc` file.
393 include "/usr/share/nano/icinga2.nanorc"
397 $ nano /etc/icinga2/conf.d/templates.conf
399 ![Nano with syntax highlighting](images/getting-started/nano-syntax.png "Nano with Icinga 2 syntax highlighting")
401 ## Setting up Icinga Web 2 <a id="setting-up-icingaweb2"></a>
403 Icinga 2 can be used with Icinga Web 2 and a number of other web interfaces.
404 This chapter explains how to set up Icinga Web 2.
406 The DB IDO (Database Icinga Data Output) modules for Icinga 2 take care of
407 exporting all configuration and status information into a database. The IDO
408 database is used by a number of projects including
409 [Icinga Web 2](02-getting-started.md#setting-up-icingaweb2), Icinga Reporting
412 There is a separate module for each database backend. At present support for
413 both MySQL and PostgreSQL is implemented.
415 Please choose whether to install [MySQL](02-getting-started.md#configuring-db-ido-mysql) or
416 [PostgreSQL](02-getting-started.md#configuring-db-ido-postgresql).
418 ### Configuring DB IDO MySQL <a id="configuring-db-ido-mysql"></a>
420 #### Installing MySQL database server <a id="installing-database-mysql-server"></a>
424 # apt-get install mysql-server mysql-client
425 # mysql_secure_installation
429 # yum install mysql-server mysql
430 # chkconfig mysqld on
431 # service mysqld start
432 # mysql_secure_installation
434 RHEL/CentOS 7 and Fedora:
436 # yum install mariadb-server mariadb
437 # systemctl enable mariadb
438 # systemctl start mariadb
439 # mysql_secure_installation
443 # zypper install mysql mysql-client
444 # chkconfig mysqld on
445 # service mysqld start
449 # pkg install mysql56-server
450 # sysrc mysql_enable=yes
451 # service mysql-server restart
452 # mysql_secure_installation
454 #### Installing the IDO modules for MySQL <a id="installing-database-mysql-modules"></a>
456 The next step is to install the `icinga2-ido-mysql` package using your
457 distribution's package manager.
461 # apt-get install icinga2-ido-mysql
465 # yum install icinga2-ido-mysql
469 # zypper install icinga2-ido-mysql
473 On FreeBSD the IDO modules for MySQL are included with the icinga2 package
474 and located at /usr/local/share/icinga2-ido-mysql/schema/mysql.sql
478 > The Debian/Ubuntu packages provide a database configuration wizard by
479 > default. You can skip the automated setup and install/upgrade the
480 > database manually if you prefer that.
482 #### Setting up the MySQL database <a id="setting-up-mysql-db"></a>
484 Set up a MySQL database for Icinga 2:
488 mysql> CREATE DATABASE icinga;
489 mysql> GRANT SELECT, INSERT, UPDATE, DELETE, DROP, CREATE VIEW, INDEX, EXECUTE ON icinga.* TO 'icinga'@'localhost' IDENTIFIED BY 'icinga';
492 ![setting up the database on CentOS 7](images/getting-started/mariadb-centos7.png "Setting up the database on CentOS 7")
494 After creating the database you can import the Icinga 2 IDO schema using the
497 # mysql -u root -p icinga < /usr/share/icinga2-ido-mysql/schema/mysql.sql
500 #### Enabling the IDO MySQL module <a id="enabling-ido-mysql"></a>
502 The package provides a new configuration file that is installed in
503 `/etc/icinga2/features-available/ido-mysql.conf`. You will need to
504 update the database credentials in this file.
506 All available attributes are explained in the
507 [IdoMysqlConnection object](09-object-types.md#objecttype-idomysqlconnection)
510 You can enable the `ido-mysql` feature configuration file using
511 `icinga2 feature enable`:
513 # icinga2 feature enable ido-mysql
514 Module 'ido-mysql' was enabled.
515 Make sure to restart Icinga 2 for these changes to take effect.
517 After enabling the ido-mysql feature you have to restart Icinga 2:
519 RHEL/CentOS 7/Fedora, SLES 12, Debian Jessie/Stretch, Ubuntu Xenial:
521 # systemctl restart icinga2
523 Debian/Ubuntu, RHEL/CentOS 6 and SUSE 11:
525 # service icinga2 restart
529 # service icinga2 restart
532 Continue with the [webserver setup](02-getting-started.md#icinga2-user-interface-webserver).
534 ### Configuring DB IDO PostgreSQL <a id="configuring-db-ido-postgresql"></a>
536 #### Installing PostgreSQL database server <a id="installing-database-postgresql-server"></a>
540 # apt-get install postgresql
544 # yum install postgresql-server postgresql
545 # chkconfig postgresql on
546 # service postgresql start
550 # yum install postgresql-server postgresql
551 # postgresql-setup initdb
552 # systemctl enable postgresql
553 # systemctl start postgresql
557 # zypper install postgresql postgresql-server
558 # chkconfig postgresql on
559 # service postgresql start
563 # pkg install postgresql93-server
564 # sysrc postgresql_enable=yes
565 # service postgresql start
567 #### Installing the IDO modules for PostgreSQL <a id="installing-database-postgresql-modules"></a>
569 The next step is to install the `icinga2-ido-pgsql` package using your
570 distribution's package manager.
574 # apt-get install icinga2-ido-pgsql
578 # yum install icinga2-ido-pgsql
582 # zypper install icinga2-ido-pgsql
586 On FreeBSD the IDO modules for PostgreSQL are included with the icinga2 package
587 and located at /usr/local/share/icinga2-ido-pgsql/schema/pgsql.sql
591 > Upstream Debian packages provide a database configuration wizard by default.
592 > You can skip the automated setup and install/upgrade the database manually
593 > if you prefer that.
595 #### Setting up the PostgreSQL database
597 Set up a PostgreSQL database for Icinga 2:
600 # sudo -u postgres psql -c "CREATE ROLE icinga WITH LOGIN PASSWORD 'icinga'"
601 # sudo -u postgres createdb -O icinga -E UTF8 icinga
602 # sudo -u postgres createlang plpgsql icinga
606 > When using PostgreSQL 9.x you can omit the `createlang` command.
607 > Also it is assumed here that your locale is set to utf-8, you may run into
608 > problems otherwise.
610 Locate your pg\_hba.conf (Debian: `/etc/postgresql/*/main/pg_hba.conf`,
611 RHEL/SUSE: `/var/lib/pgsql/data/pg_hba.conf`), add the icinga user with md5
612 authentication method and restart the postgresql server.
615 local icinga icinga md5
616 host icinga icinga 127.0.0.1/32 md5
617 host icinga icinga ::1/128 md5
619 # "local" is for Unix domain socket connections only
621 # IPv4 local connections:
622 host all all 127.0.0.1/32 ident
623 # IPv6 local connections:
624 host all all ::1/128 ident
626 # service postgresql restart
629 After creating the database and permissions you can import the Icinga 2 IDO
630 schema using the following command:
632 # export PGPASSWORD=icinga
633 # psql -U icinga -d icinga < /usr/share/icinga2-ido-pgsql/schema/pgsql.sql
635 ![importing the Icinga 2 IDO schema](images/getting-started/postgr-import-ido.png "Importing the Icinga 2 IDO schema on Debian Jessie")
638 #### Enabling the IDO PostgreSQL module <a id="enabling-ido-postgresql"></a>
640 The package provides a new configuration file that is installed in
641 `/etc/icinga2/features-available/ido-pgsql.conf`. You will need to update
642 the database credentials in this file.
644 All available attributes are explained in the
645 [IdoPgsqlConnection object](09-object-types.md#objecttype-idopgsqlconnection)
648 You can enable the `ido-pgsql` feature configuration file using
649 `icinga2 feature enable`:
651 # icinga2 feature enable ido-pgsql
652 Module 'ido-pgsql' was enabled.
653 Make sure to restart Icinga 2 for these changes to take effect.
655 After enabling the ido-pgsql feature you have to restart Icinga 2:
657 RHEL/CentOS 7/Fedora, SLES 12, Debian Jessie/Stretch, Ubuntu Xenial:
659 # systemctl restart icinga2
661 Debian/Ubuntu, RHEL/CentOS 6, SUSE and FreeBSD:
663 # service icinga2 restart
667 # service icinga2 restart
669 Continue with the [webserver setup](02-getting-started.md#icinga2-user-interface-webserver).
671 ### Webserver <a id="icinga2-user-interface-webserver"></a>
675 # apt-get install apache2
681 # service httpd start
683 RHEL/CentOS 7, Fedora:
686 # systemctl enable httpd
687 # systemctl start httpd
691 # zypper install apache2
693 # service apache2 start
695 FreeBSD (nginx, but you could also use the apache24 package):
697 # 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
698 # sysrc php_fpm_enable=yes
699 # sysrc nginx_enable=yes
700 # sed -i '' "s/listen\ =\ 127.0.0.1:9000/listen\ =\ \/var\/run\/php5-fpm.sock/" /usr/local/etc/php-fpm.conf
701 # sed -i '' "s/;listen.owner/listen.owner/" /usr/local/etc/php-fpm.conf
702 # sed -i '' "s/;listen.group/listen.group/" /usr/local/etc/php-fpm.conf
703 # sed -i '' "s/;listen.mode/listen.mode/" /usr/local/etc/php-fpm.conf
704 # service php-fpm start
705 # service nginx start
707 ### Firewall Rules <a id="icinga2-user-interface-firewall-rules"></a>
711 # iptables -A INPUT -p tcp -m tcp --dport 80 -j ACCEPT
712 # service iptables save
714 RHEL/CentOS 7 specific:
716 # firewall-cmd --add-service=http
717 # firewall-cmd --permanent --add-service=http
720 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.
723 ### Setting Up Icinga 2 REST API <a id="setting-up-rest-api"></a>
725 Icinga Web 2 and other web interfaces require the [REST API](12-icinga2-api.md#icinga2-api-setup)
726 to send actions (reschedule check, etc.) and query object details.
728 You can run the CLI command `icinga2 api setup` to enable the
729 `api` [feature](11-cli-commands.md#enable-features) and set up
730 certificates as well as a new API user `root` with an auto-generated password in the
731 `/etc/icinga2/conf.d/api-users.conf` configuration file:
735 Edit the `api-users.conf` file and add a new ApiUser object. Specify the [permissions](12-icinga2-api.md#icinga2-api-permissions)
736 attribute with minimal permissions required by Icinga Web 2.
738 # vim /etc/icinga2/conf.d/api-users.conf
740 object ApiUser "icingaweb2" {
741 password = "Wijsn8Z9eRs5E25d"
742 permissions = [ "status/query", "actions/*", "objects/modify/*", "objects/query/*" ]
745 Make sure to restart Icinga 2 to activate the configuration.
747 RHEL/CentOS 7/Fedora, SLES 12, Debian Jessie/Stretch, Ubuntu Xenial:
749 # systemctl restart icinga2
751 Debian/Ubuntu, RHEL/CentOS 6 and SUSE:
753 # service icinga2 restart
757 # service icinga2 restart
759 ### Installing Icinga Web 2 <a id="installing-icingaweb2"></a>
761 Please consult the [installation documentation](https://github.com/Icinga/icingaweb2/blob/master/doc/02-Installation.md)
762 for further instructions on how to install Icinga Web 2.
764 The Icinga 2 API can be defined as [command transport](https://github.com/Icinga/icingaweb2/blob/master/modules/monitoring/doc/commandtransports.md)
765 in Icinga Web 2 >= 2.4.
767 ## Addons <a id="install-addons"></a>
769 A number of additional features are available in the form of addons. A list of
770 popular addons is available in the
771 [Addons and Plugins](13-addons.md#addons) chapter.
773 ## Backup <a id="install-backup"></a>
775 Ensure to include the following in your backups:
777 * Configuration files in `/etc/icinga2`
778 * Runtime files in `/var/lib/icinga2` (the master's CA is stored here as well)
779 * Optional: IDO database backup