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-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
103 ### <a id="installation-enabled-features"></a> Enabled Features during Installation
105 The default installation will enable three features required for a basic
106 Icinga 2 installation:
108 * `checker` for executing checks
109 * `notification` for sending notifications
110 * `mainlog` for writing the `icinga2.log` file
112 You can verify that by calling `icinga2 feature list`
113 [CLI command](8-cli-commands.md#cli-command-feature) to see which features are
114 enabled and disabled.
116 # icinga2 feature list
117 Disabled features: api command compatlog debuglog graphite icingastatus ido-mysql ido-pgsql livestatus notification perfdata statusdata syslog
118 Enabled features: checker mainlog notification
121 ### <a id="installation-paths"></a> Installation Paths
123 By default Icinga 2 uses the following files and directories:
126 ------------------------------------|------------------------------------
127 /etc/icinga2 | Contains Icinga 2 configuration files.
128 /etc/init.d/icinga2 | The Icinga 2 init script.
129 /usr/sbin/icinga2 | The Icinga 2 binary.
130 /usr/share/doc/icinga2 | Documentation files that come with Icinga 2.
131 /usr/share/icinga2/include | The Icinga Template Library and plugin command configuration.
132 /var/run/icinga2 | PID file.
133 /var/run/icinga2/cmd | Command pipe and Livestatus socket.
134 /var/cache/icinga2 | status.dat/objects.cache, icinga2.debug files
135 /var/spool/icinga2 | Used for performance data spool files.
136 /var/lib/icinga2 | Icinga 2 state file, cluster log, local CA and configuration files.
137 /var/log/icinga2 | Log file location and compat/ directory for the CompatLogger feature.
139 ## <a id="setting-up-check-plugins"></a> Setting up Check Plugins
141 Without plugins Icinga 2 does not know how to check external services. The
142 [Monitoring Plugins Project](https://www.monitoring-plugins.org/) provides
143 an extensive set of plugins which can be used with Icinga 2 to check whether
144 services are working properly.
146 The recommended way of installing these standard plugins is to use your
147 distribution's package manager.
149 For your convenience here is a list of package names for some of the more
150 popular operating systems/distributions:
152 OS/Distribution | Package Name | Installation Path
153 -----------------------|--------------------|---------------------------
154 RHEL/CentOS (EPEL) | nagios-plugins-all | /usr/lib/nagios/plugins or /usr/lib64/nagios/plugins
155 Debian | nagios-plugins | /usr/lib/nagios/plugins
156 FreeBSD | nagios-plugins | /usr/local/libexec/nagios
157 OS X (MacPorts) | nagios-plugins | /opt/local/libexec
159 Depending on which directory your plugins are installed into you may need to
160 update the global `PluginDir` constant in your [Icinga 2 configuration](4-configuring-icinga-2.md#constants-conf).
161 This constant is used by the check command definitions contained in the Icinga Template Library
162 to determine where to find the plugin binaries.
164 Please refer to the [plugins](14-addons-plugins.md#plugins) chapter for details about how to integrate
165 additional check plugins into your Icinga 2 setup.
167 ## <a id="running-icinga2"></a> Running Icinga 2
169 ### <a id="init-script"></a> Init Script
171 Icinga 2's init script is installed in `/etc/init.d/icinga2` by default:
173 # /etc/init.d/icinga2
174 Usage: /etc/init.d/icinga2 {start|stop|restart|reload|checkconfig|status}
176 The init script supports the following actions:
178 Command | Description
179 --------------------|------------------------
180 start | The `start` action starts the Icinga 2 daemon.
181 stop | The `stop` action stops the Icinga 2 daemon.
182 restart | The `restart` action is a shortcut for running the `stop` action followed by `start`.
183 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.
184 checkconfig | The `checkconfig` action checks if the `/etc/icinga2/icinga2.conf` configuration file contains any errors.
185 status | The `status` action checks if Icinga 2 is running.
187 By default the Icinga 2 daemon is running as `icinga` user and group
188 using the init script. Using Debian packages the user and group are set to
189 `nagios` for historical reasons.
191 ### <a id="systemd-service"></a> systemd Service
193 Some distributions (e.g. Fedora, openSUSE and RHEL/CentOS 7) use systemd. The
194 Icinga 2 packages automatically install the necessary systemd unit files.
196 The Icinga 2 systemd service can be (re-)started, reloaded, stopped and also
197 queried for its current status.
199 # systemctl status icinga2
200 icinga2.service - Icinga host/service/network monitoring system
201 Loaded: loaded (/usr/lib/systemd/system/icinga2.service; disabled)
202 Active: active (running) since Mi 2014-07-23 13:39:38 CEST; 15s ago
203 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)
204 Process: 21674 ExecStartPre=/usr/sbin/icinga2-prepare-dirs /etc/sysconfig/icinga2 (code=exited, status=0/SUCCESS)
205 Main PID: 21727 (icinga2)
206 CGroup: /system.slice/icinga2.service
207 21727 /usr/sbin/icinga2 -c /etc/icinga2/icinga2.conf -d -e /var/log/icinga2/error.log -u icinga -g icinga --no-stack-rlimit
209 Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 309 Service(s).
210 Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 1 User(s).
211 Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 15 Notification(s).
212 Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 4 ScheduledDowntime(s).
213 Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 1 UserGroup(s).
214 Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 1 IcingaApplication(s).
215 Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 8 Dependency(s).
216 Jul 23 13:39:38 nbmif systemd[1]: Started Icinga host/service/network monitoring system.
218 The `systemctl` command supports the following actions:
220 Command | Description
221 --------------------|------------------------
222 start | The `start` action starts the Icinga 2 daemon.
223 stop | The `stop` action stops the Icinga 2 daemon.
224 restart | The `restart` action is a shortcut for running the `stop` action followed by `start`.
225 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.
226 status | The `status` action checks if Icinga 2 is running.
227 enable | The `enable` action enables the service being started at system boot time (similar to `chkconfig`)
231 # systemctl enable icinga2
233 # systemctl restart icinga2
234 Job for icinga2.service failed. See 'systemctl status icinga2.service' and 'journalctl -xn' for details.
236 If you're stuck with configuration errors, you can manually invoke the
237 [configuration validation](8-cli-commands.md#config-validation).
240 ## <a id="configuration-syntax-highlighting"></a> Configuration Syntax Highlighting
242 Icinga 2 ships configuration examples for syntax highlighting using the `vim` and `nano` editors.
243 The RHEL, SUSE and Debian package `icinga2-common` install these files into
244 `/usr/share/*/icinga2-common/syntax`. Sources provide these files in `tools/syntax`.
246 ### <a id="configuration-syntax-highlighting-vim"></a> Configuration Syntax Highlighting using Vim
248 Create a new local vim configuration storage, if not already existing.
249 Edit `vim/ftdetect/icinga2.vim` if your paths to the Icinga 2 configuration
253 $ mkdir -p $PREFIX/{syntax,ftdetect}
254 $ cp vim/syntax/icinga2.vim $PREFIX/syntax/
255 $ cp vim/ftdetect/icinga2.vim $PREFIX/ftdetect/
259 $ vim /etc/icinga2/conf.d/templates.conf
261 ### <a id="configuration-syntax-highlighting-nano"></a> Configuration Syntax Highlighting using Nano
263 Copy the `/etc/nanorc` sample file to your home directory. Create the `/etc/nano` directory
264 and copy the provided `icinga2.nanorc` into it.
266 $ cp /etc/nanorc ~/.nanorc
269 # cp icinga2.nanorc /etc/nano/
271 Then include the icinga2.nanorc file in your ~/.nanorc by adding the following line:
276 include "/etc/nano/icinga2.nanorc"
280 $ nano /etc/icinga2/conf.d/templates.conf
283 ## <a id="setting-up-the-user-interface"></a> Setting up Icinga Web 2
285 Icinga 2 can be used with Icinga Web 2 and a number of other web interfaces.
286 This chapter explains how to set up Icinga Web 2. The
287 [Alternative Frontends](15-alternative-frontends.md#alternative-frontends)
288 chapter can be used as a starting point for installing some of the other web
289 interfaces which are also available.
291 The DB IDO (Database Icinga Data Output) modules for Icinga 2 take care of
292 exporting all configuration and status information into a database. The IDO
293 database is used by a number of projects including
294 [Icinga Web 2](2-getting-started.md#setting-up-icingaweb2), Icinga Reporting
297 There is a separate module for each database backend. At present support for
298 both MySQL and PostgreSQL is implemented.
300 ### <a id="configuring-db-ido-mysql"></a> Configuring DB IDO MySQL
302 #### <a id="installing-database-mysql-server"></a> Installing MySQL database server
306 # apt-get install mysql-server mysql-client
310 # yum install mysql-server mysql
311 # chkconfig mysqld on
312 # service mysqld start
313 # mysql_secure_installation
315 RHEL/CentOS 7 and Fedora:
317 # yum install mariadb-server mariadb
318 # systemctl enable mariadb
319 # systemctl start mariadb
320 # mysql_secure_installation
324 # zypper install mysql mysql-client
325 # chkconfig mysqld on
326 # service mysqld start
328 #### <a id="installing-database-mysql-modules"></a> Installing the IDO modules for MySQL
330 The next step is to install the `icinga2-ido-mysql` package using your
331 distribution's package manager.
335 # apt-get install icinga2-ido-mysql
339 # yum install icinga2-ido-mysql
343 # zypper install icinga2-ido-mysql
348 > The Debian/Ubuntu packages provide a database configuration wizard by
349 > default. You can skip the automated setup and install/upgrade the
350 > database manually if you prefer that.
352 #### <a id="setting-up-mysql-db"></a> Setting up the MySQL database
354 Set up a MySQL database for Icinga 2:
358 mysql> CREATE DATABASE icinga;
359 GRANT SELECT, INSERT, UPDATE, DELETE, DROP, CREATE VIEW, INDEX, EXECUTE ON icinga.* TO 'icinga'@'localhost' IDENTIFIED BY 'icinga';
361 After creating the database you can import the Icinga 2 IDO schema using the
364 # mysql -u root -p icinga < /usr/share/icinga2-ido-mysql/schema/mysql.sql
367 #### <a id="enabling-ido-mysql"></a> Enabling the IDO MySQL module
369 The package provides a new configuration file that is installed in
370 `/etc/icinga2/features-available/ido-mysql.conf`. You will need to
371 update the database credentials in this file.
373 All available attributes are explained in the
374 [IdoMysqlConnection object](6-object-types.md#objecttype-idomysqlconnection)
377 You can enable the `ido-mysql` feature configuration file using
378 `icinga2 feature enable`:
380 # icinga2 feature enable ido-mysql
381 Module 'ido-mysql' was enabled.
382 Make sure to restart Icinga 2 for these changes to take effect.
384 After enabling the ido-mysql feature you have to restart Icinga 2:
386 Debian/Ubuntu, RHEL/CentOS 6 and SUSE:
388 # service icinga2 restart
390 RHEL/CentOS 7 and Fedora:
392 # systemctl restart icinga2
394 ### <a id="configuring-db-ido-postgresql"></a> Configuring DB IDO PostgreSQL
396 #### <a id="installing-database-postgresql-server"></a> Installing PostgreSQL database server
400 # apt-get install postgresql
404 # yum install postgresql-server postgresql
405 # chkconfig postgresql on
406 # service postgresql start
410 # yum install postgresql-server postgresql
411 # systemctl enable postgresql
412 # systemctl start postgresql
416 # zypper install postgresql postgresql-server
417 # chkconfig postgresql on
418 # service postgresql start
420 #### <a id="installing-database-postgresql-modules"></a> Installing the IDO modules for PostgreSQL
422 The next step is to install the `icinga2-ido-pgsql` package using your
423 distribution's package manager.
427 # apt-get install icinga2-ido-pgsql
431 # yum install icinga2-ido-pgsql
435 # zypper install icinga2-ido-pgsql
439 > Upstream Debian packages provide a database configuration wizard by default.
440 > You can skip the automated setup and install/upgrade the database manually
441 > if you prefer that.
443 #### Setting up the PostgreSQL database
445 Set up a PostgreSQL database for Icinga 2:
448 # sudo -u postgres psql -c "CREATE ROLE icinga WITH LOGIN PASSWORD 'icinga'";
449 # sudo -u postgres createdb -O icinga -E UTF8 icinga
450 # sudo -u postgres createlang plpgsql icinga
454 > When using PostgreSQL 9.x you can omit the `createlang` command.
456 Locate your pg_hba.conf (Debian: `/etc/postgresql/*/main/pg_hba.conf`,
457 RHEL/SUSE: `/var/lib/pgsql/data/pg_hba.conf`), add the icinga user with md5
458 authentication method and restart the postgresql server.
460 # vim /var/lib/pgsql/data/pg_hba.conf
463 local icinga icinga md5
464 host icinga icinga 127.0.0.1/32 md5
465 host icinga icinga ::1/128 md5
467 # "local" is for Unix domain socket connections only
469 # IPv4 local connections:
470 host all all 127.0.0.1/32 ident
471 # IPv6 local connections:
472 host all all ::1/128 ident
474 # /etc/init.d/postgresql restart
477 After creating the database and permissions you can import the Icinga 2 IDO
478 schema using the following command:
480 # export PGPASSWORD=icinga
481 # psql -U icinga -d icinga < /usr/share/icinga2-ido-pgsql/schema/pgsql.sql
484 #### <a id="enabling-ido-postgresql"></a> Enabling the IDO PostgreSQL module
486 The package provides a new configuration file that is installed in
487 `/etc/icinga2/features-available/ido-pgsql.conf`. You will need to update
488 the database credentials in this file.
490 All available attributes are explained in the
491 [IdoPgsqlConnection object](6-object-types.md#objecttype-idopgsqlconnection)
494 You can enable the `ido-pgsql` feature configuration file using
495 `icinga2 feature enable`:
497 # icinga2 feature enable ido-pgsql
498 Module 'ido-pgsql' was enabled.
499 Make sure to restart Icinga 2 for these changes to take effect.
501 After enabling the ido-pgsql feature you have to restart Icinga 2:
503 Debian/Ubuntu, RHEL/CentOS 6 and SUSE:
505 # service icinga2 restart
507 RHEL/CentOS 7 and Fedora:
509 # systemctl restart icinga2
512 ### <a id="icinga2-user-interface-webserver"></a> Webserver
516 # apt-get install apache2
522 # service httpd start
524 RHEL/CentOS 7/Fedora:
527 # systemctl enable httpd
528 # systemctl start httpd
532 # zypper install apache2
534 # service apache2 start
536 ### <a id="icinga2-user-interface-firewall-rules"></a> Firewall Rules
540 # iptables -A INPUT -p tcp -m tcp --dport 80 -j ACCEPT
541 # service iptables save
543 RHEL/CentOS 7 specific:
545 # firewall-cmd --add-service=http
546 # firewall-cmd --permanent --add-service=http
549 ### <a id="setting-up-external-command-pipe"></a> Setting Up External Command Pipe
551 Web interfaces and other Icinga addons are able to send commands to
552 Icinga 2 through the external command pipe.
554 You can enable the External Command Pipe using the CLI:
556 # icinga2 feature enable command
558 After that you will have to restart Icinga 2:
560 Debian/Ubuntu, RHEL/CentOS 6 and SUSE:
562 # service icinga2 restart
564 RHEL/CentOS 7 and Fedora:
566 # systemctl restart icinga2
568 By default the command pipe file is owned by the group `icingacmd` with
569 read/write permissions. Add your webserver's user to the group `icingacmd` to
570 enable sending commands to Icinga 2 through your web interface:
572 # usermod -a -G icingacmd www-data
574 Debian packages use `nagios` as the default user and group name. Therefore
575 change `icingacmd` to `nagios`.
577 The webserver's user is different between distributions so you might have to
578 change `www-data` to `wwwrun`, `www`, or `apache`.
580 Change "www-data" to the user you're using to run queries.
582 You can verify that the user has been successfully added to the `icingacmd`
583 group using the `id` command:
585 $ id <your-webserver-user>
588 ### <a id="setting-up-icingaweb2"></a> Installing up Icinga Web 2
590 Please consult the [installation documentation](https://github.com/Icinga/icingaweb2/blob/master/doc/installation.md)
591 for further instructions on how to install Icinga Web 2.
594 ## <a id="install-addons"></a> Addons
596 A number of additional features are available in the form of addons. A list of
597 popular addons is available in the
598 [Addons and Plugins](14-addons-plugins.md#addons-plugins) chapter.