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 Details on troubleshooting problems can be found [here](#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                  | [Upstream](https://packages.debian.org/sid/icinga2), [DebMon](http://debmon.org/packages/debmon-wheezy/icinga2), [Icinga Repository](http://packages.icinga.org/debian/)
  18   Ubuntu                  | [Upstream](https://launchpad.net/ubuntu/+source/icinga2), [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     # cat >/etc/apt/sources.list.d/debmon.list<<EOF
  38     deb http://debmon.org/debmon debmon-wheezy main
  39     EOF
  40     # apt-get update
  41
  42 Ubuntu (PPA):
  43
  44     # add-apt-repository ppa:formorer/icinga
  45     # apt-get update
  46
  47 RHEL/CentOS:
  48
  49     # rpm --import http://packages.icinga.org/icinga.key
  50     # wget http://packages.icinga.org/epel/ICINGA-release.repo -O /etc/yum.repos.d/ICINGA-release.repo
  51     # yum makecache
  52
  53 Fedora:
  54
  55     # wget http://packages.icinga.org/fedora/ICINGA-release.repo -O /etc/yum.repos.d/ICINGA-release.repo
  56     # yum makecache
  57
  58 SLES:
  59
  60     # zypper ar http://packages.icinga.org/SUSE/ICINGA-release.repo
  61     # zypper ref
  62
  63 OpenSUSE:
  64
  65     # zypper ar http://packages.icinga.org/openSUSE/ICINGA-release.repo
  66     # zypper ref
  67
  68 The packages for RHEL/CentOS depend on other packages which are distributed
  69 as part of the [EPEL repository](http://fedoraproject.org/wiki/EPEL). Please
  70 make sure to enable this repository by following
  71 [these instructions](#http://fedoraproject.org/wiki/EPEL#How_can_I_use_these_extra_packages.3F).
  72
  73 ### <a id="installing-icinga2"></a> Installing Icinga 2
  74
  75 You can install Icinga 2 by using your distribution's package manager
  76 to install the `icinga2` package.
  77
  78 Debian/Ubuntu:
  79
  80     # apt-get install icinga2
  81
  82 RHEL/CentOS/Fedora:
  83
  84     # yum install icinga2
  85
  86 SLES/OpenSUSE:
  87
  88     # zypper install icinga2
  89
  90 On RHEL/CentOS and SLES you will need to use `chkconfig` to enable the
  91 `icinga2` service. You can manually start Icinga 2 using `service icinga2 start`.
  92
  93     # chkconfig icinga2 on
  94     # service icinga2 start
  95
  96 RHEL/CentOS 7 use [Systemd](#systemd-service) with `systemctl {enable,start} icinga2`.
  97
  98     # systemctl enable icinga2
  99     # systemctl start icinga2
 100
 101 Some parts of Icinga 2's functionality are available as separate packages:
 102
 103   Name                    | Description
 104   ------------------------|--------------------------------
 105   icinga2-ido-mysql       | [DB IDO](#configuring-db-ido) provider module for MySQL
 106   icinga2-ido-pgsql       | [DB IDO](#configuring-db-ido) provider module for PostgreSQL
 107
 108 If you're running a distribution for which Icinga 2 packages are
 109 not yet available you will need to use the release tarball which you
 110 can download from the [Icinga website](https://www.icinga.org/). The
 111 release tarballs contain an `INSTALL` file with further instructions.
 112
 113 ### <a id="installation-enabled-features"></a> Enabled Features during Installation
 114
 115 The default installation will enable three features required for a basic
 116 Icinga 2 installation:
 117
 118 * `checker` for executing checks
 119 * `notification` for sending notifications
 120 * `mainlog` for writing the `icinga2.log` file
 121
 122 You can verify that by calling `icinga2 feature list` [cli command](#cli-command-feature)
 123 to see which features are enabled and disabled.
 124
 125     # icinga2 feature list
 126     Disabled features: api command compatlog debuglog graphite icingastatus ido-mysql ido-pgsql livestatus notification perfdata statusdata syslog
 127     Enabled features: checker mainlog notification
 128
 129
 130 ### <a id="installation-paths"></a> Installation Paths
 131
 132 By default Icinga 2 uses the following files and directories:
 133
 134   Path                                | Description
 135   ------------------------------------|------------------------------------
 136   /etc/icinga2                        | Contains Icinga 2 configuration files.
 137   /etc/init.d/icinga2                 | The Icinga 2 init script.
 138   /usr/sbin/icinga2*                  | The Icinga 2 binary.
 139   /usr/share/doc/icinga2              | Documentation files that come with Icinga 2.
 140   /usr/share/icinga2/include          | The Icinga Template Library and plugin command configuration.
 141   /var/run/icinga2                    | PID file.
 142   /var/run/icinga2/cmd                | Command pipe and Livestatus socket.
 143   /var/cache/icinga2                  | status.dat/objects.cache, icinga2.debug files
 144   /var/spool/icinga2                  | Used for performance data spool files.
 145   /var/lib/icinga2                    | Icinga 2 state file, cluster log, local CA and configuration files.
 146   /var/log/icinga2                    | Log file location and compat/ directory for the CompatLogger feature.
 147
 148 ## <a id="setting-up-check-plugins"></a> Setting up Check Plugins
 149
 150 Without plugins Icinga 2 does not know how to check external services. The
 151 [Monitoring Plugins Project](https://www.monitoring-plugins.org/) provides
 152 an extensive set of plugins which can be used with Icinga 2 to check whether
 153 services are working properly.
 154
 155 The recommended way of installing these standard plugins is to use your
 156 distribution's package manager.
 157
 158 > **Note**
 159 >
 160 > The `Nagios Plugins` project was renamed to `Monitoring Plugins`
 161 > in January 2014. At the time of this writing some packages are still
 162 > using the old name while some distributions have adopted the new package
 163 > name `monitoring-plugins` already.
 164
 165 > **Note**
 166 >
 167 > EPEL for RHEL/CentOS 7 is still in beta mode at the time of writing and does
 168 > not provide a `monitoring-plugins` package. You are required to manually install
 169 > them.
 170
 171 For your convenience here is a list of package names for some of the more
 172 popular operating systems/distributions:
 173
 174 OS/Distribution        | Package Name       | Installation Path
 175 -----------------------|--------------------|---------------------------
 176 RHEL/CentOS (EPEL)     | nagios-plugins-all | /usr/lib/nagios/plugins or /usr/lib64/nagios/plugins
 177 Debian                 | nagios-plugins     | /usr/lib/nagios/plugins
 178 FreeBSD                | nagios-plugins     | /usr/local/libexec/nagios
 179 OS X (MacPorts)        | nagios-plugins     | /opt/local/libexec
 180
 181 Depending on which directory your plugins are installed into you may need to
 182 update the global `PluginDir` constant in your Icinga 2 configuration. This macro is used
 183 by the service templates contained in the Icinga Template Library to determine
 184 where to find the plugin binaries.
 185
 186 ### <a id="integrate-additional-plugins"></a> Integrate Additional Plugins
 187
 188 For some services you may need additional 'check plugins' which are not provided
 189 by the official Monitoring Plugins project.
 190
 191 All existing Nagios or Icinga 1.x plugins work with Icinga 2. Here's a
 192 list of popular community sites which host check plugins:
 193
 194 * [Icinga Exchange](https://exchange.icinga.org)
 195 * [Icinga Wiki](https://wiki.icinga.org)
 196
 197 The recommended way of setting up these plugins is to copy them to a common directory
 198 and create an extra global constant, e.g. `CustomPluginDir` in your [constants.conf](#constants-conf)
 199 configuration file:
 200
 201     # cp check_snmp_int.pl /opt/plugins
 202     # chmod +x /opt/plugins/check_snmp_int.pl
 203
 204     # cat /etc/icinga2/constants.conf
 205     /**
 206      * This file defines global constants which can be used in
 207      * the other configuration files. At a minimum the
 208      * PluginDir constant should be defined.
 209      */
 210
 211     const PluginDir = "/usr/lib/nagios/plugins"
 212     const CustomPluginDir = "/opt/monitoring"
 213
 214 Prior to using the check plugin with Icinga 2 you should ensure that it is working properly
 215 by trying to run it on the console using whichever user Icinga 2 is running as:
 216
 217     # su - icinga -s /bin/bash
 218     $ /opt/plugins/check_snmp_int.pl --help
 219
 220 Additional libraries may be required for some plugins. Please consult the plugin
 221 documentation and/or plugin provided README for installation instructions.
 222 Sometimes plugins contain hard-coded paths to other components. Instead of changing
 223 the plugin it might be easier to create logical links which is (more) update-safe.
 224
 225 Each plugin requires a [CheckCommand](#objecttype-checkcommand) object in your
 226 configuration which can be used in the [Service](#objecttype-service) or
 227 [Host](#objecttype-host) object definition.
 228
 229 There are the following conventions to follow when adding a new command object definition:
 230
 231 * Always import the `plugin-check-command` template
 232 * Use [command-arguments](#) whenever possible. The `command` attribute must be an array
 233 in `[ ... ]` then for shell escaping.
 234 * Define a unique `prefix` for the command's specific command arguments. That way you can safely
 235 set them on host/service level and you'll always know which command they control.
 236 * Use command argument default values, e.g. for thresholds
 237 * Use [advanced conditions](#objecttype-checkcommand) like `set_if` definitions.
 238
 239 Example for a custom `my-snmp-int` check command:
 240
 241     object CheckCommand "my-snmp-int" {
 242       import "plugin-check-command"
 243
 244       command = [ PluginDir + "/check_snmp_int.pl" ]
 245
 246       arguments = {
 247             "-H" = "$snmp_address$"
 248             "-C" = "$snmp_community$"
 249                 "-p" = "$snmp_port$"
 250                 "-2" = {
 251           set_if = "$snmp_v2$"
 252                 }
 253                 "-n" = "$snmp_interface$"
 254                 "-f" = {
 255                         set_if = "$snmp_perf$"
 256                 }
 257                 "-w" = "$snmp_warn$"
 258                 "-c" = "$snmp_crit$"
 259       }
 260
 261       vars.snmp_v2 = true
 262       vars.snmp_perf = true
 263           vars.snmp_warn = "300,400"
 264           vars.snmp_crit = "0,600"
 265     }
 266
 267 You can find an existing `CheckCommand` definition for the `check_snmp_int.pl` plugin
 268 shipped with the optional [Manubulon Plugin Check Command](#snmp-manubulon-plugin-check-commands)
 269 definitions already.
 270
 271
 272 For further information on your monitoring configuration read the
 273 [monitoring basics](#monitoring-basics).
 274
 275
 276 ## <a id="configuring-icinga2-first-steps"></a> Configuring Icinga 2: First Steps
 277
 278 ### <a id="icinga2-conf"></a> icinga2.conf
 279
 280 An example configuration file is installed for you in `/etc/icinga2/icinga2.conf`.
 281
 282 Here's a brief description of the example configuration:
 283
 284     /**
 285      * Icinga 2 configuration file
 286      * - this is where you define settings for the Icinga application including
 287      * which hosts/services to check.
 288      *
 289      * For an overview of all available configuration options please refer
 290      * to the documentation that is distributed as part of Icinga 2.
 291      */
 292
 293 Icinga 2 supports [C/C++-style comments](#comments).
 294
 295     /**
 296      * The constants.conf defines global constants.
 297      */
 298     include "constants.conf"
 299
 300 The `include` directive can be used to include other files.
 301
 302     /**
 303      * The zones.conf defines zones for a cluster setup.
 304      * Not required for single instance setups.
 305      */
 306      include "zones.conf"
 307
 308     /**
 309      * The Icinga Template Library (ITL) provides a number of useful templates
 310      * and command definitions.
 311      * Common monitoring plugin command definitions are included separately.
 312      */
 313     include <itl>
 314     include <plugins>
 315
 316     /**
 317      * The features-available directory contains a number of configuration
 318      * files for features which can be enabled and disabled using the
 319      * icinga2 feature enable / icinga2 feature disable CLI commands.
 320      * These commands work by creating and removing symbolic links in
 321      * the features-enabled directory.
 322      */
 323     include "features-enabled/*.conf"
 324
 325 This `include` directive takes care of including the configuration files for all
 326 the features which have been enabled with `icinga2 feature enable`. See
 327 [Enabling/Disabling Features](#features) for more details.
 328
 329     /**
 330      * The repository.d directory contains all configuration objects
 331      * managed by the 'icinga2 repository' CLI commands.
 332      */
 333     include_recursive "repository.d"
 334
 335 This `include_recursive` directive is used for discovery of services on remote clients
 336 and their generated configuration described in
 337 [this chapter](#icinga2-remote-monitoring-master-discovery-generate-config).
 338
 339
 340     /**
 341      * Although in theory you could define all your objects in this file
 342      * the preferred way is to create separate directories and files in the conf.d
 343      * directory. Each of these files must have the file extension ".conf".
 344      */
 345     include_recursive "conf.d"
 346
 347 You can put your own configuration files in the [conf.d](#conf-d) directory. This
 348 directive makes sure that all of your own configuration files are included.
 349
 350 > **Tip**
 351 >
 352 > The example configuration is shipped in this directory too. You can either
 353 > remove it entirely, or adapt the existing configuration structure with your
 354 > own object configuration.
 355
 356
 357 ### <a id="constants-conf"></a> constants.conf
 358
 359 The `constants.conf` configuration file can be used to define global constants.
 360
 361 By default, you need to make sure to set these constants:
 362
 363 * The `PluginDir` constant must be pointed to your [check plugins](#setting-up-check-plugins) path.
 364 This constant is required by the shipped
 365 [plugin check command configuration](#plugin-check-commands).
 366 * The `NodeName` constant defines your local node name. Should be set to FQDN which is the default
 367 if not set. This constant is required for local host configuration, monitoring remote clients and
 368 cluster setup.
 369
 370 Example:
 371
 372     /* The directory which contains the plugins from the Monitoring Plugins project. */
 373     const PluginDir = "/usr/lib64/nagios/plugins"
 374
 375
 376     /* The directory which contains the Manubulon plugins.
 377      * Check the documentation, chapter "SNMP Manubulon Plugin Check Commands", for details.
 378      */
 379     const ManubulonPluginDir = "/usr/lib64/nagios/plugins"
 380
 381     /* Our local instance name. By default this is the server's hostname as returned by `hostname --fqdn`.
 382      * This should be the common name from the API certificate.
 383      */
 384     //const NodeName = "localhost"
 385
 386     /* Our local zone name. */
 387     const ZoneName = NodeName
 388
 389     /* Secret key for remote node tickets */
 390     const TicketSalt = ""
 391
 392 The `ZoneName` and `TicketSalt` constants are required for remote client
 393 and distributed setups only.
 394
 395
 396 ### <a id="zones-conf"></a> zones.conf
 397
 398 The `zones.conf` configuration file can be used to configure `Endpoint` and `Zone` objects
 399 required for a [distributed zone setup](#distributed-monitoring-high-availability). By default
 400 a local dummy zone is defined based on the `NodeName` constant defined in
 401 [constants.conf](#constants-conf).
 402
 403 > **Note**
 404 >
 405 > Not required for single instance installations.
 406
 407
 408 ### <a id="conf-d"></a> Configuration in conf.d Directory
 409
 410 This directory contains example configuration getting your started with monitoring
 411 the local host and its services. It is included in [icinga2.conf](#icinga2-conf)
 412 in the default installation.
 413
 414 It can be used as reference example for your own configuration strategy.
 415 Just keep in mind to include the main directories in the
 416 [icinga2.conf](#icinga2-conf) file.
 417
 418 You are certainly not bound to it. Remove it, if you prefer your own
 419 way of deploying Icinga 2 configuration.
 420
 421 Further details on configuration best practice and how to build your
 422 own strategy is described in [this chapter](#configuration-best-practice).
 423
 424 Available configuration files shipped by default:
 425
 426 * [hosts.conf](#hosts-conf)
 427 * [services.conf](#services-conf)
 428 * [users.conf](#users-conf)
 429 * [notifications.conf](#notifications-conf)
 430 * [commands.conf](#commands-conf)
 431 * [groups.conf](#groups-conf)
 432 * [templates.conf](#templates-conf)
 433 * [downtimes.conf](#downtimes-conf)
 434 * [timeperiods.conf](#timeperiods-conf)
 435 * [satellite.conf](#satellite-conf)
 436
 437 #### <a id="hosts-conf"></a> hosts.conf
 438
 439 The `conf.d/hosts.conf` file contains an example host based on your
 440 `NodeName` setting in [constants.conf](#constants-conf).
 441
 442 The `import` keyword is used to import the `generic-host` template which
 443 takes care of setting up the host check command to `hostalive`. If you
 444 require a different check command, you can override it in the object definition.
 445
 446 The `vars` attribute can be used to define custom attributes which are available
 447 for check and notification commands. Most of the [Plugin Check Commands](#plugin-check-commands)
 448 in the Icinga Template Library require an `address` attribute.
 449
 450 The custom attribute `os` is evaluated by the `linux-servers` group in
 451 [groups.conf](#groups-conf) making the local host a member.
 452
 453 The example host will show you how to
 454
 455 * define http vhost attributes for the `http` service apply rule defined
 456 in [services.conf](#services.conf).
 457 * define disks (all, specific `/`) and their attributes for the `disk`
 458 service apply rule defined in [services.conf](#services.conf).
 459 * define notification types (`mail`) and set the groups attribute. This
 460 will be used by notification apply rules in [notifications.conf](notifications-conf).
 461
 462 If you've installed [Icinga Web 2](#setting-up-icingaweb2) you can
 463 uncomment the http vhost attributes and relaod Icinga 2. The apply
 464 rules in [services.conf](#services.conf) will automatically
 465 generate a new service checking the `/icingaweb` URI using the `http`
 466 check.
 467
 468     /*
 469      * Host definitions with object attributes
 470      * used for apply rules for Service, Notification,
 471      * Dependency and ScheduledDowntime objects.
 472      *
 473      * Tip: Use `icinga2 object list --type Host` to
 474      * list all host objects after running
 475      * configuration validation (`icinga2 daemon -C`).
 476      */
 477
 478     /*
 479      * This is an example host based on your
 480      * local host's FQDN. Specify the NodeName
 481      * constant in `constants.conf` or use your
 482      * own description, e.g. "db-host-1".
 483      */
 484
 485     object Host NodeName {
 486       /* Import the default host template defined in `templates.conf`. */
 487       import "generic-host"
 488
 489       /* Specify the address attributes for checks e.g. `ssh` or `http`. */
 490       address = "127.0.0.1"
 491       address6 = "::1"
 492
 493       /* Set custom attribute `os` for hostgroup assignment in `groups.conf`. */
 494       vars.os = "Linux"
 495
 496       /* Define http vhost attributes for service apply rules in `services.conf`. */
 497       vars.http_vhosts["http"] = {
 498         http_uri = "/"
 499       }
 500       /* Uncomment if you've sucessfully installed Icinga Web 2. */
 501       //vars.http_vhosts["Icinga Web 2"] = {
 502       //  http_uri = "/icingaweb"
 503       //}
 504
 505       /* Define disks and attributes for service apply rules in `services.conf`. */
 506       vars.disks["disk"] = {
 507         /* No parameters. */
 508       }
 509       vars.disks["disk /"] = {
 510         disk_partition = "/"
 511       }
 512
 513       /* Define notification mail attributes for notification apply rules in `notifications.conf`. */
 514       vars.notification["mail"] = {
 515         /* The UserGroup `icingaadmins` is defined in `users.conf`. */
 516         groups = [ "icingaadmins" ]
 517       }
 518     }
 519
 520 This is only the host object definition. Now we'll need to make sure that this
 521 host and your additional hosts are getting [services](#services-conf) applied.
 522
 523 > **Tip**
 524 >
 525 > If you don't understand all the attributes and how to use [apply rules](#apply)
 526 > don't worry - the [monitoring basics](#monitoring-basics) chapter will explain
 527 > that in detail.
 528
 529 #### <a id="services-conf"></a> services.conf
 530
 531 These service [apply rules](#apply) will show you how to monitor
 532 the local host, but also allow you to re-use or modify them for
 533 your own requirements.
 534
 535 You should define all your service apply rules in `services.conf`
 536 or any other central location keeping them organized.
 537
 538 By default, the local host will be monitored by the following services
 539
 540 Service(s)                                  | Applied on host(s)
 541 --------------------------------------------|------------------------
 542 `load`, `procs`, `swap`, `users`, `icinga`  | The `NodeName` host only
 543 `ping4`, `ping6`                            | All hosts with `address` resp. `address6` attribute
 544 `ssh`                                       | All hosts with `address` and `vars.os` set to `Linux`
 545 `http`, optional: `Icinga Web 2`            | All hosts with custom attribute `http_vhosts` defined as dictionary
 546 `disk`, `disk /`                            | All hosts with custom attribute `disks` defined as dictionary
 547
 548 The Debian packages also ship an additional `apt` service check applied to the local host.
 549
 550 The command object `icinga` for the embedded health check is provided by the
 551 [Icinga Template Library (ITL)](#itl) while `http_ip`, `ssh`, `load`, `processes`,
 552 `users` and `disk` are all provided by the [Plugin Check Commands](#plugin-check-commands)
 553 which we enabled earlier by including the `itl` and `plugins` configuration file.
 554
 555
 556 Example `load` service apply rule:
 557
 558     apply Service "load" {
 559       import "generic-service"
 560
 561       check_command = "load"
 562
 563       /* Used by the ScheduledDowntime apply rule in `downtimes.conf`. */
 564       vars.backup_downtime = "02:00-03:00"
 565
 566       assign where host.name == NodeName
 567     }
 568
 569 The `apply` keyword can be used to create new objects which are associated with
 570 another group of objects. You can `import` existing templates, define (custom)
 571 attributes.
 572
 573 The custom attribe `backup_downtime` is defined to a specific timerange string.
 574 This variable value will be used for applying a `ScheduledDowntime` object to
 575 these services in [downtimes.conf](#downtimes-conf).
 576
 577 In this example the `assign where` condition is a boolean expression which is
 578 evaluated for all objects of type `Host` and a new service with name "load"
 579 is created for each matching host. [Expression operators](#expression-operators)
 580 may be used in `assign where` conditions.
 581
 582 Multiple `assign where` condition can be combined with `AND` using the `&&` operator
 583 as shown in the `ssh` example:
 584
 585     apply Service "ssh" {
 586       import "generic-service"
 587
 588       check_command = "ssh"
 589
 590       assign where host.address && host.vars.os == "Linux"
 591     }
 592
 593 In this example, the service `ssh` is applied to all hosts having the `address`
 594 attribute defined `AND` having the custom attribute `os` set to the string
 595 `Linux`.
 596 You can modify this condition to match multiple expressions by combinding `AND`
 597 and `OR` using `&&` and `||` [operators](#expression-operators), for example
 598 `assign where host.address && (vars.os == "Linux" || vars.os == "Windows")`.
 599
 600
 601 A more advanced example is shown by the `http` and `disk` service apply
 602 rules. While one `apply` rule for `ssh` will only create a service for matching
 603 hosts, you can go one step further: Generate apply rules based on array items
 604 or dictionary key-value pairs.
 605
 606 The idea is simple: Your host in [hosts.conf](#hosts-conf) defines the
 607 `disks` dictionary as custom attribute in `vars`.
 608
 609 Remember the example from [hosts.conf](#hosts-conf):
 610
 611     ...
 612
 613       /* Define disks and attributes for service apply rules in `services.conf`. */
 614       vars.disks["disk"] = {
 615         /* No parameters. */
 616       }
 617       vars.disks["disk /"] = {
 618         disk_partition = "/"
 619       }
 620     ...
 621
 622
 623 This dictionary contains multiple service names we want to monitor. `disk`
 624 should just check all available disks, while `disk /` will pass an additional
 625 parameter `disk_partition` to the check command.
 626
 627 You'll recognize that the naming is important - that's the very same name
 628 as it is passed from a service to a check command argument. Read about services
 629 and passing check commands in [this chapter](#command-passing-parameters).
 630
 631 Using `apply Service for` omits the service name, it will take the key stored in
 632 the `disk` variable in `key => config` as new service object name.
 633
 634 The `for` keyword expects a loop definition, for example `key => value in dictionary`
 635 as known from Perl and other scripting languages.
 636
 637 Once defined like this, the `apply` rule defined below will do the following:
 638
 639 * only match hosts with `host.vars.disks` defined through the `assign where` condition
 640 * loop through all entries in the `host.vars.disks` dictionary. That's `disk` and `disk /` as keys.
 641 * call `apply` on each, and set the service object name from the provided key
 642 * inside apply, the `generic-service` template is imported
 643 * defining the [disk](#plugin-check-command-disk) check command requiring command arguments like `disk_partition`
 644 * adding the `config` dictionary items to `vars`. Simply said, there's now `vars.disk_partition` defined for the
 645 generated service
 646
 647
 648     apply Service for (disk => config in host.vars.disks) {
 649       import "generic-service"
 650
 651       check_command = "disk"
 652
 653       vars += config
 654
 655       assign where host.vars.disks
 656     }
 657
 658 A similar example is used for the `http` services. That way you can make your
 659 host the information provider for all apply rules. Define them once, and only
 660 manage your hosts.
 661
 662 Look into [notifications.conf](#notifications-conf) how this technique is used
 663 for applying notifications to hosts and services using their type and user
 664 attributes.
 665
 666 Don't forget to install the [check plugins](#setting-up-check-plugins) required by
 667 the hosts and services and their check commands.
 668
 669 Further details on the monitoring configuration can be found in the
 670 [monitoring basics](#monitoring-basics) chapter.
 671
 672 #### <a id="users-conf"></a> users.conf
 673
 674 Defines the `icingaadmin` User and the `icingaadmins` UserGroup. The latter is used in
 675 [hosts.conf](#hostss-conf) for defining a custom host attribute later used in
 676 [notifications.conf](#notifications-conf) for notification apply rules.
 677
 678     object User "icingaadmin" {
 679       import "generic-user"
 680
 681       display_name = "Icinga 2 Admin"
 682       groups = [ "icingaadmins" ]
 683
 684       email = "icinga@localhost"
 685     }
 686
 687     object UserGroup "icingaadmins" {
 688       display_name = "Icinga 2 Admin Group"
 689     }
 690
 691
 692 #### <a id="notifications-conf"></a> notifications.conf
 693
 694 Notifications for check alerts are an integral part or your
 695 Icinga 2 monitoring stack.
 696
 697 The shipped example defines two notification apply rules for hosts and services.
 698 Both `apply` rules match on the same condition: They are only applied if the
 699 nested dictionary attribute `notification.mail` is set.
 700
 701 Please note that the `to` keyword is important in [notification apply rules](#using-apply-notifications)
 702 defining whether these notifications are applies to hosts or services.
 703 The `import` keyword imports the specific mail templates defined in [templates.conf](templates-conf)
 704
 705 By setting the `user_groups` to the value provided by the
 706 respective [host.vars.notification.mail](#hosts-conf) attribute we'll
 707 implicitely use the`icingaadmins` UserGroup defined in [users.conf](#users.conf).
 708
 709     apply Notification "mail-icingaadmin" to Host {
 710       import "mail-host-notification"
 711
 712       user_groups = host.vars.notification.mail.groups
 713
 714       assign where host.vars.notification.mail
 715     }
 716
 717     apply Notification "mail-icingaadmin" to Service {
 718       import "mail-service-notification"
 719
 720       user_groups = host.vars.notification.mail.groups
 721
 722       assign where host.vars.notification.mail
 723     }
 724
 725 More details on defining notifications and their additional attributes such as
 726 filters can be read in [this chapter](#notifications).
 727
 728 #### <a id="commands-conf"></a> commands.conf
 729
 730 This is the place where your own command configuration can be defined. By default
 731 only the notification commands used by the notification templates defined in [templates.conf](#templates-conf).
 732
 733 > **Tip**
 734 >
 735 > Icinga 2 ships the most common command definitions already in the
 736 > [Plugin Check Commands](#plugin-check-commands) definitions. More details on
 737 > that topic in the [troubleshooting section](#check-command-definitions).
 738
 739 You can freely customize these notification commands, and adapt them for your needs.
 740 Read more on that topic [here](#notification-commands).
 741
 742 #### <a id="groups-conf"></a> groups.conf
 743
 744 The example host defined in [hosts.conf](hosts-conf) already has the
 745 custom attribute `os` set to `Linux` and is therefore automatically
 746 a member of the host group `linux-servers`.
 747
 748 This is done by using the [group assign](#group-assign) expressions similar
 749 to previously seen [apply rules](#using-apply).
 750
 751     object HostGroup "linux-servers" {
 752       display_name = "Linux Servers"
 753
 754       assign where host.vars.os == "Linux"
 755     }
 756
 757     object HostGroup "windows-servers" {
 758       display_name = "Windows Servers"
 759
 760       assign where host.vars.os == "Windows"
 761     }
 762
 763 Service groups can be grouped together by similar pattern matches.
 764 The [match() function](#function-calls) expects a wildcard match string
 765 and the attribute string to match with.
 766
 767     object ServiceGroup "ping" {
 768       display_name = "Ping Checks"
 769
 770       assign where match("ping*", service.name)
 771     }
 772
 773     object ServiceGroup "http" {
 774       display_name = "HTTP Checks"
 775
 776       assign where match("http*", service.check_command)
 777     }
 778
 779     object ServiceGroup "disk" {
 780       display_name = "Disk Checks"
 781
 782       assign where match("disk*", service.check_command)
 783     }
 784
 785
 786 #### <a id="templates-conf"></a> templates.conf
 787
 788 All shipped example configuration objects use generic global templates by
 789 default. Be it setting a default `check_command` attribute in the `generic-host`
 790 templates for your hosts defined in [hosts.conf](#hosts-conf), or defining
 791 the default `states` and `types` filters for notification apply rules defined in
 792 [notifications.conf](#notifications-conf).
 793
 794
 795     template Host "generic-host" {
 796       max_check_attempts = 5
 797       check_interval = 1m
 798       retry_interval = 30s
 799
 800       check_command = "hostalive"
 801     }
 802
 803     template Service "generic-service" {
 804       max_check_attempts = 3
 805       check_interval = 1m
 806       retry_interval = 30s
 807     }
 808
 809 The `hostalive` check command is shipped with Icinga 2 in the
 810 [Plugin Check Commands](#plugin-check-commands).
 811
 812
 813     template Notification "mail-host-notification" {
 814       command = "mail-host-notification"
 815
 816       states = [ Up, Down ]
 817       types = [ Problem, Acknowledgement, Recovery, Custom,
 818                 FlappingStart, FlappingEnd,
 819                 DowntimeStart, DowntimeEnd, DowntimeRemoved ]
 820
 821       period = "24x7"
 822     }
 823
 824     template Notification "mail-service-notification" {
 825       command = "mail-service-notification"
 826
 827       states = [ OK, Warning, Critical, Unknown ]
 828       types = [ Problem, Acknowledgement, Recovery, Custom,
 829                 FlappingStart, FlappingEnd,
 830                 DowntimeStart, DowntimeEnd, DowntimeRemoved ]
 831
 832       period = "24x7"
 833     }
 834
 835 More details on `Notification` object attributes can be found [here](#objecttype-notification).
 836
 837
 838 #### <a id="downtimes-conf"></a> downtimes.conf
 839
 840 The `load` service apply rule defined in [services.conf](#services-conf) defines
 841 the `backup_downtime` custom attribute.
 842
 843 The [ScheduledDowntime](#objecttype-scheduleddowntime) apply rule uses this attribute
 844 to define the default value for the time ranges required for recurring downtime slots.
 845
 846     apply ScheduledDowntime "backup-downtime" to Service {
 847       author = "icingaadmin"
 848       comment = "Scheduled downtime for backup"
 849
 850       ranges = {
 851         monday = service.vars.backup_downtime
 852         tuesday = service.vars.backup_downtime
 853         wednesday = service.vars.backup_downtime
 854         thursday = service.vars.backup_downtime
 855         friday = service.vars.backup_downtime
 856         saturday = service.vars.backup_downtime
 857         sunday = service.vars.backup_downtime
 858       }
 859
 860       assign where service.vars.backup_downtime != ""
 861     }
 862
 863
 864 #### <a id="timeperiods-conf"></a> timeperiods.conf
 865
 866 This file ships the default timeperiod definitions for `24x7`, `9to5`
 867 and `never`. Timeperiod objects are referenced by `*period`
 868 objects such as hosts, services or notifications.
 869
 870
 871 #### <a id="satellite-conf"></a> satellite.conf
 872
 873 Ships default templates and dependencies for [monitoring remote clients](#icinga2-remote-client-monitoring)
 874 using service discovery and [config generation](#icinga2-remote-monitoring-master-discovery-generate-config)
 875 on the master. Can be ignored/removed on setups not using this features.
 876
 877
 878 Further details on the monitoring configuration can be found in the
 879 [monitoring basics](#monitoring-basics) chapter.
 880
 881
 882
 883 ## <a id="configuring-db-ido"></a> Configuring DB IDO
 884
 885 The DB IDO (Database Icinga Data Output) modules for Icinga 2 take care of exporting
 886 all configuration and status information into a database. The IDO database is used
 887 by a number of projects including Icinga Web 1.x, Reporting or Icinga Web 2.
 888
 889 There is a separate module for each database back-end. At present support for
 890 both MySQL and PostgreSQL is implemented.
 891
 892 Icinga 2 uses the Icinga 1.x IDOUtils database schema. Icinga 2 requires additional
 893 features not yet released with older Icinga 1.x versions.
 894
 895 > **Note**
 896 >
 897 > Please check the [what's new](#whats-new) section for the required schema version.
 898
 899 > **Tip**
 900 >
 901 > Only install the IDO feature if your web interface or reporting tool requires
 902 > you to do so (for example, [Icinga Web](#setting-up-icinga-web) or [Icinga Web 2](#setting-up-icingaweb2)).
 903 > [Icinga Classic UI](#setting-up-icinga-classic-ui) does not use IDO as backend.
 904
 905 ### <a id="installing-database"></a> Installing the Database Server
 906
 907 In order to use DB IDO you need to setup either [MySQL](#installing-database-mysql-server)
 908 or [PostgreSQL](#installing-database-postgresql-server) as supported database server.
 909
 910 > **Note**
 911 >
 912 > It's up to you whether you choose to install it on the same server where Icinga 2 is running on,
 913 > or on a dedicated database host (or cluster).
 914
 915 #### <a id="installing-database-mysql-server"></a> Installing MySQL database server
 916
 917 Debian/Ubuntu:
 918
 919     # apt-get install mysql-server mysql-client
 920
 921 RHEL/CentOS 5/6:
 922
 923     # yum install mysql-server mysql
 924     # chkconfig mysqld on
 925     # service mysqld start
 926
 927 RHEL/CentOS 7 and Fedora 20 prefer MariaDB over MySQL:
 928
 929     # yum install mariadb-server mariadb
 930     # systemctl enable mariadb.service
 931     # systemctl start mariadb.service
 932
 933 SUSE:
 934
 935     # zypper install mysql mysql-client
 936     # chkconfig mysqld on
 937     # service mysqld start
 938
 939 RHEL based distributions do not automatically set a secure root password. Do that **now**:
 940
 941     # /usr/bin/mysql_secure_installation
 942
 943
 944 #### <a id="installing-database-postgresql-server"></a> Installing PostgreSQL database server
 945
 946 Debian/Ubuntu:
 947
 948     # apt-get install postgresql
 949
 950 RHEL/CentOS 5/6:
 951
 952     # yum install postgresql-server postgresql
 953     # chkconfig postgresql on
 954     # service postgresql start
 955
 956 RHEL/CentOS 7 and Fedora 20 use [systemd](#systemd-service):
 957
 958     # yum install postgresql-server postgresql
 959     # systemctl enable postgresql.service
 960     # systemctl start postgresql.service
 961
 962 SUSE:
 963
 964     # zypper install postgresql postgresql-server
 965     # chkconfig postgresql on
 966     # service postgresql start
 967
 968 ### <a id="configuring-db-ido-mysql"></a> Configuring DB IDO MySQL
 969
 970 First of all you have to install the `icinga2-ido-mysql` package using your
 971 distribution's package manager.
 972
 973 Debian/Ubuntu:
 974
 975     # apt-get install icinga2-ido-mysql
 976
 977 RHEL/CentOS:
 978
 979     # yum install icinga2-ido-mysql
 980
 981 SUSE:
 982
 983     # zypper install icinga2-ido-mysql
 984
 985
 986
 987 > **Note**
 988 >
 989 > Upstream Debian packages provide a database configuration wizard by default.
 990 > You can skip the automated setup and install/upgrade the database manually
 991 > if you prefer that.
 992
 993 #### <a id="setting-up-mysql-db"></a> Setting up the MySQL database
 994
 995 Set up a MySQL database for Icinga 2:
 996
 997     # mysql -u root -p
 998
 999     mysql>  CREATE DATABASE icinga;
1000             GRANT SELECT, INSERT, UPDATE, DELETE, DROP, CREATE VIEW, INDEX, EXECUTE ON icinga.* TO 'icinga'@'localhost' IDENTIFIED BY 'icinga';
1001             quit
1002
1003 After creating the database you can import the Icinga 2 IDO schema using the
1004 following command:
1005
1006     # mysql -u root -p icinga < /usr/share/icinga2-ido-mysql/schema/mysql.sql
1007
1008
1009 #### <a id="upgrading-mysql-db"></a> Upgrading the MySQL database
1010
1011 Check the `/usr/share/icinga2-ido-mysql/schema/upgrade` directory for an
1012 incremental schema upgrade file.
1013
1014 > **Note**
1015 >
1016 > If there isn't an upgrade file for your current version available there's nothing to do.
1017
1018 Apply all database schema upgrade files incrementially.
1019
1020     # mysql -u root -p icinga < /usr/share/icinga2-ido-mysql/schema/upgrade/<version>.sql
1021
1022 The Icinga 2 DB IDO module will check for the required database schema version on startup
1023 and generate an error message if not satisfied.
1024
1025
1026 **Example:** You are upgrading Icinga 2 from version `2.0.2` to `2.1.0`. Look into
1027 the *upgrade* directory:
1028
1029     $ ls /usr/share/icinga2-ido-mysql/schema/upgrade/
1030     2.0.2.sql  2.1.0.sql
1031
1032 There is a new upgrade file called `2.1.0.sql` which must be applied to your IDO database.
1033
1034
1035 #### <a id="installing-ido-mysql"></a> Installing the IDO MySQL module
1036
1037 The package provides a new configuration file that is installed in
1038 `/etc/icinga2/features-available/ido-mysql.conf`. You will need to update the
1039 database credentials in this file.
1040
1041 You can enable the `ido-mysql` feature configuration file using `icinga2 feature enable`:
1042
1043     # icinga2 feature enable ido-mysql
1044     Module 'ido-mysql' was enabled.
1045     Make sure to restart Icinga 2 for these changes to take effect.
1046
1047 After enabling the ido-mysql feature you have to restart Icinga 2:
1048
1049 Debian/Ubuntu, RHEL/CentOS 6 and SUSE:
1050
1051     # service icinga2 restart
1052
1053 RHEL/CentOS 7 and Fedora 20:
1054
1055     # systemctl restart icinga2.service
1056
1057 ### <a id="configuring-db-ido-postgresql"></a> Configuring DB IDO PostgreSQL
1058
1059 First of all you have to install the `icinga2-ido-pgsql` package using your
1060 distribution's package manager.
1061
1062 Debian/Ubuntu:
1063
1064     # apt-get install icinga2-ido-pgsql
1065
1066 RHEL/CentOS:
1067
1068     # yum install icinga2-ido-pgsql
1069
1070 SUSE:
1071
1072     # zypper install icinga2-ido-pgsql
1073
1074 > **Note**
1075 >
1076 > Upstream Debian packages provide a database configuration wizard by default.
1077 > You can skip the automated setup and install/upgrade the database manually
1078 > if you prefer that.
1079
1080 #### Setting up the PostgreSQL database
1081
1082 Set up a PostgreSQL database for Icinga 2:
1083
1084     # cd /tmp
1085     # sudo -u postgres psql -c "CREATE ROLE icinga WITH LOGIN PASSWORD 'icinga'";
1086     # sudo -u postgres createdb -O icinga -E UTF8 icinga
1087     # sudo -u postgres createlang plpgsql icinga
1088
1089 > **Note**
1090 >
1091 > Using PostgreSQL 9.x you can omit the `createlang` command.
1092
1093 Locate your pg_hba.conf (Debian: `/etc/postgresql/*/main/pg_hba.conf`,
1094 RHEL/SUSE: `/var/lib/pgsql/data/pg_hba.conf`), add the icinga user with md5
1095 authentication method and restart the postgresql server.
1096
1097     # vim /var/lib/pgsql/data/pg_hba.conf
1098
1099     # icinga
1100     local   icinga      icinga                            md5
1101     host    icinga      icinga      127.0.0.1/32          md5
1102     host    icinga      icinga      ::1/128               md5
1103
1104     # "local" is for Unix domain socket connections only
1105     local   all         all                               ident
1106     # IPv4 local connections:
1107     host    all         all         127.0.0.1/32          ident
1108     # IPv6 local connections:
1109     host    all         all         ::1/128               ident
1110
1111     # /etc/init.d/postgresql restart
1112
1113
1114 After creating the database and permissions you can import the Icinga 2 IDO schema
1115 using the following command:
1116
1117     # export PGPASSWORD=icinga
1118     # psql -U icinga -d icinga < /usr/share/icinga2-ido-pgsql/schema/pgsql.sql
1119
1120 #### <a id="upgrading-postgresql-db"></a> Upgrading the PostgreSQL database
1121
1122 Check the `/usr/share/icinga2-ido-pgsql/schema/upgrade` directory for an
1123 incremental schema upgrade file.
1124
1125 > **Note**
1126 >
1127 > If there isn't an upgrade file for your current version available there's nothing to do.
1128
1129 Apply all database schema upgrade files incrementially.
1130
1131     # export PGPASSWORD=icinga
1132     # psql -U icinga -d icinga < /usr/share/icinga2-ido-pgsql/schema/upgrade/<version>.sql
1133
1134 The Icinga 2 DB IDO module will check for the required database schema version on startup
1135 and generate an error message if not satisfied.
1136
1137 **Example:** You are upgrading Icinga 2 from version `2.0.2` to `2.1.0`. Look into
1138 the *upgrade* directory:
1139
1140     $ ls /usr/share/icinga2-ido-pgsql/schema/upgrade/
1141     2.0.2.sql  2.1.0.sql
1142
1143 There is a new upgrade file called `2.1.0.sql` which must be applied to your IDO database.
1144
1145
1146 #### <a id="installing-ido-postgresql"></a> Installing the IDO PostgreSQL module
1147
1148 The package provides a new configuration file that is installed in
1149 `/etc/icinga2/features-available/ido-pgsql.conf`. You will need to update the
1150 database credentials in this file.
1151
1152 You can enable the `ido-pgsql` feature configuration file using `icinga2 feature enable`:
1153
1154     # icinga2 feature enable ido-pgsql
1155     Module 'ido-pgsql' was enabled.
1156     Make sure to restart Icinga 2 for these changes to take effect.
1157
1158 After enabling the ido-pgsql feature you have to restart Icinga 2:
1159
1160 Debian/Ubuntu, RHEL/CentOS 6 and SUSE:
1161
1162     # service icinga2 restart
1163
1164 RHEL/CentOS 7 and Fedora 20:
1165
1166     # systemctl restart icinga2.service
1167
1168
1169 ### <a id="setting-up-external-command-pipe"></a> Setting Up External Command Pipe
1170
1171 Web interfaces and other Icinga addons are able to send commands to
1172 Icinga 2 through the external command pipe.
1173
1174 You can enable the External Command Pipe using icinga2 feature enable:
1175
1176     # icinga2 feature enable command
1177
1178 After that you will have to restart Icinga 2:
1179
1180 Debian/Ubuntu, RHEL/CentOS 6 and SUSE:
1181
1182     # service icinga2 restart
1183
1184 RHEL/CentOS 7 and Fedora 20:
1185
1186     # systemctl restart icinga2.service
1187
1188 By default the command pipe file is owned by the group `icingacmd` with read/write
1189 permissions. Add your webserver's user to the group `icingacmd` to
1190 enable sending commands to Icinga 2 through your web interface:
1191
1192     # usermod -a -G icingacmd www-data
1193
1194 Debian packages use `nagios` as the default user and group name. Therefore change `icingacmd` to
1195 `nagios`.
1196 The webserver's user is different between distributions so you might have to change `www-data` to
1197 `wwwrun`, `www`, or `apache`.
1198
1199 Change "www-data" to the user you're using to run queries.
1200
1201 > **Note**
1202 >
1203 > Packages will do that automatically. Verify that by running `id <your-webserver-user>` and skip this
1204 > step.
1205
1206 ## <a id="setting-up-livestatus"></a> Setting up Livestatus
1207
1208 The [MK Livestatus](http://mathias-kettner.de/checkmk_livestatus.html) project
1209 implements a query protocol that lets users query their Icinga instance for
1210 status information. It can also be used to send commands.
1211
1212 > **Tip**
1213 >
1214 > Only install the Livestatus feature if your web interface or addon requires
1215 > you to do so (for example, [Icinga Web 2](#setting-up-icingaweb2)).
1216 > [Icinga Classic UI](#setting-up-icinga-classic-ui) and [Icinga Web](#setting-up-icinga-web)
1217 > do not use Livestatus as backend.
1218
1219 The Livestatus component that is distributed as part of Icinga 2 is a
1220 re-implementation of the Livestatus protocol which is compatible with MK
1221 Livestatus.
1222
1223 Details on the available tables and attributes with Icinga 2 can be found
1224 in the [Livestatus](#livestatus) section.
1225
1226 You can enable Livestatus using icinga2 feature enable:
1227
1228     # icinga2 feature enable livestatus
1229
1230 After that you will have to restart Icinga 2:
1231
1232 Debian/Ubuntu, RHEL/CentOS 6 and SUSE:
1233
1234     # service icinga2 restart
1235
1236 RHEL/CentOS 7 and Fedora 20:
1237
1238     # systemctl restart icinga2.service
1239
1240 By default the Livestatus socket is available in `/var/run/icinga2/cmd/livestatus`.
1241
1242 In order for queries and commands to work you will need to add your query user
1243 (e.g. your web server) to the `icingacmd` group:
1244
1245     # usermod -a -G icingacmd www-data
1246
1247 The Debian packages use `nagios` as the user and group name. Make sure to change `icingacmd` to
1248 `nagios` if you're using Debian.
1249
1250 Change "www-data" to the user you're using to run queries.
1251
1252 In order to use the historical tables provided by the livestatus feature (for example, the
1253 `log` table) you need to have the `CompatLogger` feature enabled. By default these logs
1254 are expected to be in `/var/log/icinga2/compat`. A different path can be set using the
1255 `compat_log_path` configuration attribute.
1256
1257     # icinga2 feature enable compatlog
1258
1259 ## <a id="setting-up-icinga2-user-interfaces"></a> Setting up Icinga 2 User Interfaces
1260
1261 Icinga 2 is compatible with Icinga 1.x user interfaces by providing additional
1262 features required as backends.
1263
1264 Furthermore these interfaces can be used for the newly created `Icinga Web 2`
1265 user interface.
1266
1267 Some interface features will only work in a limited manner due to
1268 [compatibility reasons](#differences-1x-2), other features like the
1269 statusmap parents are available by dumping the host dependencies as parents.
1270 Special restrictions are noted specifically in the sections below.
1271
1272 > **Tip**
1273 >
1274 > Choose your preferred interface. There's no need to install [Classic UI](#setting-up-icinga-classic-ui)
1275 > if you prefer [Icinga Web](#setting-up-icinga-web) or [Icinga Web 2](#setting-up-icingaweb2) for example.
1276
1277 ### <a id="icinga2-user-interface-requirements"></a> Requirements
1278
1279 * Web server (Apache2/Httpd, Nginx, Lighttp, etc)
1280 * User credentials
1281 * Firewall ports (tcp/80)
1282
1283 The Debian, RHEL and SUSE packages for Icinga [Classic UI](#setting-up-icinga-classic-ui),
1284 [Web](#setting-up-icinga-web) and [Icingaweb 2](#setting-up-icingaweb2) depend on Apache2
1285 as web server.
1286
1287 #### <a id="icinga2-user-interface-webserver"></a> Webserver
1288
1289 Debian/Ubuntu packages will automatically fetch and install the required packages.
1290
1291 RHEL/CentOS/Fedora:
1292
1293     # yum install httpd
1294     # chkconfig httpd on && service httpd start
1295     ## RHEL7
1296     # systemctl enable httpd && systemctl start httpd
1297
1298 SUSE:
1299
1300     # zypper install apache2
1301     # chkconfig on && service apache2 start
1302
1303 #### <a id="icinga2-user-interface-firewall-rules"></a> Firewall Rules
1304
1305 Example:
1306
1307     # iptables -A INPUT -p tcp -m tcp --dport 80 -j ACCEPT
1308     # service iptables save
1309
1310 RHEL/CentOS 7 specific:
1311
1312     # firewall-cmd --add-service=http
1313     # firewall-cmd --permanent --add-service=http
1314
1315 ### <a id="setting-up-icinga-classic-ui"></a> Setting up Icinga Classic UI
1316
1317 Icinga 2 can write `status.dat` and `objects.cache` files in the format that
1318 is supported by the Icinga 1.x Classic UI. [External commands](#external-commands)
1319 (a.k.a. the "command pipe") are also supported. It also supports writing Icinga 1.x
1320 log files which are required for the reporting functionality in the Classic UI.
1321
1322 #### <a id="installing-icinga-classic-ui"></a> Installing Icinga Classic UI
1323
1324 The Icinga package repository has both Debian and RPM packages. You can install
1325 the Classic UI using the following packages:
1326
1327   Distribution  | Packages
1328   --------------|---------------------
1329   Debian        | icinga2-classicui
1330   RHEL/SUSE     | icinga2-classicui-config icinga-gui
1331
1332 The Debian packages require additional packages which are provided by the
1333 [Debian Monitoring Project](http://www.debmon.org) (`DebMon`) repository.
1334
1335 `libjs-jquery-ui` requires at least version `1.10.*` which is not available
1336 in Debian 7 (Wheezy) and Ubuntu 12.04 LTS (Precise). Add the following repositories
1337 to satisfy this dependency:
1338
1339   Distribution                  | Package Repositories
1340   ------------------------------|------------------------------
1341   Debian Wheezy                 | [wheezy-backports](http://backports.debian.org/Instructions/) or [DebMon](http://www.debmon.org)
1342   Ubuntu 12.04 LTS (Precise)    | [Icinga PPA](https://launchpad.net/~formorer/+archive/icinga)
1343
1344 On all distributions other than Debian you may have to restart both your web
1345 server as well as Icinga 2 after installing the Classic UI package.
1346
1347 Icinga Classic UI requires the [StatusDataWriter](#status-data), [CompatLogger](#compat-logging)
1348 and [ExternalCommandListener](#external-commands) features.
1349 Enable these features and restart Icinga 2.
1350
1351     # icinga2 feature enable statusdata compatlog command
1352
1353 In order for commands to work you will need to [setup the external command pipe](#setting-up-external-command-pipe).
1354
1355 #### <a id="setting-up-icinga-classic-ui-summary"></a> Setting Up Icinga Classic UI Summary
1356
1357 Verify that your Icinga 1.x Classic UI works by browsing to your Classic
1358 UI installation URL:
1359
1360   Distribution  | URL                                                                      | Default Login
1361   --------------|--------------------------------------------------------------------------|--------------------------
1362   Debian        | [http://localhost/icinga2-classicui](http://localhost/icinga2-classicui) | asked during installation
1363   all others    | [http://localhost/icinga](http://localhost/icinga)                       | icingaadmin/icingaadmin
1364
1365 For further information on configuration, troubleshooting and interface documentation
1366 please check the official [Icinga 1.x user interface documentation](http://docs.icinga.org/latest/en/ch06.html).
1367
1368 ### <a id="setting-up-icinga-web"></a> Setting up Icinga Web
1369
1370 Icinga 2 can write to the same schema supplied by `Icinga IDOUtils 1.x` which
1371 is an explicit requirement to run `Icinga Web` next to the external command pipe.
1372 Therefore you need to setup the [DB IDO feature](#configuring-ido) remarked in the previous sections.
1373
1374 #### <a id="installing-icinga-web"></a> Installing Icinga Web
1375
1376 The Icinga package repository has both Debian and RPM packages. You can install
1377 Icinga Web using the following packages (RPMs ship an additional configuration package):
1378
1379   Distribution  | Packages
1380   --------------|-------------------------------------------------------
1381   RHEL/SUSE     | icinga-web icinga-web-{mysql,pgsql}
1382   Debian        | icinga-web icinga-web-config-icinga2-ido-{mysql,pgsql}
1383
1384 #### <a id="icinga-web-rpm-notes"></a> Icinga Web on RPM based systems
1385
1386 Additionally you need to setup the `icinga_web` database and import the database schema.
1387 Details can be found in the package `README` files, for example [README.RHEL](https://github.com/Icinga/icinga-web/blob/master/doc/README.RHEL)
1388
1389 The Icinga Web RPM packages install the schema files into
1390 `/usr/share/doc/icinga-web-*/schema` (`*` means package version).
1391 The Icinga Web dist tarball ships the schema files in `etc/schema`.
1392
1393 On SuSE-based distributions the schema files are installed in
1394 `/usr/share/doc/packages/icinga-web/schema`.
1395
1396 Example for RHEL and MySQL:
1397
1398     # mysql -u root -p
1399
1400     mysql> CREATE DATABASE icinga_web;
1401            GRANT SELECT, INSERT, UPDATE, DELETE, DROP, CREATE VIEW, INDEX, EXECUTE ON icinga_web.* TO 'icinga_web'@'localhost' IDENTIFIED BY 'icinga_web';
1402            quit
1403
1404     # mysql -u root -p icinga_web <  /usr/share/doc/icinga-web-<version>/schema/mysql.sql
1405
1406 Icinga Web requires the IDO feature as database backend using MySQL or PostgreSQL.
1407 Enable that feature, e.g. for MySQL.
1408
1409     # icinga2 feature enable ido-mysql
1410
1411 If you've changed your default credentials you may either create a read-only user
1412 or use the credentials defined in the IDO feature for Icinga Web backend configuration.
1413 Edit `databases.xml` accordingly and clear the cache afterwards. Further details can be
1414 found in the [Icinga Web documentation](http://docs.icinga.org/latest/en/icinga-web-config.html).
1415
1416     # vim /etc/icinga-web/conf.d/databases.xml
1417
1418     # icinga-web-clearcache
1419
1420 Additionally you need to enable the `command` feature for sending [external commands](#external-commands):
1421
1422     # icinga2 feature enable command
1423
1424 In order for commands to work you will need to [setup the external command pipe](#setting-up-external-command-pipe).
1425
1426 Then edit the Icinga Web configuration for sending commands in `/etc/icinga-web/conf.d/access.xml`
1427 (RHEL) or `/etc/icinga-web/access.xml` (SUSE) setting the command pipe path
1428 to the default used in Icinga 2. Make sure to clear the cache afterwards.
1429
1430     # vim /etc/icinga-web/conf.d/access.xml
1431
1432                 <write>
1433                     <files>
1434                         <resource name="icinga_pipe">/var/run/icinga2/cmd/icinga2.cmd</resource>
1435                     </files>
1436                 </write>
1437
1438     # icinga-web-clearcache
1439
1440 > **Note**
1441 >
1442 > The path to the Icinga Web `clearcache` script may differ. Please check the
1443 > [Icinga Web documentation](https://docs.icinga.org) for details.
1444
1445 #### <a id="icinga-web-debian-notes"></a> Icinga Web on Debian systems
1446
1447 Since Icinga Web `1.11.1-2` the IDO auto-configuration has been moved into
1448 additional packages on Debian and Ubuntu.
1449
1450 The package `icinga-web` no longer configures the IDO connection. You must now
1451 use one of the config packages:
1452
1453  - `icinga-web-config-icinga2-ido-mysql`
1454  - `icinga-web-config-icinga2-ido-pgsql`
1455
1456 These packages take care of setting up the [DB IDO](#configuring-db-ido) configuration,
1457 enabling the external command pipe for Icinga Web and depend on
1458 the corresponding packages of Icinga 2.
1459
1460 Please read the `README.Debian` files for details and advanced configuration:
1461
1462  - `/usr/share/doc/icinga-web/README.Debian`
1463  - `/usr/share/doc/icinga-web-config-icinga2-ido-mysql/README.Debian`
1464  - `/usr/share/doc/icinga-web-config-icinga2-ido-pgsql/README.Debian`
1465
1466 When changing Icinga Web configuration files make sure to clear the config cache:
1467
1468     # /usr/lib/icinga-web/bin/clearcache.sh
1469
1470 > **Note**
1471 >
1472 > If you are using an older version of Icinga Web, install it like this and adapt
1473 > the configuration manually as shown in [the RPM notes](#icinga-web-rpm-notes):
1474 >
1475 > `apt-get install --no-install-recommends icinga-web`
1476
1477 #### <a id="setting-up-icinga-web-summary"></a> Setting Up Icinga Web Summary
1478
1479 Verify that your Icinga 1.x Web works by browsing to your Web installation URL:
1480
1481   Distribution  | URL                                                         | Default Login
1482   --------------|-------------------------------------------------------------|--------------------------
1483   Debian        | [http://localhost/icinga-web](http://localhost/icinga-web)  | asked during installation
1484   all others    | [http://localhost/icinga-web](http://localhost/icinga-web)  | root/password
1485
1486 For further information on configuration, troubleshooting and interface documentation
1487 please check the official [Icinga 1.x user interface documentation](http://docs.icinga.org/latest/en/ch06.html).
1488
1489
1490 ### <a id="setting-up-icingaweb2"></a> Setting up Icinga Web 2
1491
1492 Icinga Web 2 will support `DB IDO` or `Livestatus` as backends.
1493
1494 Using DB IDO as backend, you need to install and configure the [DB IDO backend](#configuring-db-ido).
1495 Once finished, you can enable the feature for DB IDO MySQL:
1496
1497     # icinga2 feature enable ido-mysql
1498
1499 Furthermore [external commands](#external-commands) are supported through the external
1500 command pipe.
1501
1502     # icinga2 feature enable command
1503
1504 In order for commands to work you will need to [setup the external command pipe](#setting-up-external-command-pipe).
1505
1506 Please consult the INSTALL documentation shipped with `Icinga Web 2` for
1507 further instructions on how to install Icinga Web 2 and to configure
1508 backends, resources and instances.
1509
1510 > **Note**
1511 >
1512 > Icinga Web 2 is still under heavy development. Rather than installing it
1513 > yourself you should consider testing it using the available
1514 > [Vagrant demo VM](https://github.com/icinga/icinga-vagrant).
1515
1516 Check the [Icinga website](https://www.icinga.org) for release schedules,
1517 blog updates and more.
1518
1519
1520 ### <a id="additional-visualization"></a> Additional visualization
1521
1522 There are many visualization addons which can be used with Icinga 2.
1523
1524 Some of the more popular ones are [PNP](#addons-graphing-pnp), [inGraph](#addons-graphing-pnp)
1525 (graphing performance data), [Graphite](#addons-graphing-pnp), and
1526 [NagVis](#addons-visualization-nagvis) (network maps).
1527
1528
1529 ## <a id="configuration-tools"></a> Configuration Tools
1530
1531 If you require your favourite configuration tool to export Icinga 2 configuration, please get in
1532 touch with their developers. The Icinga project does not provide a configuration web interface
1533 or similar.
1534
1535 > **Tip**
1536 >
1537 > Get to know the new configuration format and the advanced [apply](#using-apply) rules and
1538 > use [syntax highlighting](#configuration-syntax-highlighting) in vim/nano.
1539
1540 If you're looking for puppet manifests, chef cookbooks, ansible recipes, etc - we're happy
1541 to integrate them upstream, so please get in touch at [https://support.icinga.org](https://support.icinga.org).
1542
1543 These tools are in development and require feedback and tests:
1544
1545 * [Ansible Roles](https://github.com/Icinga/icinga2-ansible)
1546 * [Puppet Module](https://github.com/Icinga/puppet-icinga2)
1547
1548 ## <a id="configuration-syntax-highlighting"></a> Configuration Syntax Highlighting
1549
1550 Icinga 2 ships configuration examples for syntax highlighting using the `vim` and `nano` editors.
1551 The RHEL, SUSE and Debian package `icinga2-common` install these files into
1552 `/usr/share/*/icinga2-common/syntax`. Sources provide these files in `tools/syntax`.
1553
1554 ### <a id="configuration-syntax-highlighting-vim"></a> Configuration Syntax Highlighting using Vim
1555
1556 Create a new local vim configuration storage, if not already existing.
1557 Edit `vim/ftdetect/icinga2.vim` if your paths to the Icinga 2 configuration
1558 differ.
1559
1560     $ PREFIX=~/.vim
1561     $ mkdir -p $PREFIX/{syntax,ftdetect}
1562     $ cp vim/syntax/icinga2.vim $PREFIX/syntax/
1563     $ cp vim/ftdetect/icinga2.vim $PREFIX/ftdetect/
1564
1565 Test it:
1566
1567     $ vim /etc/icinga2/conf.d/templates.conf
1568
1569 ### <a id="configuration-syntax-highlighting-nano"></a> Configuration Syntax Highlighting using Nano
1570
1571 Copy the `/etc/nanorc` sample file to your home directory. Create the `/etc/nano` directory
1572 and copy the provided `icinga2.nanorc` into it.
1573
1574     $ cp /etc/nanorc ~/.nanorc
1575
1576     # mkdir -p /etc/nano
1577     # cp icinga2.nanorc /etc/nano/
1578
1579 Then include the icinga2.nanorc file in your ~/.nanorc by adding the following line:
1580
1581     $ vim ~/.nanorc
1582
1583     ## Icinga 2
1584     include "/etc/nano/icinga2.nanorc"
1585
1586 Test it:
1587
1588     $ nano /etc/icinga2/conf.d/templates.conf
1589
1590
1591 ## <a id="running-icinga2"></a> Running Icinga 2
1592
1593 ### <a id="init-script"></a> Init Script
1594
1595 Icinga 2's init script is installed in `/etc/init.d/icinga2` by default:
1596
1597     # /etc/init.d/icinga2
1598     Usage: /etc/init.d/icinga2 {start|stop|restart|reload|checkconfig|status}
1599
1600   Command             | Description
1601   --------------------|------------------------
1602   start               | The `start` action starts the Icinga 2 daemon.
1603   stop                | The `stop` action stops the Icinga 2 daemon.
1604   restart             | The `restart` action is a shortcut for running the `stop` action followed by `start`.
1605   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.
1606   checkconfig         | The `checkconfig` action checks if the `/etc/icinga2/icinga2.conf` configuration file contains any errors.
1607   status              | The `status` action checks if Icinga 2 is running.
1608
1609 By default the Icinga 2 daemon is running as `icinga` user and group
1610 using the init script. Using Debian packages the user and group are set to `nagios`
1611 for historical reasons.
1612
1613 ### <a id="systemd-service"></a> Systemd Service
1614
1615 Modern distributions (Fedora, OpenSUSE, etc.) already use `Systemd` natively. Enterprise-grade
1616 distributions such as RHEL7 changed to `Systemd` recently. Icinga 2 Packages will install the
1617 service automatically.
1618
1619 The Icinga 2 `Systemd` service can be (re)started, reloaded, stopped and also queried for its current status.
1620
1621     # systemctl status icinga2
1622     icinga2.service - Icinga host/service/network monitoring system
1623        Loaded: loaded (/usr/lib/systemd/system/icinga2.service; disabled)
1624        Active: active (running) since Mi 2014-07-23 13:39:38 CEST; 15s ago
1625       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)
1626       Process: 21674 ExecStartPre=/usr/sbin/icinga2-prepare-dirs /etc/sysconfig/icinga2 (code=exited, status=0/SUCCESS)
1627      Main PID: 21727 (icinga2)
1628        CGroup: /system.slice/icinga2.service
1629                └─21727 /usr/sbin/icinga2 -c /etc/icinga2/icinga2.conf -d -e /var/log/icinga2/error.log -u icinga -g icinga --no-stack-rlimit
1630
1631     Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 309 Service(s).
1632     Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 1 User(s).
1633     Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 15 Notification(s).
1634     Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 4 ScheduledDowntime(s).
1635     Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 1 UserGroup(s).
1636     Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 1 IcingaApplication(s).
1637     Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 8 Dependency(s).
1638     Jul 23 13:39:38 nbmif systemd[1]: Started Icinga host/service/network monitoring system.
1639
1640 `Systemd` supports the following command actions:
1641
1642   Command             | Description
1643   --------------------|------------------------
1644   start               | The `start` action starts the Icinga 2 daemon.
1645   stop                | The `stop` action stops the Icinga 2 daemon.
1646   restart             | The `restart` action is a shortcut for running the `stop` action followed by `start`.
1647   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.
1648   status              | The `status` action checks if Icinga 2 is running.
1649   enable              | The `enable` action enables the service being started at system boot time (similar to `chkconfig`)
1650
1651 If you're stuck with configuration errors, you can manually invoke the [configuration validation](#config-validation).
1652
1653     # systemctl enable icinga2
1654
1655     # systemctl restart icinga2
1656     Job for icinga2.service failed. See 'systemctl status icinga2.service' and 'journalctl -xn' for details.
1657
1658
1659
1660 ### <a id="cli-commands"></a> Icinga 2 CLI Commands
1661
1662 Icinga 2 ships its own integrated cli commands supporting bash-autocompletion.
1663
1664 These cli commands will allow you to use certain functionality
1665 provided by and around the Icinga 2 daemon.
1666
1667 > **Note**
1668 >
1669 > The cli commands are available in Icinga 2 starting with *2.2*.
1670
1671 Each cli command provides its own help and usage information, so please
1672 make sure to always run them withthe  `--help` parameter.
1673
1674 Run `icinga2` without any arguments (or using `--help`) to get a list of
1675 all available global options.
1676
1677     # icinga2
1678
1679     icinga2 - The Icinga 2 network monitoring daemon (version: v2.1.1-299-gf695275)
1680
1681     Usage:
1682       icinga2 <command> [<arguments>]
1683
1684     Supported commands:
1685       * daemon (starts Icinga 2)
1686       * feature disable (disables specified feature)
1687       * feature enable (enables specified feature)
1688       * feature list (lists all enabled features)
1689       * node add (add node)
1690       * node blacklist add (adds a new blacklist filter)
1691       * node blacklist list (lists all blacklist filters)
1692       * node blacklist remove (removes a blacklist filter)
1693       * node list (lists all nodes)
1694       * node remove (removes node)
1695       * node set (set node attributes)
1696       * node setup (set up node)
1697       * node update-config (update node config)
1698       * node whitelist add (adds a new whitelist filter)
1699       * node whitelist list (lists all whitelist filters)
1700       * node whitelist remove (removes a whitelist filter)
1701       * node wizard (wizard for node setup)
1702       * object list (lists all objects)
1703       * pki new-ca (sets up a new CA)
1704       * pki new-cert (creates a new CSR)
1705       * pki request (requests a certificate)
1706       * pki save-cert (saves another Icinga 2 instance's certificate)
1707       * pki sign-csr (signs a CSR)
1708       * pki ticket (generates a ticket)
1709       * repository clear-changes (clear uncommitted repository changes)
1710       * repository commit (commit repository changes)
1711       * repository endpoint add (adds a new Endpoint object)
1712       * repository endpoint list (lists all Endpoint objects)
1713       * repository endpoint remove (removes a Endpoint object)
1714       * repository host add (adds a new Host object)
1715       * repository host list (lists all Host objects)
1716       * repository host remove (removes a Host object)
1717       * repository service add (adds a new Service object)
1718       * repository service list (lists all Service objects)
1719       * repository service remove (removes a Service object)
1720       * repository zone add (adds a new Zone object)
1721       * repository zone list (lists all Zone objects)
1722       * repository zone remove (removes a Zone object)
1723       * variable get (gets a variable)
1724       * variable list (lists all variables)
1725
1726     Global options:
1727       -h [ --help ]          show this help message
1728       -V [ --version ]       show version information
1729       --color                use VT100 color codes even when stdout is not a
1730                              terminal
1731       -D [ --define ] arg    define a constant
1732       -l [ --library ] arg   load a library
1733       -I [ --include ] arg   add include search directory
1734       -x [ --log-level ] arg specify the log level for the console log
1735
1736     Command options:
1737
1738     Report bugs at <https://dev.icinga.org/>
1739     Icinga home page: <http://www.icinga.org/>
1740
1741
1742 #### <a id="cli-commands-autocompletion"></a> Icinga 2 CLI Bash Autocompletion
1743
1744 Bash Auto-Completion (pressing `<TAB>`) is provided only for the corresponding context.
1745
1746 While `--config` will suggest and auto-complete files and directories on disk,
1747 `feature enable` will only suggest disabled features. `repository` will know
1748 about object specific attributes, and so on. Try it yourself.
1749
1750 RPM and Debian packages install the bash completion files into
1751 `/etc/bash_completion.d/icinga2`.
1752
1753 You will need to install the `bash-completion` package if not already installed.
1754
1755 RHEL/CentOS/Fedora:
1756     # yum install bash-completion
1757
1758 SUSE:
1759     # zypper install bash-completion
1760
1761 Debian/Ubuntu:
1762     # apt-get install bash-completion
1763
1764 #### <a id="cli-commands-global-options"></a> Icinga 2 CLI Global Options
1765
1766 ##### Libraries
1767
1768 Instead of loading libraries using the [`library` config directive](#library)
1769 you can also use the `--library` command-line option.
1770
1771 ##### Constants
1772
1773 [Global constants](#global-constants) can be set using the `--define` command-line option.
1774
1775 ##### Config Include Path
1776
1777 When including files you can specify that the include search path should be
1778 checked. You can do this by putting your configuration file name in angle
1779 brackets like this:
1780
1781     include <test.conf>
1782
1783 This would cause Icinga 2 to search its include path for the configuration file
1784 `test.conf`. By default the installation path for the Icinga Template Library
1785 is the only search directory.
1786
1787 Using the `--include` command-line option additional search directories can be
1788 added.
1789
1790
1791
1792 #### <a id="cli-command-daemon"></a> Cli command: Daemon
1793
1794 The cli command `daemon` provides the functionality to start/stop Icinga 2.
1795 Furthermore it provides the [configuration validation](#config-validation).
1796
1797     # icinga2 daemon --help
1798     icinga2 - The Icinga 2 network monitoring daemon (version: v2.1.1-299-gf695275)
1799
1800     Usage:
1801       icinga2 daemon [<arguments>]
1802
1803     Starts Icinga 2.
1804
1805     Global options:
1806       -h [ --help ]          show this help message
1807       -V [ --version ]       show version information
1808       --color                use VT100 color codes even when stdout is not a
1809                              terminal
1810       -D [ --define ] arg    define a constant
1811       -l [ --library ] arg   load a library
1812       -I [ --include ] arg   add include search directory
1813       -x [ --log-level ] arg specify the log level for the console log
1814
1815     Command options:
1816       -c [ --config ] arg   parse a configuration file
1817       -z [ --no-config ]    start without a configuration file
1818       -C [ --validate ]     exit after validating the configuration
1819       -e [ --errorlog ] arg log fatal errors to the specified log file (only works
1820                             in combination with --daemonize)
1821       -d [ --daemonize ]    detach from the controlling terminal
1822
1823     Report bugs at <https://dev.icinga.org/>
1824     Icinga home page: <http://www.icinga.org/>
1825
1826 ##### Config Files
1827
1828 Using the `--config` option you can specify one or more configuration files.
1829 Config files are processed in the order they're specified on the command-line.
1830
1831 When no configuration file is specified and the `--no-config` is not used
1832 Icinga 2 automatically falls back to using the configuration file
1833 `SysconfDir + "/icinga2/icinga2.conf"` (where SysconfDir is usually `/etc`).
1834
1835 ##### Config Validation
1836
1837 The `--validate` option can be used to check if your configuration files
1838 contain errors. If any errors are found the exit status is 1, otherwise 0
1839 is returned. More details in the [configuration validation](#config-validation) chapter.
1840
1841
1842 #### <a id="cli-command-feature"></a> Cli command: Feature
1843
1844 The cli commands for `enable` and `disable` feature support bash auto-completion
1845 and will only suggest features for the corresponding context. Like disabling a
1846 feature will only bring up all enabled features.
1847
1848     # icinga2 feature disable <tab>
1849     checker       --color       --define      --help        --include     --library     --log-level   mainlog       notification  --version
1850
1851     # icinga2 feature enable <tab>
1852     api           command       debuglog      graphite      icingastatus  ido-pgsql     --library     --log-level   statusdata    --version
1853     --color       compatlog     --define      --help        ido-mysql     --include     livestatus    perfdata      syslog
1854
1855 #### <a id="cli-command-node"></a> Cli command: Node
1856
1857 Provides the functionality to install and manage master and client
1858 nodes in a [remote monitoring ](#icinga2-remote-client-monitoring) or
1859 [distributed cluster](#distributed-monitoring-high-availability) scenario.
1860
1861
1862     # icinga2 node --help
1863     icinga2 - The Icinga 2 network monitoring daemon (version: v2.1.1-299-gf695275)
1864
1865     Usage:
1866       icinga2 <command> [<arguments>]
1867
1868     Supported commands:
1869       * node add (add node)
1870       * node blacklist add (adds a new blacklist filter)
1871       * node blacklist list (lists all blacklist filters)
1872       * node blacklist remove (removes a blacklist filter)
1873       * node list (lists all nodes)
1874       * node remove (removes node)
1875       * node set (set node attributes)
1876       * node setup (set up node)
1877       * node update-config (update node config)
1878       * node whitelist add (adds a new whitelist filter)
1879       * node whitelist list (lists all whitelist filters)
1880       * node whitelist remove (removes a whitelist filter)
1881       * node wizard (wizard for node setup)
1882
1883     Global options:
1884       -h [ --help ]          show this help message
1885       -V [ --version ]       show version information
1886       --color                use VT100 color codes even when stdout is not a
1887                              terminal
1888       -D [ --define ] arg    define a constant
1889       -l [ --library ] arg   load a library
1890       -I [ --include ] arg   add include search directory
1891       -x [ --log-level ] arg specify the log level for the console log
1892
1893     Command options:
1894
1895     Report bugs at <https://dev.icinga.org/>
1896     Icinga home page: <http://www.icinga.org/>
1897
1898
1899 #### <a id="cli-command-object"></a> Cli command: Object
1900
1901 The `object` cli command can be used to list all configuration objects and their
1902 attributes. The command also shows where each of the attributes was modified.
1903 That way you can also identify which objects have been created from your [apply rules](#apply).
1904
1905 More information can be found in the [troubleshooting](#list-configuration-objects) section.
1906
1907     # icinga2 object --help
1908     icinga2 - The Icinga 2 network monitoring daemon (version: v2.1.1-299-gf695275)
1909
1910     Usage:
1911       icinga2 <command> [<arguments>]
1912
1913     Supported commands:
1914       * object list (lists all objects)
1915
1916     Global options:
1917       -h [ --help ]          show this help message
1918       -V [ --version ]       show version information
1919       --color                use VT100 color codes even when stdout is not a
1920                              terminal
1921       -D [ --define ] arg    define a constant
1922       -l [ --library ] arg   load a library
1923       -I [ --include ] arg   add include search directory
1924       -x [ --log-level ] arg specify the log level for the console log
1925
1926     Command options:
1927
1928     Report bugs at <https://dev.icinga.org/>
1929     Icinga home page: <http://www.icinga.org/>
1930
1931
1932
1933 #### <a id="cli-command-pki"></a> Cli command: Pki
1934
1935 Provides the cli commands to
1936
1937 * generate a new local CA
1938 * generate a new CSR or self-signed certificate
1939 * sign a CSR and return a certificate
1940 * save a master certificate manually
1941 * request a signed certificate from the master
1942 * generate a new ticket for the client setup
1943
1944 This functionality is used by the [node setup/wizard](#cli-command-pki) cli commands too.
1945
1946     # icinga2 pki --help
1947     icinga2 - The Icinga 2 network monitoring daemon (version: v2.1.1-299-gf695275)
1948
1949     Usage:
1950       icinga2 <command> [<arguments>]
1951
1952     Supported commands:
1953       * pki new-ca (sets up a new CA)
1954       * pki new-cert (creates a new CSR)
1955       * pki request (requests a certificate)
1956       * pki save-cert (saves another Icinga 2 instance's certificate)
1957       * pki sign-csr (signs a CSR)
1958       * pki ticket (generates a ticket)
1959
1960     Global options:
1961       -h [ --help ]          show this help message
1962       -V [ --version ]       show version information
1963       --color                use VT100 color codes even when stdout is not a
1964                              terminal
1965       -D [ --define ] arg    define a constant
1966       -l [ --library ] arg   load a library
1967       -I [ --include ] arg   add include search directory
1968       -x [ --log-level ] arg specify the log level for the console log
1969
1970     Command options:
1971
1972     Report bugs at <https://dev.icinga.org/>
1973     Icinga home page: <http://www.icinga.org/>
1974
1975
1976 #### <a id="cli-command-repository"></a> Cli command: Repository
1977
1978 Provides the functionality to manage the Icinga 2 configuration repository in
1979 `/etc/icinga2/repository.d`. All changes are logged and must be committed or
1980 cleared after review.
1981
1982
1983 > **Note**
1984 >
1985 > The cli command `repository` only supports basic configuration manipulation (add, remove)
1986 > and a limited set of objects required for the [remote client] integration. Future
1987 > versions will support more options (set, etc.).
1988 >
1989 > Please check the Icinga 2 development roadmap for updates.
1990
1991
1992     # icinga2 repository --help
1993     icinga2 - The Icinga 2 network monitoring daemon (version: v2.1.1-299-gf695275)
1994
1995     Usage:
1996       icinga2 <command> [<arguments>]
1997
1998     Supported commands:
1999       * repository clear-changes (clear uncommitted repository changes)
2000       * repository commit (commit repository changes)
2001       * repository endpoint add (adds a new Endpoint object)
2002       * repository endpoint list (lists all Endpoint objects)
2003       * repository endpoint remove (removes a Endpoint object)
2004       * repository host add (adds a new Host object)
2005       * repository host list (lists all Host objects)
2006       * repository host remove (removes a Host object)
2007       * repository service add (adds a new Service object)
2008       * repository service list (lists all Service objects)
2009       * repository service remove (removes a Service object)
2010       * repository zone add (adds a new Zone object)
2011       * repository zone list (lists all Zone objects)
2012       * repository zone remove (removes a Zone object)
2013
2014     Global options:
2015       -h [ --help ]          show this help message
2016       -V [ --version ]       show version information
2017       --color                use VT100 color codes even when stdout is not a
2018                              terminal
2019       -D [ --define ] arg    define a constant
2020       -l [ --library ] arg   load a library
2021       -I [ --include ] arg   add include search directory
2022       -x [ --log-level ] arg specify the log level for the console log
2023
2024     Command options:
2025
2026     Report bugs at <https://dev.icinga.org/>
2027     Icinga home page: <http://www.icinga.org/>
2028
2029
2030
2031 #### <a id="cli-command-variable"></a> Cli command: Variable
2032
2033 Lists all configured variables (constants) in a similar fasion like [object list](#cli-command-object).
2034
2035     # icinga2 variable --help
2036     icinga2 - The Icinga 2 network monitoring daemon (version: v2.1.1-299-gf695275)
2037
2038     Usage:
2039       icinga2 <command> [<arguments>]
2040
2041     Supported commands:
2042       * variable get (gets a variable)
2043       * variable list (lists all variables)
2044
2045     Global options:
2046       -h [ --help ]          show this help message
2047       -V [ --version ]       show version information
2048       --color                use VT100 color codes even when stdout is not a
2049                              terminal
2050       -D [ --define ] arg    define a constant
2051       -l [ --library ] arg   load a library
2052       -I [ --include ] arg   add include search directory
2053       -x [ --log-level ] arg specify the log level for the console log
2054
2055     Command options:
2056
2057     Report bugs at <https://dev.icinga.org/>
2058     Icinga home page: <http://www.icinga.org/>
2059
2060
2061
2062
2063
2064 ### <a id="features"></a> Enabling/Disabling Features
2065
2066 Icinga 2 provides configuration files for some commonly used features. These
2067 are installed in the `/etc/icinga2/features-available` directory and can be
2068 enabled and disabled using the `icinga2 feature enable` and `icinga2 feature disable`
2069 [cli commands](#cli-command-feature), respectively.
2070
2071 The `icinga2 feature enable` cli command creates symlinks in the
2072 `/etc/icinga2/features-enabled` directory which is included by default
2073 in the example configuration file.
2074
2075 You can view a list of enabled and disabled features:
2076
2077     # icinga2 feature list
2078     Disabled features: api command compatlog debuglog graphite icingastatus ido-mysql ido-pgsql livestatus notification perfdata statusdata syslog
2079     Enabled features: checker mainlog notification
2080
2081 Using the `icinga2 feature enable` command you can enable features:
2082
2083     # icinga2 feature enable graphite
2084     Enabling feature graphite. Make sure to restart Icinga 2 for these changes to take effect.
2085
2086
2087 You can disable features using the `icinga2 feature disable` command:
2088
2089     # icinga2 feature disable ido-mysql livestatus
2090     Disabling feature ido-mysql. Make sure to restart Icinga 2 for these changes to take effect.
2091     Disabling feature livestatus. Make sure to restart Icinga 2 for these changes to take effect.
2092
2093
2094 The `icinga2 feature enable` and `icinga2 feature disable` commands do not
2095 restart Icinga 2. You will need to restart Icinga 2 using the init script
2096 after enabling or disabling features.
2097
2098
2099
2100 ### <a id="config-validation"></a> Configuration Validation
2101
2102 Once you've edited the configuration files make sure to tell Icinga 2 to validate
2103 the configuration changes. Icinga 2 will log any configuration error including
2104 a hint on the file, the line number and the affected configuration line itself.
2105
2106 The following example creates an apply rule without any `assign` condition.
2107
2108     apply Service "5872-ping4" {
2109       import "generic-service"
2110       check_command = "ping4"
2111       //assign where match("5872-*", host.name)
2112     }
2113
2114 Validate the configuration with the init script option `checkconfig`:
2115
2116     # /etc/init.d/icinga2 checkconfig
2117
2118 > **Note**
2119 >
2120 > Using [Systemd](#systemd-service) you need to manually validate the configuration using
2121 > the cli command below.
2122
2123 Or manually passing the `-C` argument:
2124
2125     # /usr/sbin/icinga2 daemon -c /etc/icinga2/icinga2.conf -C
2126
2127     [2014-05-22 17:07:25 +0200] critical/ConfigItem: Location:
2128     /etc/icinga2/conf.d/tests/5872.conf(5): }
2129     /etc/icinga2/conf.d/tests/5872.conf(6):
2130     /etc/icinga2/conf.d/tests/5872.conf(7): apply Service "5872-ping4" {
2131                                             ^^^^^^^^^^^^^
2132     /etc/icinga2/conf.d/tests/5872.conf(8):   import "test-generic-service"
2133     /etc/icinga2/conf.d/tests/5872.conf(9):   check_command = "ping4"
2134
2135     Config error: 'apply' is missing 'assign'
2136     [2014-05-22 17:07:25 +0200] critical/ConfigItem: 1 errors, 0 warnings.
2137     Icinga 2 detected configuration errors.
2138
2139 > **Tip**
2140 >
2141 > Icinga 2 will automatically detect the default path for `icinga2.conf`
2142 > in `SysconfDir + /icinga2/icinga2.conf` and you can safely omit this parameter.
2143 >
2144 > `# icinga2 daemon -C`
2145
2146 If you encouter errors during configuration validation, please make sure
2147 to read the [troubleshooting](#troubleshooting) chapter.
2148
2149 You can also use the [cli command](#cli-command-object) `icinga2 object list`
2150 after validation passes to analyze object attributes, inheritance or created
2151 objects by apply rules.
2152 Find more on troubleshooting with `object list` in [this chapter](#list-configuration-objects).
2153
2154 Example filtered by `Service` objects with the name `ping*`:
2155
2156     # icinga2 object list --type Service --name *ping*
2157     Object 'nbmif.int.netways.de!ping4' of type 'Service':
2158       * __name = 'nbmif.int.netways.de!ping4'
2159       * check_command = 'ping4'
2160         % = modified in '/etc/icinga2/conf.d/services.conf', lines 17:3-17:25
2161       * check_interval = 60
2162         % = modified in '/etc/icinga2/conf.d/templates.conf', lines 28:3-28:21
2163       * host_name = 'nbmif.int.netways.de'
2164         % = modified in '/etc/icinga2/conf.d/services.conf', lines 14:1-14:21
2165       * max_check_attempts = 3
2166         % = modified in '/etc/icinga2/conf.d/templates.conf', lines 27:3-27:24
2167       * name = 'ping4'
2168         % = modified in '/etc/icinga2/conf.d/services.conf', lines 14:1-14:21
2169       * retry_interval = 30
2170         % = modified in '/etc/icinga2/conf.d/templates.conf', lines 29:3-29:22
2171       * templates = [ 'ping4', 'generic-service' ]
2172         % += modified in '/etc/icinga2/conf.d/services.conf', lines 14:1-14:21
2173         % += modified in '/etc/icinga2/conf.d/templates.conf', lines 26:1-30:1
2174       * type = 'Service'
2175       * vars
2176         % += modified in '/etc/icinga2/conf.d/services.conf', lines 18:3-18:19
2177         * sla = '24x7'
2178           % = modified in '/etc/icinga2/conf.d/services.conf', lines 18:3-18:19
2179
2180
2181
2182 ### <a id="config-change-reload"></a> Reload on Configuration Changes
2183
2184 Everytime you have changed your configuration you should first tell Icinga 2
2185 to [validate](#config-validation). If there are no validation errors you can
2186 safely reload the Icinga 2 daemon.
2187
2188     # /etc/init.d/icinga2 reload
2189
2190 > **Note**
2191 >
2192 > The `reload` action will send the `SIGHUP` signal to the Icinga 2 daemon
2193 > which will validate the configuration in a separate process and not stop
2194 > the other events like check execution, notifications, etc.
2195 >
2196 > Details can be found [here](#differences-1x-2-real-reload).
2197
2198
2199 ## <a id="vagrant"></a> Vagrant Demo VM
2200
2201 The Icinga Vagrant Git repository contains support for [Vagrant](http://docs.vagrantup.com/v2/)
2202 with VirtualBox. Please note that Vagrant version `1.0.x` is not supported. At least
2203 version `1.2.x` is required.
2204
2205 In order to build the Vagrant VM first you will have to check out
2206 the Git repository:
2207
2208     $ git clone git://git.icinga.org/icinga-vagrant.git
2209
2210 For Icinga 2 there are currently two scenarios available:
2211
2212 * `icinga2x` bringing up a standalone box with Icinga 2
2213 * `icinga2x-cluster` setting up two virtual machines in a master/slave cluster
2214
2215 > **Note**
2216 >
2217 > Please consult the `README.md` file for each project for further installation
2218 > details at [https://github.com/Icinga/icinga-vagrant]
2219
2220 Once you have checked out the Git repository navigate to your required
2221 vagrant box and build the VM using the following command:
2222
2223     $ vagrant up
2224
2225 The Vagrant VMs are based on CentOS 6.x and are using the official
2226 Icinga 2 RPM snapshot packages from `packages.icinga.org`. The check
2227 plugins are installed from EPEL providing RPMs with sources from the
2228 Monitoring Plugins project.