From 2034ff5eee8457180fe0aa73cb66c5954c9c4431 Mon Sep 17 00:00:00 2001 From: Gunnar Beutner Date: Sun, 30 Mar 2014 11:52:39 +0200 Subject: [PATCH] Update documentation. Refs #5870 --- doc/1-about.md | 5 +- doc/2.1-setting-up-icinga-2.md | 38 +++++---- doc/2.2-setting-up-check-plugins.md | 51 +++++++----- doc/3.10-logging.md | 31 +++---- doc/4.1-configuration-syntax.md | 125 +++++++++++++++------------- doc/4.2-global-variables.md | 2 +- doc/4.3-object-types.md | 12 +-- doc/4.5-best-practice.md | 6 +- 8 files changed, 143 insertions(+), 127 deletions(-) diff --git a/doc/1-about.md b/doc/1-about.md index da0ade501..00e89ee0c 100644 --- a/doc/1-about.md +++ b/doc/1-about.md @@ -2,8 +2,9 @@ ## What is Icinga 2? -Icinga 2 is an open source monitoring system which keeps watch over network resources, -notifies users of outages and recoveries and generates performance data for reporting. +Icinga 2 is an open source monitoring system which checks the availability of your +network resources, notifies users of outages and generates performance data for reporting. + Scalable and extensible, Icinga 2 can monitor complex, large environments across multiple locations. diff --git a/doc/2.1-setting-up-icinga-2.md b/doc/2.1-setting-up-icinga-2.md index 23d8e82c6..7443d43ae 100644 --- a/doc/2.1-setting-up-icinga-2.md +++ b/doc/2.1-setting-up-icinga-2.md @@ -4,14 +4,14 @@ First of all you will have to install Icinga 2. The preferred way of doing this is to use the official Debian or RPM package repositories depending on which operating system and distribution you are running. - Distribution |Repository URL + Distribution | Repository URL ------------------------|--------------------------- - Debian |http://packages.icinga.org/debian/ - Ubuntu |http://packages.icinga.org/ubuntu/ - RHEL/CentOS 5 |http://packages.icinga.org/epel/5/release/ - RHEL/CentOS 6 |http://packages.icinga.org/epel/6/release/ - OpenSUSE 12.3 |http://packages.icinga.org/openSUSE/12.3/release/ - SLES 11 SP3 |http://packages.icinga.org/SUSE/sles11-sp3/release/ + Debian | http://packages.icinga.org/debian/ + Ubuntu | http://packages.icinga.org/ubuntu/ + RHEL/CentOS 5 | http://packages.icinga.org/epel/5/release/ + RHEL/CentOS 6 | http://packages.icinga.org/epel/6/release/ + OpenSUSE 12.3 | http://packages.icinga.org/openSUSE/12.3/release/ + SLES 11 SP3 | http://packages.icinga.org/SUSE/sles11-sp3/release/ Packages for distributions other than the ones listed above may also be available. Please check http://packages.icinga.org/ to see if packages @@ -29,8 +29,7 @@ to install the `icinga2` package. > **Note** > > 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 `/etc/init.d/icinga2 start`. Some parts of Icinga 2's functionality are available as separate packages: @@ -114,7 +113,7 @@ The `conf.d/macros.conf` file can be used to define global macros: /** * Global macros */ - set IcingaMacros = { + const IcingaMacros = { plugindir = "/usr/local/icinga/libexec" } @@ -137,6 +136,15 @@ The `conf.d/localhost.conf` file contains our first host definition: macros.address6 = "::1" } +This defines the host `localhost`. The `import` keyword is used to import +the `linux-server` template which takes care of setting up the `ping4` and +`ping6` services for the host as well as adding the host to the `linux-servers` +host group. + +The `macros` attribute can be used to define macros that are available for all +services which belong to this host. Most of the templates in the Icinga Template +Library require an `address` macro. + apply Service "icinga" { import "generic-service", @@ -199,13 +207,9 @@ The `conf.d/localhost.conf` file contains our first host definition: assign where host.name == "localhost" } -This defines a host named "localhost" which has a couple of services. Services -may import one or more service templates. +The `apply` keyword can be used to dynamically create services for all hosts based +on rules. -The command objects `ping4`, `ping6`, `http_ip`, `ssh`, `load`, `processes`, `users` +The command objects `http_ip`, `ssh`, `load`, `processes`, `users` and `disk` are all provided by the Icinga Template Library (short ITL) which we enabled earlier by including the `itl/itl.conf` configuration file. - -The `macros` attribute can be used to define macros that are available for all -services which belong to this host. Most of the templates in the Icinga Template -Library require an `address` macro. diff --git a/doc/2.2-setting-up-check-plugins.md b/doc/2.2-setting-up-check-plugins.md index 89dcb25ac..622fc7004 100644 --- a/doc/2.2-setting-up-check-plugins.md +++ b/doc/2.2-setting-up-check-plugins.md @@ -1,17 +1,18 @@ ## Setting up Check Plugins On its own Icinga 2 does not know how to check external services. The -[Monitoring Plugins Project](https://www.monitoring-plugins.org/) (former -Nagios Plugins) provides an extensive set of plugins which can be used by -Icinga 2 to check whether services are working properly. +[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` project -> in Jan 2014. Therefore package names may still reflect the old name. +> 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: @@ -27,29 +28,41 @@ Depending on which directory your plugins are installed into you may need to update the `plugindir` macro 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. -Alternatively you can create a symbolic link pointing to the installation path -of the plugins. ### Integrate Additional Plugins -You may require a custom check plugin not provided by the official Nagios plugins. -All existing Nagios or Icinga 1.x plugins found on public community websites -will work with Icinga 2 as well. +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) -Once you have downloaded the plugin copy it into the directory defined by the global -`IcingaMacro` `$plugindir$` and make sure that the user the Icinga daemon is running as -can execute the the plugin binary. Plugins should support the `--help` parameter -providing details how they have to be called in your command definition later on. +The recommended way of setting up these plugins is to copy them to a common directory +and creating an extra global macro, e.g. `customplugindir` in your `macros.conf` +configuration file: - # cp check_snmp_int.pl /usr/local/icinga/libexec/ - # chmod +x /usr/local/icinga/libexec/check_snmp_int.pl - - # /usr/local/icinga/libexec/check_snmp_int.pl --help + # cp check_snmp_int.pl /opt/plugins + # chmod +x /opt/plugins/check_snmp_int.pl + + # cat /etc/icinga2/conf/macros.conf + /** + * Global macros + */ + const IcingaMacros = { + plugindir = "/usr/lib/nagios/plugins", + 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 > **Note** > -> You may require additional libraries for scripts. Please consult the installation +> You may require additional libraries for some plugins. Please consult the installation > documentation and/or README for their installation requirements. diff --git a/doc/3.10-logging.md b/doc/3.10-logging.md index b83d7f915..0db6ba424 100644 --- a/doc/3.10-logging.md +++ b/doc/3.10-logging.md @@ -2,26 +2,19 @@ Icinga 2 supports three different types of logging: -* File logging (local Icinga 2 log file) -* Syslog facility logging (system's syslog application) +* File logging +* Syslog (on *NIX-based operating systems) * Console logging (`STDOUT` on tty) -> **Note** -> -> You can define multiple logging objects at once. +You can enable additional loggers using the `icinga2-enable-feature` +and `icinga2-disable-feature` commands to configure loggers: -The most common scenario will be logging Icinga 2's output to -syslog with severity `information`. - - object SyslogLogger "syslog" { - severity = "information" - } - -For debugging purposes you can install a `FileLogger` object -and forward the `debug` severity into an Icinga 2 debug file. - - object FileLogger "debug-file" { - severity = "debug", - path = "/var/log/icinga2/debug.log" - } +Feature | Description +---------|------------ +debuglog | Debug log (path: `/var/log/icinga2/debug.log`, severity: `debug` or higher) +mainlog | Main log (path: `/var/log/icinga2/icinga2.log`, severity: `information` or higher) +syslog | Syslog (severity: `warning` or higher) +By default file the `mainlog` feature is enabled. When running Icinga 2 +on a terminal log messages with severity `information` or higher are +written to the console. diff --git a/doc/4.1-configuration-syntax.md b/doc/4.1-configuration-syntax.md index e739a20c3..6485496ae 100644 --- a/doc/4.1-configuration-syntax.md +++ b/doc/4.1-configuration-syntax.md @@ -66,15 +66,15 @@ Example: Certain characters need to be escaped. The following escape sequences are supported: -Character |Escape sequence -------------------------------------|------------------------------------ -" |\\" -\\ |\\\\ -\ |\\t -\ |\\r -\ |\\n -\ |\\b -\ |\\f +Character | Escape sequence +--------------------------|------------------------------------ +" | \\" +\\ | \\\\ +<TAB> | \\t +<CARRIAGE-RETURN> | \\r +<LINE-FEED> | \\n +<BEL> | \\b +<FORM-FEED> | \\f In addition to these pre-defined escape sequences you can specify arbitrary ASCII characters using the backslash character (\\) followed @@ -154,7 +154,8 @@ The following operators are supported in expressions: Operator | Examples (Result) | Description ---------|-----------------------------------------------|-------------------------------- -!, ~ | ~true (false) | Bitwise negation of the operand +! | !"Hello" (false), !false (true) | Logical negation of the operand +~ | ~true (false) | Bitwise negation of the operand + | 1 + 3 (4), "hello " + "world" ("hello world") | Adds two numbers; concatenates strings - | 3 - 1 (2) | Subtracts two numbers * | 5m * 10 (3000) | Multiplies two numbers @@ -295,6 +296,12 @@ The indexer syntax provides a convenient way to set dictionary elements. Example: + { + hello.key = "world" + } + +Example (alternative syntax): + { hello["key"] = "world" } @@ -307,80 +314,55 @@ This is equivalent to writing: } } -### Object Inheritance +### Template Imports -Objects can inherit attributes from other objects. +Objects can import attributes from other objects. Example: template Host "default-host" { - macros["color"] = "red" + macros.color = "red" } template Host "test-host" { import "default-host", - macros["color"] = "blue" + macros.color = "blue" } object Host "localhost" { import "test-host", - macros["address"] = "127.0.0.1", - macros["address6"] = "::1" + macros.address = "127.0.0.1", + macros.address6 = "::1" } The `default-host` and `test-host` objects are marked as templates using the `template` keyword. Unlike ordinary objects templates are not instantiated at run-time. Parent objects do not necessarily have to be -templates though in general they are. +templates, however in general they are. > **Note** > -> The final macros dictionary contains all three macros and the macro -> `color` has the value `"blue"`. +> The macros dictionary for the `localhost` object contains all three +> macros and the macro `color` has the value `"blue"`. Parent objects are resolved in the order they're specified using the `import` keyword. -### Disable/Override Objects and Attributes - -Object attributes can be overridden by defining the additional changed attribute -directly on the object. Use the `+=` operator for the inline services dictionary. - - services["overridden-custom-attr"] += { - custom = { - notes = "disabled all custom attr" - } - } - -If you don't require an attribute inherited from templates, you can simply -override its value by setting it explicitely to `null`. - - services["no-custom-attr"] += { - custom = null - } - -The same method applies for disabling services defined in the inline `services` -dictionary by explicitly overriding their value with `null`. - - services["ping6"] = null - ### Constants Global constants can be set using the `const` keyword: const VarName = "some value" -The value can be a string, number, array, or a dictionary. - Once defined a constant can be access from any file. Constants cannot be changed once they are set. ### Apply -The `apply` keyword can be used to associate a template with another group of -objects. The exact effect of this association depends on the object type. +The `apply` keyword can be used to create new objects which are associated with +another group of objects. apply Service "ping" { import "generic-service", @@ -390,19 +372,43 @@ objects. The exact effect of this association depends on the object type. assign where host.name == "localhost" } -In this example the `assign where` condition is an expression which is -evaluated for all objects of type Host and a new service with name "ping" +In this example the `assign where` condition is a boolean expression which is +evaluated for all objects of type `Host` and a new service with name "ping" is created for each matching host. Depending on the object type used in the `apply` expression additional local variables may be available for use in the `where` condition: - Type |Variables - -----------------|---------------- - Dependency |host, service - Notification |host, service - Service |host - ScheduledDowntime|host, service +Source Type | Target Type | Variables +-----------------|-------------|-------------- +Service | Host | host +Dependency | Service | host, service +Notification | Service | host, service +ScheduledDowntime| Service | host, service + +> **Note** +> +> Any valid config attribute can be accessed using the `host` and `service` +> variables. For example, `host.macros.address` would return the host's +> "address" macro - or null if it doesn't have that macro. + +### Boolean Values + +The `assign where` and `ignore where` statements, the unary `!`, `&&` and `||` +operators as well as the `bool()` function convert their arguments to a +boolean value based on the following rules: + +Description | Example Value | Boolean Value +---------------------|-------------------|-------------- +Empty value | null | false +Zero | 0 | false +Non-zero integer | -23945 | true +Empty string | "" | false +Non-empty string | "Hello" | true +Empty array | [] | false +Non-empty array | [ "Hello" ] | true +Empty dictionary | {} | false +Non-empty dictionary | { key = "value" } | true ### Comments @@ -440,7 +446,7 @@ C/C++ compiler: Note the use of angle brackets instead of double quotes. This causes the config compiler to search the include search paths for the specified -file. By default $PREFIX/icinga2 is included in the list of search +file. By default $PREFIX/share/icinga2 is included in the list of search paths. Additional include search paths can be added using [command-line options](#cmdline). @@ -466,7 +472,7 @@ When no pattern is specified the default pattern "*.conf" is used. The `library` directive can be used to manually load additional libraries. Libraries can be used to provide additional object types and -methods. +functions. Example: @@ -474,8 +480,8 @@ Example: > **Note** > -> The `icinga` library is automatically loaded at startup. You don't need -> to load it manually. +> The `icinga` and `methods` libraries is automatically loaded at startup. +> You don't need to load them manually.