granicus.if.org Git - icinga2/blob - 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 Icinga Web 2. It assumes that you are familiar with the operating system
   5 you're using to install Icinga 2.
   6
   7 ## <a id="setting-up-icinga2"></a> Setting up Icinga 2
   8
   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.
  12
  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)
  23
  24 Packages for distributions other than the ones listed above may also be
  25 available. Please contact your distribution packagers.
  26
  27 ### <a id="installing-requirements"></a> Installing Requirements for Icinga 2
  28
  29 You need to add the Icinga repository to your package management configuration.
  30 Below is a list with examples for the various distributions.
  31
  32 Debian (debmon):
  33
  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
  36     # apt-get update
  37
  38 Ubuntu (PPA):
  39
  40     # add-apt-repository ppa:formorer/icinga
  41     # apt-get update
  42
  43 RHEL/CentOS:
  44
  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
  47     # yum makecache
  48
  49 Fedora:
  50
  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
  53     # yum makecache
  54
  55 SLES 11
  56
  57     # zypper ar http://packages.icinga.org/SUSE/ICINGA-release-11.repo
  58     # zypper ref
  59
  60 SLES 12:
  61
  62     # zypper ar http://packages.icinga.org/SUSE/ICINGA-release.repo
  63     # zypper ref
  64
  65 openSUSE:
  66
  67     # zypper ar http://packages.icinga.org/openSUSE/ICINGA-release.repo
  68     # zypper ref
  69
  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).
  74
  75 ### <a id="installing-icinga2"></a> Installing Icinga 2
  76
  77 You can install Icinga 2 by using your distribution's package manager
  78 to install the `icinga2` package.
  79
  80 Debian/Ubuntu:
  81
  82     # apt-get install icinga2
  83
  84 RHEL/CentOS 5/6:
  85
  86     # yum install icinga2
  87     # chkconfig icinga2 on
  88     # service icinga2 start
  89
  90 RHEL/CentOS 7 and Fedora:
  91
  92     # yum install icinga2
  93     # systemctl enable icinga2
  94     # systemctl start icinga2
  95
  96 SLES/openSUSE:
  97
  98     # zypper install icinga2
  99
 100 ### <a id="installation-enabled-features"></a> Enabled Features during Installation
 101
 102 The default installation will enable three features required for a basic
 103 Icinga 2 installation:
 104
 105 * `checker` for executing checks
 106 * `notification` for sending notifications
 107 * `mainlog` for writing the `icinga2.log` file
 108
 109 You can verify that by calling `icinga2 feature list` [CLI command](7-cli-commands.md#cli-command-feature)
 110 to see which features are enabled and disabled.
 111
 112     # icinga2 feature list
 113     Disabled features: api command compatlog debuglog graphite icingastatus ido-mysql ido-pgsql livestatus notification perfdata statusdata syslog
 114     Enabled features: checker mainlog notification
 115
 116
 117 ### <a id="installation-paths"></a> Installation Paths
 118
 119 By default Icinga 2 uses the following files and directories:
 120
 121   Path                                | Description
 122   ------------------------------------|------------------------------------
 123   /etc/icinga2                        | Contains Icinga 2 configuration files.
 124   /etc/init.d/icinga2                 | The Icinga 2 init script.
 125   /usr/sbin/icinga2*                  | The Icinga 2 binary.
 126   /usr/share/doc/icinga2              | Documentation files that come with Icinga 2.
 127   /usr/share/icinga2/include          | The Icinga Template Library and plugin command configuration.
 128   /var/run/icinga2                    | PID file.
 129   /var/run/icinga2/cmd                | Command pipe and Livestatus socket.
 130   /var/cache/icinga2                  | status.dat/objects.cache, icinga2.debug files
 131   /var/spool/icinga2                  | Used for performance data spool files.
 132   /var/lib/icinga2                    | Icinga 2 state file, cluster log, local CA and configuration files.
 133   /var/log/icinga2                    | Log file location and compat/ directory for the CompatLogger feature.
 134
 135 ## <a id="setting-up-check-plugins"></a> Setting up Check Plugins
 136
 137 Without plugins Icinga 2 does not know how to check external services. The
 138 [Monitoring Plugins Project](https://www.monitoring-plugins.org/) provides
 139 an extensive set of plugins which can be used with Icinga 2 to check whether
 140 services are working properly.
 141
 142 The recommended way of installing these standard plugins is to use your
 143 distribution's package manager.
 144
 145 For your convenience here is a list of package names for some of the more
 146 popular operating systems/distributions:
 147
 148 OS/Distribution        | Package Name       | Installation Path
 149 -----------------------|--------------------|---------------------------
 150 RHEL/CentOS (EPEL)     | nagios-plugins-all | /usr/lib/nagios/plugins or /usr/lib64/nagios/plugins
 151 Debian                 | nagios-plugins     | /usr/lib/nagios/plugins
 152 FreeBSD                | nagios-plugins     | /usr/local/libexec/nagios
 153 OS X (MacPorts)        | nagios-plugins     | /opt/local/libexec
 154
 155 Depending on which directory your plugins are installed into you may need to
 156 update the global `PluginDir` constant in your [Icinga 2 configuration](4-configuring-icinga-2.md#constants-conf).
 157 This constant is used by the check command definitions contained in the Icinga Template Library
 158 to determine where to find the plugin binaries.
 159
 160 Please refer to the [plugins](9-addons-plugins.md#plugins) chapter for details about how to integrate
 161 additional check plugins into your Icinga 2 setup.
 162
 163 ## <a id="running-icinga2"></a> Running Icinga 2
 164
 165 ### <a id="init-script"></a> Init Script
 166
 167 Icinga 2's init script is installed in `/etc/init.d/icinga2` by default:
 168
 169     # /etc/init.d/icinga2
 170     Usage: /etc/init.d/icinga2 {start|stop|restart|reload|checkconfig|status}
 171
 172 The init script supports the following actions:
 173
 174   Command             | Description
 175   --------------------|------------------------
 176   start               | The `start` action starts the Icinga 2 daemon.
 177   stop                | The `stop` action stops the Icinga 2 daemon.
 178   restart             | The `restart` action is a shortcut for running the `stop` action followed by `start`.
 179   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.
 180   checkconfig         | The `checkconfig` action checks if the `/etc/icinga2/icinga2.conf` configuration file contains any errors.
 181   status              | The `status` action checks if Icinga 2 is running.
 182
 183 By default the Icinga 2 daemon is running as `icinga` user and group
 184 using the init script. Using Debian packages the user and group are set to
 185 `nagios` for historical reasons.
 186
 187 ### <a id="systemd-service"></a> systemd Service
 188
 189 Some distributions (e.g. Fedora, openSUSE and RHEL/CentOS 7) use systemd. The
 190 Icinga 2 packages automatically install the necessary systemd unit files.
 191
 192 The Icinga 2 systemd service can be (re-)started, reloaded, stopped and also queried for its current status.
 193
 194     # systemctl status icinga2
 195     icinga2.service - Icinga host/service/network monitoring system
 196        Loaded: loaded (/usr/lib/systemd/system/icinga2.service; disabled)
 197        Active: active (running) since Mi 2014-07-23 13:39:38 CEST; 15s ago
 198       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)
 199       Process: 21674 ExecStartPre=/usr/sbin/icinga2-prepare-dirs /etc/sysconfig/icinga2 (code=exited, status=0/SUCCESS)
 200      Main PID: 21727 (icinga2)
 201        CGroup: /system.slice/icinga2.service
 202                └─21727 /usr/sbin/icinga2 -c /etc/icinga2/icinga2.conf -d -e /var/log/icinga2/error.log -u icinga -g icinga --no-stack-rlimit
 203
 204     Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 309 Service(s).
 205     Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 1 User(s).
 206     Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 15 Notification(s).
 207     Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 4 ScheduledDowntime(s).
 208     Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 1 UserGroup(s).
 209     Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 1 IcingaApplication(s).
 210     Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 8 Dependency(s).
 211     Jul 23 13:39:38 nbmif systemd[1]: Started Icinga host/service/network monitoring system.
 212
 213 The `systemctl` command supports the following actions:
 214
 215   Command             | Description
 216   --------------------|------------------------
 217   start               | The `start` action starts the Icinga 2 daemon.
 218   stop                | The `stop` action stops the Icinga 2 daemon.
 219   restart             | The `restart` action is a shortcut for running the `stop` action followed by `start`.
 220   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.
 221   status              | The `status` action checks if Icinga 2 is running.
 222   enable              | The `enable` action enables the service being started at system boot time (similar to `chkconfig`)
 223
 224 Examples:
 225
 226     # systemctl enable icinga2
 227
 228     # systemctl restart icinga2
 229     Job for icinga2.service failed. See 'systemctl status icinga2.service' and 'journalctl -xn' for details.
 230
 231 If you're stuck with configuration errors, you can manually invoke the [configuration validation](7-cli-commands.md#config-validation).
 232
 233 ## <a id="setting-up-the-user-interface"></a> Setting up Icinga Web 2
 234
 235 Icinga 2 can be used with Icinga Web 2 and a number of other web interfaces.
 236 This chapter explains how to set up Icinga Web 2. The
 237 [Alternative Frontends](10-alternative-frontends.md#alternative-frontends)
 238 chapter can be used as a starting point for installing some of the other web
 239 interfaces which are also available.
 240
 241 The DB IDO (Database Icinga Data Output) modules for Icinga 2 take care of exporting
 242 all configuration and status information into a database. The IDO database is used
 243 by a number of projects including [Icinga Web 2](2-getting-started.md#setting-up-icingaweb2),
 244 Icinga Reporting or Icinga Web 1.x.
 245
 246 There is a separate module for each database backend. At present support for
 247 both MySQL and PostgreSQL is implemented.
 248
 249 ### <a id="configuring-db-ido-mysql"></a> Configuring DB IDO MySQL
 250
 251 #### <a id="installing-database-mysql-server"></a> Installing MySQL database server
 252
 253 Debian/Ubuntu:
 254
 255     # apt-get install mysql-server mysql-client
 256
 257 RHEL/CentOS 5/6:
 258
 259     # yum install mysql-server mysql
 260     # chkconfig mysqld on
 261     # service mysqld start
 262     # mysql_secure_installation
 263
 264 RHEL/CentOS 7 and Fedora:
 265
 266     # yum install mariadb-server mariadb
 267     # systemctl enable mariadb
 268     # systemctl start mariadb
 269     # mysql_secure_installation
 270
 271 SUSE:
 272
 273     # zypper install mysql mysql-client
 274     # chkconfig mysqld on
 275     # service mysqld start
 276
 277 #### <a id="installing-database-mysql-modules"></a> Installing the IDO modules for MySQL
 278
 279 The next step is to install the `icinga2-ido-mysql` package using your
 280 distribution's package manager.
 281
 282 Debian/Ubuntu:
 283
 284     # apt-get install icinga2-ido-mysql
 285
 286 RHEL/CentOS:
 287
 288     # yum install icinga2-ido-mysql
 289
 290 SUSE:
 291
 292     # zypper install icinga2-ido-mysql
 293
 294
 295 > **Note**
 296 >
 297 > The Debian/Ubuntu packages provide a database configuration wizard by
 298 > default. You can skip the automated setup and install/upgrade the
 299 > database manually if you prefer that.
 300
 301 #### <a id="setting-up-mysql-db"></a> Setting up the MySQL database
 302
 303 Set up a MySQL database for Icinga 2:
 304
 305     # mysql -u root -p
 306
 307     mysql>  CREATE DATABASE icinga;
 308             GRANT SELECT, INSERT, UPDATE, DELETE, DROP, CREATE VIEW, INDEX, EXECUTE ON icinga.* TO 'icinga'@'localhost' IDENTIFIED BY 'icinga';
 309
 310 After creating the database you can import the Icinga 2 IDO schema using the
 311 following command:
 312
 313     # mysql -u root -p icinga < /usr/share/icinga2-ido-mysql/schema/mysql.sql
 314
 315
 316 #### <a id="enabling-ido-mysql"></a> Enabling the IDO MySQL module
 317
 318 The package provides a new configuration file that is installed in
 319 `/etc/icinga2/features-available/ido-mysql.conf`. You will need to
 320 update the database credentials in this file.
 321
 322 All available attributes are explained in the
 323 [IdoMysqlConnection object](5-object-types.md#objecttype-idomysqlconnection) chapter.
 324
 325 You can enable the `ido-mysql` feature configuration file using `icinga2 feature enable`:
 326
 327     # icinga2 feature enable ido-mysql
 328     Module 'ido-mysql' was enabled.
 329     Make sure to restart Icinga 2 for these changes to take effect.
 330
 331 After enabling the ido-mysql feature you have to restart Icinga 2:
 332
 333 Debian/Ubuntu, RHEL/CentOS 6 and SUSE:
 334
 335     # service icinga2 restart
 336
 337 RHEL/CentOS 7 and Fedora:
 338
 339     # systemctl restart icinga2
 340
 341 ### <a id="configuring-db-ido-postgresql"></a> Configuring DB IDO PostgreSQL
 342
 343 #### <a id="installing-database-postgresql-server"></a> Installing PostgreSQL database server
 344
 345 Debian/Ubuntu:
 346
 347     # apt-get install postgresql
 348
 349 RHEL/CentOS 5/6:
 350
 351     # yum install postgresql-server postgresql
 352     # chkconfig postgresql on
 353     # service postgresql start
 354
 355 RHEL/CentOS 7:
 356
 357     # yum install postgresql-server postgresql
 358     # systemctl enable postgresql
 359     # systemctl start postgresql
 360
 361 SUSE:
 362
 363     # zypper install postgresql postgresql-server
 364     # chkconfig postgresql on
 365     # service postgresql start
 366
 367 #### <a id="installing-database-postgresql-modules"></a> Installing the IDO modules for PostgreSQL
 368
 369 The next step is to install the `icinga2-ido-pgsql` package using your
 370 distribution's package manager.
 371
 372 Debian/Ubuntu:
 373
 374     # apt-get install icinga2-ido-pgsql
 375
 376 RHEL/CentOS:
 377
 378     # yum install icinga2-ido-pgsql
 379
 380 SUSE:
 381
 382     # zypper install icinga2-ido-pgsql
 383
 384 > **Note**
 385 >
 386 > Upstream Debian packages provide a database configuration wizard by default.
 387 > You can skip the automated setup and install/upgrade the database manually
 388 > if you prefer that.
 389
 390 #### Setting up the PostgreSQL database
 391
 392 Set up a PostgreSQL database for Icinga 2:
 393
 394     # cd /tmp
 395     # sudo -u postgres psql -c "CREATE ROLE icinga WITH LOGIN PASSWORD 'icinga'";
 396     # sudo -u postgres createdb -O icinga -E UTF8 icinga
 397     # sudo -u postgres createlang plpgsql icinga
 398
 399 > **Note**
 400 >
 401 > Using PostgreSQL 9.x you can omit the `createlang` command.
 402
 403 Locate your pg_hba.conf (Debian: `/etc/postgresql/*/main/pg_hba.conf`,
 404 RHEL/SUSE: `/var/lib/pgsql/data/pg_hba.conf`), add the icinga user with md5
 405 authentication method and restart the postgresql server.
 406
 407     # vim /var/lib/pgsql/data/pg_hba.conf
 408
 409     # icinga
 410     local   icinga      icinga                            md5
 411     host    icinga      icinga      127.0.0.1/32          md5
 412     host    icinga      icinga      ::1/128               md5
 413
 414     # "local" is for Unix domain socket connections only
 415     local   all         all                               ident
 416     # IPv4 local connections:
 417     host    all         all         127.0.0.1/32          ident
 418     # IPv6 local connections:
 419     host    all         all         ::1/128               ident
 420
 421     # /etc/init.d/postgresql restart
 422
 423
 424 After creating the database and permissions you can import the Icinga 2 IDO schema
 425 using the following command:
 426
 427     # export PGPASSWORD=icinga
 428     # psql -U icinga -d icinga < /usr/share/icinga2-ido-pgsql/schema/pgsql.sql
 429
 430
 431 #### <a id="enabling-ido-postgresql"></a> Enabling the IDO PostgreSQL module
 432
 433 The package provides a new configuration file that is installed in
 434 `/etc/icinga2/features-available/ido-pgsql.conf`. You will need to update
 435 the database credentials in this file.
 436
 437 All available attributes are explained in the
 438 [IdoPgsqlConnection object](5-object-types.md#objecttype-idopgsqlconnection) chapter.
 439
 440 You can enable the `ido-pgsql` feature configuration file using `icinga2 feature enable`:
 441
 442     # icinga2 feature enable ido-pgsql
 443     Module 'ido-pgsql' was enabled.
 444     Make sure to restart Icinga 2 for these changes to take effect.
 445
 446 After enabling the ido-pgsql feature you have to restart Icinga 2:
 447
 448 Debian/Ubuntu, RHEL/CentOS 6 and SUSE:
 449
 450     # service icinga2 restart
 451
 452 RHEL/CentOS 7 and Fedora:
 453
 454     # systemctl restart icinga2
 455
 456
 457 ### <a id="icinga2-user-interface-webserver"></a> Webserver
 458
 459 Debian/Ubuntu:
 460
 461     # apt-get install apache2
 462
 463 RHEL/CentOS 6:
 464
 465     # yum install httpd
 466     # chkconfig httpd on
 467     # service httpd start
 468
 469 RHEL/CentOS 7/Fedora:
 470
 471     # yum install httpd
 472     # systemctl enable httpd
 473     # systemctl start httpd
 474
 475 SUSE:
 476
 477     # zypper install apache2
 478     # chkconfig on
 479     # service apache2 start
 480
 481 ### <a id="icinga2-user-interface-firewall-rules"></a> Firewall Rules
 482
 483 Example:
 484
 485     # iptables -A INPUT -p tcp -m tcp --dport 80 -j ACCEPT
 486     # service iptables save
 487
 488 RHEL/CentOS 7 specific:
 489
 490     # firewall-cmd --add-service=http
 491     # firewall-cmd --permanent --add-service=http
 492
 493
 494 ### <a id="setting-up-external-command-pipe"></a> Setting Up External Command Pipe
 495
 496 Web interfaces and other Icinga addons are able to send commands to
 497 Icinga 2 through the external command pipe.
 498
 499 You can enable the External Command Pipe using the CLI:
 500
 501     # icinga2 feature enable command
 502
 503 After that you will have to restart Icinga 2:
 504
 505 Debian/Ubuntu, RHEL/CentOS 6 and SUSE:
 506
 507     # service icinga2 restart
 508
 509 RHEL/CentOS 7 and Fedora:
 510
 511     # systemctl restart icinga2
 512
 513 By default the command pipe file is owned by the group `icingacmd` with read/write
 514 permissions. Add your webserver's user to the group `icingacmd` to
 515 enable sending commands to Icinga 2 through your web interface:
 516
 517     # usermod -a -G icingacmd www-data
 518
 519 Debian packages use `nagios` as the default user and group name. Therefore change `icingacmd` to
 520 `nagios`.
 521 The webserver's user is different between distributions so you might have to change `www-data` to
 522 `wwwrun`, `www`, or `apache`.
 523
 524 Change "www-data" to the user you're using to run queries.
 525
 526 You can verify that the user has been successfully added to the `icingacmd` group using the `id` command:
 527
 528     id <your-webserver-user>
 529
 530
 531 ### <a id="setting-up-icingaweb2"></a> Installing up Icinga Web 2
 532
 533 Please consult the [installation documentation](https://github.com/Icinga/icingaweb2/blob/master/doc/installation.md) for further instructions on how to install Icinga Web 2.
 534
 535
 536 ## <a id="install-addons"></a> Addons
 537
 538 A number of additional features are available in the form of addons. A list of popular
 539 addons is available in the [Addons and Plugins](9-addons-plugins.md#addons-plugins) chapter.
 540