--- /dev/null
+Icinga 2 Configuration
+======================
+
+:keywords: Icinga, documentation, configuration
+:description: Description of the Icinga 2 config
+
+Configuration Syntax
+--------------------
+
+Object Definition
+~~~~~~~~~~~~~~~~~
+
+Icinga 2 features an object-based configuration format. In order to define
+objects the 'object' keyword is used:
+
+-------------------------------------------------------------------------------
+object Host "host1.example.org" {
+ display_name = "host1",
+
+ check_interval = 30,
+ retry_interval = 15,
+
+ macros = {
+ address = "192.168.0.1"
+ }
+}
+-------------------------------------------------------------------------------
+
+NOTE: The Icinga 2 configuration format is agnostic to whitespaces and
+new-lines.
+
+Each object is uniquely identified by its type ('Host') and name
+('host1.example.org'). Objects can contain a comma-separated list of property
+declarations. The following data types are available for property values:
+
+Numeric Literals
+^^^^^^^^^^^^^^^^
+
+A floating-point number.
+
+Example:
+
+-------------------------------------------------------------------------------
+-27.3
+-------------------------------------------------------------------------------
+
+Duration Literal
+^^^^^^^^^^^^^^^^
+
+Similar to floating-point numbers except for that fact that they support
+suffixes to help with specifying time durations.
+
+Example:
+
+-------------------------------------------------------------------------------
+2.5m
+-------------------------------------------------------------------------------
+
+Supported suffixes include ms (milliseconds), s (seconds), m (minutes) and h (hours).
+
+String Literals
+^^^^^^^^^^^^^^^
+
+A string.
+
+Example:
+
+-------------------------------------------------------------------------------
+"Hello World!"
+-------------------------------------------------------------------------------
+
+Certain characters need to be escaped. The following escape sequences are supported:
+
+|===================================
+|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 by an ASCII character in
+octal encoding.
+
+Multiline String Literals
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Strings spanning multiple lines can be specified by enclosing them in {{{ and }}}.
+
+Example.
+
+-------------------------------------------------------------------------------
+{{{This
+is
+a multi-line
+string.}}}
+-------------------------------------------------------------------------------
+
+Boolean Literals
+^^^^^^^^^^^^^^^^
+
+The keywords 'true' and 'false' are equivalent to 1 and 0 respectively.
+
+Null Value
+^^^^^^^^^^
+
+The 'null' keyword can be used to specify an empty value.
+
+Dictionary
+^^^^^^^^^^
+
+An unordered list of key-value pairs. Keys must be unique and are compared in
+a case-insensitive manner.
+
+Individual key-value pairs must be separated from each other with a comma. The
+comma after the last key-value pair is optional.
+
+Example:
+
+-------------------------------------------------------------------------------
+{
+ address = "192.168.0.1",
+ port = 443
+}
+-------------------------------------------------------------------------------
+
+NOTE: Identifiers may not contain certain characters (e.g. space) or start with
+certain characters (e.g. digits). If you want to use a dictionary key that is
+not a valid identifier you can put the key in double quotes.
+
+NOTE: Setting a dictionary key to null causes the key to be removed from the
+dictionary.
+
+Array
+^^^^^
+
+An ordered list of values.
+
+Individual array elements must be separated from each other with a comma. The
+comma after the last element is optional.
+
+Example:
+
+-------------------------------------------------------------------------------
+[
+ "hello",
+ "world",
+ 42,
+ [ "a", "nested", "array" ]
+]
+-------------------------------------------------------------------------------
+
+NOTE: An array may simultaneously contain values of different types, e.g.
+strings and numbers.
+
+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 available
+operators:
+
+Operator '='
+^^^^^^^^^^^^
+
+Sets a dictionary element to the specified value.
+
+Example:
+
+-------------------------------------------------------------------------------
+{
+ a = 5,
+ a = 7
+}
+-------------------------------------------------------------------------------
+
+In this example a has the value 7 after both instructions are executed.
+
+Operator '+='
+^^^^^^^^^^^^^
+
+Modifies a dictionary or array by adding new elements to it.
+
+Example:
+
+-------------------------------------------------------------------------------
+{
+ a = [ "hello" ],
+ a += [ "world" ]
+}
+-------------------------------------------------------------------------------
+
+In this example a contains both '"hello"' and '"world"'. This currently only works
+for dictionaries and arrays. Support for numbers might be added later on.
+
+Operator '-='
+^^^^^^^^^^^^^
+
+Removes elements from a dictionary.
+
+Example:
+
+-------------------------------------------------------------------------------
+{
+ a = { "hello", "world" },
+ a -= { "world" }
+}
+-------------------------------------------------------------------------------
+
+In this example a contains '"hello"'. Trying to remove an item that does not
+exist is not an error. Not implemented yet.
+
+Operator '*='
+^^^^^^^^^^^^^
+
+Multiplies an existing dictionary element with the specified number. If the
+dictionary element does not already exist 0 is used as its value.
+
+Example:
+
+-------------------------------------------------------------------------------
+{
+ a = 60,
+ a *= 5
+}
+-------------------------------------------------------------------------------
+
+In this example a is 300. This only works for numbers. Not implemented yet.
+
+Operator '/='
+^^^^^^^^^^^^^
+
+Divides an existing dictionary element by the specified number. If the
+dictionary element does not already exist 0 is used as its value.
+
+Example:
+
+-------------------------------------------------------------------------------
+{
+ a = 300,
+ a /= 5
+}
+-------------------------------------------------------------------------------
+
+In this example a is 60. This only works for numbers. Not implemented yet.
+
+Attribute Shortcuts
+~~~~~~~~~~~~~~~~~~~
+
+Indexer Shortcut
+^^^^^^^^^^^^^^^^
+
+Example:
+
+-------------------------------------------------------------------------------
+{
+ hello["key"] = "world"
+}
+-------------------------------------------------------------------------------
+
+This is equivalent to writing:
+
+-------------------------------------------------------------------------------
+{
+ hello += {
+ key = "world"
+ }
+}
+-------------------------------------------------------------------------------
+
+Specifiers
+~~~~~~~~~~
+
+Objects can have specifiers that have special meaning. The following specifiers
+can be used (prefacing the 'object' keyword):
+
+Specifier 'abstract'
+^^^^^^^^^^^^^^^^^^^^
+
+This specifier identifies the object as a template which can be used by other
+object definitions. The object will not be instantiated on its own.
+
+Instead of using the 'abstract' specifier you can use the 'template' keyword
+which is a shorthand for writing 'abstract object':
+
+-------------------------------------------------------------------------------
+template Service "http" {
+ ...
+}
+-------------------------------------------------------------------------------
+
+Specifier 'local'
+^^^^^^^^^^^^^^^^^
+
+This specifier disables replication for this object. The object will not be
+sent to remote Icinga instances.
+
+Inheritance
+~~~~~~~~~~~
+
+Objects can inherit attributes from one or more other objects.
+
+Example:
+
+-------------------------------------------------------------------------------
+template Host "default-host" {
+ check_interval = 30,
+
+ macros = {
+ color = "red"
+ }
+}
+
+template Host "test-host" inherits "default-host" {
+ macros += {
+ color = "blue"
+ }
+}
+
+object Host "localhost" inherits "test-host" {
+ macros += {
+ address = "127.0.0.1",
+ address6 = "::1"
+ }
+}
+-------------------------------------------------------------------------------
+
+NOTE: The '"default-host"' and '"test-host"' objects are marked as templates using
+the 'abstract' keyword. Parent objects do not necessarily have to be 'abstract'
+though in general they are.
+
+NOTE: The += operator is used to insert additional properties into the macros
+dictionary. The final dictionary contains all 3 macros and the property 'color'
+has the value '"blue"'.
+
+Parent objects are resolved in the order they're specified using the 'inherits'
+keyword.
+
+Comments
+~~~~~~~~
+
+The Icinga 2 configuration format supports C/C++-style comments.
+
+Example:
+
+-------------------------------------------------------------------------------
+/*
+ This is a comment.
+ */
+object Host "localhost" {
+ check_interval = 30, // this is also a comment.
+ retry_interval = 15
+}
+-------------------------------------------------------------------------------
+
+Includes
+~~~~~~~~
+
+Other configuration files can be included using the 'include' directive. Paths
+must be relative to the configuration file that contains the 'include'
+directive.
+
+Example:
+
+-------------------------------------------------------------------------------
+include "some/other/file.conf"
+include "conf.d/*.conf"
+-------------------------------------------------------------------------------
+
+NOTE: Wildcard includes are not recursive.
+
+Icinga also supports include search paths similar to how they work in a
+C/C++ compiler:
+
+-------------------------------------------------------------------------------
+include <itl/itl.conf>
+-------------------------------------------------------------------------------
+
+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 paths.
+
+Wildcards are not permitted when using angle brackets.
+
+Library directive
+~~~~~~~~~~~~~~~~~
+
+The 'library' directive can be used to manually load additional libraries.
+Upon loading these libraries may provide additional types or methods.
+
+Example:
+
+-------------------------------------------------------------------------------
+library "snmphelper"
+-------------------------------------------------------------------------------
+
+NOTE: The 'icinga' library is automatically loaded at startup.
+
+Type Definition
+~~~~~~~~~~~~~~~
+
+By default Icinga has no way of semantically verifying its configuration
+objects. This is where type definitions come in. Using type definitions you
+can specify which attributes are allowed in an object definition.
+
+Example:
+
+-------------------------------------------------------------------------------
+type Pizza {
+ %require "radius",
+ %attribute number "radius",
+
+ %attribute dictionary "ingredients" {
+ %validator "ValidateIngredients",
+
+ %attribute string "*",
+
+ %attribute dictionary "*" {
+ %attribute number "quantity",
+ %attribute string "name"
+ }
+ },
+
+ %attribute any "custom::*"
+}
+-------------------------------------------------------------------------------
+
+The Pizza definition provides the following validation rules:
+
+* Pizza objects must contain an attribute 'radius' which has to be a number.
+* Pizza objects may contain an attribute 'ingredients' which has to be a
+dictionary.
+* Elements in the ingredients dictionary can be either a string or a dictionary.
+* 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
+validation of the ingredients dictionary.
+* Pizza objects may contain attribute matching the pattern 'custom::*' of any
+type.
+
+Valid types for type rules include:
+* any
+* number
+* string
+* scalar (an alias for string)
+* dictionary
--- /dev/null
+Icinga 2 Configuration
+======================
+
+:keywords: Icinga, documentation, installation, configuration, tutorial
+:description: Quick introduction to monitoring network services with Icinga 2
+
+Preface
+-------
+
+This tutorial is a step-by-step introduction to setting up Icinga 2 in order to
+monitor network services. It assumes some familiarity with Icinga 1.x.
+
+Installation
+------------
+
+In order to get started with Icinga 2 we will have to install it. The preferred way
+of doing this is to use Debian or RPM packages depending on which Linux distribution
+you are running.
+
+<INSERT LIST OF PACKAGES HERE>
+
+In case you're running a distribution for which Icinga 2 packages are not available
+you will have to check out the Icinga 2 git repository from git://git.icinga.org/icinga2
+and run the "autogen.sh" script and follow its instructions to get Icinga 2 installed.
+
+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 (a collection of configuration fragments).
+|/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.
+|===
+
+Our First Service Check
+-----------------------
+
+The Icinga 2 package comes with a number of example configuration files. However, in order
+to explain some of the basics we're going write our own configuration file from scratch.
+
+Start by creating the file /etc/icinga2/icinga2.conf with the following content:
+
+-------------------------------------------------------------------------------
+include <itl/itl.conf>
+include <itl/standalone.conf>
+
+local object IcingaApplication "my-icinga" {
+ macros["plugindir"] = "/usr/lib/nagios/plugins"
+}
+-------------------------------------------------------------------------------
+
+The configuration snippet includes the "itl/itl.conf" and "itl/standalone.conf" files
+which are distributed as part of Icinga 2. The Icinga Template Library (ITL) is a
+collection of templates for commonly used templates.
+
+The "itl/standalone.conf" configuration file takes care of configuring Icinga 2 for
+single-instance (i.e. non-clustered) mode.
+
+Our configuration file also creates an object of type 'IcingaApplication' with the
+name 'my-icinga'. The 'IcingaApplication' type can be used to define global macros and some
+other global settings.
+
+For now we're only setting one global macro named 'plugindir' which you may need to update
+with your plugin directory's path.
+
+You can verify that your configuration file works by starting Icinga 2:
+
+-------------------------------------------------------------------------------
+$ /usr/sbin/icinga2 -c /etc/icinga2/icinga2.conf
+[2013/04/23 13:36:20 +0200] <Main Thread> information/icinga-app: Icinga application loader (version: 0.0.1, git branch master, commit 0fcbfdb2)
+[2013/04/23 13:36:20 +0200] <Main Thread> information/base: Adding library search dir: /usr/lib/icinga2
+[2013/04/23 13:36:20 +0200] <Main Thread> information/base: Loading library 'libicinga.la'
+[2013/04/23 13:36:20 +0200] <Main Thread> information/config: Adding include search dir: /usr/share/icinga2
+[2013/04/23 13:36:20 +0200] <Main Thread> information/config: Compiling config file: /etc/icinga2/icinga2.conf
+[2013/04/23 13:36:20 +0200] <Main Thread> information/config: Linking config items...
+[2013/04/23 13:36:20 +0200] <Main Thread> information/config: Validating config items...
+[2013/04/23 13:36:20 +0200] <Main Thread> information/config: Activating config items in compilation unit 'b2d21c28-a2e8-4fcb-ba00-45646bc1afb9'
+[2013/04/23 13:36:20 +0200] <Main Thread> information/base: Restoring program state from file '/var/lib/icinga2/icinga2.state'
+[2013/04/23 13:36:20 +0200] <Main Thread> information/base: Restored 0 objects
+-------------------------------------------------------------------------------
+
+In case there are any configuration errors Icinga 2 should print error messages
+containing details about what went wrong.
+
+You can stop Icinga 2 by hitting Control-C:
+
+-------------------------------------------------------------------------------
+^C
+[2013/04/23 13:39:39 +0200] <TP 0x7f2e9070f500 Worker #0> information/base: Shutting down Icinga...
+[2013/04/23 13:39:39 +0200] <TP 0x7f2e9070f500 Worker #0> information/base: Dumping program state to file '/var/lib/icinga2/icinga2.state'
+[2013/04/23 13:39:39 +0200] <Main Thread> information/icinga: Icinga has shut down.
+$
+-------------------------------------------------------------------------------
+
+Icinga 2 automatically saves its current state every couple of minutes and when it's being shut down.
+
+So far our Icinga 2 setup doesn't do much. Lets change that by setting up a service check for localhost. Edit your
+'icinga2.conf' configuration file by adding the following lines:
+
+-------------------------------------------------------------------------------
+template Service "my-ping" inherits "plugin-service" {
+ check_command = [
+ "$plugindir$/check_ping",
+ "-H", "$address$",
+ "-w", "10,5%",
+ "-c", "25,10%"
+ ]
+}
+
+object Host "localhost" {
+ display_name = "Home, sweet home!",
+
+ services["ping"] = {
+ templates = [ "my-ping" ]
+ },
+
+ macros = {
+ address = "127.0.0.1"
+ },
+
+ check_interval = 10s,
+
+ hostcheck = "ping"
+}
+-------------------------------------------------------------------------------
+
+We're defining a service template called "my-ping" which inherits from the
+'plugin-service' template. The 'plugin-service' template is provided as part of
+the ITL and describes how services are checked. In the case of plugin-based services
+this means that the command specified by the 'check_command' property is executed.
+
+The 'check_command' property is an array or command-line arguments for the check
+plugin. Alternatively you can specify the check command as a string.
+
+The check command can make use of macros. Unlike in Icinga 1.x we have free-form
+macros which means that users can choose arbitrary names for their macros.
+
+By convention the following macros are usually used:
+
+|===
+|Macro |Description
+|plugindir |The path of your check plugins.
+|address |The IPv4 address of the host.
+|address6 |The IPv6 address of the host.
+|===
+
+Note how the 'my-ping' template does not define a value for the 'address' macro. This
+is perfectly fine as long as that macro is defined somewhere else (e.g. in the host).
+
+Next we're defining a 'Host' object with name 'localhost'. We're setting an optional
+display_name which is used by the CGIs when showing that host in the host list.
+
+The services dictionary defines which services belong to a host. Using the [] indexing
+operator we can manipulate individual items in this dictionary. In this case we're creating
+a new service called 'ping'.
+
+The templates array inside the service definition lists all the templates we want to use
+for this particular service. For now we're just listing our 'my-ping' template.
+
+Remember how we used the 'address' macro in the 'check_command' setting earlier? Now we're
+defining a value for this macro which is used for all services which belong to the 'localhost'
+Host object.
+
+We're also setting the check_interval for all services belonging to this host to
+10 seconds.
+
+NOTE: When you don't specify an explicit time unit Icinga 2 automatically assumes that
+you meant seconds.
+
+And finally we're defining which of the services we've defined before is used to define
+the host's state. Note that unlike in Icinga 1.x this just "clones" the service's state
+and does not cause any additional checks to be performed.
+
+Setting up the Icinga 1.x CGIs
+------------------------------
+
+Icinga 2 can write status.dat and objects.cache files in the format that is supported
+by the Icinga 1.x CGIs.
+
+In order to do this you will need to load the library 'compat' by adding the following lines
+to your configuration file:
+
+-------------------------------------------------------------------------------
+library "compat"
+
+local object CompatComponent "compat" { }
+-------------------------------------------------------------------------------
+
+After restarting Icinga 2 you should be able to find the status.dat and objects.cache files in
+/var/cache/icinga2.
+
+You can create symlinks in your Icinga 1.x installation directory to make the CGIs use
+Icinga 2's status files and its command pipe:
+
+-------------------------------------------------------------------------------
+cd /usr/local/icinga # Change this to your Icinga 1.x installation directory
+ln -sf /var/cache/icinga2/status.dat var/status.dat
+ln -sf /var/cache/icinga2/objects.cache var/objects.cache
+ln -sf /var/run/icinga2/icinga2.cmd var/rw/icinga.cmd
+-------------------------------------------------------------------------------
+
+Verify that your Icinga 1.x CGIs work by browsing to your CGI's installation URL.
+
+Some More Templates
+-------------------
+
+Now that we've got a work basic monitoring setup as well as the CGIs we can define
+a second host. Add the following lines to your configuration file:
+
+-------------------------------------------------------------------------------
+object Host "icinga.org" {
+ display_name = "Icinga Website",
+
+ services["ping"] = {
+ templates = [ "my-ping" ]
+ },
+
+ macros = {
+ address = "www.icinga.org"
+ },
+
+ check_interval = 10s,
+
+ hostcheck = "ping"
+}
+-------------------------------------------------------------------------------
+
+Restart your Icinga 2 instance and check the CGIs for your new service's state. Unless
+you have a low-latency network connection you will note that the service's state is 'CRITICAL'.
+
+Ideally we'd be able to specify different timeouts for our new service. Using macros we
+can easily do this.
+
+Start by replacing your 'my-ping' service template with this:
+
+-------------------------------------------------------------------------------
+template Service "my-ping" inherits "plugin-service" {
+ check_command = [
+ "$plugindir$/check_ping",
+ "-H", "$address$",
+ "-w", "$wrta$,$wpl$%",
+ "-c", "$crta$,$cpl$%"
+ ],
+
+ macros = {
+ wrta = 10,
+ wpl = 5,
+
+ crta = 25,
+ cpl = 10
+ }
+}
+-------------------------------------------------------------------------------
+
+We have replaced our hard-coded timeout values with macros and we're providing default
+values for these same macros right in the template definition.
+
+In order to oderride some of these macros for a specific host we need to update our
+host 'icinga.org' like this:
+
+-------------------------------------------------------------------------------
+object Host "icinga.org" {
+ display_name = "Icinga Website",
+
+ services["ping"] = {
+ templates = [ "my-ping" ],
+
+ macros += {
+ wrta = 100,
+ crta = 250
+ }
+ },
+
+ macros = {
+ address = "www.icinga.org"
+ },
+
+ check_interval = 10s,
+
+ hostcheck = "ping"
+}
+-------------------------------------------------------------------------------
+
+The '+=' operator allows us to selectively modify an existing dictionary. If we were
+to use the '=' operator instead we would have to provide values for all the macros from
+the 'my-ping' template.
+
+ITL
+---
+
+TODO
+
+Notifications
+-------------
+
+TODO
+
+Time Periods
+------------
+
+TODO
+
+Host/Service Groups
+-------------------
+
+TODO
projects / icinga2 / commitdiff