1 # <a id="getting-started"></a> Getting Started
3 This tutorial is a step-by-step introduction to installing Icinga 2 and
4 available Icinga web interfaces. It assumes that you are familiar with
5 the system you're installing Icinga 2 on.
7 Details on troubleshooting problems can be found [here](12-troubleshooting.md#troubleshooting).
9 ## <a id="setting-up-icinga2"></a> Setting up Icinga 2
11 First off you will have to install Icinga 2. The preferred way of doing this
12 is to use the official package repositories depending on which operating system
13 and distribution you are running.
15 Distribution | Repository
16 ------------------------|---------------------------
17 Debian | [debmon](http://debmon.org/packages/debmon-wheezy/icinga2), [Icinga Repository](http://packages.icinga.org/debian/)
18 Ubuntu | [Icinga PPA](https://launchpad.net/~formorer/+archive/ubuntu/icinga), [Icinga Repository](http://packages.icinga.org/ubuntu/)
19 RHEL/CentOS | [Icinga Repository](http://packages.icinga.org/epel/)
20 openSUSE | [Icinga Repository](http://packages.icinga.org/openSUSE/), [Server Monitoring Repository](https://build.opensuse.org/package/show/server:monitoring/icinga2)
21 SLES | [Icinga Repository](http://packages.icinga.org/SUSE/)
22 Gentoo | [Upstream](http://packages.gentoo.org/package/net-analyzer/icinga2)
23 FreeBSD | [Upstream](http://www.freshports.org/net-mgmt/icinga2)
24 ArchLinux | [Upstream](https://aur.archlinux.org/packages/icinga2)
26 Packages for distributions other than the ones listed above may also be
27 available. Please contact your distribution packagers.
29 ### <a id="installing-requirements"></a> Installing Requirements for Icinga 2
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 - http://debmon.org/debmon/repo.key 2>/dev/null | apt-key add -
37 # echo 'deb http://debmon.org/debmon debmon-wheezy main' >/etc/apt/sources.list.d/debmon.list
42 # add-apt-repository ppa:formorer/icinga
47 # rpm --import http://packages.icinga.org/icinga.key
48 # wget http://packages.icinga.org/epel/ICINGA-release.repo -O /etc/yum.repos.d/ICINGA-release.repo
53 # wget http://packages.icinga.org/fedora/ICINGA-release.repo -O /etc/yum.repos.d/ICINGA-release.repo
58 # zypper ar http://packages.icinga.org/SUSE/ICINGA-release.repo
63 # zypper ar http://packages.icinga.org/openSUSE/ICINGA-release.repo
66 The packages for RHEL/CentOS depend on other packages which are distributed
67 as part of the [EPEL repository](http://fedoraproject.org/wiki/EPEL). Please
68 make sure to enable this repository by following
69 [these instructions](http://fedoraproject.org/wiki/EPEL#How_can_I_use_these_extra_packages.3F).
71 ### <a id="installing-icinga2"></a> Installing Icinga 2
73 You can install Icinga 2 by using your distribution's package manager
74 to install the `icinga2` package.
78 # apt-get install icinga2
86 # zypper install icinga2
88 On RHEL/CentOS and SLES you will need to use `chkconfig` and `service` to enable and start
89 the `icinga2` service:
91 # chkconfig icinga2 on
92 # service icinga2 start
94 RHEL/CentOS 7 and Fedora use [systemd](2-getting-started.md#systemd-service):
96 # systemctl enable icinga2
97 # systemctl start icinga2
99 Some parts of Icinga 2's functionality are available as separate packages:
102 ------------------------|--------------------------------
103 icinga2-ido-mysql | [DB IDO](2-getting-started.md#configuring-db-ido) provider module for MySQL
104 icinga2-ido-pgsql | [DB IDO](2-getting-started.md#configuring-db-ido) provider module for PostgreSQL
106 ### <a id="installation-enabled-features"></a> Enabled Features during Installation
108 The default installation will enable three features required for a basic
109 Icinga 2 installation:
111 * `checker` for executing checks
112 * `notification` for sending notifications
113 * `mainlog` for writing the `icinga2.log` file
115 You can verify that by calling `icinga2 feature list` [CLI command](8-cli-commands.md#cli-command-feature)
116 to see which features are enabled and disabled.
118 # icinga2 feature list
119 Disabled features: api command compatlog debuglog graphite icingastatus ido-mysql ido-pgsql livestatus notification perfdata statusdata syslog
120 Enabled features: checker mainlog notification
123 ### <a id="installation-paths"></a> Installation Paths
125 By default Icinga 2 uses the following files and directories:
128 ------------------------------------|------------------------------------
129 /etc/icinga2 | Contains Icinga 2 configuration files.
130 /etc/init.d/icinga2 | The Icinga 2 init script.
131 /usr/sbin/icinga2* | The Icinga 2 binary.
132 /usr/share/doc/icinga2 | Documentation files that come with Icinga 2.
133 /usr/share/icinga2/include | The Icinga Template Library and plugin command configuration.
134 /var/run/icinga2 | PID file.
135 /var/run/icinga2/cmd | Command pipe and Livestatus socket.
136 /var/cache/icinga2 | status.dat/objects.cache, icinga2.debug files
137 /var/spool/icinga2 | Used for performance data spool files.
138 /var/lib/icinga2 | Icinga 2 state file, cluster log, local CA and configuration files.
139 /var/log/icinga2 | Log file location and compat/ directory for the CompatLogger feature.
141 ## <a id="setting-up-check-plugins"></a> Setting up Check Plugins
143 Without plugins Icinga 2 does not know how to check external services. The
144 [Monitoring Plugins Project](https://www.monitoring-plugins.org/) provides
145 an extensive set of plugins which can be used with Icinga 2 to check whether
146 services are working properly.
148 The recommended way of installing these standard plugins is to use your
149 distribution's package manager.
153 > The `Nagios Plugins` project was renamed to `Monitoring Plugins`
154 > in January 2014. At the time of this writing some packages are still
155 > using the old name while some distributions have adopted the new package
156 > name `monitoring-plugins` already.
158 For your convenience here is a list of package names for some of the more
159 popular operating systems/distributions:
161 OS/Distribution | Package Name | Installation Path
162 -----------------------|--------------------|---------------------------
163 RHEL/CentOS (EPEL) | nagios-plugins-all | /usr/lib/nagios/plugins or /usr/lib64/nagios/plugins
164 Debian | nagios-plugins | /usr/lib/nagios/plugins
165 FreeBSD | nagios-plugins | /usr/local/libexec/nagios
166 OS X (MacPorts) | nagios-plugins | /opt/local/libexec
168 Depending on which directory your plugins are installed into you may need to
169 update the global `PluginDir` constant in your [Icinga 2 configuration](4-configuring-icinga-2.md#constants-conf).
170 This macro is used by the check command definitions contained in the Icinga Template Library
171 to determine where to find the plugin binaries.
173 Please refer to the [plugins](9-addons-plugins.md#plugins) chapter for details about how to integrate
174 additional check plugins into your Icinga 2 setup.
176 ## <a id="configuring-db-ido"></a> Configuring DB IDO
178 The DB IDO (Database Icinga Data Output) modules for Icinga 2 take care of exporting
179 all configuration and status information into a database. The IDO database is used
180 by a number of projects including [Icinga Web 2](2-getting-started.md#setting-up-icingaweb2),
181 Icinga Reporting or Icinga Web 1.x.
183 You only need to set up the IDO modules if you're planning to use one of the web interfaces or
184 another external project which uses the IDO database.
186 There is a separate module for each database backend. At present support for
187 both MySQL and PostgreSQL is implemented.
189 ### <a id="configuring-db-ido-mysql"></a> Configuring DB IDO MySQL
191 #### <a id="installing-database-mysql-server"></a> Installing MySQL database server
195 # apt-get install mysql-server mysql-client
199 # yum install mysql-server mysql
200 # chkconfig mysqld on
201 # service mysqld start
203 RHEL/CentOS 7 and Fedora:
205 # yum install mariadb-server mariadb
206 # systemctl enable mariadb
207 # systemctl start mariadb
211 # zypper install mysql mysql-client
212 # chkconfig mysqld on
213 # service mysqld start
215 RHEL based distributions do not automatically set a secure root password. Do that **now**:
217 # /usr/bin/mysql_secure_installation
219 #### <a id="installing-database-mysql-modules"></a> Installing the IDO modules for MySQL
221 The next step is to install the `icinga2-ido-mysql` package using your
222 distribution's package manager.
226 # apt-get install icinga2-ido-mysql
230 # yum install icinga2-ido-mysql
234 # zypper install icinga2-ido-mysql
239 > Upstream Debian packages provide a database configuration wizard by default.
240 > You can skip the automated setup and install/upgrade the database manually
241 > if you prefer that.
243 #### <a id="setting-up-mysql-db"></a> Setting up the MySQL database
245 Set up a MySQL database for Icinga 2:
249 mysql> CREATE DATABASE icinga;
250 GRANT SELECT, INSERT, UPDATE, DELETE, DROP, CREATE VIEW, INDEX, EXECUTE ON icinga.* TO 'icinga'@'localhost' IDENTIFIED BY 'icinga';
253 After creating the database you can import the Icinga 2 IDO schema using the
256 # mysql -u root -p icinga < /usr/share/icinga2-ido-mysql/schema/mysql.sql
259 #### <a id="enabling-ido-mysql"></a> Enabling the IDO MySQL module
261 The package provides a new configuration file that is installed in
262 `/etc/icinga2/features-available/ido-mysql.conf`. You will need to update the
263 database credentials in this file.
264 All available attributes are listed in the
265 [IdoMysqlConnection object](5-object-types.md#objecttype-idomysqlconnection) configuration details.
267 You can enable the `ido-mysql` feature configuration file using `icinga2 feature enable`:
269 # icinga2 feature enable ido-mysql
270 Module 'ido-mysql' was enabled.
271 Make sure to restart Icinga 2 for these changes to take effect.
273 After enabling the ido-mysql feature you have to restart Icinga 2:
275 Debian/Ubuntu, RHEL/CentOS 6 and SUSE:
277 # service icinga2 restart
279 RHEL/CentOS 7 and Fedora:
281 # systemctl restart icinga2
283 ### <a id="configuring-db-ido-postgresql"></a> Configuring DB IDO PostgreSQL
285 #### <a id="installing-database-postgresql-server"></a> Installing PostgreSQL database server
289 # apt-get install postgresql
293 # yum install postgresql-server postgresql
294 # chkconfig postgresql on
295 # service postgresql start
299 # yum install postgresql-server postgresql
300 # systemctl enable postgresql
301 # systemctl start postgresql
305 # zypper install postgresql postgresql-server
306 # chkconfig postgresql on
307 # service postgresql start
309 #### <a id="installing-database-postgresql-modules"></a> Installing the IDO modules for PostgreSQL
311 The next step is to install the `icinga2-ido-pgsql` package using your
312 distribution's package manager.
316 # apt-get install icinga2-ido-pgsql
320 # yum install icinga2-ido-pgsql
324 # zypper install icinga2-ido-pgsql
328 > Upstream Debian packages provide a database configuration wizard by default.
329 > You can skip the automated setup and install/upgrade the database manually
330 > if you prefer that.
332 #### Setting up the PostgreSQL database
334 Set up a PostgreSQL database for Icinga 2:
337 # sudo -u postgres psql -c "CREATE ROLE icinga WITH LOGIN PASSWORD 'icinga'";
338 # sudo -u postgres createdb -O icinga -E UTF8 icinga
339 # sudo -u postgres createlang plpgsql icinga
343 > Using PostgreSQL 9.x you can omit the `createlang` command.
345 Locate your pg_hba.conf (Debian: `/etc/postgresql/*/main/pg_hba.conf`,
346 RHEL/SUSE: `/var/lib/pgsql/data/pg_hba.conf`), add the icinga user with md5
347 authentication method and restart the postgresql server.
349 # vim /var/lib/pgsql/data/pg_hba.conf
352 local icinga icinga md5
353 host icinga icinga 127.0.0.1/32 md5
354 host icinga icinga ::1/128 md5
356 # "local" is for Unix domain socket connections only
358 # IPv4 local connections:
359 host all all 127.0.0.1/32 ident
360 # IPv6 local connections:
361 host all all ::1/128 ident
363 # /etc/init.d/postgresql restart
366 After creating the database and permissions you can import the Icinga 2 IDO schema
367 using the following command:
369 # export PGPASSWORD=icinga
370 # psql -U icinga -d icinga < /usr/share/icinga2-ido-pgsql/schema/pgsql.sql
373 #### <a id="enabling-ido-postgresql"></a> Enabling the IDO PostgreSQL module
375 The package provides a new configuration file that is installed in
376 `/etc/icinga2/features-available/ido-pgsql.conf`. You will need to update the
377 database credentials in this file.
378 All available attributes are listed in the
379 [IdoPgsqlConnection object](5-object-types.md#objecttype-idopgsqlconnection) configuration details.
381 You can enable the `ido-pgsql` feature configuration file using `icinga2 feature enable`:
383 # icinga2 feature enable ido-pgsql
384 Module 'ido-pgsql' was enabled.
385 Make sure to restart Icinga 2 for these changes to take effect.
387 After enabling the ido-pgsql feature you have to restart Icinga 2:
389 Debian/Ubuntu, RHEL/CentOS 6 and SUSE:
391 # service icinga2 restart
393 RHEL/CentOS 7 and Fedora:
395 # systemctl restart icinga2
398 ### <a id="setting-up-external-command-pipe"></a> Setting Up External Command Pipe
400 Web interfaces and other Icinga addons are able to send commands to
401 Icinga 2 through the external command pipe.
403 You can enable the External Command Pipe using the CLI:
405 # icinga2 feature enable command
407 After that you will have to restart Icinga 2:
409 Debian/Ubuntu, RHEL/CentOS 6 and SUSE:
411 # service icinga2 restart
413 RHEL/CentOS 7 and Fedora:
415 # systemctl restart icinga2
417 By default the command pipe file is owned by the group `icingacmd` with read/write
418 permissions. Add your webserver's user to the group `icingacmd` to
419 enable sending commands to Icinga 2 through your web interface:
421 # usermod -a -G icingacmd www-data
423 Debian packages use `nagios` as the default user and group name. Therefore change `icingacmd` to
425 The webserver's user is different between distributions so you might have to change `www-data` to
426 `wwwrun`, `www`, or `apache`.
428 Change "www-data" to the user you're using to run queries.
432 > Packages will do that automatically. Verify that by running `id <your-webserver-user>` and skip this
435 ## <a id="running-icinga2"></a> Running Icinga 2
437 ### <a id="init-script"></a> Init Script
439 Icinga 2's init script is installed in `/etc/init.d/icinga2` by default:
441 # /etc/init.d/icinga2
442 Usage: /etc/init.d/icinga2 {start|stop|restart|reload|checkconfig|status}
444 Command | Description
445 --------------------|------------------------
446 start | The `start` action starts the Icinga 2 daemon.
447 stop | The `stop` action stops the Icinga 2 daemon.
448 restart | The `restart` action is a shortcut for running the `stop` action followed by `start`.
449 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.
450 checkconfig | The `checkconfig` action checks if the `/etc/icinga2/icinga2.conf` configuration file contains any errors.
451 status | The `status` action checks if Icinga 2 is running.
453 By default the Icinga 2 daemon is running as `icinga` user and group
454 using the init script. Using Debian packages the user and group are set to `nagios`
455 for historical reasons.
457 ### <a id="systemd-service"></a> systemd Service
459 Some distributions (e.g. Fedora, openSUSE and RHEL/CentOS 7) use systemd. The Icinga 2
460 packages automatically install the necessary systemd unit files.
462 The Icinga 2 systemd service can be (re)started, reloaded, stopped and also queried for its current status.
464 # systemctl status icinga2
465 icinga2.service - Icinga host/service/network monitoring system
466 Loaded: loaded (/usr/lib/systemd/system/icinga2.service; disabled)
467 Active: active (running) since Mi 2014-07-23 13:39:38 CEST; 15s ago
468 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)
469 Process: 21674 ExecStartPre=/usr/sbin/icinga2-prepare-dirs /etc/sysconfig/icinga2 (code=exited, status=0/SUCCESS)
470 Main PID: 21727 (icinga2)
471 CGroup: /system.slice/icinga2.service
472 └─21727 /usr/sbin/icinga2 -c /etc/icinga2/icinga2.conf -d -e /var/log/icinga2/error.log -u icinga -g icinga --no-stack-rlimit
474 Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 309 Service(s).
475 Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 1 User(s).
476 Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 15 Notification(s).
477 Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 4 ScheduledDowntime(s).
478 Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 1 UserGroup(s).
479 Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 1 IcingaApplication(s).
480 Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 8 Dependency(s).
481 Jul 23 13:39:38 nbmif systemd[1]: Started Icinga host/service/network monitoring system.
483 The `systemctl` command supports the following actions:
485 Command | Description
486 --------------------|------------------------
487 start | The `start` action starts the Icinga 2 daemon.
488 stop | The `stop` action stops the Icinga 2 daemon.
489 restart | The `restart` action is a shortcut for running the `stop` action followed by `start`.
490 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.
491 status | The `status` action checks if Icinga 2 is running.
492 enable | The `enable` action enables the service being started at system boot time (similar to `chkconfig`)
494 If you're stuck with configuration errors, you can manually invoke the [configuration validation](8-cli-commands.md#config-validation).
496 # systemctl enable icinga2
498 # systemctl restart icinga2
499 Job for icinga2.service failed. See 'systemctl status icinga2.service' and 'journalctl -xn' for details.
502 ## <a id="setting-up-the-user-interface"></a> Setting up the User Interface
504 Icinga 2 can be used with Icinga Web 2 and a number of other web interfaces. This chapter explains how
505 to set up Icinga Web 2. The [Alternative Frontends](10-alternative-frontends.md#alternative-frontends) chapter can be used as a
506 starting point for installing some of the other web interfaces which are also available.
509 #### <a id="icinga2-user-interface-webserver"></a> Webserver
513 # apt-get install apache2
518 # chkconfig httpd on && service httpd start
520 # systemctl enable httpd && systemctl start httpd
524 # zypper install apache2
525 # chkconfig on && service apache2 start
527 #### <a id="icinga2-user-interface-firewall-rules"></a> Firewall Rules
531 # iptables -A INPUT -p tcp -m tcp --dport 80 -j ACCEPT
532 # service iptables save
534 RHEL/CentOS 7 specific:
536 # firewall-cmd --add-service=http
537 # firewall-cmd --permanent --add-service=http
539 ### <a id="setting-up-icingaweb2"></a> Setting up Icinga Web 2
541 Icinga Web 2 supports `DB IDO` or `Livestatus` as backends.
543 Using DB IDO as backend, you need to install and configure the
544 [DB IDO backend](2-getting-started.md#configuring-db-ido).
546 In order to use commands in Web 2 you need to [set up the external command pipe](2-getting-started.md#setting-up-external-command-pipe).
548 [Icinga Web 2](https://github.com/Icinga/icingaweb2) ships its own
549 web-based setup wizard which will guide you through the entire setup process.
551 Generate the Webserver configuration and a setup token using its local cli
552 and proceed with the web setup when accessing `/icingaweb2` after reloading
553 your webserver configuration.
555 Please consult the [installation documentation](https://github.com/Icinga/icingaweb2/blob/master/doc/installation.md)
556 shipped with `Icinga Web 2` for further instructions on how to install
557 `Icinga Web 2` and to configure backends, resources and instances manually.
559 Check the [Icinga website](https://www.icinga.org) for release announcements
563 ### <a id="install-addons"></a> Addons
565 A number of additional features are available in the form of plugins. A list of popular
566 addons is available in the [Addons and Plugins](9-addons-plugins.md#addons-plugins) chapter.