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 available Icinga web interfaces. It assumes that you are familiar with
   5 the system you're installing Icinga 2 on.
   6
   7 ## <a id="setting-up-icinga2"></a> Setting up Icinga 2
   8
   9 First of all you will have to install Icinga 2. The preferred way of doing this
  10 is to use the official Debian or RPM package repositories depending on which
  11 operating system and distribution you are running.
  12
  13   Distribution            | Repository URL
  14   ------------------------|---------------------------
  15   Debian                  | http://packages.icinga.org/debian/
  16   Ubuntu                  | http://packages.icinga.org/ubuntu/
  17   RHEL/CentOS             | http://packages.icinga.org/epel/
  18   OpenSUSE                | http://packages.icinga.org/openSUSE/
  19   SLES                    | http://packages.icinga.org/SUSE/
  20
  21 Packages for distributions other than the ones listed above may also be
  22 available. Please check http://packages.icinga.org/ to see if packages
  23 are available for your favourite distribution.
  24
  25 The packages for RHEL/CentOS 5 depend on other packages which are distributed
  26 as part of the [EPEL repository](http://fedoraproject.org/wiki/EPEL). Please
  27 make sure to enable this repository.
  28
  29 You can install Icinga 2 by using your distribution's package manager
  30 to install the `icinga2` package.
  31
  32 On RHEL/CentOS and SLES you will need to use `chkconfig` to enable the
  33 `icinga2` service. You can manually start Icinga 2 using `/etc/init.d/icinga2 start`.
  34
  35 Some parts of Icinga 2's functionality are available as separate packages:
  36
  37   Name                    | Description
  38   ------------------------|--------------------------------
  39   icinga2-ido-mysql       | IDO provider module for MySQL
  40   icinga2-ido-pgsql       | IDO provider module for PostgreSQL
  41
  42 In case you're running a distribution for which Icinga 2 packages are
  43 not yet available you will have to use the release tarball which you
  44 can download from the [Icinga website](https://www.icinga.org/). The
  45 release tarballs contain an `INSTALL` file with further instructions.
  46
  47
  48 ### <a id="installation-paths"></a> Installation Paths
  49
  50 By default Icinga 2 uses the following files and directories:
  51
  52   Path                                | Description
  53   ------------------------------------|------------------------------------
  54   /etc/icinga2                        | Contains Icinga 2 configuration files.
  55   /etc/init.d/icinga2                 | The Icinga 2 init script.
  56   /usr/bin/icinga2-*                  | Migration and certificate build scripts.
  57   /usr/sbin/icinga2*                  | The Icinga 2 binary and feature enable/disable scripts.
  58   /usr/share/doc/icinga2              | Documentation files that come with Icinga 2.
  59   /usr/share/icinga2/include          | The Icinga Template Library and plugin command configuration.
  60   /var/run/icinga2                    | PID file.
  61   /var/run/icinga2/cmd                | Command pipe and Livestatus socket.
  62   /var/cache/icinga2                  | status.dat/objects.cache.
  63   /var/spool/icinga2                  | Used for performance data spool files.
  64   /var/lib/icinga2                    | Icinga 2 state file, cluster feature replay log and configuration files.
  65   /var/log/icinga2                    | Log file location and compat/ directory for the CompatLogger feature.
  66
  67 ### <a id="icinga2-conf"></a> icinga2.conf
  68
  69 An example configuration file is installed for you in `/etc/icinga2/icinga2.conf`.
  70
  71 Here's a brief description of the example configuration:
  72
  73     /**
  74      * Icinga 2 configuration file
  75      * - this is where you define settings for the Icinga application including
  76      * which hosts/services to check.
  77      *
  78      * For an overview of all available configuration options please refer
  79      * to the documentation that is distributed as part of Icinga 2.
  80      */
  81
  82 Icinga 2 supports [C/C++-style comments](#comments).
  83
  84     /**
  85      * The constants.conf defines global constants.
  86      */
  87     include "constants.conf"
  88
  89 The `include` directive can be used to include other files.
  90
  91     /**
  92      * The Icinga Template Library (ITL) provides a number of useful templates
  93      * and command definitions.
  94      * Common monitoring plugin command definitions are included seperately.
  95      */
  96     include <itl>
  97     include <plugins>
  98
  99     /**
 100      * The features-available directory contains a number of configuration
 101      * files for features which can be enabled and disabled using the
 102      * icinga2-enable-feature / icinga2-disable-feature tools. These two tools work by creating
 103      * and removing symbolic links in the features-enabled directory.
 104      */
 105     include "features-enabled/*.conf"
 106
 107 This `include` directive takes care of including the configuration files for all
 108 the features which have been enabled with `icinga2-enable-feature`. See
 109 [Enabling/Disabling Features](#features) for more details.
 110
 111     /**
 112      * Although in theory you could define all your objects in this file
 113      * the preferred way is to create separate directories and files in the conf.d
 114      * directory. Each of these files must have the file extension ".conf".
 115      */
 116     include_recursive "conf.d"
 117
 118 You can put your own configuration files in the `conf.d` directory. This
 119 directive makes sure that all of your own configuration files are included.
 120
 121 ### <a id="constants-conf"></a> constants.conf
 122
 123 The `constants.conf` configuration file can be used to define global constants:
 124
 125     /**
 126      * This file defines global constants which can be used in
 127      * the other configuration files.
 128      */
 129
 130     /* The directory which contains the plugins from the Monitoring Plugins project. */
 131     const PluginDir = "/usr/lib/nagios/plugins"
 132
 133     /* Our local instance name. This should be the common name from the API certificate */
 134     const NodeName = "localhost"
 135
 136     /* Our local zone name. */
 137     const ZoneName = NodeName
 138
 139
 140 ### <a id="localhost-conf"></a> localhost.conf
 141
 142 The `conf.d/localhost.conf` file contains our first host definition:
 143
 144     /**
 145      * A host definition. You can create your own configuration files
 146      * in the conf.d directory (e.g. one per host). By default all *.conf
 147      * files in this directory are included.
 148      */
 149     object Host "localhost" {
 150       import "linux-server"
 151
 152       address = "127.0.0.1"
 153       address6 = "::1"
 154     }
 155
 156 This defines the host `localhost`. The `import` keyword is used to import
 157 the `linux-server` template which takes care of setting up the host check
 158 as well as adding the host to the `linux-servers` host group.
 159
 160 The `vars` attribute can be used to define custom attributes which are available
 161 for check and notification commands. Most of the templates in the Icinga
 162 Template Library require an `address` custom attribute.
 163
 164     object Service "icinga" {
 165       import "generic-service"
 166
 167       host_name = "localhost"
 168       check_command = "icinga"
 169     }
 170
 171     object Service "http" {
 172       import "generic-service"
 173
 174       host_name = "localhost"
 175       check_command = "http_ip"
 176     }
 177
 178     object Service "ssh" {
 179       import "generic-service"
 180
 181       host_name = "localhost"
 182       check_command = "ssh"
 183     }
 184
 185     object Service "load" {
 186       import "generic-service"
 187
 188       host_name = "localhost"
 189       check_command = "load"
 190     }
 191
 192     object ScheduledDowntime "backup-downtime" {
 193       import "backup-downtime"
 194
 195       host_name = "localhost"
 196       service_name = "load"
 197     }
 198
 199     object Service "processes" {
 200       import "generic-service"
 201
 202       host_name = "localhost"
 203       check_command = "processes"
 204     }
 205
 206     object Service "users" {
 207       import "generic-service"
 208
 209       host_name = "localhost"
 210       check_command = "users"
 211     }
 212
 213     object Service "disk" {
 214       import "generic-service"
 215
 216       host_name = "localhost"
 217       check_command = "disk"
 218     }
 219
 220 The command object `icinga` for the embedded health check is provided by the
 221 [Icinga Template Library (ITL)](#itl) while `http_ip`, `ssh`, `load`, `processes`,
 222 `users` and `disk` are all provided by the plugin check commands which we enabled
 223 earlier by including the `itl` and `plugins` configuration file.
 224
 225 > **Best Practice**
 226 >
 227 > Instead of defining each service object and assigning it to a host object
 228 > using the `host_name` attribute rather use the [apply rules](#apply)
 229 > simplifying your configuration.
 230
 231
 232 ## <a id="setting-up-check-plugins"></a> Setting up Check Plugins
 233
 234 On its own Icinga 2 does not know how to check external services. The
 235 [Monitoring Plugins Project](https://www.monitoring-plugins.org/) provides
 236 an extensive set of plugins which can be used with Icinga 2 to check whether
 237 services are working properly.
 238
 239 The recommended way of installing these standard plugins is to use your
 240 distribution's package manager.
 241
 242 > **Note**
 243 >
 244 > The `Nagios Plugins` project was renamed to `Monitoring Plugins`
 245 > in January 2014. At the time of this writing the packages are still
 246 > using the old name.
 247
 248 For your convenience here is a list of package names for some of the more
 249 popular operating systems/distributions:
 250
 251 OS/Distribution        | Package Name       | Installation Path
 252 -----------------------|--------------------|---------------------------
 253 RHEL/CentOS (EPEL)     | nagios-plugins-all | /usr/lib/nagios/plugins or /usr/lib64/nagios/plugins
 254 Debian                 | nagios-plugins     | /usr/lib/nagios/plugins
 255 FreeBSD                | nagios-plugins     | /usr/local/libexec/nagios
 256 OS X (MacPorts)        | nagios-plugins     | /opt/local/libexec
 257
 258 Depending on which directory your plugins are installed into you may need to
 259 update the global `PluginDir` constant in your Icinga 2 configuration. This macro is used
 260 by the service templates contained in the Icinga Template Library to determine
 261 where to find the plugin binaries.
 262
 263 ### <a id="integrate-additional-plugins"></a> Integrate Additional Plugins
 264
 265 For some services you may need additional check plugins which are not provided
 266 by the official Monitoring Plugins project.
 267
 268 All existing Nagios or Icinga 1.x plugins should work with Icinga 2. Here's a
 269 list of popular community sites which host check plugins:
 270
 271 * [MonitoringExchange](https://www.monitoringexchange.org)
 272 * [Icinga Wiki](https://wiki.icinga.org)
 273
 274 The recommended way of setting up these plugins is to copy them to a common directory
 275 and create an extra global constant, e.g. `CustomPluginDir` in your `constants.conf`
 276 configuration file:
 277
 278     # cp check_snmp_int.pl /opt/plugins
 279     # chmod +x /opt/plugins/check_snmp_int.pl
 280
 281     # cat /etc/icinga2/constants.conf
 282     /**
 283      * This file defines global constants which can be used in
 284      * the other configuration files. At a minimum the
 285      * PluginDir constant should be defined.
 286      */
 287
 288     const PluginDir = "/usr/lib/nagios/plugins"
 289     const CustomPluginDir = "/opt/monitoring"
 290
 291 Prior to using the check plugin with Icinga 2 you should ensure that it is working properly
 292 by trying to run it on the console using whichever user Icinga 2 is running as:
 293
 294     # su - icinga -s /bin/bash
 295     $ /opt/plugins/check_snmp_int.pl --help
 296
 297 Additional libraries may be required for some plugins. Please consult the plugin
 298 documentation and/or README for installation instructions.
 299
 300 Each plugin requires a [CheckCommand](#objecttype-checkcommand) object in your
 301 configuration which can be used in the [Service](#objecttype-service) or
 302 [Host](#objecttype-host) object definition. Examples for `CheckCommand`
 303 objects can be found in the [Plugin Check Commands](#plugin-check-commands) shipped
 304 with Icinga 2.
 305 For further information on your monitoring configuration read the
 306 [monitoring basics](#monitoring-basics).
 307
 308
 309 ## <a id="configuring-ido"></a> Configuring IDO
 310
 311 The IDO (Icinga Data Output) modules for Icinga 2 take care of exporting all
 312 configuration and status information into a database. The IDO database is used
 313 by a number of projects including Icinga Web.
 314
 315 There is a separate module for each database back-end. At present support for
 316 both MySQL and PostgreSQL is implemented.
 317
 318 Icinga 2 uses the Icinga 1.x IDOUtils database schema starting with version
 319 `1.11.0`. Icinga 2 may require additional features not yet released with
 320 Icinga 1.x and therefore require manual upgrade steps during pre-final
 321 milestone releases.
 322
 323 > **Tip**
 324 >
 325 > Only install the IDO feature if your web interface or reporting tool requires
 326 > you to do so (for example, [Icinga Web](#setting-up-icinga-web) or [Icinga Web 2](#setting-up-icingaweb2)).
 327 > [Icinga Classic UI](#setting-up-icinga-classic-ui) does not use IDO as backend.
 328
 329 ### <a id="configuring-ido-mysql"></a> Configuring IDO MySQL
 330
 331 #### <a id="setting-up-mysql-db"></a> Setting up the MySQL database
 332
 333 First of all you have to install the `icinga2-ido-mysql` package using your
 334 distribution's package manager. Once you have done that you can proceed with
 335 setting up a MySQL database for Icinga 2:
 336
 337 > **Note**
 338 >
 339 > The Debian packages can optionally create and maintain the database for you
 340 > using Debian's `dbconfig` framework. This is the recommended way of setting up
 341 > the database.
 342
 343     # mysql -u root -p
 344
 345     mysql>  CREATE DATABASE icinga;
 346
 347     mysql>  GRANT SELECT, INSERT, UPDATE, DELETE, DROP, CREATE VIEW, INDEX, EXECUTE ON icinga.* TO 'icinga'@'localhost' IDENTIFIED BY 'icinga';
 348
 349     mysql> quit
 350
 351
 352 After creating the database you can import the Icinga 2 IDO schema using the
 353 following command:
 354
 355     # mysql -u root -p icinga < /usr/share/doc/icinga2-ido-mysql-*/schema/mysql.sql
 356
 357 The Icinga 2 RPM packages install the schema files into
 358 `/usr/share/doc/icinga2-ido-mysql-*/schema` (`*` means package version).
 359
 360 On SuSE-based distributions the schema files are installed in
 361 `/usr/share/doc/packages/icinga2-ido-mysql/schema`.
 362
 363 The Debian/Ubuntu packages put the schema files into
 364 `/usr/share/icinga2-ido-mysql/schema`.
 365
 366 #### <a id="upgrading-mysql-db"></a> Upgrading the MySQL database
 367
 368 Check the `schema/upgrade` directory for an incremental schema upgrade file.
 369 If there isn't an upgrade file available there's nothing to do.
 370
 371 > **Note**
 372 >
 373 > During pre release status (0.x.y releases) small snippets called for example
 374 > `0.0.10.sql` will ship the required schema updates.
 375
 376 Apply all database schema upgrade files incrementially.
 377
 378     # mysql -u root -p icinga < /usr/share/doc/icinga2-ido-mysql-*/schema/upgrade/0.0.10.sql
 379
 380 The Icinga 2 IDO module will check for the required database schema version on startup
 381 and generate an error message if not satisfied.
 382
 383 #### <a id="installing-ido-mysql"></a> Installing the IDO MySQL module
 384
 385 The package provides a new configuration file that is installed in
 386 `/etc/icinga2/features-available/ido-mysql.conf`. You will need to update the
 387 database credentials in this file.
 388
 389 You can enable the `ido-mysql` feature configuration file using `icinga2-enable-feature`:
 390
 391     # icinga2-enable-feature ido-mysql
 392     Module 'ido-mysql' was enabled.
 393     Make sure to restart Icinga 2 for these changes to take effect.
 394
 395 After enabling the ido-mysql feature you have to restart Icinga 2:
 396
 397     # /etc/init.d/icinga2 restart
 398
 399
 400 ### <a id="configuring-ido-postgresql"></a> Configuring IDO PostgreSQL
 401
 402 #### Setting up the PostgreSQL database
 403
 404 First of all you have to install the `icinga2-ido-pgsql` package using your
 405 distribution's package manager. Once you have done that you can proceed with
 406 setting up a PostgreSQL database for Icinga 2:
 407
 408 > **Note**
 409 >
 410 > The Debian packages can optionally create and maintain the database for you
 411 > using Debian's `dbconfig` framework. This is the recommended way of setting up
 412 > the database.
 413
 414     # cd /tmp
 415     # sudo -u postgres psql -c "CREATE ROLE icinga WITH LOGIN PASSWORD 'icinga'";
 416     # sudo -u postgres createdb -O icinga -E UTF8 icinga
 417     # sudo -u postgres createlang plpgsql icinga
 418
 419 Locate your pg_hba.conf (Debian: `/etc/postgresql/*/main/pg_hba.conf`,
 420 RHEL/SUSE: `/var/lib/pgsql/data/pg_hba.conf`), add the icinga user with md5
 421 authentication method and restart the postgresql server.
 422
 423     # vim /var/lib/pgsql/data/pg_hba.conf
 424
 425     # icinga
 426     local   icinga      icinga                            md5
 427     host    icinga      icinga      127.0.0.1/32          md5
 428     host    icinga      icinga      ::1/128               md5
 429
 430     # "local" is for Unix domain socket connections only
 431     local   all         all                               ident
 432     # IPv4 local connections:
 433     host    all         all         127.0.0.1/32          ident
 434     # IPv6 local connections:
 435     host    all         all         ::1/128               ident
 436
 437     # /etc/init.d/postgresql restart
 438
 439
 440 After creating the database and permissions you can import the Icinga 2 IDO schema
 441 using the following command:
 442
 443     # export PGPASSWORD=icinga
 444     # psql -U icinga -d icinga < /usr/share/doc/icinga2-ido-pgsql-*/schema/pgsql.sql
 445
 446 The Icinga 2 RPM packages install the schema files into
 447 `/usr/share/doc/icinga2-ido-pgsql-*/schema` (`*` means package version).
 448
 449 On SuSE-based distributions the schema files are installed in
 450 `/usr/share/doc/packages/icinga2-ido-pgsql/schema`.
 451
 452 The Debian/Ubuntu packages put the schema files into
 453 `/usr/share/icinga2-ido-pgsql/schema`.
 454
 455 #### <a id="upgrading-postgresql-db"></a> Upgrading the PostgreSQL database
 456
 457 Check the `schema/upgrade` directory for an incremental schema upgrade file.
 458 If there isn't an upgrade file available there's nothing to do.
 459
 460 > **Note**
 461 >
 462 > During pre release status (0.x.y releases) small snippets called for example
 463 > `0.0.10.sql` will ship the required schema updates.
 464
 465 Apply all database schema upgrade files incrementially.
 466
 467     # export PGPASSWORD=icinga
 468     # psql -U icinga -d icinga < /usr/share/doc/icinga2-ido-pgsql-*/schema/upgrade/0.0.10.sql
 469
 470 The Icinga 2 IDO module will check for the required database schema version on startup
 471 and generate an error message if not satisfied.
 472
 473 #### <a id="installing-ido-postgresql"></a> Installing the IDO PostgreSQL module
 474
 475 The package provides a new configuration file that is installed in
 476 `/etc/icinga2/features-available/ido-pgsql.conf`. You will need to update the
 477 database credentials in this file.
 478
 479 You can enable the `ido-pgsql` feature configuration file using `icinga2-enable-feature`:
 480
 481     # icinga2-enable-feature ido-pgsql
 482     Module 'ido-pgsql' was enabled.
 483     Make sure to restart Icinga 2 for these changes to take effect.
 484
 485 After enabling the ido-pgsql feature you have to restart Icinga 2:
 486
 487     # /etc/init.d/icinga2 restart
 488
 489
 490 ## <a id="setting-up-livestatus"></a> Setting up Livestatus
 491
 492 The [MK Livestatus](http://mathias-kettner.de/checkmk_livestatus.html) project
 493 implements a query protocol that lets users query their Icinga instance for
 494 status information. It can also be used to send commands.
 495
 496 > **Tip**
 497 >
 498 > Only install the Livestatus feature if your web interface or addon requires
 499 > you to do so (for example, [Icinga Web 2](#setting-up-icingaweb2)).
 500 > [Icinga Classic UI](#setting-up-icinga-classic-ui) and [Icinga Web](#setting-up-icinga-web)
 501 > do not use Livestatus as backend.
 502
 503 The Livestatus component that is distributed as part of Icinga 2 is a
 504 re-implementation of the Livestatus protocol which is compatible with MK
 505 Livestatus.
 506
 507 Details on the available tables and attributes with Icinga 2 can be found
 508 in the [Livestatus Schema](#schema-livestatus) section.
 509
 510 You can enable Livestatus using icinga2-enable-feature:
 511
 512     # icinga2-enable-feature livestatus
 513
 514 After that you will have to restart Icinga 2:
 515
 516     # /etc/init.d/icinga2 restart
 517
 518 By default the Livestatus socket is available in `/var/run/icinga2/cmd/livestatus`.
 519
 520 In order for queries and commands to work you will need to add your query user
 521 (e.g. your web server) to the `icingacmd` group:
 522
 523     # usermod -a -G icingacmd www-data
 524
 525 The Debian packages use `nagios` as the user and group name. Make sure to change `icingacmd` to
 526 `nagios` if you're using Debian.
 527
 528 Change "www-data" to the user you're using to run queries.
 529
 530 In order to use the historical tables provided by the livestatus feature (for example, the
 531 `log` table) you need to have the `CompatLogger` feature enabled. By default these logs
 532 are expected in `/var/log/icinga2/compat`. A different path can be set using the `compat_log_path`
 533 configuration attribute.
 534
 535     # icinga2-enable-feature compatlog
 536
 537
 538 ## <a id="setting-up-icinga2-user-interfaces"></a> Setting up Icinga 2 User Interfaces
 539
 540 Icinga 2 is compatible to Icinga 1.x user interfaces by providing additional
 541 features required as backends.
 542
 543 Furthermore these interfaces (and somewhere in the future an Icinga 2
 544 exclusive interface) can be used for the newly created `Icinga Web 2`
 545 user interface.
 546
 547 Some interface features will only work in a limited manner due to
 548 [compatibility reasons](#differences-1x-2), other features like the
 549 statusmap parents are available dumping the host dependencies as parents.
 550 Special restrictions are noted specifically in the sections below.
 551
 552 > **Tip**
 553 >
 554 > Choose your preferred interface. There's no need to install [Classic UI](#setting-up-icinga-classic-ui)
 555 > if you prefer [Icinga Web](#setting-up-icinga-web) or [Icinga Web 2](#setting-up-icingaweb2) for example.
 556
 557 ### <a id="setting-up-icinga-classic-ui"></a> Setting up Icinga Classic UI
 558
 559 Icinga 2 can write `status.dat` and `objects.cache` files in the format that
 560 is supported by the Icinga 1.x Classic UI. External commands (a.k.a. the
 561 "command pipe") are also supported. It also supports writing Icinga 1.x
 562 log files which are required for the reporting functionality in the Classic UI.
 563
 564 #### <a id="installing-icinga-classic-ui"></a> Installing Icinga Classic UI
 565
 566 The Icinga package repository has both Debian and RPM packages. You can install
 567 the Classic UI using the following packages:
 568
 569   Distribution  | Packages
 570   --------------|---------------------
 571   Debian        | icinga2-classicui
 572   all others    | icinga2-classicui-config icinga-gui
 573
 574 The Debian packages require additional packages which are provided by the
 575 [Debian Monitoring Project](http://www.debmon.org) repository.
 576
 577 On all distributions other than Debian you may have to restart both your web
 578 server as well as Icinga 2 after installing the Classic UI package.
 579
 580 Verify that your Icinga 1.x Classic UI works by browsing to your Classic
 581 UI installation URL:
 582
 583   Distribution  | URL                                                                      | Default Login
 584   --------------|--------------------------------------------------------------------------|--------------------------
 585   Debian        | [http://localhost/icinga2-classicui](http://localhost/icinga2-classicui) | asked during installation
 586   all others    | [http://localhost/icinga](http://localhost/icinga)                       | icingaadmin/icingaadmin
 587
 588 ### <a id="setting-up-icinga-web"></a> Setting up Icinga Web
 589
 590 Icinga 2 can write to the same schema supplied by `Icinga IDOUtils 1.x` which
 591 is an explicit requirement to run `Icinga Web` next to the external command pipe.
 592 Therefore you need to setup the [DB IDO feature](#configuring-ido) remarked in the previous sections.
 593
 594 #### <a id="installing-icinga-web"></a> Installing Icinga Web
 595
 596 The Icinga package repository has both Debian and RPM packages. You can install
 597 the Classic UI using the following packages:
 598
 599   Distribution  | Packages
 600   --------------|-------------------------------------
 601   RHEL/SUSE     | icinga-web icinga-web-{mysql,pgsql}
 602   Debian        | icinga-web
 603
 604 Additionally you need to setup the `icinga_web` database.
 605
 606 The Icinga Web RPM packages install the schema files into
 607 `/usr/share/doc/icinga-web-*/schema` (`*` means package version).
 608 The Icinga Web dist tarball ships the schema files in `etc/schema`.
 609
 610 On SuSE-based distributions the schema files are installed in
 611 `/usr/share/doc/packages/icinga-web/schema`.
 612
 613 Icinga Web requires the IDO feature as database backend using MySQL or PostgreSQL.
 614 Enable that feature, e.g. for MySQL.
 615
 616     # icinga2-enable-feature ido-mysql
 617
 618 If you've changed your default credentials you may either create a read-only user
 619 or use the credentials defined in the IDO feature for Icinga Web backend configuration.
 620 Edit `databases.xml` accordingly and clear the cache afterwards. Further details can be
 621 found in the [Icinga Web documentation](http://docs.icinga.org/latest/en/icinga-web-config.html).
 622
 623     # vim /etc/icinga-web/conf.d/databases.xml
 624
 625     # icinga-web-clearcache
 626
 627 Additionally you need to enable the `command` feature:
 628
 629     # icinga2-enable-feature command
 630
 631 Then edit the Icinga Web configuration for sending commands in `/etc/icinga-web/conf.d/access.xml`
 632 (RHEL) or `/etc/icinga-web/access.xml` (SUSE) setting the command pipe path
 633 to the default used in Icinga 2. Make sure to clear the cache afterwards.
 634
 635     # vim /etc/icinga-web/conf.d/access.xml
 636
 637                 <write>
 638                     <files>
 639                         <resource name="icinga_pipe">/var/run/icinga2/cmd/icinga.cmd</resource>
 640                     </files>
 641                 </write>
 642
 643     # icinga-web-clearcache
 644
 645 Verify that your Icinga 1.x Web works by browsing to your Web installation URL:
 646
 647   Distribution  | URL                                                         | Default Login
 648   --------------|-------------------------------------------------------------|--------------------------
 649   Debian        | [http://localhost/icinga-web](http://localhost/icinga-web)  | asked during installation
 650   all others    | [http://localhost/icinga-web](http://localhost/icinga-web)  | root/password
 651
 652
 653 ### <a id="setting-up-icingaweb2"></a> Setting up Icinga Web 2
 654
 655 Icinga Web 2 currently supports `status.dat`, `DB IDO`, or `Livestatus` as backends.
 656 Please consult the INSTALL documentation shipped with `Icinga Web 2` for
 657 further instructions.
 658
 659 Icinga Web 2 is still under development. Rather than installing it
 660 yourself you should consider testing it using the available Vagrant
 661 demo VM.
 662
 663
 664 ### <a id="additional-visualization"></a> Additional visualization
 665
 666 There are many visualization addons which can be used with Icinga 2.
 667
 668 Some of the more popular ones are PNP, inGraph (graphing performance data),
 669 Graphite, and NagVis (network maps).
 670
 671
 672 ## <a id="configuration-tools"></a> Configuration Tools
 673
 674 Well known configuration tools for Icinga 1.x such as [LConf](http://www.netways.de/en/de/produkte/icinga/addons/lconf/),
 675 [NConf](http://www.nconf.org/) or [NagiosQL](http://www.nagiosql.org/)
 676 store their configuration in a custom format in their backends (LDAP or RDBMS).
 677 Currently only LConf 1.4.x supports Icinga 2 configuration export. If you require
 678 your favourite configuration tool to export Icinga 2 configuration, please get in
 679 touch with their developers.
 680
 681 If you're looking for puppet manifests, chef cookbooks, ansible recipes, etc - we're happy
 682 to integrate them upstream, so please get in touch at [https://support.icinga.org](https://support.icinga.org).
 683
 684
 685 ## <a id="running-icinga2"></a> Running Icinga 2
 686
 687 ### <a id="init-script"></a> Init Script
 688
 689 Icinga 2's init script is installed in `/etc/init.d/icinga2` by default:
 690
 691     # /etc/init.d/icinga2
 692     Usage: /etc/init.d/icinga2 {start|stop|restart|reload|checkconfig|status}
 693
 694   Command             | Description
 695   --------------------|------------------------
 696   start               | The `start` action starts the Icinga 2 daemon.
 697   stop                | The `stop` action stops the Icinga 2 daemon.
 698   restart             | The `restart` action is a shortcut for running the `stop` action followed by `start`.
 699   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.
 700   checkconfig         | The `checkconfig` action checks if the `/etc/icinga2/icinga2.conf` configuration file contains any errors.
 701   status              | The `status` action checks if Icinga 2 is running.
 702
 703 By default the Icinga 2 daemon is running as `icinga` user and group
 704 using the init script. Using Debian packages the user and group are set to `nagios`
 705 for historical reasons.
 706
 707 ### <a id="cmdline"></a> Command-line Options
 708
 709     $ icinga2 --help
 710     icinga2 - The Icinga 2 network monitoring daemon.
 711
 712     Supported options:
 713       --help                show this help message
 714       -V [ --version ]      show version information
 715       -l [ --library ] arg  load a library
 716       -I [ --include ] arg  add include search directory
 717       -D [ --define] args   define a constant
 718       -c [ --config ] arg   parse a configuration file
 719       -C [ --validate ]     exit after validating the configuration
 720       -x [ --debug ]        enable debugging
 721       -d [ --daemonize ]    detach from the controlling terminal
 722       -e [ --errorlog ] arg log fatal errors to the specified log file (only works
 723                             in combination with --daemonize)
 724       -u [ --user ] arg     user to run Icinga as
 725       -g [ --group ] arg    group to run Icinga as
 726
 727     Report bugs at <https://dev.icinga.org/>
 728     Icinga home page: <http://www.icinga.org/>
 729
 730 #### Libraries
 731
 732 Instead of loading libraries using the [`library` config directive](#library)
 733 you can also use the `--library` command-line option.
 734
 735 #### Constants
 736
 737 [Global constants](#global-constants) can be set using the `--define` command-line option.
 738
 739 #### Config Include Path
 740
 741 When including files you can specify that the include search path should be
 742 checked. You can do this by putting your configuration file name in angle
 743 brackets like this:
 744
 745     include <test.conf>
 746
 747 This would cause Icinga 2 to search its include path for the configuration file
 748 `test.conf`. By default the installation path for the Icinga Template Library
 749 is the only search directory.
 750
 751 Using the `--include` command-line option additional search directories can be
 752 added.
 753
 754 #### Config Files
 755
 756 Using the `--config` option you can specify one or more configuration files.
 757 Config files are processed in the order they're specified on the command-line.
 758
 759 #### Config Validation
 760
 761 The `--validate` option can be used to check if your configuration files
 762 contain errors. If any errors are found the exit status is 1, otherwise 0
 763 is returned.
 764
 765 ### <a id="features"></a> Enabling/Disabling Features
 766
 767 Icinga 2 provides configuration files for some commonly used features. These
 768 are installed in the `/etc/icinga2/features-available` directory and can be
 769 enabled and disabled using the `icinga2-enable-feature` and `icinga2-disable-feature` tools,
 770 respectively.
 771
 772 The `icinga2-enable-feature` tool creates symlinks in the `/etc/icinga2/features-enabled`
 773 directory which is included by default in the example configuration file.
 774
 775 You can view a list of available feature configuration files:
 776
 777     # icinga2-enable-feature
 778     Syntax: icinga2-enable-feature <feature>
 779     Enables the specified feature.
 780
 781     Available features: statusdata
 782
 783 Using the `icinga2-enable-feature` command you can enable features:
 784
 785     # icinga2-enable-feature statusdata
 786     Module 'statusdata' was enabled.
 787     Make sure to restart Icinga 2 for these changes to take effect.
 788
 789 You can disable features using the `icinga2-disable-feature` command:
 790
 791     # icinga2-disable-feature statusdata
 792     Module 'statusdata' was disabled.
 793     Make sure to restart Icinga 2 for these changes to take effect.
 794
 795 The `icinga2-enable-feature` and `icinga2-disable-feature` commands do not
 796 restart Icinga 2. You will need to restart Icinga 2 using the init script
 797 after enabling or disabling features.
 798
 799
 800 ## <a id="vagrant"></a> Vagrant Demo VM
 801
 802 The Icinga 2 Git repository contains support for [Vagrant](http://docs.vagrantup.com/v2/)
 803 with VirtualBox. Please note that Vagrant version `1.0.x` is not supported. At least
 804 version `1.2.x` is required.
 805
 806 In order to build the Vagrant VM first you will have to check out
 807 the Git repository:
 808
 809     $ git clone git://git.icinga.org/icinga2.git
 810
 811 Once you have checked out the Git repository you can build the VM using the
 812 following command:
 813
 814     $ vagrant up
 815
 816 The Vagrant VM is based on CentOS 6.x and uses the official Icinga 2 RPM
 817 packages from `packages.icinga.org`. The check plugins are installed from
 818 EPEL providing RPMs with sources from the Monitoring Plugins project.
 819
 820 ### <a id="vagrant-demo-guis"></a> Demo GUIs
 821
 822 In addition to installing Icinga 2 the Vagrant puppet modules also install the
 823 Icinga 1.x Classic UI and Icinga Web.
 824
 825   GUI             | Url                                                                  | Credentials
 826   ----------------|----------------------------------------------------------------------|------------------------
 827   Classic UI      | [http://localhost:8080/icinga](http://localhost:8080/icinga)         | icingaadmin / icingaadmin
 828   Icinga Web      | [http://localhost:8080/icinga-web](http://localhost:8080/icinga-web) | root / password
 829
 830
 831 ### <a id="vagrant-ssh"></a> SSH Access
 832
 833 You can access the Vagrant VM using SSH:
 834
 835     $ vagrant ssh
 836
 837 Alternatively you can use your favorite SSH client:
 838
 839   Name            | Value
 840   ----------------|----------------
 841   Host            | 127.0.0.1
 842   Port            | 2222
 843   Username        | vagrant
 844   Password        | vagrant