Update documentation.

doc/2.1.1-setting-up-icinga-2.md

@@ -15,6 +15,10 @@ Packages for distributions other than the ones listed above may also be
 available. Please check http://packages.icinga.org/ to see if packages
 are available for your favorite distribution.
 
+You can install Icinga 2 by using your distribution's package manager
+to install the *icinga2* package. Some parts of Icinga 2's functionality
+are available as separate packages.
+
 In case you're running a distribution for which Icinga 2 packages are
 not yet available you will have to use the release tarball which you
 can download from the [Icinga website](https://www.icinga.org/). The

doc/2.1.2-setting-up-icinga-classic-ui.md

@@ -30,6 +30,20 @@ following commands:
 > found on the Icinga Wiki here:
 > [https://wiki.icinga.org/display/howtos/Setting+up+Icinga+Classic+UI+Standalone](https://wiki.icinga.org/display/howtos/Setting+up+Icinga+Classic+UI+Standalone)
 
+#### Configuring Icinga 2
+
+By default Icinga 2 does not write *status.dat* and *objects.cache* files which are used
+by the Classic UI. The command pipe is also not enabled by default.
+
+You can use i2enfeature to enable these features:
+
+    # i2enfeature statusdat
+    # i2enfeature command
+
+After enabling these features you will need to restart Icinga 2:
+
+    # /etc/init.d/icinga2 restart
+
 #### Configuring the Classic UI
 
 After installing the Classic UI you will need to update the following

doc/2.1.4-setting-up-ido.md

@@ -1,14 +1,15 @@
 ### Configuring IDO
 
 The IDO (Icinga Data Output) modules for Icinga 2 takes care of exporting all
-configuration and status information into a database.
+configuration and status information into a database. The IDO database is used
+by a number of projects including Icinga Web.
 
 There is a separate module for each database backend. At present only support
 for MySQL is implemented.
 
 #### Setting up the database
 
-First of all you will need to create a database for Icinga 2:
+First of all you have to create a database for Icinga 2:
 
     # mysql -u root -p
 
@@ -29,14 +30,13 @@ First of all you will need to create a database for Icinga 2:
     mysql> quit
 
 After creating the database you can import the Icinga 2 IDO schema using the
-following commands:
+following command:
 
-    # cd /path/to/icinga-src/components/db_ido_mysql/schema
+    # mysql -u root -p icinga < /path/to/icinga-src/components/db_ido_mysql/schema/mysql.sql
-    # mysql -u root -p icinga < mysql.sql
 
 #### Installing the IDO module
 
-Once you've set up your database you will need to install the *icinga2-ido-mysql*
+Once you've set up your database you have to install the *icinga2-ido-mysql*
 package using your distribution's package manager.
 
 The package provides a new configuration file that is installed in
@@ -49,6 +49,6 @@ You can enable the ido-mysql feature configuration file using *i2enfeature*:
     Module 'ido-mysql' was enabled.
     Make sure to restart Icinga 2 for these changes to take effect.
 
-After enabling the ido-mysql feature you will need to restart Icinga 2:
+After enabling the ido-mysql feature you have to restart Icinga 2:
 
-    # /etc/init.d/icinga2 restart
+    # /etc/init.d/icinga2 restart

doc/2.3-monitoring-basics.md

@@ -1,12 +1,85 @@
 ## Monitoring Basics
 
-### Hosts
+This part of the Icinga 2 documentation provides an overview of all the basic
+monitoring concepts you need to know to run Icinga 2.
 
-TODO
+### Hosts and Services
 
-### Services
+Icinga 2 can be used to monitor the availability of hosts and services. Services
+can be virtually anything which can be checked in some way:
 
-TODO
+* Network services (HTTP, SMTP, SNMP, SSH, etc.)
+* Printers
+* Switches / Routers
+* Temperature Sensors
+* Other local or network-accessible services
+
+Host objects provide a mechanism to group together services that are running
+on the same physical device.
+
+Here is an example of a host object which defines two child services:
+
+    object Host "my-server1" {
+      services["ping4"] = {
+        check_command = "ping4"
+      },
+
+      services["http"] = {
+        check_command = "http_ip"
+      },
+
+      check = "ping4",
+
+      macros["address"] = "10.0.0.1"
+    }
+
+The example host *my-server1* creates two services which belong to this host:
+*ping4* and *http*.
+
+It also specifies that the host should inherit its availability state from the
+*ping4* service.
+
+> **Note**
+>
+> In Icinga 1.x hosts had their own check command, check interval and
+> notification settings. Instead, in Icinga 2 hosts inherit their state
+> from one of its child services. No checks are performed for the host
+> itself.
+
+The *address* macro is used by check commands to determine which network
+address is associated with the host object.
+
+#### Host States
+
+  Name        | Description
+  ------------|--------------
+  UP          | The host is available.
+  DOWN        | The host is unavailable.
+  UNREACHABLE | At least one of the host's dependencies (e.g. its upstream router) is unavailable causing the host to be unreachable.
+
+#### Service States
+
+  Name        | Description
+  ------------|--------------
+  OK          | The service is fully available.
+  WARNING     | The service is experiencing some problems but is still considered available.
+  CRITICAL    | The service is in a critical state.
+  UNKNOWN     | The check could not determine the service's state.
+
+#### Hard and Soft States
+
+When detecting a problem with a service Icinga re-checks the service a number of
+times (based on the *max_check_attempts* and *retry_interval* settings) before sending
+notifications. This ensures that no unnecessary notifications are sent for
+transient failures. During this time the service is in a *SOFT* state.
+
+After all re-checks have been executed and the service is still in a non-OK
+state the service switches to a *HARD* state and notifications are sent.
+
+  Name        | Description
+  ------------|--------------
+  HARD        | The host/service's state hasn't recently changed.
+  SOFT        | The host/service has recently changed state and is being re-checked.
 
 ### Check Commands
 
@@ -14,25 +87,187 @@ TODO
 
 ### Macros
 
-TODO
+Macros may be used in command definitions to dynamically change how the command
+is executed.
 
-## Using Templates
+Here is an example of a command definition which uses user-defined macros:
+
+    object CheckCommand "my-ping" inherits "plugin-check-command" {
+      command = [
+        "$plugindir$/check_ping",
+        "-4",
+        "-H", "$address$",
+        "-w", "$wrta$,$wpl$%",
+        "-c", "$crta$,$cpl$%",
+        "-p", "$packets$",
+        "-t", "$timeout$"
+      ],
+
+      macros = {
+        wrta = 100,
+        wpl = 5,
+
+        crta = 200,
+        cpl = 15,
+
+        packets = 5,
+        timeout = 0
+      }
+    }
+
+> **Note**
+>
+> If you have previously used Icinga 1.x you may already be familiar with
+> user and argument macros (e.g., USER1 or ARG1). Unlike in Icinga 1.x macros
+> may have arbitrary names and arguments are no longer specified in the
+> check_command setting.
+
+Macro names must be enclosed in two *$* signs, e.g. *$plugindir$*. When
+executing the command Icinga 2 checks the following objects in this
+order to look up macros:
+
+1. User object (only for notifications)
+2. Service object
+3. Host object
+4. Command object
+5. Global macros in the IcingaMacros variable
+
+This execution order allows you to define default values for macros in your
+command objects. The *my-ping* command shown above uses this to set default
+values for some of the latency thresholds and timeouts.
+
+When using the *my-ping* command you can overwrite all or some of the macros
+in the service definition like this:
+
+    object Host "my-server1" {
+      services["ping"] = {
+        check_command = "my-ping",
+
+        macros["packets"] = 10 // Overwrites the default value of 5 given in the command
+      },
+
+      macros["address"] = "10.0.0.1"
+    }
+
+If a macro isn't defined anywhere an empty value is used and a warning is
+emitted to the Icinga 2 log.
+
+> **Note**
+>
+> Macros in capital letters (e.g. HOSTNAME) are reserved for use by Icinga 2
+> and should not be overwritten by users.
+
+By convention every host should have an *address* macro. Hosts
+which have an IPv6 address should also have an *address6* macro.
+
+The *plugindir* macro should be set to the path of your check plugins. The
+*/etc/icinga2/conf.d/macros.conf* file is usually used to define global macros
+including this one.
+
+#### Host Macros
+
+The following host macros are available in all commands that are executed for
+hosts or services:
+
+  Name                   | Description
+  -----------------------|--------------
+  HOSTNAME               |The name of the host object.
+  HOSTDISPLAYNAME        |The value of the display_name attribute.
+  HOSTALIAS              |This is an alias for the *HOSTDISPLAYNAME* macro.
+  HOSTSTATE              |The host's current state. Can be one of UNREACHABLE, UP and DOWN.
+  HOSTSTATEID            |The host's current state. Can be one of 0 (up), 1 (down) and 2 (unreachable).
+  HOSTSTATETYPE          |The host's current state type. Can be one of SOFT and HARD.
+  HOSTATTEMPT            |The current check attempt number.
+  MAXHOSTATTEMPT         |The maximum number of checks which are executed before changing to a hard state.
+  LASTHOSTSTATE          |The host's previous state. Can be one of UNREACHABLE, UP and DOWN.
+  LASTHOSTSTATEID        |The host's previous state. Can be one of 0 (up), 1 (down) and 2 (unreachable).
+  LASTHOSTSTATETYPE      |The host's previous state type. Can be one of SOFT and HARD.
+  HOSTLATENCY            |The host's check latency.
+  HOSTEXECUTIONTIME      |The host's check execution time.
+  HOSTOUTPUT             |The last check's output.
+  HOSTPERFDATA           |The last check's performance data.
+  LASTHOSTCHECK          |The timestamp when the last check was executed.
+  HOSTADDRESS            |This is an alias for the *address* macro. If the *address* macro is not defined the host object's name is used instead.
+  HOSTADDRESS6           |This is an alias for the *address6* macro. If the *address* macro is not defined the host object's name is used instead.
+
+#### Service Macros
+
+The following service macros are available in all commands that are executed for
+services:
+
+  Name                   | Description
+  -----------------------|--------------
+  SERVICEDESC            |The short name of the service object.
+  SERVICEDISPLAYNAME     |The value of the display_name attribute.
+  SERVICECHECKCOMMAND    |This is an alias for the *SERVICEDISPLAYNAME* macro.
+  SERVICESTATE           |The service's current state. Can be one of OK, WARNING, CRITICAL, UNCHECKABLE and UNKNOWN.
+  SERVICESTATEID         |The service's current state. Can be one of 0 (ok), 1 (warning), 2 (critical), 3 (unknown) and 4 (uncheckable).
+  SERVICESTATETYPE       |The service's current state type. Can be one of SOFT and HARD.
+  SERVICEATTEMPT         |The current check attempt number.
+  MAXSERVICEATTEMPT      |The maximum number of checks which are executed before changing to a hard state.
+  LASTSERVICESTATE       |The service's previous state. Can be one of OK, WARNING, CRITICAL, UNCHECKABLE and UNKNOWN.
+  LASTSERVICESTATEID     |The service's previous state. Can be one of 0 (ok), 1 (warning), 2 (critical), 3 (unknown) and 4 (uncheckable).
+  LASTSERVICESTATETYPE   |The service's previous state type. Can be one of SOFT and HARD.
+  LASTSERVICESTATECHANGE |The last state change's timestamp.
+  SERVICELATENCY         |The service's check latency.
+  SERVICEEXECUTIONTIME   |The service's check execution time.
+  SERVICEOUTPUT          |The last check's output.
+  SERVICEPERFDATA        |The last check's performance data.
+  LASTSERVICECHECK       |The timestamp when the last check was executed.
+
+#### User Macros
+
+The following service macros are available in all commands that are executed for
+users:
+
+  Name                   |  Description
+  -----------------------|---------------
+  CONTACTNAME            | The name of the user object.
+  CONTACTALIAS           | The value of the display_name attribute.
+  CONTACTEMAIL           | This is an alias for the *email* macro.
+  CONTACTPAGER           | This is an alias for the *pager* macro.
+
+### 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
+config:
+
+    template Host "linux-server" {
+      services["ping"] = {
+        check_command = "ping4"
+      },
+
+      check = "ping4"
+    }
+
+    object Host "my-server1" inherits "linux-server" {
+      macros["address"] = "10.0.0.1"
+    }
+
+    object Host "my-server2" inherits "linux-server" {
+      macros["address"] = "10.0.0.2"
+    }
+
+In this example both *my-server1* and *my-server2* each get their own ping
+service check.
+
+Objects as well as templates themselves can inherit from an arbitrary number of
+templates. Attributes inherited from a template can be overwritten in the
+object if necessary.
+
+### Groups
 
 TODO
 
-## Groups
+### Host/Service Dependencies
 
 TODO
 
-## Host/Service Dependencies
+### Notifications
-
-TODO
-
-## Time Periods
-
-TODO
-
-## Notifications
 
 TODO
 

doc/3.3-object-types.md

@@ -106,15 +106,15 @@ Attributes:
   display_name    |**Optional.** A short description of the service.
   macros          |**Optional.**
   check\_command  |**Required.** The name of the check command.
-  max\_check\_attempts|TODO
+  max\_check\_attempts|**Optional.** The number of times a service is re-checked before changing into a hard state. Defaults to 3.
   check\_period   |**Optional.** The name of a time period which determines when this service should be checked. Not set by default.
-  check\_interval |**Optional.** The check interval (in seconds).
+  check\_interval |**Optional.** The check interval (in seconds). This interval is used for checks when the service is in a *HARD* state. Defaults to 5 minutes.
-  retry\_interval |**Optional.** The retry interval (in seconds). This is used when the service is in a soft state. Defaults to 1/5th of the check interval if not specified.
+  retry\_interval |**Optional.** The retry interval (in seconds). This interval is used for checks when the service is in a *SOFT* state. Defaults to 1/5th of the check interval if not specified.
   event\_command  |**Optional.** The name of an event command that should be executed every time the service's state changes.
   flapping\_threshold|TODO
   volatile        |TODO
-  host\_dependencies|TODO
+  host_dependencies|**Optional.** A list of host names which this host depends on. These dependencies are used to determine whether the host is unreachable.
-  service\_dependencies|TODO
+  service_dependencies|**Optional.** A list of services which this host depends on. Each array element must be a dictionary containing the keys "host" and "service". These dependencies are used to determine whether the host is unreachable.
   groups          |**Optional.** The service groups this service belongs to.
   notifications   |TODO
 
@@ -397,10 +397,11 @@ Example:
       database = "icinga",
       table_prefix = "icinga_",
       instance_name = "icinga2",
-      instance_description = "icinga2 dev instance"
+      instance_description = "icinga2 dev instance",
+
       cleanup = {
         downtimehistory_age = 48h,
-	logentries_age = 31d,
+        logentries_age = 31d,
       }
     }
 
@@ -420,22 +421,23 @@ Attributes:
 
 Cleanup Items:
 
+  Name            | Description
   ----------------|----------------
-  acknowledgement_age |**Optional.** Max age for acknowledgement table rows (entry_time)
+  acknowledgement_age |**Optional.** Max age for acknowledgement table rows (entry_time). Defaults to 0 (never).
-  commenthistory_age |**Optional.** Max age for commenthistory table rows (entry_time)
+  commenthistory_age |**Optional.** Max age for commenthistory table rows (entry_time). Defaults to 0 (never).
-  contactnotifications_age |**Optional.** Max age for contactnotifications table rows (start_time)
+  contactnotifications_age |**Optional.** Max age for contactnotifications table rows (start_time). Defaults to 0 (never).
-  contactnotificationmethods_age |**Optional.** Max age for contactnotificationmethods table rows (start_time)
+  contactnotificationmethods_age |**Optional.** Max age for contactnotificationmethods table rows (start_time). Defaults to 0 (never).
-  downtimehistory_age |**Optional.** Max age for downtimehistory table rows (entry_time)
+  downtimehistory_age |**Optional.** Max age for downtimehistory table rows (entry_time). Defaults to 0 (never).
-  eventhandlers_age |**Optional.** Max age for eventhandlers table rows (start_time)
+  eventhandlers_age |**Optional.** Max age for eventhandlers table rows (start_time). Defaults to 0 (never).
-  externalcommands_age |**Optional.** Max age for externalcommands table rows (entry_time)
+  externalcommands_age |**Optional.** Max age for externalcommands table rows (entry_time). Defaults to 0 (never).
-  flappinghistory_age |**Optional.** Max age for flappinghistory table rows (event_time)
+  flappinghistory_age |**Optional.** Max age for flappinghistory table rows (event_time). Defaults to 0 (never).
-  hostchecks_age |**Optional.** Max age for hostchecks table rows (start_time)
+  hostchecks_age |**Optional.** Max age for hostchecks table rows (start_time). Defaults to 0 (never).
-  logentries_age |**Optional.** Max age for logentries table rows (logentry_time)
+  logentries_age |**Optional.** Max age for logentries table rows (logentry_time). Defaults to 0 (never).
-  notifications_age |**Optional.** Max age for notifications table rows (start_time)
+  notifications_age |**Optional.** Max age for notifications table rows (start_time). Defaults to 0 (never).
-  processevents_age |**Optional.** Max age for processevents table rows (event_time)
+  processevents_age |**Optional.** Max age for processevents table rows (event_time). Defaults to 0 (never).
-  statehistory_age |**Optional.** Max age for statehistory table rows (state_time)
+  statehistory_age |**Optional.** Max age for statehistory table rows (state_time). Defaults to 0 (never).
-  servicechecks_age |**Optional.** Max age for servicechecks table rows (start_time)
+  servicechecks_age |**Optional.** Max age for servicechecks table rows (start_time). Defaults to 0 (never).
-  systemcommands_age |**Optional.** Max age for systemcommands table rows (start_time)
+  systemcommands_age |**Optional.** Max age for systemcommands table rows (start_time). Defaults to 0 (never).
 
 ### LiveStatusListener
 
@@ -529,21 +531,27 @@ Attributes:
 
 ### CheckResultReader
 
-TODO
+Reads Icinga 1.x check results from a directory. This functionality is provided
+to help existing Icinga 1.x users and might be useful for certain cluster
+scenarios.
 
 Example:
 
-    TODO
+    library "compat"
+
+    object CheckResultReader "reader" {
+      spool_dir = "/data/check-results"
+    }
 
 Attributes:
 
   Name            |Description
   ----------------|----------------
-  spool\_dir      |TODO
+  spool\_dir      |**Optional.** The directory which contains the check result files. Defaults to IcingaLocalStateDir + "/lib/icinga2/spool/checkresults/".
 
 ### CheckerComponent
 
-TODO
+The checker component is responsible for scheduling active checks. There are no configurable options.
 
 Example:
 
@@ -553,7 +561,7 @@ Example:
 
 ### NotificationComponent
 
-TODO
+The notification component is responsible for sending notifications. There are no configurable options.
 
 Example:
 

doc/4-icinga-template-library.md

@@ -0,0 +1,46 @@
+## Icinga Template Library
+
+TODO
+
+### Overview
+
+### Check Commands
+
+#### ping4
+
+#### ping6
+
+#### dummy
+
+#### tcp
+
+#### udp
+
+#### http_vhost
+
+#### http_ip
+
+#### https_vhost
+
+#### https_ip
+
+#### smtp
+
+#### ssmtp
+
+#### ntp_time
+
+#### ssh
+
+#### disk
+
+#### users
+
+#### processes
+
+#### load
+
+#### snmp
+
+#### snmp-uptime
+

doc/5-advanced-topics.md

@@ -1,5 +1,7 @@
 # Advanced Topics
 
+## Time Periods
+
 ## External Commands
 
 TODO