From 6744f9d9bb3c32042fa7b91d1f7aa6de4006b457 Mon Sep 17 00:00:00 2001 From: Gunnar Beutner Date: Sun, 6 Apr 2014 10:57:51 +0200 Subject: [PATCH] Update documentation. Refs #5925 --- doc/1-about.md | 1 - doc/2.1-setting-up-icinga-2.md | 14 +++++------ doc/2.3-setting-up-ido.md | 2 -- doc/2.5-setting-up-icinga2-uis.md | 11 +++------ doc/2.7-running-icinga-2.md | 2 -- doc/3.01-hosts-and-services.md | 4 ++-- doc/3.03-custom-attributes-runtime-macros.md | 19 +++++---------- doc/3.04-notifications.md | 25 +++++++------------- doc/3.05-using-templates.md | 20 +++++++--------- 9 files changed, 35 insertions(+), 63 deletions(-) diff --git a/doc/1-about.md b/doc/1-about.md index 688ccc028..8e968889f 100644 --- a/doc/1-about.md +++ b/doc/1-about.md @@ -63,4 +63,3 @@ Please get in touch with the Icinga team at [https://www.icinga.org/ecosystem/]. ### Archive Please check the `ChangeLog` file. - diff --git a/doc/2.1-setting-up-icinga-2.md b/doc/2.1-setting-up-icinga-2.md index 80819e196..fe0328a1e 100644 --- a/doc/2.1-setting-up-icinga-2.md +++ b/doc/2.1-setting-up-icinga-2.md @@ -115,7 +115,7 @@ directive makes sure that all of your own configuration files are included. ### constants.conf -The `constants.conf` constants file can be used to define global constants: +The `constants.conf` configuration file can be used to define global constants: /** * This file defines global constants which can be used in @@ -142,14 +142,12 @@ The `conf.d/localhost.conf` file contains our first host definition: } 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 `linux-server` template which takes care of setting up the host check +as well as adding the host to the `linux-servers` host group. -The `vars` attribute can be used to define custom attributes that are available -for all services which belong to this host. Most of the templates in the Icinga -Template Library require an `address` custom attribute defined in the `vars` -dictionary. +The `vars` attribute can be used to define custom attributes which are available +for check and notification commands. Most of the templates in the Icinga +Template Library require an `address` custom attribute. object Service "icinga" { import "generic-service" diff --git a/doc/2.3-setting-up-ido.md b/doc/2.3-setting-up-ido.md index 8cb16d4b0..7c9ee43ab 100644 --- a/doc/2.3-setting-up-ido.md +++ b/doc/2.3-setting-up-ido.md @@ -212,5 +212,3 @@ 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 - - diff --git a/doc/2.5-setting-up-icinga2-uis.md b/doc/2.5-setting-up-icinga2-uis.md index 2cd2fa7f7..40d2e1831 100644 --- a/doc/2.5-setting-up-icinga2-uis.md +++ b/doc/2.5-setting-up-icinga2-uis.md @@ -60,7 +60,6 @@ UI installation URL: > [commands](#differences-1x-2-commands) and [custom attributes](#differences-1x-2-macros) > renders the command expander invalid for example. - ### Setting up Icinga Web Icinga 2 can write to the same schema supplied by `Icinga IDOUtils 1.x` which @@ -114,8 +113,6 @@ Verify that your Icinga 1.x Web works by browsing to your Web installation URL: Debian | [http://localhost/icinga-web](http://localhost/icinga-web) | asked during installation all others | [http://localhost/icinga-web](http://localhost/icinga-web) | root/password - - ### Setting up Icinga Web 2 Icinga Web 2 currently supports `status.dat`, `DB IDO`, or `Livestatus` as backends. @@ -130,9 +127,7 @@ further instructions. ### Additional visualization -There are many addons in the wild which are using Icinga 1.x backends and -are well integrated into user interfaces. - -The most famous ones are PNP or inGraph (graphing performance data), graphite, NagVis -(network maps), etc. +There are many visualization addons which can be used with Icinga 2. +Some of the more popular ones are PNP, inGraph (graphing performance data), +Graphite, and NagVis (network maps). diff --git a/doc/2.7-running-icinga-2.md b/doc/2.7-running-icinga-2.md index 8b650c299..3b305eee3 100644 --- a/doc/2.7-running-icinga-2.md +++ b/doc/2.7-running-icinga-2.md @@ -114,5 +114,3 @@ You can disable features using the `icinga2-disable-feature` command: > **Note** > > The `icinga2-enable-feature` and `icinga2-disable-feature` commands do not restart Icinga 2. - - diff --git a/doc/3.01-hosts-and-services.md b/doc/3.01-hosts-and-services.md index eec41e50a..6a9b88c86 100644 --- a/doc/3.01-hosts-and-services.md +++ b/doc/3.01-hosts-and-services.md @@ -29,8 +29,8 @@ Here is an example of a host object which defines two child services: check_command = "http_ip" } -The example host `my-server1` creates two services which belong to this host: -`ping4` and `http`. +The example creates two services `ping4` and `http` which belong to the +host `my-server1`. It also specifies that the host should perform its own check using the `hostalive` check command. diff --git a/doc/3.03-custom-attributes-runtime-macros.md b/doc/3.03-custom-attributes-runtime-macros.md index 27186daad..90e427fec 100644 --- a/doc/3.03-custom-attributes-runtime-macros.md +++ b/doc/3.03-custom-attributes-runtime-macros.md @@ -1,17 +1,13 @@ -## Custom Attributes and Runtime Macros - -> **Note** -> -> There is a limited set of special [global constants](#global-constants) which can be re-used and -> also partly overridden such as `IcingaEnableChecks`. +## Custom Attributes ### Using Custom Attributes at Runtime Custom attributes may be used in command definitions to dynamically change how the command is executed. -Additionally there are Icinga 2 features for example the `PerfDataWriter` -using the available Custom attributes for output formatting. + +Additionally there are Icinga 2 features such as the `PerfDataWriter` type +which use custom attributes to format their output. > **Tip** > @@ -21,8 +17,8 @@ using the available Custom attributes for output formatting. > **Note** > > Custom attributes in command definitions or performance data templates are evaluated at -> runtime when executing a command. These custom attributes cannot be used/accessed inside -> the configuration objects to add references or similar unless stated otherwise. +> runtime when executing a command. These custom attributes cannot be used elsewhere +> (e.g. in other configuration attributes). Here is an example of a command definition which uses user-defined custom attributes: @@ -219,6 +215,3 @@ The following macros are available in all executed commands: icinga.shortdatetime | Current date and time. Example: `2014-01-03 11:23:08` icinga.date | Current date. Example: `2014-01-03` icinga.time | Current time including timezone information. Example: `11:23:08 +0000` - - - diff --git a/doc/3.04-notifications.md b/doc/3.04-notifications.md index 9b94eeefe..9669c91fa 100644 --- a/doc/3.04-notifications.md +++ b/doc/3.04-notifications.md @@ -1,22 +1,15 @@ ## Notifications -Notifications on alerts are an integral part of your Icinga 2 monitoring application. -There are many ways of getting a notification to the actual receiver - Email, XMPP, -IRC, Twitter, etc. The default method for executing a notification command are -plugin scripts used for notifications. -These may either be shell commands to invoke a system call to the `mail` binary -or your own script fetching available custom attribute values and doing proper formatting -before sending the notification. -Other mechanism will require writing the notification string into an api processing -it there (for example ticket system integration). +Notifications for service and host problems are an integral part of your +monitoring setup. -Such notification plugins are available from community users and professionals for -example on the [MonitoringExchange](http://www.monitoringexchange.org) or the -[Icinga Wiki](https://wiki.icinga.org). Or you'll write your own and share it. - -A notification requires one or more users (and/or user groups) who will be notified -in case. These users must have all custom attributes defined which will be used in -the `NotificationCommand` on execution. +There are many ways of sending notifications, e.g. by e-mail, XMPP, +IRC, Twitter, etc. On its own Icinga 2 does not know how to send notifications. +Instead it relies on external mechanisms such as shell scripts to notify users. + +A notification specification requires one or more users (and/or user groups) +who will be notified in case of problems. These users must have all custom +attributes defined which will be used in the `NotificationCommand` on execution. TODO diff --git a/doc/3.05-using-templates.md b/doc/3.05-using-templates.md index 6ce8ee924..f0c6a6618 100644 --- a/doc/3.05-using-templates.md +++ b/doc/3.05-using-templates.md @@ -1,11 +1,7 @@ ## Using Templates -Templates may be used to apply a set of similar settings to more than one -object. - -For example, rather than manually creating a `ping` service object for each of -your hosts you can use templates to avoid having to copy & paste parts of your -configuration: +Templates may be used to apply a set of identical attributes to more than one +object: template Service "generic-service" { max_check_attempts = 3 @@ -14,19 +10,21 @@ configuration: enable_perfdata = true } - apply Service "ping4" { + object Service "ping4" { import "generic-service" + + host_name = "localhost" check_command = "ping4" - assign where host.vars.address } - apply Service "ping6" { + object Service "ping6" { import "generic-service" + + host_name = "localhost" check_command = "ping6" - assign where host.vars.address6 } -In this example both `ping4` and `ping6` services inherit properties from the +In this example the `ping4` and `ping6` services inherit properties from the template `generic-service`. Objects as well as templates themselves can import an arbitrary number of