Update documentation.

doc/.gitignore

@@ -0,0 +1 @@
+index.html

doc/1-about.md

@@ -4,8 +4,19 @@
 
 ### What is Icinga?
 
+Icinga 2 is a network monitoring application.
+
 ### Licensing
 
+Icinga 2 and the Icinga 2 documentation are licensed under the terms of the GNU
+General Public License Version 2, you will find a copy of this license in the
+LICENSE file included in the package.
+
 ### Support
 
-## What's New in Version 0.0.3
+Support for Icinga 2 is available in a number of ways. Please have a look at
+the support overview page at https://www.icinga.org/support/.
+
+## What's New in Version 0.0.3
+
+* Lots of things.

doc/2-getting-started.md

@@ -1,3 +1,218 @@
 # Getting Started
 
 ## Installation
+
+This tutorial is a step-by-step introduction to installing Icinga 2 and
+the standalone version of the Icinga 1.x classic web interface. It assumes
+that you are familiar with the system you're installing Icinga 2 on.
+
+### Installing Icinga 2
+
+In order to get started with Icinga 2 you will have to install it. The
+preferred way of doing this is to use the official Debian or RPM
+package repositories depending on which Linux distribution you are
+running.
+
+  Distribution            |Repository URL
+  ------------------------|---------------------------
+  Debian                  |http://packages.icinga.org/debian/
+  RHEL/CentOS 5           |http://packages.icinga.org/epel/5/release/
+  RHEL/CentOS 6           |http://packages.icinga.org/epel/6/release/
+
+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.
+
+In case you're running a distribution for which Icinga 2 packages are
+not yet available you will have to check out the Icinga 2 Git repository
+from git://git.icinga.org/icinga2 and read the *INSTALL* file.
+
+By default Icinga 2 uses the following files and directories:
+
+  Path                                |Description
+  ------------------------------------|------------------------------------
+  /etc/icinga2                        |Contains Icinga 2 configuration files.
+  /etc/init.d/icinga2                 |The Icinga 2 init script.
+  /usr/share/doc/icinga2              |Documentation files that come with Icinga 2.
+  /usr/share/icinga2/itl              |The Icinga Template Library.
+  /var/run/icinga2                    |Command pipe and PID file.
+  /var/cache/icinga2                  |Performance data files and status.dat/objects.cache.
+  /var/lib/icinga2                    |The Icinga 2 state file.
+
+An example configuration file is installed for you in /etc/icinga2/icinga2.conf.
+
+Here's a brief description of the concepts the example configuration file
+introduces:
+
+    /**
+     * Icinga 2 configuration file
+     * - this is where you define settings for the Icinga application including
+     * which hosts/services to check.
+     *
+     * The docs/icinga2-config.adoc file in the source tarball has a detailed
+     * description of what configuration options are available.
+     */
+
+Icinga 2 supports C- and C++-style comments.
+
+    include <itl/itl.conf>
+    include <itl/standalone.conf>
+
+The *include* directive can be used to include other files. The *itl/itl.conf*
+file defines a number of useful templates and constants you can use to
+configure your services.
+
+    /**
+     * Global macros
+     */
+    set IcingaMacros = {
+      plugindir = "/usr/local/icinga/libexec"
+    }
+
+Icinga 2 lets you define free-form macros. The IcingaMacros variable can be used
+to define global macros which are available in all command definitions.
+
+    /**
+     * The compat library periodically updates the status.dat and objects.cache
+     * files. These are used by the Icinga 1.x CGIs to display the state of
+     * hosts and services. CompatLog writeis the Icinga 1.x icinga.log and archives.
+     */
+    library "compat"
+
+Some of Icinga 2's functionality is available in separate libraries. These
+libraries usually implement their own object types that can be used to configure
+what you want the library to do.
+
+    object StatusDataWriter "status" { }
+    object ExternalCommandListener "command" { }
+    object CompatLogger "compat-log" { }
+
+Those three object types are provided by the *compat* library. The *StatusDataWriter*
+
+  Type                     | Description
+  StatusDataWriter         | Is responsible for writing the status.dat and objects.cache files.
+  ExternalCommandListener  | Implements the command pipe which is used by the CGIs to send commands to Icinga 2.
+  CompatLogger             | Writes log files in a format that is compatible with Icinga 1.x.
+
+    /**
+     * And finally we define some host that should be checked.
+     */
+    object Host "localhost" {
+      services["ping4"] = {
+        templates = [ "ping4" ]
+      },
+
+      services["ping6"] = {
+        templates = [ "ping6" ]
+      },
+
+      services["http"] = {
+        templates = [ "http_ip" ]
+      },
+
+      services["ssh"] = {
+        templates = [ "ssh" ]
+      },
+
+      services["load"] = {
+        templates = [ "load" ]
+      },
+
+      services["processes"] = {
+        templates = [ "processes" ]
+      },
+
+      services["users"] = {
+        templates = [ "users" ]
+      },
+
+      services["disk"] = {
+        templates = [ "disk" ]
+      },
+
+      macros = {
+        address = "127.0.0.1",
+        address6 = "::1",
+      },
+
+      check = "ping4",
+    }
+
+This defines a host named "localhost" which has a couple of services. Services
+may inherit from one or more service templates.
+
+The templates *ping4*, *ping6*, *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.
+
+### Installing the Icinga Classic UI
+
+Icinga 2 can write status.dat and objects.cache files in the format that
+is supported by the Icinga 1.x Classic UI. External commands (a.k.a. the
+"command pipe") are also supported. It also supports writing Icinga 1.x
+log files which are required for the reporting functionality in the Classic UI.
+
+These features are implemented as part of the "compat" library and are enabled
+by default in the example configuration file.
+
+You should be able to find the status.dat and objects.cache files in
+/var/cache/icinga2. The log files can be found in /var/log/icinga2/compat.
+The command pipe can be found in /var/run/icinga2.
+
+You can install the Icinga 1.x Classic UI in standalone mode using the
+following commands:
+
+    $ wget http://downloads.sourceforge.net/project/icinga/icinga/1.9.3/icinga-1.9.3.tar.gz
+    $ tar xzf icinga-1.9.3.tar.gz ; cd icinga-1.9.3
+    $ ./configure --enable-classicui-standalone --prefix=/usr/local/icinga2-classicui
+    $ make classicui-standalone
+    $ sudo make install classicui-standalone install-webconf-auth
+    $ sudo service apache2 restart
+
+> **Note**
+>
+> A detailed guide on installing Icinga 1.x Classic UI Standalone can be
+> 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)
+
+After installing the Classic UI you will need to update the following
+settings in your cgi.cfg configuration file in the "STANDALONE (ICINGA 2)
+OPTIONS" section:
+
+  Configuration Setting               |Value
+  ------------------------------------|------------------------------------
+  object\_cache\_file                 |/var/cache/icinga2/objects.cache
+  status\_file                        |/var/cache/icinga2/status.dat
+  resource\_file                      |-
+  command\_file                       |/var/run/icinga2/icinga2.cmd
+  check\_external\_commands           |1
+  interval\_length                    |60
+  status\_update\_interval            |10
+  log\_file                           |/var/log/icinga2/compat/icinga.log
+  log\_rotation\_method               |h
+  log\_archive\_path                  |/var/log/icinga2/compat/archives
+  date\_format                        |us
+  ------------------------------------ ------------------------------------
+
+> **Note**
+>
+> Depending on how you installed Icinga 2 some of those paths and options
+> might be different.
+
+In order for commands to work you will need to grant the web server
+write permissions for the command pipe:
+
+    # chgrp www-data /var/run/icinga2/icinga2.cmd
+    # chmod 660 /var/run/icinga2/icinga2.cmd
+
+> **Note**
+>
+> Change "www-data" to the group the Apache HTTP daemon is running as.
+
+Verify that your Icinga 1.x Classic UI works by browsing to your Classic
+UI installation URL, e.g.
+[http://localhost/icinga](http://localhost/icinga)

doc/3.1-configuration-syntax.md

@@ -146,10 +146,10 @@ Operators
 ---------
 
 In addition to the *=* operator shown above a number of other operators
-to manipulate configuration objects are supported. Here’s a list of all
+to manipulate configuration objects are supported. Here's a list of all
 available operators:
 
-### Operator *=*
+### Operator =
 
 Sets a dictionary element to the specified value.
 
@@ -162,7 +162,7 @@ Example:
 
 In this example a has the value 7 after both instructions are executed.
 
-### Operator *+=*
+### Operator +=
 
 Modifies a dictionary or array by adding new elements to it.
 
@@ -177,6 +177,7 @@ In this example a contains both *"hello"* and *"world"*. This currently
 only works for dictionaries and arrays.
 
 <!--
+
 ### Operator *-=*
 
 Removes elements from a dictionary.
@@ -220,6 +221,7 @@ Example:
 
 In this example a is 60. This only works for numbers. Not implemented
 yet.
+
 -->
 
 Attribute Shortcuts
@@ -273,7 +275,7 @@ templates though in general they are.
 > The final macros dictionary contains all 3 macros and the macro
 > *color* has the value *"blue"*.
 
-Parent objects are resolved in the order they’re specified using the
+Parent objects are resolved in the order they're specified using the
 *inherits* keyword.
 
 Variables
@@ -375,6 +377,7 @@ Example:
 > The *icinga* library is automatically loaded at startup.
 
 <!--
+
 Type Definition
 ---------------
 
@@ -413,7 +416,7 @@ The Pizza definition provides the following validation rules:
 -   Elements in the ingredients dictionary can be either a string or a
     dictionary.
 
--   If they’re a dictionary they may contain attributes *quantity* (of
+-   If they're a dictionary they may contain attributes *quantity* (of
     type number) and *name* (of type string).
 
 -   The script function *ValidateIngredients* is run to perform further
@@ -424,4 +427,5 @@ The Pizza definition provides the following validation rules:
 
 Valid types for type rules include: \* any \* number \* string \* scalar
 (an alias for string) \* dictionary
--->
+
+-->

doc/3.3-object-types.md

@@ -14,9 +14,9 @@ Example:
 
 Attributes:
 
+  Name            |Description
   ----------------|----------------
   severity        |**Optional.** The minimum severity for this log. Can be "debug", "information", "warning" or "critical". Defaults to "information".
-  ----------------|----------------
 
 FileLogger
 ----------
@@ -32,6 +32,7 @@ Example:
 
 Attributes:
 
+  Name            |Description
   ----------------|----------------
   path            |**Required.** The log path.
   severity        |**Optional.** The minimum severity for this log. Can be "debug", "information", "warning" or "critical". Defaults to "information".
@@ -49,6 +50,7 @@ Example:
 
 Attributes:
 
+  Name            |Description
   ----------------|----------------
   severity        |**Optional.** The minimum severity for this log. Can be "debug", "information", "warning" or "critical". Defaults to "information".
 
@@ -149,6 +151,7 @@ Example:
 
 Attributes:
 
+  Name            |Description
   ----------------|----------------
   host            |**Required.** The host this service belongs to. There must be a *Host* object with that name.
   short_name      |**Required.** The service name. Must be unique on a per-host basis (Similar to the service_description attribute in Icinga 1.x).
@@ -180,6 +183,7 @@ Example:
 
 Attributes:
 
+  Name            |Description
   ----------------|----------------
   display_name    |**Optional.** A short description of the service group.
 
@@ -194,6 +198,7 @@ Example:
 
 Attributes:
 
+  Name            |Description
   ----------------|----------------
   host            |TODO
   service         |TODO
@@ -218,6 +223,7 @@ Example:
 
 Attributes:
 
+  Name            |Description
   ----------------|----------------
   display_name    |TODO
   macros          |TODO
@@ -238,6 +244,7 @@ Example:
 
 Attributes:
 
+  Name            |Description
   ----------------|----------------
   display_name    |TODO
 
@@ -252,6 +259,7 @@ Example:
 
 Attributes:
 
+  Name            |Description
   ----------------|----------------
   display_name    |TODO
   methods         |TODO
@@ -268,6 +276,7 @@ Example:
 
 Attributes:
 
+  Name            |Description
   ----------------|----------------
   display_name    |TODO
 
@@ -282,6 +291,7 @@ Example:
 
 Attributes:
 
+  Name            |Description
   ----------------|----------------
   acl             |TODO
 
@@ -325,13 +335,14 @@ Example:
 
 Attributes:
 
+  Name            |Description
   ----------------|----------------
   display_name    |**Optional.** A short description of the host.
   check           |**Optional.** A service that is used to determine whether the host is up or down. This must be a service short name of a service that belongs to the host.
   groups          |**Optional.** A list of host groups this host belongs to.
   host_dependencies|**Optional.** An array of host names which this host depends on. These dependencies are used to determine whether the host is unreachable.
   service_dependencies|**Optional.** An array of service names 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.
-  services        |**Optional.** Inline definition of services. Each dictionary item specifies a service.<br /><br />The *templates* attribute can be used to specify an array of templates that should be inherited by the service.<br /><br />The new service’s name is "hostname:service" - where "service" is the dictionary key in the services dictionary.<br /><br />The dictionary key is used as the service's short name.
+  services        |**Optional.** Inline definition of services. Each dictionary item specifies a service.<br /><br />The *templates* attribute can be used to specify an array of templates that should be inherited by the service.<br /><br />The new service's name is "hostname:service" - where "service" is the dictionary key in the services dictionary.<br /><br />The dictionary key is used as the service's short name.
   macros          |TODO
 
 HostGroup
@@ -347,6 +358,7 @@ Example:
 
 Attributes:
 
+  Name            |Description
   ----------------|----------------
   display_name    |**Optional.** A short description of the host group.
 
@@ -368,6 +380,7 @@ Example
 
 Attributes:
 
+  Name            |Description
   ----------------|----------------
   perfdata\_path  |**Optional.** Path to the service perfdata file. Defaults to IcingaLocalStateDir + "/cache/icinga2/perfdata/perfdata".
   format\_template|**Optional.** Format template for the perfdata file. Defaults to a template that's suitable for use with PNP4Nagios.
@@ -400,11 +413,12 @@ Example:
 
 Attributes:
 
+  Name            |Description
   ----------------|----------------
   host            |**Optional.** MySQL database host address. Defaults to "localhost".
   port            |**Optional.** MySQL database port. Defaults to 3306.
   user            |**Optional.** MySQL database user with read/write permission to the icinga database. Defaults to "icinga".
-  password        |**Optional.** MySQL database user’s password. Defaults to "icinga".
+  password        |**Optional.** MySQL database user's password. Defaults to "icinga".
   database        |**Optional.** MySQL database name. Defaults to "icinga".
   table\_prefix   |**Optional.** MySQL database table prefix. Defaults to "icinga\_".
   instance\_name  |**Optional.** Unique identifier for the local Icinga 2 instance. Defaults to "default".
@@ -432,6 +446,7 @@ Example:
 
 Attributes:
 
+  Name            |Description
   ----------------|----------------
   socket\_type    |**Optional.** Specifies the socket type. Can be either "tcp" or "unix". Defaults to "unix".
   bind\_host      |**Optional.** Only valid when socket\_type is "tcp". Host address to listen on for connections. Defaults to "127.0.0.1".
@@ -453,6 +468,7 @@ Example:
 
 Attributes:
 
+  Name            |Description
   ----------------|----------------
   status\_path    |TODO
   objects\_path   |TODO
@@ -468,6 +484,7 @@ Example:
 
 Attributes:
 
+  Name            |Description
   ----------------|----------------
   command\_path   |TODO
 
@@ -482,6 +499,7 @@ Example:
 
 Attributes:
 
+  Name            |Description
   ----------------|----------------
   log\_dir        |TODO
   rotation\_method|TODO
@@ -497,6 +515,7 @@ Example:
 
 Attributes:
 
+  Name            |Description
   ----------------|----------------
   spool\_dir      |TODO
 
@@ -533,6 +552,7 @@ Example:
 
 Attributes:
 
+  Name            |Description
   ----------------|----------------
   cert\_path      |TODO
   ca\_path        |TODO
@@ -557,6 +577,7 @@ Example:
 
 Attributes:
 
+  Name            |Description
   ----------------|----------------
   node            |**Required.** The hostname/IP address of the remote Icinga 2 instance.
   service         |**Required.** The service name/port of the remote Icinga 2 instance.

doc/jquery.toc.min.js

@@ -0,0 +1,8 @@
+/*!
+ * toc - jQuery Table of Contents Plugin
+ * v0.1.2
+ * http://projects.jga.me/toc/
+ * copyright Greg Allen 2013
+ * MIT License
+*/
+(function(t){t.fn.toc=function(e){var n,i=this,r=t.extend({},jQuery.fn.toc.defaults,e),o=t(r.container),a=t(r.selectors,o),l=[],h=r.prefix+"-active",s=function(e){if(r.smoothScrolling){e.preventDefault();var n=t(e.target).attr("href"),o=t(n);t("body,html").animate({scrollTop:o.offset().top},400,"swing",function(){location.hash=n})}t("li",i).removeClass(h),t(e.target).parent().addClass(h)},c=function(){n&&clearTimeout(n),n=setTimeout(function(){for(var e,n=t(window).scrollTop(),o=0,a=l.length;a>o;o++)if(l[o]>=n){t("li",i).removeClass(h),e=t("li:eq("+(o-1)+")",i).addClass(h),r.onHighlight(e);break}},50)};return r.highlightOnScroll&&(t(window).bind("scroll",c),c()),this.each(function(){var e=t(this),n=t("<ul/>");a.each(function(i,o){var a=t(o);l.push(a.offset().top-r.highlightOffset),t("<span/>").attr("id",r.anchorName(i,o,r.prefix)).insertBefore(a);var h=t("<a/>").text(r.headerText(i,o,a)).attr("href","#"+r.anchorName(i,o,r.prefix)).bind("click",function(n){s(n),e.trigger("selected",t(this).attr("href"))}),c=t("<li/>").addClass(r.itemClass(i,o,a,r.prefix)).append(h);n.append(c)}),e.html(n)})},jQuery.fn.toc.defaults={container:"body",selectors:"h1,h2,h3",smoothScrolling:!0,prefix:"toc",onHighlight:function(){},highlightOnScroll:!0,highlightOffset:100,anchorName:function(t,e,n){return n+t},headerText:function(t,e,n){return n.text()},itemClass:function(t,e,n,i){return i+"-"+n[0].tagName.toLowerCase()}}})(jQuery);

doc/mkdoc.sh

@@ -3,17 +3,63 @@ cd -- `dirname $0`
 cat <<HTML
 <!DOCTYPE html>
 <html>
+<head>
+<link rel="stylesheet" type="text/css" href="toc.css" media="all" />
+<link rel="stylesheet" type="text/css" href="toc-print.css" media="print" />
 <xmp theme="united" style="display:none;">
 HTML
 
 for file in *.md; do
 	cat $file
-	echo
+	echo; echo
 done
 
 cat <<HTML
 </xmp>
 
 <script src="http://strapdownjs.com/v/0.2/strapdown.js"></script>
+<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.9.1/jquery.min.js"></script>
+<script src="jquery.toc.min.js"></script>
+<script>
+\$('div#content').prepend('<div id="toc"></div>');
+\$('#toc').toc({
+    'selectors': 'h1,h2,h3,h4,h5,h6'
+});
+</script>
+</head>
+<body>
+<div id="content" />
+<script>
+var indices = [];
+
+function addIndex() {
+  // jQuery will give all the HNs in document order
+  jQuery('h1,h2,h3,h4,h5,h6').each(function(i,e) {
+      var hIndex = parseInt(this.nodeName.substring(1)) - 1;
+
+      // just found a levelUp event
+      if (indices.length - 1 > hIndex) {
+        indices= indices.slice(0, hIndex + 1 );
+      }
+
+      // just found a levelDown event
+      if (indices[hIndex] == undefined) {
+         indices[hIndex] = 0;
+      }
+
+      // count + 1 at current level
+      indices[hIndex]++;
+
+      // display the full position in the hierarchy
+      jQuery(this).prepend(indices.join(".") + " ");
+
+  });
+}
+
+jQuery(document).ready(function() {
+  addIndex();
+});
+</script>
+</body>
 </html>
 HTML

doc/toc-print.css

@@ -0,0 +1,3 @@
+#toc {
+    display:none;
+}

doc/toc.css

@@ -0,0 +1,47 @@
+#toc {
+    top: 0px;
+    left: 0px;
+    height: 100%;
+    position: fixed;
+    background: #333;
+    box-shadow: inset -5px 0 5px 0px #000;
+    width: 250px;
+    padding-top: 20px;
+    color: #fff;
+    overflow:scroll;
+}
+
+#toc ul {
+    margin: 0;
+    padding: 0;
+    list-style: none;
+}
+
+#toc li {
+    padding: 5px 10px;
+}
+
+#toc a {
+    color: #fff;
+    text-decoration: none;
+    display: block;
+}
+
+#toc .toc-h1 {
+    font-size: 1.5em;
+}
+
+#toc .toc-h2 {
+    font-size: 1.2em;
+    padding-left: 10px;
+}
+
+#toc .toc-h3 {
+    padding-left: 20px;
+}
+
+#toc .toc-active {
+    background: #336699;
+    box-shadow: inset -5px 0px 10px -5px #000;
+}
+