]> granicus.if.org Git - icinga2/blob - doc/2-getting-started.md
Update documentation
[icinga2] / doc / 2-getting-started.md
1 # <a id="getting-started"></a> Getting Started
2
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.
6
7 Details on troubleshooting problems can be found [here](12-troubleshooting.md#troubleshooting).
8
9 ## <a id="setting-up-icinga2"></a> Setting up Icinga 2
10
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.
14
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)
25
26 Packages for distributions other than the ones listed above may also be
27 available. Please contact your distribution packagers.
28
29 ### <a id="installing-requirements"></a> Installing Requirements for Icinga 2
30
31 You need to add the Icinga repository to your package management configuration.
32 Below is a list with examples for the various distributions.
33
34 Debian (debmon):
35
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
38     # apt-get update
39
40 Ubuntu (PPA):
41
42     # add-apt-repository ppa:formorer/icinga
43     # apt-get update
44
45 RHEL/CentOS:
46
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
49     # yum makecache
50
51 Fedora:
52
53     # wget http://packages.icinga.org/fedora/ICINGA-release.repo -O /etc/yum.repos.d/ICINGA-release.repo
54     # yum makecache
55
56 SLES:
57
58     # zypper ar http://packages.icinga.org/SUSE/ICINGA-release.repo
59     # zypper ref
60
61 openSUSE:
62
63     # zypper ar http://packages.icinga.org/openSUSE/ICINGA-release.repo
64     # zypper ref
65
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).
70
71 ### <a id="installing-icinga2"></a> Installing Icinga 2
72
73 You can install Icinga 2 by using your distribution's package manager
74 to install the `icinga2` package.
75
76 Debian/Ubuntu:
77
78     # apt-get install icinga2
79
80 RHEL/CentOS/Fedora:
81
82     # yum install icinga2
83
84 SLES/openSUSE:
85
86     # zypper install icinga2
87
88 On RHEL/CentOS and SLES you will need to use `chkconfig` and `service` to enable and start
89 the `icinga2` service:
90
91     # chkconfig icinga2 on
92     # service icinga2 start
93
94 RHEL/CentOS 7 and Fedora use [systemd](2-getting-started.md#systemd-service):
95
96     # systemctl enable icinga2
97     # systemctl start icinga2
98
99 Some parts of Icinga 2's functionality are available as separate packages:
100
101   Name                    | Description
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
105
106 ### <a id="installation-enabled-features"></a> Enabled Features during Installation
107
108 The default installation will enable three features required for a basic
109 Icinga 2 installation:
110
111 * `checker` for executing checks
112 * `notification` for sending notifications
113 * `mainlog` for writing the `icinga2.log` file
114
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.
117
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
121
122
123 ### <a id="installation-paths"></a> Installation Paths
124
125 By default Icinga 2 uses the following files and directories:
126
127   Path                                | Description
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.
140
141 ## <a id="setting-up-check-plugins"></a> Setting up Check Plugins
142
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.
147
148 The recommended way of installing these standard plugins is to use your
149 distribution's package manager.
150
151 > **Note**
152 >
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.
157
158 For your convenience here is a list of package names for some of the more
159 popular operating systems/distributions:
160
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
167
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.
172
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.
175
176 ## <a id="configuring-db-ido"></a> Configuring DB IDO
177
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.
182
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.
185
186 There is a separate module for each database backend. At present support for
187 both MySQL and PostgreSQL is implemented.
188
189 ### <a id="configuring-db-ido-mysql"></a> Configuring DB IDO MySQL
190
191 #### <a id="installing-database-mysql-server"></a> Installing MySQL database server
192
193 Debian/Ubuntu:
194
195     # apt-get install mysql-server mysql-client
196
197 RHEL/CentOS 5/6:
198
199     # yum install mysql-server mysql
200     # chkconfig mysqld on
201     # service mysqld start
202
203 RHEL/CentOS 7 and Fedora:
204
205     # yum install mariadb-server mariadb
206     # systemctl enable mariadb
207     # systemctl start mariadb
208
209 SUSE:
210
211     # zypper install mysql mysql-client
212     # chkconfig mysqld on
213     # service mysqld start
214
215 RHEL based distributions do not automatically set a secure root password. Do that **now**:
216
217     # /usr/bin/mysql_secure_installation
218
219 #### <a id="installing-database-mysql-modules"></a> Installing the IDO modules for MySQL
220
221 The next step is to install the `icinga2-ido-mysql` package using your
222 distribution's package manager.
223
224 Debian/Ubuntu:
225
226     # apt-get install icinga2-ido-mysql
227
228 RHEL/CentOS:
229
230     # yum install icinga2-ido-mysql
231
232 SUSE:
233
234     # zypper install icinga2-ido-mysql
235
236
237 > **Note**
238 >
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.
242
243 #### <a id="setting-up-mysql-db"></a> Setting up the MySQL database
244
245 Set up a MySQL database for Icinga 2:
246
247     # mysql -u root -p
248
249     mysql>  CREATE DATABASE icinga;
250             GRANT SELECT, INSERT, UPDATE, DELETE, DROP, CREATE VIEW, INDEX, EXECUTE ON icinga.* TO 'icinga'@'localhost' IDENTIFIED BY 'icinga';
251             quit
252
253 After creating the database you can import the Icinga 2 IDO schema using the
254 following command:
255
256     # mysql -u root -p icinga < /usr/share/icinga2-ido-mysql/schema/mysql.sql
257
258
259 #### <a id="enabling-ido-mysql"></a> Enabling the IDO MySQL module
260
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.
266
267 You can enable the `ido-mysql` feature configuration file using `icinga2 feature enable`:
268
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.
272
273 After enabling the ido-mysql feature you have to restart Icinga 2:
274
275 Debian/Ubuntu, RHEL/CentOS 6 and SUSE:
276
277     # service icinga2 restart
278
279 RHEL/CentOS 7 and Fedora:
280
281     # systemctl restart icinga2
282
283 ### <a id="configuring-db-ido-postgresql"></a> Configuring DB IDO PostgreSQL
284
285 #### <a id="installing-database-postgresql-server"></a> Installing PostgreSQL database server
286
287 Debian/Ubuntu:
288
289     # apt-get install postgresql
290
291 RHEL/CentOS 5/6:
292
293     # yum install postgresql-server postgresql
294     # chkconfig postgresql on
295     # service postgresql start
296
297 RHEL/CentOS 7:
298
299     # yum install postgresql-server postgresql
300     # systemctl enable postgresql
301     # systemctl start postgresql
302
303 SUSE:
304
305     # zypper install postgresql postgresql-server
306     # chkconfig postgresql on
307     # service postgresql start
308
309 #### <a id="installing-database-postgresql-modules"></a> Installing the IDO modules for PostgreSQL
310
311 The next step is to install the `icinga2-ido-pgsql` package using your
312 distribution's package manager.
313
314 Debian/Ubuntu:
315
316     # apt-get install icinga2-ido-pgsql
317
318 RHEL/CentOS:
319
320     # yum install icinga2-ido-pgsql
321
322 SUSE:
323
324     # zypper install icinga2-ido-pgsql
325
326 > **Note**
327 >
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.
331
332 #### Setting up the PostgreSQL database
333
334 Set up a PostgreSQL database for Icinga 2:
335
336     # cd /tmp
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
340
341 > **Note**
342 >
343 > Using PostgreSQL 9.x you can omit the `createlang` command.
344
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.
348
349     # vim /var/lib/pgsql/data/pg_hba.conf
350
351     # icinga
352     local   icinga      icinga                            md5
353     host    icinga      icinga      127.0.0.1/32          md5
354     host    icinga      icinga      ::1/128               md5
355
356     # "local" is for Unix domain socket connections only
357     local   all         all                               ident
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
362
363     # /etc/init.d/postgresql restart
364
365
366 After creating the database and permissions you can import the Icinga 2 IDO schema
367 using the following command:
368
369     # export PGPASSWORD=icinga
370     # psql -U icinga -d icinga < /usr/share/icinga2-ido-pgsql/schema/pgsql.sql
371
372
373 #### <a id="enabling-ido-postgresql"></a> Enabling the IDO PostgreSQL module
374
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.
380
381 You can enable the `ido-pgsql` feature configuration file using `icinga2 feature enable`:
382
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.
386
387 After enabling the ido-pgsql feature you have to restart Icinga 2:
388
389 Debian/Ubuntu, RHEL/CentOS 6 and SUSE:
390
391     # service icinga2 restart
392
393 RHEL/CentOS 7 and Fedora:
394
395     # systemctl restart icinga2
396
397
398 ### <a id="setting-up-external-command-pipe"></a> Setting Up External Command Pipe
399
400 Web interfaces and other Icinga addons are able to send commands to
401 Icinga 2 through the external command pipe.
402
403 You can enable the External Command Pipe using the CLI:
404
405     # icinga2 feature enable command
406
407 After that you will have to restart Icinga 2:
408
409 Debian/Ubuntu, RHEL/CentOS 6 and SUSE:
410
411     # service icinga2 restart
412
413 RHEL/CentOS 7 and Fedora:
414
415     # systemctl restart icinga2
416
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:
420
421     # usermod -a -G icingacmd www-data
422
423 Debian packages use `nagios` as the default user and group name. Therefore change `icingacmd` to
424 `nagios`.
425 The webserver's user is different between distributions so you might have to change `www-data` to
426 `wwwrun`, `www`, or `apache`.
427
428 Change "www-data" to the user you're using to run queries.
429
430 > **Note**
431 >
432 > Packages will do that automatically. Verify that by running `id <your-webserver-user>` and skip this
433 > step.
434
435 ## <a id="running-icinga2"></a> Running Icinga 2
436
437 ### <a id="init-script"></a> Init Script
438
439 Icinga 2's init script is installed in `/etc/init.d/icinga2` by default:
440
441     # /etc/init.d/icinga2
442     Usage: /etc/init.d/icinga2 {start|stop|restart|reload|checkconfig|status}
443
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.
452
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.
456
457 ### <a id="systemd-service"></a> systemd Service
458
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.
461
462 The Icinga 2 systemd service can be (re)started, reloaded, stopped and also queried for its current status.
463
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
473
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.
482
483 The `systemctl` command supports the following actions:
484
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`)
493
494 If you're stuck with configuration errors, you can manually invoke the [configuration validation](8-cli-commands.md#config-validation).
495
496     # systemctl enable icinga2
497
498     # systemctl restart icinga2
499     Job for icinga2.service failed. See 'systemctl status icinga2.service' and 'journalctl -xn' for details.
500
501
502 ## <a id="setting-up-the-user-interface"></a> Setting up the User Interface
503
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.
507
508
509 #### <a id="icinga2-user-interface-webserver"></a> Webserver
510
511 Debian/Ubuntu:
512
513     # apt-get install apache2
514
515 RHEL/CentOS/Fedora:
516
517     # yum install httpd
518     # chkconfig httpd on && service httpd start
519     ## RHEL7
520     # systemctl enable httpd && systemctl start httpd
521
522 SUSE:
523
524     # zypper install apache2
525     # chkconfig on && service apache2 start
526
527 #### <a id="icinga2-user-interface-firewall-rules"></a> Firewall Rules
528
529 Example:
530
531     # iptables -A INPUT -p tcp -m tcp --dport 80 -j ACCEPT
532     # service iptables save
533
534 RHEL/CentOS 7 specific:
535
536     # firewall-cmd --add-service=http
537     # firewall-cmd --permanent --add-service=http
538
539 ### <a id="setting-up-icingaweb2"></a> Setting up Icinga Web 2
540
541 Icinga Web 2 supports `DB IDO` or `Livestatus` as backends.
542
543 Using DB IDO as backend, you need to install and configure the
544 [DB IDO backend](2-getting-started.md#configuring-db-ido).
545
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).
547
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.
550
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.
554
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.
558
559 Check the [Icinga website](https://www.icinga.org) for release announcements
560 and packages.
561
562
563 ### <a id="install-addons"></a> Addons
564
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.
567