1 # <a id="getting-started"></a> Getting Started
3 This tutorial is a step-by-step introduction to installing Icinga 2 and
4 Icinga Web 2. It assumes that you are familiar with the operating system
5 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-wheezy/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-wheezy 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
51 # rpm --import http://packages.icinga.org/icinga.key
52 # curl -o /etc/yum.repos.d/ICINGA-release.repo http://packages.icinga.org/fedora/ICINGA-release.repo
57 # zypper ar http://packages.icinga.org/SUSE/ICINGA-release-11.repo
62 # zypper ar http://packages.icinga.org/SUSE/ICINGA-release.repo
67 # zypper ar http://packages.icinga.org/openSUSE/ICINGA-release.repo
70 The packages for RHEL/CentOS depend on other packages which are distributed
71 as part of the [EPEL repository](http://fedoraproject.org/wiki/EPEL). Please
72 make sure to enable this repository by following
73 [these instructions](http://fedoraproject.org/wiki/EPEL#How_can_I_use_these_extra_packages.3F).
75 ### <a id="installing-icinga2"></a> Installing Icinga 2
77 You can install Icinga 2 by using your distribution's package manager
78 to install the `icinga2` package.
82 # apt-get install icinga2
87 # chkconfig icinga2 on
88 # service icinga2 start
90 RHEL/CentOS 7 and Fedora:
93 # systemctl enable icinga2
94 # systemctl start icinga2
98 # zypper install icinga2
100 ### <a id="installation-enabled-features"></a> Enabled Features during Installation
102 The default installation will enable three features required for a basic
103 Icinga 2 installation:
105 * `checker` for executing checks
106 * `notification` for sending notifications
107 * `mainlog` for writing the `icinga2.log` file
109 You can verify that by calling `icinga2 feature list`
110 [CLI command](8-cli-commands.md#cli-command-feature) to see which features are
111 enabled and disabled.
113 # icinga2 feature list
114 Disabled features: api command compatlog debuglog graphite icingastatus ido-mysql ido-pgsql livestatus notification perfdata statusdata syslog
115 Enabled features: checker mainlog notification
118 ### <a id="installation-paths"></a> Installation Paths
120 By default Icinga 2 uses the following files and directories:
123 ------------------------------------|------------------------------------
124 /etc/icinga2 | Contains Icinga 2 configuration files.
125 /etc/init.d/icinga2 | The Icinga 2 init script.
126 /usr/sbin/icinga2 | The Icinga 2 binary.
127 /usr/share/doc/icinga2 | Documentation files that come with Icinga 2.
128 /usr/share/icinga2/include | The Icinga Template Library and plugin command configuration.
129 /var/run/icinga2 | PID file.
130 /var/run/icinga2/cmd | Command pipe and Livestatus socket.
131 /var/cache/icinga2 | status.dat/objects.cache, icinga2.debug files
132 /var/spool/icinga2 | Used for performance data spool files.
133 /var/lib/icinga2 | Icinga 2 state file, cluster log, local CA and configuration files.
134 /var/log/icinga2 | Log file location and compat/ directory for the CompatLogger feature.
136 ## <a id="setting-up-check-plugins"></a> Setting up Check Plugins
138 Without plugins Icinga 2 does not know how to check external services. The
139 [Monitoring Plugins Project](https://www.monitoring-plugins.org/) provides
140 an extensive set of plugins which can be used with Icinga 2 to check whether
141 services are working properly.
143 The recommended way of installing these standard plugins is to use your
144 distribution's package manager.
146 For your convenience here is a list of package names for some of the more
147 popular operating systems/distributions:
149 OS/Distribution | Package Name | Installation Path
150 -----------------------|--------------------|---------------------------
151 RHEL/CentOS (EPEL) | nagios-plugins-all | /usr/lib/nagios/plugins or /usr/lib64/nagios/plugins
152 Debian | nagios-plugins | /usr/lib/nagios/plugins
153 FreeBSD | nagios-plugins | /usr/local/libexec/nagios
154 OS X (MacPorts) | nagios-plugins | /opt/local/libexec
156 Depending on which directory your plugins are installed into you may need to
157 update the global `PluginDir` constant in your [Icinga 2 configuration](5-configuring-icinga-2.md#constants-conf).
158 This constant is used by the check command definitions contained in the Icinga Template Library
159 to determine where to find the plugin binaries.
161 Please refer to the [plugins](13-addons-plugins.md#plugins) chapter for details about how to integrate
162 additional check plugins into your Icinga 2 setup.
164 ## <a id="running-icinga2"></a> Running Icinga 2
166 ### <a id="init-script"></a> Init Script
168 Icinga 2's init script is installed in `/etc/init.d/icinga2` by default:
170 # /etc/init.d/icinga2
171 Usage: /etc/init.d/icinga2 {start|stop|restart|reload|checkconfig|status}
173 The init script supports the following actions:
175 Command | Description
176 --------------------|------------------------
177 start | The `start` action starts the Icinga 2 daemon.
178 stop | The `stop` action stops the Icinga 2 daemon.
179 restart | The `restart` action is a shortcut for running the `stop` action followed by `start`.
180 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.
181 checkconfig | The `checkconfig` action checks if the `/etc/icinga2/icinga2.conf` configuration file contains any errors.
182 status | The `status` action checks if Icinga 2 is running.
184 By default the Icinga 2 daemon is running as `icinga` user and group
185 using the init script. Using Debian packages the user and group are set to
186 `nagios` for historical reasons.
188 ### <a id="systemd-service"></a> systemd Service
190 Some distributions (e.g. Fedora, openSUSE and RHEL/CentOS 7) use systemd. The
191 Icinga 2 packages automatically install the necessary systemd unit files.
193 The Icinga 2 systemd service can be (re-)started, reloaded, stopped and also
194 queried for its current status.
196 # systemctl status icinga2
197 icinga2.service - Icinga host/service/network monitoring system
198 Loaded: loaded (/usr/lib/systemd/system/icinga2.service; disabled)
199 Active: active (running) since Mi 2014-07-23 13:39:38 CEST; 15s ago
200 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)
201 Process: 21674 ExecStartPre=/usr/sbin/icinga2-prepare-dirs /etc/sysconfig/icinga2 (code=exited, status=0/SUCCESS)
202 Main PID: 21727 (icinga2)
203 CGroup: /system.slice/icinga2.service
204 21727 /usr/sbin/icinga2 -c /etc/icinga2/icinga2.conf -d -e /var/log/icinga2/error.log -u icinga -g icinga --no-stack-rlimit
206 Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 309 Service(s).
207 Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 1 User(s).
208 Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 15 Notification(s).
209 Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 4 ScheduledDowntime(s).
210 Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 1 UserGroup(s).
211 Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 1 IcingaApplication(s).
212 Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 8 Dependency(s).
213 Jul 23 13:39:38 nbmif systemd[1]: Started Icinga host/service/network monitoring system.
215 The `systemctl` command supports the following actions:
217 Command | Description
218 --------------------|------------------------
219 start | The `start` action starts the Icinga 2 daemon.
220 stop | The `stop` action stops the Icinga 2 daemon.
221 restart | The `restart` action is a shortcut for running the `stop` action followed by `start`.
222 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.
223 status | The `status` action checks if Icinga 2 is running.
224 enable | The `enable` action enables the service being started at system boot time (similar to `chkconfig`)
228 # systemctl enable icinga2
230 # systemctl restart icinga2
231 Job for icinga2.service failed. See 'systemctl status icinga2.service' and 'journalctl -xn' for details.
233 If you're stuck with configuration errors, you can manually invoke the
234 [configuration validation](8-cli-commands.md#config-validation).
237 ## <a id="configuration-syntax-highlighting"></a> Configuration Syntax Highlighting
239 Icinga 2 ships configuration examples for syntax highlighting using the `vim` and `nano` editors.
240 The RHEL, SUSE and Debian package `icinga2-common` install these files into
241 `/usr/share/*/icinga2-common/syntax`. Sources provide these files in `tools/syntax`.
243 ### <a id="configuration-syntax-highlighting-vim"></a> Configuration Syntax Highlighting using Vim
245 Create a new local vim configuration storage, if not already existing.
246 Edit `vim/ftdetect/icinga2.vim` if your paths to the Icinga 2 configuration
250 $ mkdir -p $PREFIX/{syntax,ftdetect}
251 $ cp vim/syntax/icinga2.vim $PREFIX/syntax/
252 $ cp vim/ftdetect/icinga2.vim $PREFIX/ftdetect/
256 $ vim /etc/icinga2/conf.d/templates.conf
258 ### <a id="configuration-syntax-highlighting-nano"></a> Configuration Syntax Highlighting using Nano
260 Copy the `/etc/nanorc` sample file to your home directory. Create the `/etc/nano` directory
261 and copy the provided `icinga2.nanorc` into it.
263 $ cp /etc/nanorc ~/.nanorc
266 # cp icinga2.nanorc /etc/nano/
268 Then include the icinga2.nanorc file in your ~/.nanorc by adding the following line:
273 include "/etc/nano/icinga2.nanorc"
277 $ nano /etc/icinga2/conf.d/templates.conf
280 ## <a id="setting-up-the-user-interface"></a> Setting up Icinga Web 2
282 Icinga 2 can be used with Icinga Web 2 and a number of other web interfaces.
283 This chapter explains how to set up Icinga Web 2. The
284 [Alternative Frontends](14-alternative-frontends.md#alternative-frontends)
285 chapter can be used as a starting point for installing some of the other web
286 interfaces which are also available.
288 The DB IDO (Database Icinga Data Output) modules for Icinga 2 take care of
289 exporting all configuration and status information into a database. The IDO
290 database is used by a number of projects including
291 [Icinga Web 2](2-getting-started.md#setting-up-icingaweb2), Icinga Reporting
294 There is a separate module for each database backend. At present support for
295 both MySQL and PostgreSQL is implemented.
297 ### <a id="configuring-db-ido-mysql"></a> Configuring DB IDO MySQL
299 #### <a id="installing-database-mysql-server"></a> Installing MySQL database server
303 # apt-get install mysql-server mysql-client
307 # yum install mysql-server mysql
308 # chkconfig mysqld on
309 # service mysqld start
310 # mysql_secure_installation
312 RHEL/CentOS 7 and Fedora:
314 # yum install mariadb-server mariadb
315 # systemctl enable mariadb
316 # systemctl start mariadb
317 # mysql_secure_installation
321 # zypper install mysql mysql-client
322 # chkconfig mysqld on
323 # service mysqld start
325 #### <a id="installing-database-mysql-modules"></a> Installing the IDO modules for MySQL
327 The next step is to install the `icinga2-ido-mysql` package using your
328 distribution's package manager.
332 # apt-get install icinga2-ido-mysql
336 # yum install icinga2-ido-mysql
340 # zypper install icinga2-ido-mysql
345 > The Debian/Ubuntu packages provide a database configuration wizard by
346 > default. You can skip the automated setup and install/upgrade the
347 > database manually if you prefer that.
349 #### <a id="setting-up-mysql-db"></a> Setting up the MySQL database
351 Set up a MySQL database for Icinga 2:
355 mysql> CREATE DATABASE icinga;
356 GRANT SELECT, INSERT, UPDATE, DELETE, DROP, CREATE VIEW, INDEX, EXECUTE ON icinga.* TO 'icinga'@'localhost' IDENTIFIED BY 'icinga';
358 After creating the database you can import the Icinga 2 IDO schema using the
361 # mysql -u root -p icinga < /usr/share/icinga2-ido-mysql/schema/mysql.sql
364 #### <a id="enabling-ido-mysql"></a> Enabling the IDO MySQL module
366 The package provides a new configuration file that is installed in
367 `/etc/icinga2/features-available/ido-mysql.conf`. You will need to
368 update the database credentials in this file.
370 All available attributes are explained in the
371 [IdoMysqlConnection object](6-object-types.md#objecttype-idomysqlconnection)
374 You can enable the `ido-mysql` feature configuration file using
375 `icinga2 feature enable`:
377 # icinga2 feature enable ido-mysql
378 Module 'ido-mysql' was enabled.
379 Make sure to restart Icinga 2 for these changes to take effect.
381 After enabling the ido-mysql feature you have to restart Icinga 2:
383 Debian/Ubuntu, RHEL/CentOS 6 and SUSE:
385 # service icinga2 restart
387 RHEL/CentOS 7 and Fedora:
389 # systemctl restart icinga2
391 ### <a id="configuring-db-ido-postgresql"></a> Configuring DB IDO PostgreSQL
393 #### <a id="installing-database-postgresql-server"></a> Installing PostgreSQL database server
397 # apt-get install postgresql
401 # yum install postgresql-server postgresql
402 # chkconfig postgresql on
403 # service postgresql start
407 # yum install postgresql-server postgresql
408 # systemctl enable postgresql
409 # systemctl start postgresql
413 # zypper install postgresql postgresql-server
414 # chkconfig postgresql on
415 # service postgresql start
417 #### <a id="installing-database-postgresql-modules"></a> Installing the IDO modules for PostgreSQL
419 The next step is to install the `icinga2-ido-pgsql` package using your
420 distribution's package manager.
424 # apt-get install icinga2-ido-pgsql
428 # yum install icinga2-ido-pgsql
432 # zypper install icinga2-ido-pgsql
436 > Upstream Debian packages provide a database configuration wizard by default.
437 > You can skip the automated setup and install/upgrade the database manually
438 > if you prefer that.
440 #### Setting up the PostgreSQL database
442 Set up a PostgreSQL database for Icinga 2:
445 # sudo -u postgres psql -c "CREATE ROLE icinga WITH LOGIN PASSWORD 'icinga'";
446 # sudo -u postgres createdb -O icinga -E UTF8 icinga
447 # sudo -u postgres createlang plpgsql icinga
451 > When using PostgreSQL 9.x you can omit the `createlang` command.
453 Locate your pg_hba.conf (Debian: `/etc/postgresql/*/main/pg_hba.conf`,
454 RHEL/SUSE: `/var/lib/pgsql/data/pg_hba.conf`), add the icinga user with md5
455 authentication method and restart the postgresql server.
457 # vim /var/lib/pgsql/data/pg_hba.conf
460 local icinga icinga md5
461 host icinga icinga 127.0.0.1/32 md5
462 host icinga icinga ::1/128 md5
464 # "local" is for Unix domain socket connections only
466 # IPv4 local connections:
467 host all all 127.0.0.1/32 ident
468 # IPv6 local connections:
469 host all all ::1/128 ident
471 # /etc/init.d/postgresql restart
474 After creating the database and permissions you can import the Icinga 2 IDO
475 schema using the following command:
477 # export PGPASSWORD=icinga
478 # psql -U icinga -d icinga < /usr/share/icinga2-ido-pgsql/schema/pgsql.sql
481 #### <a id="enabling-ido-postgresql"></a> Enabling the IDO PostgreSQL module
483 The package provides a new configuration file that is installed in
484 `/etc/icinga2/features-available/ido-pgsql.conf`. You will need to update
485 the database credentials in this file.
487 All available attributes are explained in the
488 [IdoPgsqlConnection object](6-object-types.md#objecttype-idopgsqlconnection)
491 You can enable the `ido-pgsql` feature configuration file using
492 `icinga2 feature enable`:
494 # icinga2 feature enable ido-pgsql
495 Module 'ido-pgsql' was enabled.
496 Make sure to restart Icinga 2 for these changes to take effect.
498 After enabling the ido-pgsql feature you have to restart Icinga 2:
500 Debian/Ubuntu, RHEL/CentOS 6 and SUSE:
502 # service icinga2 restart
504 RHEL/CentOS 7 and Fedora:
506 # systemctl restart icinga2
509 ### <a id="icinga2-user-interface-webserver"></a> Webserver
513 # apt-get install apache2
519 # service httpd start
521 RHEL/CentOS 7/Fedora:
524 # systemctl enable httpd
525 # systemctl start httpd
529 # zypper install apache2
531 # service apache2 start
533 ### <a id="icinga2-user-interface-firewall-rules"></a> Firewall Rules
537 # iptables -A INPUT -p tcp -m tcp --dport 80 -j ACCEPT
538 # service iptables save
540 RHEL/CentOS 7 specific:
542 # firewall-cmd --add-service=http
543 # firewall-cmd --permanent --add-service=http
546 ### <a id="setting-up-external-command-pipe"></a> Setting Up External Command Pipe
548 Web interfaces and other Icinga addons are able to send commands to
549 Icinga 2 through the external command pipe.
551 You can enable the External Command Pipe using the CLI:
553 # icinga2 feature enable command
555 After that you will have to restart Icinga 2:
557 Debian/Ubuntu, RHEL/CentOS 6 and SUSE:
559 # service icinga2 restart
561 RHEL/CentOS 7 and Fedora:
563 # systemctl restart icinga2
565 By default the command pipe file is owned by the group `icingacmd` with
566 read/write permissions. Add your webserver's user to the group `icingacmd` to
567 enable sending commands to Icinga 2 through your web interface:
569 # usermod -a -G icingacmd www-data
571 Debian packages use `nagios` as the default user and group name. Therefore
572 change `icingacmd` to `nagios`.
574 The webserver's user is different between distributions so you might have to
575 change `www-data` to `wwwrun`, `www`, or `apache`.
577 Change "www-data" to the user you're using to run queries.
579 You can verify that the user has been successfully added to the `icingacmd`
580 group using the `id` command:
582 $ id <your-webserver-user>
585 ### <a id="setting-up-icingaweb2"></a> Installing up Icinga Web 2
587 Please consult the [installation documentation](https://github.com/Icinga/icingaweb2/blob/master/doc/installation.md)
588 for further instructions on how to install Icinga Web 2.
591 ## <a id="install-addons"></a> Addons
593 A number of additional features are available in the form of addons. A list of
594 popular addons is available in the
595 [Addons and Plugins](13-addons-plugins.md#addons-plugins) chapter.