granicus.if.org Git - icinga2/blob - doc/2.1-setting-up-icinga-2.md

   1 ## <a id="setting-up-icinga2"></a> Setting up Icinga 2
   2
   3 First of all you will have to install Icinga 2. The preferred way of doing this
   4 is to use the official Debian or RPM package repositories depending on which
   5 operating system and distribution you are running.
   6
   7   Distribution            | Repository URL
   8   ------------------------|---------------------------
   9   Debian                  | http://packages.icinga.org/debian/
  10   Ubuntu                  | http://packages.icinga.org/ubuntu/
  11   RHEL/CentOS             | http://packages.icinga.org/epel/
  12   OpenSUSE                | http://packages.icinga.org/openSUSE/
  13   SLES                    | http://packages.icinga.org/SUSE/
  14
  15 Packages for distributions other than the ones listed above may also be
  16 available. Please check http://packages.icinga.org/ to see if packages
  17 are available for your favourite distribution.
  18
  19 The packages for RHEL/CentOS 5 depend on other packages which are distributed
  20 as part of the [EPEL repository](http://fedoraproject.org/wiki/EPEL). Please
  21 make sure to enable this repository.
  22
  23 You can install Icinga 2 by using your distribution's package manager
  24 to install the `icinga2` package.
  25
  26 On RHEL/CentOS and SLES you will need to use `chkconfig` to enable the
  27 `icinga2` service. You can manually start Icinga 2 using `/etc/init.d/icinga2 start`.
  28
  29 Some parts of Icinga 2's functionality are available as separate packages:
  30
  31   Name                    | Description
  32   ------------------------|--------------------------------
  33   icinga2-ido-mysql       | IDO provider module for MySQL
  34   icinga2-ido-pgsql       | IDO provider module for PostgreSQL
  35
  36 In case you're running a distribution for which Icinga 2 packages are
  37 not yet available you will have to use the release tarball which you
  38 can download from the [Icinga website](https://www.icinga.org/). The
  39 release tarballs contain an `INSTALL` file with further instructions.
  40
  41 ### <a id="installation-paths"></a> Installation Paths
  42
  43 By default Icinga 2 uses the following files and directories:
  44
  45   Path                                | Description
  46   ------------------------------------|------------------------------------
  47   /etc/icinga2                        | Contains Icinga 2 configuration files.
  48   /etc/init.d/icinga2                 | The Icinga 2 init script.
  49   /usr/bin/icinga2-*                  | Migration and certificate build scripts.
  50   /usr/sbin/icinga2*                  | The Icinga 2 binary and feature enable/disable scripts.
  51   /usr/share/doc/icinga2              | Documentation files that come with Icinga 2.
  52   /usr/share/icinga2/itl              | The Icinga Template Library.
  53   /var/run/icinga2                    | PID file.
  54   /var/run/icinga2/cmd                | Command pipe and Livestatus socket.
  55   /var/cache/icinga2                  | status.dat/objects.cache.
  56   /var/spool/icinga2                  | Used for performance data spool files.
  57   /var/lib/icinga2                    | Icinga 2 state file, cluster feature replay log and configuration files.
  58   /var/log/icinga2                    | Log file location and compat/ directory for the CompatLogger feature.
  59
  60 ### <a id="icinga2-conf"></a> icinga2.conf
  61
  62 An example configuration file is installed for you in `/etc/icinga2/icinga2.conf`.
  63
  64 Here's a brief description of the example configuration:
  65
  66     /**
  67      * Icinga 2 configuration file
  68      * - this is where you define settings for the Icinga application including
  69      * which hosts/services to check.
  70      *
  71      * For an overview of all available configuration options please refer
  72      * to the documentation that is distributed as part of Icinga 2.
  73      */
  74
  75 Icinga 2 supports [C/C++-style comments](#comments).
  76
  77     /**
  78      * The constants.conf defines global constants.
  79      */
  80     include "constants.conf"
  81
  82 The `include` directive can be used to include other files.
  83
  84     /**
  85      * The Icinga Template Library (ITL) provides a number of useful templates
  86      * and command definitions.
  87      */
  88     include <itl/itl.conf>
  89
  90     /**
  91      * The features-available directory contains a number of configuration
  92      * files for features which can be enabled and disabled using the
  93      * icinga2-enable-feature / icinga2-disable-feature tools. These two tools work by creating
  94      * and removing symbolic links in the features-enabled directory.
  95      */
  96     include "features-enabled/*.conf"
  97
  98 This include directive takes care of including the configuration files for all
  99 the features which have been enabled with `icinga2-enable-feature`. See
 100 [Enabling/Disabling Features](#features) for more details.
 101
 102     /**
 103      * Although in theory you could define all your objects in this file
 104      * the preferred way is to create separate directories and files in the conf.d
 105      * directory. Each of these files must have the file extension ".conf".
 106      */
 107     include_recursive "conf.d"
 108
 109 You can put your own configuration files in the `conf.d` directory. This
 110 directive makes sure that all of your own configuration files are included.
 111
 112 ### <a id="constants-conf"></a> constants.conf
 113
 114 The `constants.conf` configuration file can be used to define global constants:
 115
 116     /**
 117      * This file defines global constants which can be used in
 118      * the other configuration files. At a minimum the
 119      * PluginDir constant should be defined.
 120      */
 121
 122     const PluginDir = "/usr/lib/nagios/plugins"
 123
 124 ### <a id="localhost-conf"></a> localhost.conf
 125
 126 The `conf.d/localhost.conf` file contains our first host definition:
 127
 128     /**
 129      * A host definition. You can create your own configuration files
 130      * in the conf.d directory (e.g. one per host). By default all *.conf
 131      * files in this directory are included.
 132      */
 133     object Host "localhost" {
 134       import "linux-server"
 135
 136       vars.address = "127.0.0.1"
 137       vars.address6 = "::1"
 138     }
 139
 140 This defines the host `localhost`. The `import` keyword is used to import
 141 the `linux-server` template which takes care of setting up the host check
 142 as well as adding the host to the `linux-servers` host group.
 143
 144 The `vars` attribute can be used to define custom attributes which are available
 145 for check and notification commands. Most of the templates in the Icinga
 146 Template Library require an `address` custom attribute.
 147
 148     object Service "icinga" {
 149       import "generic-service"
 150
 151       host_name = "localhost"
 152       check_command = "icinga"
 153     }
 154
 155     object Service "http" {
 156       import "generic-service"
 157
 158       host_name = "localhost"
 159       check_command = "http_ip"
 160     }
 161
 162     object Service "ssh" {
 163       import "generic-service"
 164
 165       host_name = "localhost"
 166       check_command = "ssh"
 167     }
 168
 169     object Service "load" {
 170       import "generic-service"
 171
 172       host_name = "localhost"
 173       check_command = "load"
 174     }
 175
 176     object ScheduledDowntime "backup-downtime" {
 177       import "backup-downtime"
 178
 179       host_name = "localhost"
 180       service_name = "load"
 181     }
 182
 183     object Service "processes" {
 184       import "generic-service"
 185
 186       host_name = "localhost"
 187       check_command = "processes"
 188     }
 189
 190     object Service "users" {
 191       import "generic-service"
 192
 193       host_name = "localhost"
 194       check_command = "users"
 195     }
 196
 197     object Service "disk" {
 198       import "generic-service"
 199
 200       host_name = "localhost"
 201       check_command = "disk"
 202     }
 203
 204 The command objects `icinga`, `http_ip`, `ssh`, `load`, `processes`, `users`
 205 and `disk` are all provided by the Icinga Template Library (ITL) which
 206 we enabled earlier by including the `itl/itl.conf` configuration file.