1 # <a id="getting-started"></a> Getting Started
3 This tutorial is a step-by-step introduction to installing [Icinga 2](2-getting-started.md#setting-up-icinga2)
4 and [Icinga Web 2](2-getting-started.md#setting-up-the-user-interface).
5 It assumes that you are familiar with the operating system you're using to install Icinga 2.
7 ## <a id="setting-up-icinga2"></a> Setting up Icinga 2
9 First off you will 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 | [debmon](http://debmon.org/packages/debmon-jessie/icinga2), [Icinga Repository](http://packages.icinga.org/debian/)
16 Ubuntu | [Icinga PPA](https://launchpad.net/~formorer/+archive/ubuntu/icinga), [Icinga Repository](http://packages.icinga.org/ubuntu/)
17 RHEL/CentOS | [Icinga Repository](http://packages.icinga.org/epel/)
18 openSUSE | [Icinga Repository](http://packages.icinga.org/openSUSE/), [Server Monitoring Repository](https://build.opensuse.org/package/show/server:monitoring/icinga2)
19 SLES | [Icinga Repository](http://packages.icinga.org/SUSE/)
20 Gentoo | [Upstream](http://packages.gentoo.org/package/net-analyzer/icinga2)
21 FreeBSD | [Upstream](http://www.freshports.org/net-mgmt/icinga2)
22 ArchLinux | [Upstream](https://aur.archlinux.org/packages/icinga2)
24 Packages for distributions other than the ones listed above may also be
25 available. Please contact your distribution packagers.
27 ### <a id="package-repositories"></a> Package Repositories
29 You need to add the Icinga repository to your package management configuration.
30 Below is a list with examples for the various distributions.
34 # wget -O - http://debmon.org/debmon/repo.key 2>/dev/null | apt-key add -
35 # echo 'deb http://debmon.org/debmon debmon-jessie main' >/etc/apt/sources.list.d/debmon.list
40 # add-apt-repository ppa:formorer/icinga
45 # rpm --import http://packages.icinga.org/icinga.key
46 # curl -o /etc/yum.repos.d/ICINGA-release.repo http://packages.icinga.org/epel/ICINGA-release.repo
49 The packages for RHEL/CentOS depend on other packages which are distributed
50 as part of the [EPEL repository](http://fedoraproject.org/wiki/EPEL). Please
51 make sure to enable this repository by following
52 [these instructions](http://fedoraproject.org/wiki/EPEL#How_can_I_use_these_extra_packages.3F).
56 # rpm --import http://packages.icinga.org/icinga.key
57 # curl -o /etc/yum.repos.d/ICINGA-release.repo http://packages.icinga.org/fedora/ICINGA-release.repo
62 # zypper ar http://packages.icinga.org/SUSE/ICINGA-release-11.repo
65 The packages for SLES 11 depend on the `openssl1` package which is distributed
66 as part of the [SLES 11 Security Module](https://www.suse.com/communities/conversations/introducing-the-suse-linux-enterprise-11-security-module/).
70 # zypper ar http://packages.icinga.org/SUSE/ICINGA-release.repo
75 # zypper ar http://packages.icinga.org/openSUSE/ICINGA-release.repo
78 ### <a id="installing-icinga2"></a> Installing Icinga 2
80 You can install Icinga 2 by using your distribution's package manager
81 to install the `icinga2` package.
85 # apt-get install icinga2
90 # chkconfig icinga2 on
91 # service icinga2 start
93 RHEL/CentOS 7 and Fedora:
96 # systemctl enable icinga2
97 # systemctl start icinga2
101 # zypper install icinga2
105 # pkg install icinga2
107 ### <a id="installation-enabled-features"></a> Enabled Features during Installation
109 The default installation will enable three features required for a basic
110 Icinga 2 installation:
112 * `checker` for executing checks
113 * `notification` for sending notifications
114 * `mainlog` for writing the `icinga2.log` file
116 You can verify that by calling `icinga2 feature list`
117 [CLI command](8-cli-commands.md#cli-command-feature) to see which features are
118 enabled and disabled.
120 # icinga2 feature list
121 Disabled features: api command compatlog debuglog graphite icingastatus ido-mysql ido-pgsql livestatus notification perfdata statusdata syslog
122 Enabled features: checker mainlog notification
125 ### <a id="installation-paths"></a> Installation Paths
127 By default Icinga 2 uses the following files and directories:
130 ------------------------------------|------------------------------------
131 /etc/icinga2 | Contains Icinga 2 configuration files.
132 /etc/init.d/icinga2 | The Icinga 2 init script.
133 /usr/sbin/icinga2 | The Icinga 2 binary.
134 /usr/share/doc/icinga2 | Documentation files that come with Icinga 2.
135 /usr/share/icinga2/include | The Icinga Template Library and plugin command configuration.
136 /var/run/icinga2 | PID file.
137 /var/run/icinga2/cmd | Command pipe and Livestatus socket.
138 /var/cache/icinga2 | status.dat/objects.cache, icinga2.debug files
139 /var/spool/icinga2 | Used for performance data spool files.
140 /var/lib/icinga2 | Icinga 2 state file, cluster log, local CA and configuration files.
141 /var/log/icinga2 | Log file location and compat/ directory for the CompatLogger feature.
143 FreeBSD uses slightly different paths:
145 By default Icinga 2 uses the following files and directories:
148 ------------------------------------|------------------------------------
149 /usr/local/etc/icinga2 | Contains Icinga 2 configuration files.
150 /usr/local/etc/rc.d/icinga2 | The Icinga 2 init script.
151 /usr/local/sbin/icinga2 | The Icinga 2 binary.
152 /usr/local/share/doc/icinga2 | Documentation files that come with Icinga 2.
153 /usr/local/share/icinga2/include | The Icinga Template Library and plugin command configuration.
154 /var/run/icinga2 | PID file.
155 /var/run/icinga2/cmd | Command pipe and Livestatus socket.
156 /var/cache/icinga2 | status.dat/objects.cache, icinga2.debug files
157 /var/spool/icinga2 | Used for performance data spool files.
158 /var/lib/icinga2 | Icinga 2 state file, cluster log, local CA and configuration files.
159 /var/log/icinga2 | Log file location and compat/ directory for the CompatLogger feature.
161 ## <a id="setting-up-check-plugins"></a> Setting up Check Plugins
163 Without plugins Icinga 2 does not know how to check external services. The
164 [Monitoring Plugins Project](https://www.monitoring-plugins.org/) provides
165 an extensive set of plugins which can be used with Icinga 2 to check whether
166 services are working properly.
168 The recommended way of installing these standard plugins is to use your
169 distribution's package manager.
171 For your convenience here is a list of package names for some of the more
172 popular operating systems/distributions:
174 OS/Distribution | Package Name | Installation Path
175 -----------------------|--------------------|---------------------------
176 RHEL/CentOS (EPEL) | nagios-plugins-all | /usr/lib/nagios/plugins or /usr/lib64/nagios/plugins
177 Debian | nagios-plugins | /usr/lib/nagios/plugins
178 FreeBSD | monitoring-plugins | /usr/local/libexec/nagios
179 OS X (MacPorts) | nagios-plugins | /opt/local/libexec
181 Depending on which directory your plugins are installed into you may need to
182 update the global `PluginDir` constant in your [Icinga 2 configuration](4-configuring-icinga-2.md#constants-conf).
183 This constant is used by the check command definitions contained in the Icinga Template Library
184 to determine where to find the plugin binaries.
186 Please refer to the [plugins](14-addons-plugins.md#plugins) chapter for details about how to integrate
187 additional check plugins into your Icinga 2 setup.
189 ## <a id="running-icinga2"></a> Running Icinga 2
191 ### <a id="init-script"></a> Init Script
193 Icinga 2's init script is installed in `/etc/init.d/icinga2` (`/usr/local/etc/rc.d/icinga2` on FreeBSD) by default:
195 # /etc/init.d/icinga2
196 Usage: /etc/init.d/icinga2 {start|stop|restart|reload|checkconfig|status}
198 The init script supports the following actions:
200 Command | Description
201 --------------------|------------------------
202 start | The `start` action starts the Icinga 2 daemon.
203 stop | The `stop` action stops the Icinga 2 daemon.
204 restart | The `restart` action is a shortcut for running the `stop` action followed by `start`.
205 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.
206 checkconfig | The `checkconfig` action checks if the `/etc/icinga2/icinga2.conf` configuration file contains any errors.
207 status | The `status` action checks if Icinga 2 is running.
209 By default the Icinga 2 daemon is running as `icinga` user and group
210 using the init script. Using Debian packages the user and group are set to
211 `nagios` for historical reasons.
213 ### <a id="systemd-service"></a> systemd Service
215 Some distributions (e.g. Fedora, openSUSE and RHEL/CentOS 7) use systemd. The
216 Icinga 2 packages automatically install the necessary systemd unit files.
218 The Icinga 2 systemd service can be (re-)started, reloaded, stopped and also
219 queried for its current status.
221 # systemctl status icinga2
222 icinga2.service - Icinga host/service/network monitoring system
223 Loaded: loaded (/usr/lib/systemd/system/icinga2.service; disabled)
224 Active: active (running) since Mi 2014-07-23 13:39:38 CEST; 15s ago
225 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)
226 Process: 21674 ExecStartPre=/usr/sbin/icinga2-prepare-dirs /etc/sysconfig/icinga2 (code=exited, status=0/SUCCESS)
227 Main PID: 21727 (icinga2)
228 CGroup: /system.slice/icinga2.service
229 21727 /usr/sbin/icinga2 -c /etc/icinga2/icinga2.conf -d -e /var/log/icinga2/error.log -u icinga -g icinga --no-stack-rlimit
231 Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 309 Service(s).
232 Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 1 User(s).
233 Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 15 Notification(s).
234 Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 4 ScheduledDowntime(s).
235 Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 1 UserGroup(s).
236 Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 1 IcingaApplication(s).
237 Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 8 Dependency(s).
238 Jul 23 13:39:38 nbmif systemd[1]: Started Icinga host/service/network monitoring system.
240 The `systemctl` command supports the following actions:
242 Command | Description
243 --------------------|------------------------
244 start | The `start` action starts the Icinga 2 daemon.
245 stop | The `stop` action stops the Icinga 2 daemon.
246 restart | The `restart` action is a shortcut for running the `stop` action followed by `start`.
247 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.
248 status | The `status` action checks if Icinga 2 is running.
249 enable | The `enable` action enables the service being started at system boot time (similar to `chkconfig`)
253 # systemctl enable icinga2
255 # systemctl restart icinga2
256 Job for icinga2.service failed. See 'systemctl status icinga2.service' and 'journalctl -xn' for details.
258 If you're stuck with configuration errors, you can manually invoke the
259 [configuration validation](8-cli-commands.md#config-validation).
263 On FreeBSD you need to enable icinga2 in your rc.conf
265 # sysrc icinga2_enable=yes
267 # service icinga2 restart
269 ## <a id="configuration-syntax-highlighting"></a> Configuration Syntax Highlighting
271 Icinga 2 ships configuration examples for syntax highlighting using the `vim` and `nano` editors.
272 The RHEL, SUSE and Debian package `icinga2-common` install these files into
273 `/usr/share/*/icinga2-common/syntax`. Sources provide these files in `tools/syntax`.
275 ### <a id="configuration-syntax-highlighting-vim"></a> Configuration Syntax Highlighting using Vim
277 Create a new local vim configuration storage, if not already existing.
278 Edit `vim/ftdetect/icinga2.vim` if your paths to the Icinga 2 configuration
282 $ mkdir -p $PREFIX/{syntax,ftdetect}
283 $ cp vim/syntax/icinga2.vim $PREFIX/syntax/
284 $ cp vim/ftdetect/icinga2.vim $PREFIX/ftdetect/
288 $ vim /etc/icinga2/conf.d/templates.conf
290 ### <a id="configuration-syntax-highlighting-nano"></a> Configuration Syntax Highlighting using Nano
292 Copy the `/etc/nanorc` sample file to your home directory. Create the `/etc/nano` directory
293 and copy the provided `icinga2.nanorc` into it.
295 $ cp /etc/nanorc ~/.nanorc
298 # cp icinga2.nanorc /etc/nano/
300 Then include the icinga2.nanorc file in your ~/.nanorc by adding the following line:
305 include "/etc/nano/icinga2.nanorc"
309 $ nano /etc/icinga2/conf.d/templates.conf
312 ## <a id="setting-up-the-user-interface"></a> Setting up Icinga Web 2
314 Icinga 2 can be used with Icinga Web 2 and a number of other web interfaces.
315 This chapter explains how to set up Icinga Web 2. The
316 [Alternative Frontends](15-alternative-frontends.md#alternative-frontends)
317 chapter can be used as a starting point for installing some of the other web
318 interfaces which are also available.
320 The DB IDO (Database Icinga Data Output) modules for Icinga 2 take care of
321 exporting all configuration and status information into a database. The IDO
322 database is used by a number of projects including
323 [Icinga Web 2](2-getting-started.md#setting-up-icingaweb2), Icinga Reporting
326 There is a separate module for each database backend. At present support for
327 both MySQL and PostgreSQL is implemented.
329 ### <a id="configuring-db-ido-mysql"></a> Configuring DB IDO MySQL
331 #### <a id="installing-database-mysql-server"></a> Installing MySQL database server
335 # apt-get install mysql-server mysql-client
339 # yum install mysql-server mysql
340 # chkconfig mysqld on
341 # service mysqld start
342 # mysql_secure_installation
344 RHEL/CentOS 7 and Fedora:
346 # yum install mariadb-server mariadb
347 # systemctl enable mariadb
348 # systemctl start mariadb
349 # mysql_secure_installation
353 # zypper install mysql mysql-client
354 # chkconfig mysqld on
355 # service mysqld start
359 # pkg install mysql56-server
360 # sysrc mysql_enable=yes
361 # service mysql-server restart
362 # mysql_secure_installation
364 #### <a id="installing-database-mysql-modules"></a> Installing the IDO modules for MySQL
366 The next step is to install the `icinga2-ido-mysql` package using your
367 distribution's package manager.
371 # apt-get install icinga2-ido-mysql
375 # yum install icinga2-ido-mysql
379 # zypper install icinga2-ido-mysql
383 On FreeBSD the IDO modules for MySQL are included with the icinga2 package
384 and located at /usr/local/share/icinga2-ido-mysql/schema/mysql.sql
388 > The Debian/Ubuntu packages provide a database configuration wizard by
389 > default. You can skip the automated setup and install/upgrade the
390 > database manually if you prefer that.
392 #### <a id="setting-up-mysql-db"></a> Setting up the MySQL database
394 Set up a MySQL database for Icinga 2:
398 mysql> CREATE DATABASE icinga;
399 GRANT SELECT, INSERT, UPDATE, DELETE, DROP, CREATE VIEW, INDEX, EXECUTE ON icinga.* TO 'icinga'@'localhost' IDENTIFIED BY 'icinga';
401 After creating the database you can import the Icinga 2 IDO schema using the
404 # mysql -u root -p icinga < /usr/share/icinga2-ido-mysql/schema/mysql.sql
407 #### <a id="enabling-ido-mysql"></a> Enabling the IDO MySQL module
409 The package provides a new configuration file that is installed in
410 `/etc/icinga2/features-available/ido-mysql.conf`. You will need to
411 update the database credentials in this file.
413 All available attributes are explained in the
414 [IdoMysqlConnection object](6-object-types.md#objecttype-idomysqlconnection)
417 You can enable the `ido-mysql` feature configuration file using
418 `icinga2 feature enable`:
420 # icinga2 feature enable ido-mysql
421 Module 'ido-mysql' was enabled.
422 Make sure to restart Icinga 2 for these changes to take effect.
424 After enabling the ido-mysql feature you have to restart Icinga 2:
426 Debian/Ubuntu, RHEL/CentOS 6 and SUSE:
428 # service icinga2 restart
430 RHEL/CentOS 7 and Fedora:
432 # systemctl restart icinga2
436 # service icinga2 restart
438 ### <a id="configuring-db-ido-postgresql"></a> Configuring DB IDO PostgreSQL
440 #### <a id="installing-database-postgresql-server"></a> Installing PostgreSQL database server
444 # apt-get install postgresql
448 # yum install postgresql-server postgresql
449 # chkconfig postgresql on
450 # service postgresql start
454 # yum install postgresql-server postgresql
455 # postgresql-setup --initdb
456 # systemctl enable postgresql
457 # systemctl start postgresql
461 # zypper install postgresql postgresql-server
462 # chkconfig postgresql on
463 # service postgresql start
467 # pkg install postgresql93-server
468 # sysrc postgresql_enable=yes
469 # service postgresql start
471 #### <a id="installing-database-postgresql-modules"></a> Installing the IDO modules for PostgreSQL
473 The next step is to install the `icinga2-ido-pgsql` package using your
474 distribution's package manager.
478 # apt-get install icinga2-ido-pgsql
482 # yum install icinga2-ido-pgsql
486 # zypper install icinga2-ido-pgsql
490 On FreeBSD the IDO modules for PostgreSQL are included with the icinga2 package
491 and located at /usr/local/share/icinga2-ido-pgsql/schema/pgsql.sql
495 > Upstream Debian packages provide a database configuration wizard by default.
496 > You can skip the automated setup and install/upgrade the database manually
497 > if you prefer that.
499 #### Setting up the PostgreSQL database
501 Set up a PostgreSQL database for Icinga 2:
504 # sudo -u postgres psql -c "CREATE ROLE icinga WITH LOGIN PASSWORD 'icinga'";
505 # sudo -u postgres createdb -O icinga -E UTF8 icinga
506 # sudo -u postgres createlang plpgsql icinga
510 > When using PostgreSQL 9.x you can omit the `createlang` command.
512 Locate your pg_hba.conf (Debian: `/etc/postgresql/*/main/pg_hba.conf`,
513 RHEL/SUSE: `/var/lib/pgsql/data/pg_hba.conf`), add the icinga user with md5
514 authentication method and restart the postgresql server.
516 # vim /var/lib/pgsql/data/pg_hba.conf
519 local icinga icinga md5
520 host icinga icinga 127.0.0.1/32 md5
521 host icinga icinga ::1/128 md5
523 # "local" is for Unix domain socket connections only
525 # IPv4 local connections:
526 host all all 127.0.0.1/32 ident
527 # IPv6 local connections:
528 host all all ::1/128 ident
530 # service postgresql restart
533 After creating the database and permissions you can import the Icinga 2 IDO
534 schema using the following command:
536 # export PGPASSWORD=icinga
537 # psql -U icinga -d icinga < /usr/share/icinga2-ido-pgsql/schema/pgsql.sql
540 #### <a id="enabling-ido-postgresql"></a> Enabling the IDO PostgreSQL module
542 The package provides a new configuration file that is installed in
543 `/etc/icinga2/features-available/ido-pgsql.conf`. You will need to update
544 the database credentials in this file.
546 All available attributes are explained in the
547 [IdoPgsqlConnection object](6-object-types.md#objecttype-idopgsqlconnection)
550 You can enable the `ido-pgsql` feature configuration file using
551 `icinga2 feature enable`:
553 # icinga2 feature enable ido-pgsql
554 Module 'ido-pgsql' was enabled.
555 Make sure to restart Icinga 2 for these changes to take effect.
557 After enabling the ido-pgsql feature you have to restart Icinga 2:
559 Debian/Ubuntu, RHEL/CentOS 6, SUSE and FreeBSD:
561 # service icinga2 restart
563 RHEL/CentOS 7 and Fedora:
565 # systemctl restart icinga2
568 ### <a id="icinga2-user-interface-webserver"></a> Webserver
572 # apt-get install apache2
578 # service httpd start
580 RHEL/CentOS 7/Fedora:
583 # systemctl enable httpd
584 # systemctl start httpd
588 # zypper install apache2
590 # service apache2 start
592 FreeBSD (nginx, but you could also use the apache24 package):
594 # 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
595 # sysrc php_fpm_enable=yes
596 # sysrc nginx_enable=yes
597 # sed -i '' "s/listen\ =\ 127.0.0.1:9000/listen\ =\ \/var\/run\/php5-fpm.sock/" /usr/local/etc/php-fpm.conf
598 # sed -i '' "s/;listen.owner/listen.owner/" /usr/local/etc/php-fpm.conf
599 # sed -i '' "s/;listen.group/listen.group/" /usr/local/etc/php-fpm.conf
600 # sed -i '' "s/;listen.mode/listen.mode/" /usr/local/etc/php-fpm.conf
601 # service php-fpm start
602 # service nginx start
604 ### <a id="icinga2-user-interface-firewall-rules"></a> Firewall Rules
608 # iptables -A INPUT -p tcp -m tcp --dport 80 -j ACCEPT
609 # service iptables save
611 RHEL/CentOS 7 specific:
613 # firewall-cmd --add-service=http
614 # firewall-cmd --permanent --add-service=http
617 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.
620 ### <a id="setting-up-external-command-pipe"></a> Setting Up External Command Pipe
622 Web interfaces and other Icinga addons are able to send commands to
623 Icinga 2 through the external command pipe.
625 You can enable the External Command Pipe using the CLI:
627 # icinga2 feature enable command
629 After that you will have to restart Icinga 2:
631 Debian/Ubuntu, RHEL/CentOS 6 and SUSE:
633 # service icinga2 restart
635 RHEL/CentOS 7 and Fedora:
637 # systemctl restart icinga2
641 # service icinga2 restart
643 By default the command pipe file is owned by the group `icingacmd` with
644 read/write permissions. Add your webserver's user to the group `icingacmd` to
645 enable sending commands to Icinga 2 through your web interface:
647 # usermod -a -G icingacmd www-data
650 On FreeBSD the rw directory is owned by the group `www`. You do not need to add the
651 user `icinga` to the group `www`.
653 Debian packages use `nagios` as the default user and group name. Therefore
654 change `icingacmd` to `nagios`.
656 The webserver's user is different between distributions so you might have to
657 change `www-data` to `wwwrun`, `www`, or `apache`.
659 Change "www-data" to the user you're using to run queries.
661 You can verify that the user has been successfully added to the `icingacmd`
662 group using the `id` command:
664 $ id <your-webserver-user>
667 ### <a id="setting-up-icingaweb2"></a> Installing up Icinga Web 2
669 Please consult the [installation documentation](https://github.com/Icinga/icingaweb2/blob/master/doc/installation.md)
670 for further instructions on how to install Icinga Web 2.
673 ## <a id="install-addons"></a> Addons
675 A number of additional features are available in the form of addons. A list of
676 popular addons is available in the
677 [Addons and Plugins](14-addons-plugins.md#addons-plugins) chapter.