diff --git a/doc/2-getting-started.md b/doc/2-getting-started.md index a7d908241..c13b41eec 100644 --- a/doc/2-getting-started.md +++ b/doc/2-getting-started.md @@ -14,8 +14,8 @@ and distribution you are running. Distribution | Repository ------------------------|--------------------------- - Debian | [Icinga Repository](http://packages.icinga.org/debian/), [Upstream](https://packages.debian.org/sid/icinga2), [DebMon](http://debmon.org/packages/debmon-wheezy/icinga2) - Ubuntu | [Icinga Repository](http://packages.icinga.org/ubuntu/), [Upstream](https://launchpad.net/ubuntu/+source/icinga2) + Debian | [Upstream](https://packages.debian.org/sid/icinga2), [DebMon](http://debmon.org/packages/debmon-wheezy/icinga2), [Icinga Repository](http://packages.icinga.org/debian/) + Ubuntu | [Upstream](https://launchpad.net/ubuntu/+source/icinga2), [Icinga PPA](https://launchpad.net/~formorer/+archive/ubuntu/icinga), [Icinga Repository](http://packages.icinga.org/ubuntu/) RHEL/CentOS | [Icinga Repository](http://packages.icinga.org/epel/) OpenSUSE | [Icinga Repository](http://packages.icinga.org/openSUSE/), [Server Monitoring Repository](https://build.opensuse.org/package/show/server:monitoring/icinga2) SLES | [Icinga Repository](http://packages.icinga.org/SUSE/) @@ -26,17 +26,69 @@ and distribution you are running. Packages for distributions other than the ones listed above may also be available. Please contact your distribution packagers. -The packages for RHEL/CentOS 5 depend on other packages which are distributed +### Installing Requirements for Icinga 2 + +You need to add the Icinga repository to your package management configuration. +Below is a list with examples for the various distributions. + +Debian (debmon): + # wget -O - http://debmon.org/debmon/repo.key 2>/dev/null | apt-key add - + # cat >/etc/apt/sources.list.d/debmon.list< Installing Icinga 2 You can install Icinga 2 by using your distribution's package manager to install the `icinga2` package. +Debian/Ubuntu: + # apt-get install icinga2 + +RHEL/CentOS/Fedora: + # yum install icinga2 + +SLES/OpenSUSE: + # zypper install icinga2 + On RHEL/CentOS and SLES you will need to use `chkconfig` to enable the -`icinga2` service. You can manually start Icinga 2 using `/etc/init.d/icinga2 start`. +`icinga2` service. You can manually start Icinga 2 using `service icinga2 start`. + + # chkconfig icinga2 on + # service icinga2 start + RHEL/CentOS 7 use [Systemd](#systemd-service) with `systemctl {enable,start} icinga2`. + # systemctl enable icinga2 + # systemctl start icinga2 + Some parts of Icinga 2's functionality are available as separate packages: Name | Description @@ -88,6 +140,92 @@ By default Icinga 2 uses the following files and directories: /var/lib/icinga2 | Icinga 2 state file, cluster feature replay log and configuration files. /var/log/icinga2 | Log file location and compat/ directory for the CompatLogger feature. +## Setting up Check Plugins + +Without plugins Icinga 2 does not know how to check external services. The +[Monitoring Plugins Project](https://www.monitoring-plugins.org/) provides +an extensive set of plugins which can be used with Icinga 2 to check whether +services are working properly. + +The recommended way of installing these standard plugins is to use your +distribution's package manager. + +> **Note** +> +> The `Nagios Plugins` project was renamed to `Monitoring Plugins` +> in January 2014. At the time of this writing some packages are still +> using the old name while some distributions have adopted the new package +> name `monitoring-plugins` already. + +> **Note** +> +> EPEL for RHEL/CentOS 7 is still in beta mode at the time of writing and does +> not provide a `monitoring-plugins` package. You are required to manually install +> them. + +For your convenience here is a list of package names for some of the more +popular operating systems/distributions: + +OS/Distribution | Package Name | Installation Path +-----------------------|--------------------|--------------------------- +RHEL/CentOS (EPEL) | nagios-plugins-all | /usr/lib/nagios/plugins or /usr/lib64/nagios/plugins +Debian | nagios-plugins | /usr/lib/nagios/plugins +FreeBSD | nagios-plugins | /usr/local/libexec/nagios +OS X (MacPorts) | nagios-plugins | /opt/local/libexec + +Depending on which directory your plugins are installed into you may need to +update the global `PluginDir` constant in your Icinga 2 configuration. This macro is used +by the service templates contained in the Icinga Template Library to determine +where to find the plugin binaries. + +### Integrate Additional Plugins + +For some services you may need additional 'check plugins' which are not provided +by the official Monitoring Plugins project. + +All existing Nagios or Icinga 1.x plugins work with Icinga 2. Here's a +list of popular community sites which host check plugins: + +* [MonitoringExchange](https://www.monitoringexchange.org) +* [Icinga Wiki](https://wiki.icinga.org) + +The recommended way of setting up these plugins is to copy them to a common directory +and create an extra global constant, e.g. `CustomPluginDir` in your [constants.conf](#constants-conf) +configuration file: + + # cp check_snmp_int.pl /opt/plugins + # chmod +x /opt/plugins/check_snmp_int.pl + + # cat /etc/icinga2/constants.conf + /** + * This file defines global constants which can be used in + * the other configuration files. At a minimum the + * PluginDir constant should be defined. + */ + + const PluginDir = "/usr/lib/nagios/plugins" + const CustomPluginDir = "/opt/monitoring" + +Prior to using the check plugin with Icinga 2 you should ensure that it is working properly +by trying to run it on the console using whichever user Icinga 2 is running as: + + # su - icinga -s /bin/bash + $ /opt/plugins/check_snmp_int.pl --help + +Additional libraries may be required for some plugins. Please consult the plugin +documentation and/or plugin provided README for installation instructions. + +Each plugin requires a [CheckCommand](#objecttype-checkcommand) object in your +configuration which can be used in the [Service](#objecttype-service) or +[Host](#objecttype-host) object definition. Examples for `CheckCommand` +objects can be found in the [Plugin Check Commands](#plugin-check-commands) shipped +with Icinga 2. +For further information on your monitoring configuration read the +[monitoring basics](#monitoring-basics). + + +## Configuring Icinga 2: First Steps + ### icinga2.conf An example configuration file is installed for you in `/etc/icinga2/icinga2.conf`. @@ -365,84 +503,6 @@ their check commands. Further details on the monitoring configuration can be found in the [monitoring basics](#monitoring-basics) chapter. -## Setting up Check Plugins - -Without plugins -Icinga 2 does not know how to check external services. The -[Monitoring Plugins Project](https://www.monitoring-plugins.org/) provides -an extensive set of plugins which can be used with Icinga 2 to check whether -services are working properly. - -The recommended way of installing these standard plugins is to use your -distribution's package manager. - -> **Note** -> -> The `Nagios Plugins` project was renamed to `Monitoring Plugins` -> in January 2014. At the time of this writing the packages are still -> using the old name. - -For your convenience here is a list of package names for some of the more -popular operating systems/distributions: - -OS/Distribution | Package Name | Installation Path ------------------------|--------------------|--------------------------- -RHEL/CentOS (EPEL) | nagios-plugins-all | /usr/lib/nagios/plugins or /usr/lib64/nagios/plugins -Debian | nagios-plugins | /usr/lib/nagios/plugins -FreeBSD | nagios-plugins | /usr/local/libexec/nagios -OS X (MacPorts) | nagios-plugins | /opt/local/libexec - -Depending on which directory your plugins are installed into you may need to -update the global `PluginDir` constant in your Icinga 2 configuration. This macro is used -by the service templates contained in the Icinga Template Library to determine -where to find the plugin binaries. - -### Integrate Additional Plugins - -For some services you may need additional 'check plugins' which are not provided -by the official Monitoring Plugins project. - -All existing Nagios or Icinga 1.x plugins should work with Icinga 2. Here's a -list of popular community sites which host check plugins: - -* [MonitoringExchange](https://www.monitoringexchange.org) -* [Icinga Wiki](https://wiki.icinga.org) - -The recommended way of setting up these plugins is to copy them to a common directory -and create an extra global constant, e.g. `CustomPluginDir` in your `constants.conf` -configuration file: - - # cp check_snmp_int.pl /opt/plugins - # chmod +x /opt/plugins/check_snmp_int.pl - - # cat /etc/icinga2/constants.conf - /** - * This file defines global constants which can be used in - * the other configuration files. At a minimum the - * PluginDir constant should be defined. - */ - - const PluginDir = "/usr/lib/nagios/plugins" - const CustomPluginDir = "/opt/monitoring" - -Prior to using the check plugin with Icinga 2 you should ensure that it is working properly -by trying to run it on the console using whichever user Icinga 2 is running as: - - # su - icinga -s /bin/bash - $ /opt/plugins/check_snmp_int.pl --help - -Additional libraries may be required for some plugins. Please consult the plugin -documentation and/or plugin provided README for installation instructions. - -Each plugin requires a [CheckCommand](#objecttype-checkcommand) object in your -configuration which can be used in the [Service](#objecttype-service) or -[Host](#objecttype-host) object definition. Examples for `CheckCommand` -objects can be found in the [Plugin Check Commands](#plugin-check-commands) shipped -with Icinga 2. -For further information on your monitoring configuration read the -[monitoring basics](#monitoring-basics). - - ## Configuring DB IDO The DB IDO (Database Icinga Data Output) modules for Icinga 2 take care of exporting @@ -455,8 +515,9 @@ both MySQL and PostgreSQL is implemented. Icinga 2 uses the Icinga 1.x IDOUtils database schema. Icinga 2 requires additional features not yet released with older Icinga 1.x versions. -* Current required schema version: `1.11.6`. - +> **Note** +> +> Please check the [what's new](#whats-new) section for the required schema version. > **Tip** > @@ -464,8 +525,69 @@ features not yet released with older Icinga 1.x versions. > you to do so (for example, [Icinga Web](#setting-up-icinga-web) or [Icinga Web 2](#setting-up-icingaweb2)). > [Icinga Classic UI](#setting-up-icinga-classic-ui) does not use IDO as backend. +### Installing the Database Server + +In order to use DB IDO you need to setup either [MySQL](#installing-database-mysql-server) +or [PostgreSQL](#installing-database-postgresql-server) as supported database server. + +> **Note** +> +> It's up to you whether you choose to install it on the same server where Icinga 2 is running on, +> or on a dedicated database host (or cluster). + +#### Installing MySQL database server + +Debian/Ubuntu: + # apt-get install mysql-server mysql-client + +RHEL/CentOS 5/6: + # yum install mysql-server mysql + # chkconfig mysqld on + # service mysqld start + +RHEL/CentOS 7 and Fedora 20 prefer MariaDB over MySQL: + # yum install mariadb-server mariadb + # systemctl enable mariadb.service + # systemctl start mariadb.service + +SUSE: + # zypper install mysql mysql-client + # chkconfig mysqld on + # service mysqld start + +RHEL based distributions do not automatically set a secure root password. Do that **now**: + + # /usr/bin/mysql_secure_installation + + +#### Installing PostgreSQL database server + +Debian/Ubuntu: + # apt-get install postgresql + +RHEL/CentOS 5/6: + # yum install postgresql-server postgresql + # chkconfig postgresql on + # service postgresql start + +RHEL/CentOS 7 and Fedora 20 use [systemd](#systemd-service): + # yum install postgresql-server postgresql + # systemctl enable postgresql.service + # systemctl start postgresql.service + +SUSE: + # zypper install postgresql postgresql-server + # chkconfig postgresql on + # service postgresql start + ### Configuring DB IDO MySQL +> **Note** +> +> Upstream Debian packages provide a database configuration wizard by default. +> You can skip the automated setup and install/upgrade the database manually +> if you prefer that. + #### Setting up the MySQL database First of all you have to install the `icinga2-ido-mysql` package using your @@ -486,6 +608,7 @@ following command: # mysql -u root -p icinga < /usr/share/icinga2-ido-mysql/schema/mysql.sql + #### Upgrading the MySQL database Check the `/usr/share/icinga2-ido-mysql/schema/upgrade` directory for an @@ -513,11 +636,17 @@ You can enable the `ido-mysql` feature configuration file using `icinga2-enable- After enabling the ido-mysql feature you have to restart Icinga 2: - # /etc/init.d/icinga2 restart + # service icinga2 restart ### Configuring DB IDO PostgreSQL +> **Note** +> +> Upstream Debian packages provide a database configuration wizard by default. +> You can skip the automated setup and install/upgrade the database manually +> if you prefer that. + #### Setting up the PostgreSQL database First of all you have to install the `icinga2-ido-pgsql` package using your @@ -588,7 +717,7 @@ You can enable the `ido-pgsql` feature configuration file using `icinga2-enable- After enabling the ido-pgsql feature you have to restart Icinga 2: - # /etc/init.d/icinga2 restart + # service icinga2 restart ## Setting up Livestatus @@ -657,6 +786,40 @@ Special restrictions are noted specifically in the sections below. > Choose your preferred interface. There's no need to install [Classic UI](#setting-up-icinga-classic-ui) > if you prefer [Icinga Web](#setting-up-icinga-web) or [Icinga Web 2](#setting-up-icingaweb2) for example. +### Requirements + +* Web server (Apache2/Httpd, Nginx, Lighttp, etc) +* User credentials +* Firewall ports (tcp/80) + +The Debian, RHEL and SUSE packages for Icinga [Classic UI](#setting-up-icinga-classic-ui), +[Web](#setting-up-icinga-web) and [Icingaweb 2](#setting-up-icingaweb2) depend on Apache2 +as web server. + +#### Webserver + +Debian/Ubuntu packages will automatically fetch and install the required packages. + +RHEL/CentOS/Fedora: + # yum install httpd + # chkconfig httpd on && service httpd start + ## RHEL7 + # systemctl enable httpd && systemctl start httpd + +SUSE: + # zypper install apache2 + # chkconfig on && service apache2 start + +#### Firewall Rules + +Example: + # iptables -A INPUT -p tcp -m tcp --dport 80 -j ACCEPT + # service iptables save + +RHEL/CentOS 7 specific: + # firewall-cmd --add-service=http + # firewall-cmd --permanent --add-service=http + ### Setting up Icinga Classic UI Icinga 2 can write `status.dat` and `objects.cache` files in the format that @@ -672,7 +835,7 @@ the Classic UI using the following packages: Distribution | Packages --------------|--------------------- Debian | icinga2-classicui - all others | icinga2-classicui-config icinga-gui + RHEL/SUSE | icinga2-classicui-config icinga-gui The Debian packages require additional packages which are provided by the [Debian Monitoring Project](http://www.debmon.org) (`DebMon`) repository. @@ -810,14 +973,14 @@ please check the official [Icinga 1.x user interface documentation](http://docs. ### Setting up Icinga Web 2 -Icinga Web 2 currently supports `status.dat`, `DB IDO`, or `Livestatus` as backends. +Icinga Web 2 will support `status.dat`, `DB IDO`, or `Livestatus` as backends. Using DB IDO as backend, you need to install and configure the [DB IDO backend](#configuring-db-ido). Once finished, you can enable the feature for DB IDO MySQL: # icinga2-enable-feature ido-mysql -furthermore [external commands](#external-commands) are supported through the external +Furthermore [external commands](#external-commands) are supported through the external command pipe. # icinga2-enable-feature command @@ -965,10 +1128,14 @@ The Icinga 2 `Systemd` service can be (re)started, reloaded, stopped and also qu restart | The `restart` action is a shortcut for running the `stop` action followed by `start`. 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. status | The `status` action checks if Icinga 2 is running. + enable | The `enable` action enables the service being started at system boot time (similar to `chkconfig`) If you're stuck with configuration errors, you can manually invoke the [configuration validation](#config-validation). + # systemctl enable icinga2 + # systemctl restart icinga2 + Job for icinga2.service failed. See 'systemctl status icinga2.service' and 'journalctl -xn' for details. ### Command-line Options diff --git a/doc/3-monitoring-basics.md b/doc/3-monitoring-basics.md index fbba85f24..69b0b5c5e 100644 --- a/doc/3-monitoring-basics.md +++ b/doc/3-monitoring-basics.md @@ -496,6 +496,22 @@ Icinga 2 will not check against any end time for this notification. assign where service.name == "ping4" } +### Disable Re-notifications + +If you prefer to be notified only once, you can disable re-notifications by setting the +`interval` attribute to `0`. + + apply Notification "notify-once" to Service { + import "generic-notification" + + command = "mail-notification" + users = [ "icingaadmin" ] + + interval = 0 // disable re-notification + + assign where service.name == "ping4" + } + ### Notification Filters by State and Type If there are no notification state and type filter attributes defined at the `Notification` @@ -749,9 +765,11 @@ arguments. Each of them is optional by default and will be omitted if the value is not set. For example if the service calling the check command does not have `vars.http_port` set, it won't get added to the command line. + If the `vars.http_ssl` custom attribute is set in the service, host or command object definition, Icinga 2 will add the `-S` argument based on the `set_if` -option to the command line. +numeric value to the command line. String values are not supported. + That way you can use the `check_http` command definition for both, with and without SSL enabled checks saving you duplicated command definitions. @@ -786,6 +804,9 @@ the `my-host2` host requires a different port on 2222. Both hosts are in the hos All hosts in the `my-linux-servers` hostgroup should get the `my-ssh` service applied based on an [apply rule](#apply). The optional `ssh_port` command argument should be inherited from the host the service is applied to. If not set, the check command `my-ssh` will omit the argument. +The `host` argument is special: `skip_key` tells Icinga 2 to ignore the key, and directly put the +value onto the command line. The `order` attribute specifies that this argument is the first one +(`-1` is smaller than the other defaults). object CheckCommand "my-ssh" { import "plugin-check-command" diff --git a/doc/6-configuring-icinga-2.md b/doc/6-configuring-icinga-2.md index 3947f9096..495a1d149 100644 --- a/doc/6-configuring-icinga-2.md +++ b/doc/6-configuring-icinga-2.md @@ -26,6 +26,30 @@ EnableServiceChecks |**Read-write.** Whether active service checks are globally EnablePerfdata |**Read-write.** Whether performance data processing is globally enabled. Defaults to true. UseVfork |**Read-write.** Whether to use vfork(). Only available on *NIX. Defaults to true. +## Reserved Keywords + +These keywords are reserved by the configuration parser and must not be +used as constants or custom attributes. + + object + template + include + include_recursive + library + null + partial + true + false + const + apply + to + where + import + assign + ignore + zone + in + ## Configuration Syntax @@ -583,13 +607,13 @@ Attributes: notes |**Optional.** Notes for the host. notes_url |**Optional.** Url for notes for the host (for example, in notification commands). action_url |**Optional.** Url for actions for the host (for example, an external graphing tool). - icon_image |**Optional.** Icon image for the host. Required for external interfaces only. - icon_image_alt |**Optional.** Icon image description for the host. Required for external interface only. + icon_image |**Optional.** Icon image for the host. Used by external interfaces only. + icon_image_alt |**Optional.** Icon image description for the host. Used by external interface only. > **Best Practice** > > The `address` and `address6` attributes are required for running commands using -> the `$address$` and `$address6` runtime macros. +> the `$address$` and `$address6$` runtime macros. ### HostGroup @@ -669,8 +693,8 @@ Attributes: notes |**Optional.** Notes for the service. notes_url |**Optional.** Url for notes for the service (for example, in notification commands). action_url |**Optional.** Url for actions for the service (for example, an external graphing tool). - icon_image |**Optional.** Icon image for the service. Required for external interfaces only. - icon_image_alt |**Optional.** Icon image description for the service. Required for external interface only. + icon_image |**Optional.** Icon image for the service. Used by external interfaces only. + icon_image_alt |**Optional.** Icon image description for the service. Used by external interface only. Service objects have composite names, i.e. their names are based on the host_name attribute and the name you specified. This means @@ -849,8 +873,16 @@ CheckCommand: description = "My plugin requires this argument for doing X." required = false /* optional, no error if not set */ skip_key = false /* always use "-X " */ - set_if = "$have_x$" /* only set if variable defined */ - order = 0 /* first position */ + set_if = "$have_x$" /* only set if variable defined and resolves to a numeric value. String values are not supported */ + order = -1 /* first position */ + } + "-Y" = { + value = "$y_val$" + description = "My plugin requires this argument for doing Y." + required = false /* optional, no error if not set */ + skip_key = true /* don't prefix "-Y" only use "" */ + set_if = "$have_y$" /* only set if variable defined and resolves to a numeric value. String values are not supported */ + order = 0 /* second position */ } } @@ -860,9 +892,12 @@ CheckCommand: description | Optional argument description. required | Required argument. Execution error if not set. Defaults to false (optional). skip_key | Use the value as argument and skip the key. - set_if | Argument added if value is set (macro resolves to a defined value). + set_if | Argument is added if the macro resolves to a defined numeric value. String values are not supported. order | Set if multiple arguments require a defined argument order. +Argument order: + `..., -3, -2, -1, , 1, 2, 3, ...` + ### NotificationCommand @@ -971,7 +1006,7 @@ Attributes: user_groups | **Optional.** A list of user group names who should be notified. times | **Optional.** A dictionary containing `begin` and `end` attributes for the notification. command | **Required.** The name of the notification command which should be executed when the notification is triggered. - interval | **Optional.** The notification interval (in seconds). This interval is used for active notifications. Defaults to 30 minutes. + interval | **Optional.** The notification interval (in seconds). This interval is used for active notifications. Defaults to 30 minutes. If set to 0, [re-notifications](#disable-renotification) are disabled. period | **Optional.** The name of a time period which determines when this notification should be triggered. Not set by default. types | **Optional.** A list of type filters when this notification should be triggered. By default everything is matched. states | **Optional.** A list of state filters when this notification should be triggered. By default everything is matched. diff --git a/doc/8-migration.md b/doc/8-migration.md index fac1c6154..729711e47 100644 --- a/doc/8-migration.md +++ b/doc/8-migration.md @@ -1244,6 +1244,17 @@ as array to the `command_line` attribute i.e. for better readability. It's also possible to define default custom attributes for the command itself which can be overridden by a service macro. +#### Command Timeouts + +In Icinga 1.x there were two global options defining a host and service check +timeout. This was essentially bad when there only was a couple of check plugins +requiring some command timeouts to be extended. + +Icinga 2 allows you to specify the command timeout directly on the command. So +if your VMVware check plugin takes 15 minutes, [increase the timeout](#objecttype-checkcommand) +accordingly. + + ### Groups In Icinga 2 hosts, services and users are added to groups using the `groups`