--- /dev/null
+Configuration Format
+====================
+
+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" {
+ alias = "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. No escape characters are supported at present though this will
+likely change.
+
+Example:
+
+ "Hello World!"
+
+### Expression List
+
+A list of expressions that when executed has a dictionary as a result.
+
+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.
+
+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 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 expression lists. 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
+-------------------
+
+### Value Shortcut
+
+Example:
+
+ {
+ "hello", "world"
+ }
+
+This is equivalent to writing:
+
+ {
+ _00000001 = "hello", _00000002 = "world"
+ }
+
+The item’s keys are monotonically increasing and the config compiler
+takes care of ensuring that all keys are unique (even when adding items
+to an existing attribute using +=).
+
+### 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 (before 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:
+
+ abstract object Host "default-host" {
+ check_interval = 30,
+
+ macros = {
+ color = "red"
+ }
+ }
+
+ abstract object 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. Parent objects must already be defined by the time
+they’re used in an object definition.
+
+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" keyword:
+
+Example:
+
+ #include "some/other/file.conf"
+ #include "conf.d/*.conf"
+
+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 classes
+or methods.
+
+Example:
+
+ #library "snmphelper"
+
+> **Note**
+>
+> The "icinga" library is automatically loaded by Icinga.
+
+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
+
+Configuration Objects
+=====================
+
+Type: IcingaApplication
+-----------------------
+
+The "IcingaApplication" type is used to specify global configuration
+parameters for Icinga. There must be exactly one application object in
+each Icinga 2 configuration. The object must have the "local" specifier.
+
+Example:
+
+ local object IcingaApplication "icinga" {
+ cert_path = "my-cert.pem",
+ ca_path = "ca.crt",
+
+ node = "192.168.0.1",
+ service = 7777,
+
+ pid_path = "/var/run/icinga2.pid",
+ state_path = "/var/lib/icinga2/icinga2.state",
+
+ macros = {
+ plugindir = "/usr/local/icinga/libexec"
+ }
+ }
+
+### Attribute: cert\_path
+
+This is used to specify the SSL client certificate Icinga 2 will use
+when connecting to other Icinga 2 instances. This property is optional
+when you’re setting up a non-networked Icinga 2 instance.
+
+### Attribute: ca\_path
+
+This is the public CA certificate that is used to verify connections
+from other Icinga 2 instances. This property is optional when you’re
+setting up a non-networked Icinga 2 instance.
+
+### Attribute: node
+
+The externally visible IP address that is used by other Icinga 2
+instances to connect to this instance. This property is optional when
+you’re setting up a non-networked Icinga 2 instance.
+
+> **Note**
+>
+> Icinga does not bind to this IP address.
+
+### Attribute: service
+
+The port this Icinga 2 instance should listen on. This property is
+optional when you’re setting up a non-networked Icinga 2 instance.
+
+### Attribute: pid\_path
+
+Optional. The path to the PID file. Defaults to "icinga.pid" in the
+current working directory.
+
+### Attribute: state\_path
+
+Optional. The path of the state file. This is the file Icinga 2 uses to
+persist objects between program runs. Defaults to "icinga2.state" in the
+current working directory.
+
+### Attribute: macros
+
+Optional. Global macros that are used for service checks and
+notifications.
+
+Type: Component
+---------------
+
+Icinga 2 uses a number of components to implement its feature-set. The
+"Component" configuration object is used to load these components and
+specify additional parameters for them. "Component" objects must have
+the "local" specifier. The typical components to be loaded in the
+default configuration would be "checker", "delegation" and more.
+
+Example "compat":
+
+ local object Component "compat" {
+ status_path = "/var/cache/icinga2/status.dat",
+ objects_path = "/var/cache/icinga2/objects.cache",
+ }
+
+### Attribute: status\_path
+
+Specifies where Icinga 2 Compat component will put the status.dat file,
+which can be read by Icinga 1.x Classic UI and other addons. If not set,
+it defaults to the localstatedir location.
+
+### Attribute: objects\_path
+
+Specifies where Icinga 2 Compat component will put the objects.cache
+file, which can be read by Icinga 1.x Classic UI and other addons. If
+not set, it defaults to the localstatedir location.
+
+Type: ConsoleLogger
+-------------------
+
+Specifies Icinga 2 logging to the console. Objects of this type must
+have the "local" specifier.
+
+Example:
+
+ local object ConsoleLogger "my-debug-console" {
+ severity = "debug"
+ }
+
+### Attribute: severity
+
+The minimum severity for this log. Can be "debug", "information",
+"warning" or "critical". Defaults to "information".
+
+Type: FileLogger
+----------------
+
+Specifies Icinga 2 logging to a file. Objects of this type must have the
+"local" specifier.
+
+Example:
+
+ local object FileLogger "my-debug-file" {
+ severity = "debug",
+ path = "/var/log/icinga2/icinga2-debug.log"
+ }
+
+### Attribute: path
+
+The log path.
+
+### Attribute: severity
+
+The minimum severity for this log. Can be "debug", "information",
+"warning" or "critical". Defaults to "information".
+
+Type: SyslogLogger
+------------------
+
+Specifies Icinga 2 logging to syslog. Objects of this type must have the
+"local" specifier.
+
+Example:
+
+ local object SyslogLogger "my-crit-syslog" {
+ severity = "critical"
+ }
+
+### Attribute: severity
+
+The minimum severity for this log. Can be "debug", "information",
+"warning" or "critical". Defaults to "information".
+
+Type: Endpoint
+--------------
+
+Endpoint objects are used to specify connection information for remote
+Icinga 2 instances. Objects of this type should not be local:
+
+ object Endpoint "icinga-c2" {
+ node = "192.168.5.46",
+ service = 7777,
+ }
+
+### Attribute: node
+
+The hostname/IP address of the remote Icinga 2 instance.
+
+### Attribute: service
+
+The service name/port of the remote Icinga 2 instance.
+
+Type: CheckCommand
+------------------
+
+A check command definition. Additional default command macros can be
+defined here.
+
+Example:
+
+ object CheckCommand "check_snmp" inherits "plugin-check-command" {
+ command = "$plugindir$/check_snmp -H $address$ -C $community$ -o $oid$",
+
+ macros = {2yy
+ plugindir = "/usr/lib/nagios/plugins",
+ address = "127.0.0.1",
+ community = "public",
+ }
+ }
+
+Type: NotificationCommand
+-------------------------
+
+A notification command definition.
+
+Example:
+
+ object NotificationCommand "mail-service-notification" inherits "plugin-notification-command" {
+ command = "/usr/bin/printf \"%b\" \"***** Icinga *****\n\nNotification Type: $NOTIFICATIONTYPE$\n\nService: $SERVICEDESC$\nHost: $HOSTALIAS$\nAddress: $HOSTADDRESS$\nState: $SERVICESTATE$\n\nDate/Time: $LONGDATETIME$\n\nAdditional Info: $SERVICEOUTPUT$\n\nComment: [$NOTIFICATIONAUTHORNAME$] $NOTIFICATIONCOMMENT$\n\n\" | /usr/bin/mail -s \"$NOTIFICATIONTYPE$ - $HOSTNAME$ - $SERVICEDESC$ - $SERVICESTATE$\" $CONTACTEMAIL$",
+ }
+
+Type: EventCommand
+
+ An event command definition.
+
+ NOTE: Similar to Icinga 1.x event handlers.
+
+ Example:
+
+ -------------------------------------------------------------------------------
+ object EventCommand "restart-httpd-event" inherits "plugin-event-command" {
+ command = "/usr/local/icinga/libexec/restart-httpd.sh",
+ }
+ -------------------------------------------------------------------------------
+
+
+ Type: Service
+
+Service objects describe network services and how they should be checked
+by Icinga 2.
+
+> **Note**
+>
+> Better create a service template and use that reference on the host
+> definition as shown below.
+
+Example:
+
+ object Service "localhost-uptime" {
+ host_name = "localhost",
+
+ alias = "localhost Uptime",
+
+ methods = {
+ check = "PluginCheck"
+ },
+
+ check_command = "check_snmp",
+
+ macros = {
+ plugindir = "/usr/lib/nagios/plugins",
+ address = "127.0.0.1",
+ community = "public",
+ oid = "DISMAN-EVENT-MIB::sysUpTimeInstance"
+ }
+
+ check_interval = 60s,
+ retry_interval = 15s,
+
+ servicegroups = { "all-services", "snmp" },
+
+ checkers = { "*" },
+ }
+
+### Attribute: host\_name
+
+The host this service belongs to. There must be a "Host" object with
+that name.
+
+### Attribute: alias
+
+Optional. A short description of the service.
+
+### Attribute: methods - check
+
+The check type of the service. For now only external check plugins are
+supported ("PluginCheck").
+
+### Attribute: check\_command
+
+Optional when not using the "external plugin" check type. The check
+command. May contain macros.
+
+### Attribute: check\_interval
+
+Optional. The check interval (in seconds).
+
+### Attribute: retry\_interval
+
+Optional. The retry interval (in seconds). This is used when the service
+is in a soft state.
+
+### Attribute: servicegroups
+
+Optional. The service groups this service belongs to.
+
+### Attribute: checkers
+
+Optional. A list of remote endpoints that may check this service.
+Wildcards can be used here.
+
+Type: ServiceGroup
+------------------
+
+A group of services.
+
+Example:
+
+ object ServiceGroup "snmp" {
+ alias = "SNMP services",
+
+ custom = {
+ notes_url = "http://www.example.org/",
+ action_url = "http://www.example.org/",
+ }
+ }
+
+### Attribute: alias
+
+Optional. A short description of the service group.
+
+### Attribute: notes\_url
+
+Optional. Notes URL. Used by the CGIs.
+
+### Attribute: action\_url
+
+Optional. Action URL. Used by the CGIs.
+
+Type: Host
+----------
+
+A host. Unlike in Icinga 1.x hosts are not checkable objects in Icinga
+2.
+
+Example:
+
+ object Host "localhost" {
+ alias = "The best host there is",
+
+ hostgroups = [ "all-hosts" ],
+
+ hostcheck = "ping",
+ dependencies = [ "router-ping" ]
+
+ services["ping"] = { templates = "ping" }
+ services["http"] = {
+ templates = "my-http",
+ macros = {
+ vhost = "test1.example.org",
+ port = 81
+ }
+ }
+
+ check_interval = 60m,
+ retry_interval = 15m,
+
+ servicegroups = [ "all-services" ],
+
+ checkers = { "*" },
+ }
+
+### Attribute: alias
+
+Optional. A short description of the host.
+
+### Attribute: hostgroups
+
+Optional. A list of host groups this host belongs to.
+
+### Attribute: hostcheck
+
+Optional. A service that is used to determine whether the host is up or
+down.
+
+### Attribute: hostdependencies
+
+Optional. A list of hosts that are used to determine whether the host is
+unreachable.
+
+### Attribute: servicedependencies
+
+Optional. A list of services that are used to determine whether the host
+is unreachable.
+
+### Attribute: services
+
+Inline definition of services. Each service name is defined in square
+brackets and got its own dictionary with attribute properties, such as
+the template service being used. All other service-related properties
+are additively copied into the new service object.
+
+The new service’s name is "hostname-service" - where "service" is the
+array key in the services array.
+
+The priority for service properties is (from highest to lowest):
+
+1. Properties specified in the dictionary of the inline service
+ definition
+
+2. Host properties
+
+3. Properties inherited from the new service’s parent object
+
+### Attribute: check\_interval
+
+Optional. Copied into inline service definitions. The host itself does
+not have any checks.
+
+### Attribute: retry\_interval
+
+Optional. Copied into inline service definitions. The host itself does
+not have any checks.
+
+### Attribute: servicegroups
+
+Optional. Copied into inline service definitions. The host itself does
+not have any checks.
+
+### Attribute: checkers
+
+Optional. Copied into inline service definitions. The host itself does
+not have any checks.
+
+Type: HostGroup
+---------------
+
+A group of hosts.
+
+Example
+
+ object HostGroup "my-hosts" {
+ alias = "My hosts",
+
+ notes_url = "http://www.example.org/",
+ action_url = "http://www.example.org/",
+ }
+
+### Attribute: alias
+
+Optional. A short description of the host group.
+
+### Attribute: notes\_url
+
+Optional. Notes URL. Used by the CGIs.
+
+### Attribute: action\_url
+
+Optional. Action URL. Used by the CGIs.
+
+Type: PerfdataWriter
+--------------------
+
+Write check result performance data to a defined path using macro
+pattern.
+
+Example
+
+ local object PerfdataWriter "pnp" {
+ perfdata_path = "/var/spool/icinga2/perfdata/service-perfdata",
+ format_template = "DATATYPE::SERVICEPERFDATA\tTIMET::$TIMET$\tHOSTNAME::$HOSTNAME$\tSERVICEDESC::$SERVICEDESC$\tSERVICEPERFDATA::$SERVICEPERFDATA$\tSERVICECHECKCOMMAND::$SERVICECHECKCOMMAND$\tHOSTSTATE::$HOSTSTATE$\tHOSTSTATETYPE::$HOSTSTATETYPE$\tSERVICESTATE::$SERVICESTATE$\tSERVICESTATETYPE::$SERVICESTATETYPE$",
+ rotation_interval = 15s,
+ }
+
+### Attribute: perfdata\_path
+
+Path to the service perfdata file.
+
+> **Note**
+>
+> Will be automatically rotated with timestamp suffix.
+
+### Attribute: format\_template
+
+Formatting of performance data output for graphing addons or other post
+processing.
+
+### Attribute: rotation\_interval
+
+Rotation interval for the file defined in *perfdata\_path*.
+
+Type: IdoMySqlConnection
+------------------------
+
+IDO DB schema compatible output into mysql database.
+
+Example
+
+ library "ido_mysql"
+ local object IdoMysqlDbConnection "mysql-ido" {
+ host = "127.0.0.1",
+ port = "3306",
+ user = "icinga",
+ password = "icinga",
+ database = "icinga",
+ table_prefix = "icinga_",
+ instance_name = "icinga2",
+ instance_description = "icinga2 dev instance"
+ }
+
+### Attribute: host
+
+MySQL database host address. Default is *localhost*.
+
+### Attribute: port
+
+MySQL database port. Default is *3306*.
+
+### Attribute: user
+
+MySQL database user with read/write permission to the icinga database.
+Default is *icinga*.
+
+### Attribute: password
+
+MySQL database user’s password. Default is *icinga*.
+
+### Attribute: database
+
+MySQL database name. Default is *icinga*.
+
+### Attribute: table\_prefix
+
+MySQL database table prefix. Default is *icinga\_*.
+
+### Attribute: instance\_name
+
+Unique identifier for the local Icinga 2 instance.
+
+### Attribute: instance\_description
+
+Optional. Description for the Icinga 2 instance.
+
+Type: LiveStatusComponent
+-------------------------
+
+Livestatus api interface available as tcp or unix socket.
+
+Example
+
+ library "livestatus"
+
+ local object LivestatusComponent "livestatus-tcp" {
+ socket_type = "tcp",
+ host = "127.0.0.1",
+ port = "6558"
+ }
+
+ local object LivestatusComponent "livestatus-unix" {
+ socket_type = "unix",
+ socket_path = "/var/run/icinga2/livestatus"
+ }
+
+### Attribute: socket\_type
+
+*tcp* or *unix* socket. Default is *unix*.
+
+> **Note**
+>
+> *unix* sockets are not supported on Windows.
+
+### Attribute: host
+
+Only valid when socket\_type="tcp". Host address to listen on for
+connections.
+
+### Attribute: port
+
+Only valid when socket\_type="tcp". Port to listen on for connections.
+
+### Attribute: socket\_path
+
+Only valid when socket\_type="unix". Local unix socket file. Not
+supported on Windows.
+
+Configuration Examples
+======================
+
+Non-networked minimal example
+-----------------------------
+
+> **Note**
+>
+> Icinga 2 ITL provides itl/standalone.conf which loads all required
+> components, as well as itl/itl.conf includes many object templates
+> already for an easy start with Icinga 2.
+
+ local object IcingaApplication "icinga" {
+
+ }
+
+ local object Component "checker" {
+
+ }
+
+ local object Component "delegation" {
+
+ }
+
+ object CheckCommand "ping" {
+ command = "$plugindir$/check_ping -H $address$ -w $wrta$,$wpl$% -c $crta$,$cpl$%",
+ }
+
+ template Service "icinga-service" {
+ methods = {
+ check = "PluginCheck"
+ },
+
+ macros = {
+ plugindir = "/usr/lib/nagios/plugins"
+ }
+ }
+
+ template Service "ping-tmpl" inherits "icinga-service" {
+ check_command = "ping",
+ macros += {
+ wrta = 50,
+ wpl = 5,
+ crta = 100,
+ cpl = 10
+ }
+ }
+
+ object Host "localhost" {
+ services["ping"] = { templates = "ping-tmpl" },
+
+ macros = {
+ address = "127.0.0.1"
+ },
+
+ check_interval = 10m
+ }
+
+> **Note**
+>
+> You may also want to load the "compat" component if you want Icinga 2
+> to write status.dat and objects.cache files.
+
+/\* vim: set syntax=asciidoc filetype=asciidoc: \*/
--- /dev/null
+Preface
+=======
+
+This tutorial is a step-by-step introduction to installing Icinga 2 and
+setting up your first couple of service checks. 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 the official Debian or RPM
+packages depending on which Linux distribution you are running.
+
+ ------------------------------------ ------------------------------------
+ Distribution Package URL
+
+ Debian [http://icingabuild.dus.dg-i.net:808
+ 0/job/icinga2/](http://icingabuild.d
+ us.dg-i.net:8080/job/icinga2/)
+
+ RHEL TBD
+ ------------------------------------ ------------------------------------
+
+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.
+ ------------------------------------ ------------------------------------
+
+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>
+
+ 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.
+We will discuss the Icinga Template Library (ITL) in more detail later
+on.
+
+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 defining the global macro *plugindir* which we’re
+going to use later on when referring to the path which contains our
+check plugins. Depending on where you’ve installed your check plugins
+you may need to update this path in your configuration file.
+
+You can verify that your configuration file works by starting Icinga 2:
+
+ $ /usr/bin/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 with 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. Modify your *icinga2.conf*
+configuration file by adding the following lines:
+
+ object CheckCommand "my-ping" inherits "plugin-check-command" {
+ command = [
+ "$plugindir$/check_ping",
+ "-H", "$address$",
+ "-w", "10,5%",
+ "-c", "25,10%"
+ ]
+ }
+
+ template Service "my-ping" inherits "plugin-service" {
+ check_command = "my-ping"
+ }
+
+ 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 command object called "my-ping" which inherits from the
+*plugin-check-command* template. The *plugin-check-command* template is
+provided as part of the Icinga Template Library and describes how checks
+are performed. In the case of plugin-based services this means that the
+command specified by the *command* property is executed.
+
+The *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 that the *my-ping* command object 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).
+
+We’re also defining a service template called *my-ping* which uses the
+command object we just created.
+
+Next we’re defining a *Host* object called *localhost*. We’re setting an
+optional display\_name which is used by the Icinga Classic UI when
+showing that host in the host overview.
+
+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 *command* setting
+earlier? Now we’re defining a value for this macro which is used for all
+services and their commands 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 specifying which of the services we’ve created 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 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. If you require the icinga.log for
+history views and/or reporting in Classic UI, this can be added
+seperately to the CompatComponent object definition by adding a
+CompatLog object.
+
+In order to enable this feature you will need to load the library
+*compat* by adding the following lines to your configuration file:
+
+ library "compat"
+
+ object CompatComponent "compat" { }
+ object CompatLog "my-log" { }
+
+After restarting Icinga 2 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.0/icinga-1.9.0.tar.gz
+ $ tar xzf icinga-1.9.0.tar.gz ; cd icinga-1.9.0
+ $ ./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 at the bottom (section
+"STANDALONE (ICINGA 2) OPTIONS"):
+
+ ------------------------------------ ------------------------------------
+ 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
+ ------------------------------------ ------------------------------------
+
+Depending on how you installed Icinga 2 some of those paths and options
+might be different.
+
+> **Note**
+>
+> You need to grant permissions for the apache user manually after
+> starting Icinga 2 for now.
+
+ # chmod o+rwx /var/run/icinga2/{icinga2.cmd,livestatus}
+
+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)
+
+Some More Templates
+===================
+
+Now that we’ve got our basic monitoring setup as well as the Icinga 1.x
+Classic UI to work 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 Classic UI for your new
+service’s state. Unless you have a low-latency network connection you
+will note that the service’s state is *CRITICAL*. This is because in the
+*my-ping* command object we have hard-coded the timeout as 25
+milliseconds.
+
+Ideally we’d be able to specify different timeouts for our new service.
+Using macros we can easily do this.
+
+> **Note**
+>
+> If you’ve used Icinga 1.x before you’re probably familiar with doing
+> this by passing ARGx macros to your check commands.
+
+Start by replacing your *my-ping* command object with this:
+
+ object CheckCommand "my-ping" inherits "plugin-check-command" {
+ 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. The object inherits the basic check command attributes from
+the ITL provided template *plugin-check-command*.
+
+In order to oderride some of these macros for a specific host we need to
+update our *icinga.org* host definition 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 add new key-value pairs to an
+existing dictionary. If we were to use the *=* operator instead we would
+have to provide values for all the macros that are used in the *my-ping*
+template overriding all values there.
+
+Icinga Template Library
+=======================
+
+The Icinga Template Library is a collection of configuration templates
+for commonly used services. By default it is installed in
+*/usr/share/icinga2/itl* and you can include it in your configuration
+files using the include directive:
+
+ include <itl/itl.conf>
+
+> **Note**
+>
+> Ordinarily you’d use double-quotes for the include path. This way only
+> paths relative to the current configuration file are considered. The
+> angle brackets tell Icinga 2 to search its list of global include
+> directories.
+
+One of the templates in the ITL is the *ping4* service template which is
+quite similar to our example objects:
+
+ object CheckCommand "ping4" 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
+ }
+ }
+
+ template Service "ping4" {
+ check_command = "ping4"
+ }
+
+Lets simplify our configuration file by removing our custom *my-ping*
+template and updating our service definitions to use the *ping4*
+template instead.
+
+Include Files
+=============
+
+So far we’ve been using just one configuration file. However, once
+you’ve created a few more host objects and service templates this can
+get rather confusing.
+
+Icinga 2 lets you include other files from your configuration file. We
+can use this feature to make our configuration a bit more modular and
+easier to understand.
+
+Lets start by moving our two *Host* objects to a separate configuration
+file: hosts.conf
+
+We will also need to tell Icinga 2 that it should include our newly
+created configuration file when parsing the main configuration file.
+This can be done by adding the include directive to our *icinga2.conf*
+file:
+
+ include "hosts.conf"
+
+Depending on the number of hosts you have it might be useful to split
+your configuration files based on other criteria (e.g. device type,
+location, etc.).
+
+You can use wildcards in the include path in order to refer to multiple
+files. Assuming you’re keeping your host configuration files in a
+directory called *hosts* you could include them like this:
+
+ include "hosts/*.conf"
+
+Notifications
+=============
+
+Icinga 2 can send you notifications when your services change state. In
+order to do this we’re going to write a shell script in
+*/etc/icinga2/mail-notification.sh* that sends e-mail based
+notifications:
+
+ #!/bin/sh
+
+ if [ -z "$1" ]; then
+ echo "Syntax: $0 <e-mail>"
+ echo
+ echo "Sends a mail notification to the specified e-mail address."
+ exit 1
+ fi
+
+ mail -s "** $NOTIFICATIONTYPE Service Alert: $HOSTALIAS/$SERVICEDESC is $SERVICESTATE **" $1 <<TEXT
+ ***** Icinga *****
+
+ Notification Type: $NOTIFICATIONTYPE
+
+ Service: $SERVICEDESC
+ Host: $HOSTALIAS
+ Address: $address
+ State: $SERVICESTATE
+
+ Date/Time: $LONGDATETIME
+
+ Additional Info:
+
+ $SERVICEOUTPUT
+ TEXT
+
+ exit 0
+
+Our shell script uses a couple of pre-defined macros (e.g. SERVICEDESC,
+HOSTALIAS, etc.) that are always available.
+
+Next we’re going to create a *Notification* template which tells Icinga
+how to invoke the shell script:
+
+ object NotificationCommand "mail-notification" inherits "plugin-notification-command" {
+ command = [
+ "/etc/icinga2/mail-notification.sh",
+ "$email$"
+ ],
+
+ export_macros = [
+ "NOTIFICATIONTYPE",
+ "HOSTALIAS",
+ "SERVICEDESC",
+ "SERVICESTATE",
+ "SERVICEDESC",
+ "address",
+ "LONGDATETIME",
+ "SERVICEOUTPUT"
+ ]
+ }
+
+ template Notification "mail-notification" {
+ notification_command = "mail-notification"
+ }
+
+> **Note**
+>
+> Rather than adding these templates to your main configuration file you
+> might want to create a separate file, e.g. *notifications.conf* and
+> include it in *icinga2.conf*.
+
+The *export\_macros* property tells Icinga which macros to export into
+the environment for the notification script.
+
+We also need to create a *User* object which Icinga can use to send
+notifications to specific people:
+
+ object User "tutorial-user" {
+ display_name = "Some User",
+
+ macros = {
+ email = "tutorial@example.org"
+ }
+ }
+
+Each time a notification is sent for a service the user’s macros are
+used when resolving the macros we used in the *Notification* template.
+
+In the next step we’re going to create a *Service* template which
+specifies who notifications should be sent to:
+
+ template Service "mail-notification-service" {
+ notifications["mail"] = {
+ templates = [ "mail-notification" ],
+
+ users = [ "tutorial-user" ]
+ },
+
+ notification_interval = 1m
+ }
+
+And finally we can assign this new service template to our services:
+
+ ...
+ services["ping"] = {
+ templates = [ "ping4", "mail-notification-service" ]
+ },
+ ...
+
+In addition to defining notifications for individual services it is also
+possible to assign notification templates to all services of a host. You
+can find more information about how to do that in the documentation.
+
+> **Note**
+>
+> Escalations in Icinga 2 are just a notification, only added a defined
+> begin and end time. Check the documentation for details.
+
+Time Periods
+============
+
+Time periods allow you to specify when certain services should be
+checked and when notifications should be sent.
+
+Here is an example time period definition:
+
+ object TimePeriod "work-hours" inherits "legacy-timeperiod" {
+ ranges = {
+ monday = "9:00-17:00",
+ tuesday = "9:00-17:00",
+ wednesday = "9:00-17:00",
+ thursday = "9:00-17:00",
+ friday = "9:00-17:00",
+ }
+ }
+
+The *legacy-timeperiod* template is defined in the Icinga Template
+Library and supports Icinga 1.x time periods. A complete definition of
+the time Icinga 1.x time period syntax can be found at
+[http://docs.icinga.org/latest/en/objectdefinitions.html\#timeperiod](http://docs.icinga.org/latest/en/objectdefinitions.html#timeperiod).
+
+Using the *check\_period* attribute you can define when services should
+be checked:
+
+ ...
+ services["ping"] = {
+ templates = [ "ping4", "mail-notification-service" ],
+ check_period = "work-hours"
+ },
+ ...
+
+Also, using the *notification\_period* attribute you can define when
+notifications should be sent:
+
+ template Service "mail-notification-service" {
+ notifications["mail"] = {
+ templates = [ "mail-notification" ],
+
+ users = [ "tutorial-user" ]
+ },
+
+ notification_interval = 1m,
+ notification_period = "work-hours"
+ }
+
+The *notification\_period* attribute is also valid in *User* and
+*Notification* objects.
+
+Dependencies
+============
+
+If you are familiar with Icinga 1.x host/service dependencies and
+parent/child relations on hosts, you might want to look at the
+conversion script in order to convert your existing configuration. There
+are no separate dependency objects anymore, and no separate parent
+attribute either.
+
+Using Icinga 2, we can directly define a dependency in the current host
+or service object to any other host or service object. If we want other
+objects to inherit those dependency attributes, we can also define them
+in a template.
+
+In the following example we’ve added a cluster host with the service
+*ping* which we are going to define a dependency for in another host.
+
+ template Service "my-cluster-ping" {
+ check_command = "my-ping",
+ }
+
+ object Host "my-cluster" {
+ ...
+ services["ping"] = {
+ templates = [ "my-cluster-ping" ],
+ }
+ ...
+ }
+
+We can now define a service dependency as new service template (or
+directly on the service definition):
+
+ template Service "my-cluster-dependency" {
+ servicedependencies = [
+ { host = "my-cluster", service = "ping" },
+ ],
+ }
+
+Now let’s use that template for the *ping* service we’ve defined
+previously and assign the servicedependencies to that service.
+
+ ...
+ services["ping"] = {
+ templates = [ "ping4", "mail-notification-service", "my-cluster-dependency" ],
+ },
+ ...
+
+Performance Data
+================
+
+Because there are no host checks in Icinga 2, the PerfdataWriter object
+will only write service performance data files. Creating the object will
+allow you to set the perfdata\_path, format\_template and
+rotation\_interval. The format template is similar to existing Icinga
+1.x configuration for PNP or inGraph using macro formatted strings.
+
+Details on the common Icinga 1.x macros can be found at
+[http://docs.icinga.org/latest/en/macrolist.html](http://docs.icinga.org/latest/en/macrolist.html)
+
+> **Note**
+>
+> You can define multiple PerfdataWriter objects with different
+> configuration settings, i.e. one for PNP, one for inGraph or your
+> preferred graphite collector.
+
+Let’s create a new PNP PerfdataWriter object:
+
+ object PerfdataWriter "pnp" {
+ perfdata_path = "/var/lib/icinga2/service-perfdata",
+ format_template = "DATATYPE::SERVICEPERFDATA\tTIMET::$TIMET$\tHOSTNAME::$HOSTNAME$\tSERVICEDESC::$SERVICEDESC$\tSERVICEPERFDATA::$SERVICEPERFDATA$\tSERVICECHECKCOMMAND::$SERVICECHECKCOMMAND$\tHOSTSTATE::$HOSTSTATE$\tHOSTSTATETYPE::$HOSTSTATETYPE$\tSERVICESTATE::$SERVICESTATE$\tSERVICESTATETYPE::$SERVICESTATETYPE$",
+ rotation_interval = 15s,
+ }
+
+You may need to reconfigure your NPCD daemon with the correct path for
+your performance data files. This can be done in the PNP configuration
+file npcd.cfg:
+
+ perfdata_spool_dir = /var/lib/icinga2/
+
+Livestatus Component
+====================
+
+The Livestatus component will provide access to Icinga 2 using the
+livestatus api. In addition to the unix socket Icinga 2 also service
+livestatus directly via tcp socket.
+
+> **Note**
+>
+> Only config and status tables are available at this time. History
+> tables such as log, statehist will follow.
+
+Once Icinga 2 is started, configure your gui (e.g. Thruk) using the
+livestatus backend.
+
+TCP Socket
+
+ library "livestatus"
+ object LivestatusComponent "livestatus-tcp" {
+ socket_type = "tcp",
+ host = "10.0.10.18",
+ port = "6558"
+ }
+
+Unix Socket
+
+ library "livestatus"
+ object LivestatusComponent "livestatus-unix" {
+ socket_type = "unix",
+ socket_path = "/var/run/icinga2/livestatus"
+ }
+
+> **Note**
+>
+> You need to grant permissions for the apache user manually after
+> starting Icinga 2 for now.
+
+ # chmod o+rwx /var/run/icinga2/{icinga2.cmd,livestatus}
+
+IDO Database Component
+======================
+
+The IDO component will write to the same database backend as known from
+Icinga 1.x IDOUtils. Therefore you’ll need to have your database schema
+and users already installed, like described in
+[http://docs.icinga.org/latest/en/quickstart-idoutils.html\#createidoutilsdatabase](http://docs.icinga.org/latest/en/quickstart-idoutils.html#createidoutilsdatabase)
+
+> **Note**
+>
+> Currently there’s only MySQL support in progress, Postgresql, Oracle
+> tbd.
+
+Configure the IDO MySQL component with the defined credentials and start
+Icinga 2.
+
+> **Note**
+>
+> Make sure to define a unique instance\_name. That way the Icinga 2 IDO
+> component will not interfere with your Icinga 1.x setup, if existing.
+
+ library "ido_mysql"
+ object IdoMysqlDbConnection "my-ido-mysql" {
+ host = "127.0.0.1",
+ port = "3306",
+ user = "icinga",
+ password = "icinga",
+ database = "icinga",
+ table_prefix = "icinga_",
+ instance_name = "icinga2",
+ instance_description = "icinga2 instance"
+ }
+
+Starting Icinga 2 in debug mode in foreground using -x will show all
+database queries.
+
+Custom Attributes
+=================
+
+In Icinga 1.x there were so-called "custom variables" available prefixed
+with an underscore, as well as plenty of other attributes such as
+action\_url, notes\_url, icon\_image, etc. To overcome the limitations
+of hardcoded custom attributes, Icinga 2 ships with the *custom*
+attribute as dictionary.
+
+For example, if you have PNP installed we could add a reference url to
+Icinga Classic UI by using the classic method of defining an
+action\_url.
+
+ template Service "my-pnp-svc" {
+ custom = {
+ action_url = "/pnp4nagios/graph?host=$HOSTNAME$&srv=$SERVICEDESC$' class='tips' rel='/pnp4nagios/popup?host=$HOSTNAME$&srv=$SERVICEDESC$",
+ }
+ }
+
+And add that template again to our service definition:
+
+ ...
+ services["ping"] = {
+ templates = [ "ping4", "mail-notification-service", "my-cluster-dependency", "my-pnp-svc" ],
+ },
+ ...
+
+While at it, our configuration tool will add its LDAP DN and a snmp
+community to the service too, using += for additive attributes:
+
+ ...
+ services["ping"] = {
+ templates = [ "ping4", "mail-notification-service", "my-cluster-dependency", "my-pnp-svc" ],
+ custom += {
+ DN = "cn=icinga2-dev-svc,ou=icinga,ou=main,ou=IcingaConfig,ou=LConf,dc=icinga,dc=org",
+ SNMPCOMMUNITY = "public"
+ }
+ },
+ ...
+
+/\* vim: set syntax=asciidoc filetype=asciidoc: \*/
--- /dev/null
+Icinga 2 Main
+=============
+
+Introduction
+------------
+
+A detailed introduction can be found in the chapter
+[Introduction](icinga2-intro.html). /\* TODO insert url \*/
+
+Installation
+------------
+
+For more information see the chapter Installation. /\* TODO insert url
+\*/
+
+Quick Example
+-------------
+
+/\* TODO \*/
+
+For a general tutorial see the chapter
+[Tutorial](icinga2-tutorial.html). /\* TODO insert url \*/
+
+Requirements
+------------
+
+/\* TODO \*/
+
+License
+-------
+
+Icinga 2 is licensed under the GPLv2 license, a copy of this license can
+be found in the LICENSE file on the main source tree.
+
+Community
+---------
+
+- [\#icinga](http://webchat.freenode.net/?channels=icinga) on the
+ Freenode IRC Network
+
+- [Mailinglists](https://lists.sourceforge.net/lists/listinfo/icinga-users)
+
+- [Monitoring Portal](http://www.monitoring-portal.org)
+
+More details at
+[http://www.icinga.org/support/](http://www.icinga.org/support/)
+
+Support
+-------
+
+For more information on the support options refer to
+[https://www.icinga.org/support](https://www.icinga.org/support)
+
+Chapters
+--------
+
+/\* TODO \*/
+
+/\* vim: set syntax=asciidoc filetype=asciidoc: \*/
+
+Icinga 2 Introduction
+=====================
+
+Icinga 2 is a network monitoring application that tries to improve upon
+the success of Icinga 1.x while fixing some of its shortcomings. A few
+frequently encountered issues are:
+
+- Scalability problems in large monitoring setups
+
+- Difficult configuration with dozens of "magic" tweaks and several
+ ways of defining services
+
+- Code quality and the resulting inability to implement changes
+ without breaking add-ons
+
+- Limited access to the runtime state of Icinga (e.g. for querying a
+ service’s state or for dynamically creating new services)
+
+Fixing these issues would involve major breaking changes to the Icinga
+1.x core and configuration syntax. Icinga users would likely experience
+plenty of problems with the Icinga versions introducing these changes.
+Many of these changes would likely break add-ons which rely on the NEB
+API and other core internals.
+
+From a developer standpoint this may be justifiable in order to get to a
+better end-product. However, for (business) users spending time on
+getting familiar with these changes for each new version may become
+quite frustrating and may easily cause users to lose their confidence in
+Icinga.
+
+Nagios™ 4 is currently following this approach and it remains to be seen
+how this fares with its users.
+
+Instead the Icinga project will maintain two active development
+branches. There will be one branch for Icinga 1.x which focuses on
+improving the existing Icinga 1.x code base - just like it has been done
+so far.
+
+Independently from Icinga 1.x development on Icinga 2 will happen in a
+separate branch and some of the long-term design goals will be outlined
+in this document. Status updates for Icinga 2 will be posted on the
+project website (www.icinga.org) as they become available.
+
+Code Quality
+------------
+
+Icinga 2 will not be using any code from the Icinga 1.x branch due to
+the rampant code quality issues with the existing code base. However, an
+important property of the Icinga development process has always been to
+rely on proven technologies and Icinga 2 will be no exception.
+
+A lot of effort has gone into designing a maintainable architecture for
+Icinga 2 and making sure that algorithmic choices are in alignment with
+our scalability goals for Icinga 2.
+
+There are plans to implement unit tests for most Icinga 2 features in
+order to make sure that changes to the code base do not break things
+that were known to work before.
+
+Language Choice
+---------------
+
+Icinga 1.x is written in C and while in general C has quite a number of
+advantages (e.g. performance and relatively easy portability to other
+\*NIX- based platforms) some of its disadvantages show in the context of
+a project that is as large as Icinga.
+
+With a complex software project like Icinga an object-oriented design
+helps tremendously with keeping things modular and making changes to the
+existing code easier.
+
+While it is true that you can write object-oriented software in C (the
+Linux kernel is one of the best examples of how to do that) a truly
+object-oriented language makes the programmers' life just a little bit
+easier.
+
+For Icinga 2 we have chosen C++ as the main language. This decision was
+influenced by a number of criteria including performance, support on
+different platforms and general user acceptability.
+
+In general there is nothing wrong with other languages like Java, C\# or
+Python; however - even when ignoring technical problems for just a
+moment - in a community as conservative as the monitoring community
+these languages seem out of place.
+
+Knowing that users will likely want to run Icinga 2 on older systems
+(which are still fully vendor-supported even for years to come) we will
+make every effort to ensure that Icinga 2 can be built and run on
+commonly used operating systems and refrain from using new and exotic
+features like C++11.
+
+Unlike Icinga 1.x there will be Windows support for Icinga 2. Some of
+the compatibility features (e.g. the command pipe) which rely on \*NIX
+features may not be supported on Windows but all new features will be
+designed in such a way as to support \*NIX as well as Windows.
+
+Configuration
+-------------
+
+Icinga 1.x has a configuration format that is fully backwards-compatible
+to the Nagios™ configuration format. This has the advantage of allowing
+users to easily upgrade their existing Nagios™ installations as well as
+downgrading if they choose to do so (even though this is generally not
+the case).
+
+The Nagios™ configuration format has evolved organically over time and
+for the most part it does what it’s supposed to do. However this
+evolutionary process has brought with it a number of problems that make
+it difficult for new users to understand the full breadth of available
+options and ways of setting up their monitoring environment.
+
+Experience with other configuration formats like the one used by Puppet
+has shown that it is often better to have a single "right" way of doing
+things rather than having multiple ways like Nagios™ does (e.g. defining
+host/service dependencies and parent/child relationships for hosts).
+
+Icinga 2 tries to fix those issues by introducing a new object-based
+configuration format that is heavily based on templates and supports
+user-friendly features like freely definable macros.
+
+External Interfaces
+-------------------
+
+While Icinga 1.x has easily accessible interfaces to its internal state
+(e.g. status.dat, objects.cache and the command pipe) there is no
+standards-based way of getting that information.
+
+For example, using Icinga’s status information in a custom script
+generally involves writing a parser for the status.dat format and there
+are literally dozens of Icinga-specific status.dat parsers out there.
+
+While Icinga 2 will support these legacy interfaces in order to make
+migration easier and allowing users to use the existing CGIs and
+whatever other scripts they may have Icinga 2 will focus on providing a
+unified interface to Icinga’s state and providing similar functionality
+to that provided by the command pipe in Icinga 1.x. The exact details
+for such an interface are yet to be determined but this will likely be
+an RPC interface based on one of the commonly used web-based remoting
+technologies.
+
+Icinga 1.x exports historical data using the IDO database interface
+(Icinga Data Output). Icinga 2 will support IDO in a
+backwards-compatible fashion in order to support icinga-web.
+Additionally there will be a newly-designed backend for historical data
+which can be queried using the built-in API when available. Effort will
+be put into making this new data source more efficient for use with SLA
+reporting.
+
+Icinga 2 will also feature dynamic reconfiguration using the API which
+means users can create, delete and update any configuration object (e.g.
+hosts and services) on-the-fly. Based on the API there are plans to
+implement a command-line configuration tool similar to what Pacemaker
+has with "crm". Later on this API may also be used to implement
+auto-discovery for new services.
+
+The RPC interface may also be used to receive events in real-time, e.g.
+when service checks are being executed or when a service’s state
+changes. Some possible uses of this interface would be to export
+performance data for services (RRD, graphite, etc.) or general log
+information (logstash, graylog2, etc.).
+
+Checks
+------
+
+In Icinga 2 services are the only checkable objects. Hosts only have a
+calculated state and no check are ever run for them.
+
+In order to maintain compatibility with the hundreds of existing check
+plugins for Icinga 1.x there will be support for Nagios™-style checks.
+The check interface however will be modular so that support for other
+kinds of checks can be implemented later on (e.g. built-in checks for
+commonly used services like PING, HTTP, etc. in order to avoid spawning
+a process for each check).
+
+Based on the availability of remote Icinga 2 instances the core can
+delegate execution of service checks to them in order to support
+large-scale distributed setups with a minimal amount of maintenance.
+Services can be assigned to specific check instances using configuration
+settings.
+
+Notifications
+-------------
+
+Event handlers and notifications will be supported similar to Icinga
+1.x. Thanks to the dynamic configuration it is possible to easily adjust
+the notification settings at runtime (e.g. in order to implement on-call
+rotation).
+
+Scalability
+-----------
+
+Icinga 1.x has some serious scalability issues which explains why there
+are several add-ons which try to improve the core’s check performance.
+One of these add-ons is mod\_gearman which can be used to distribute
+checks to multiple workers running on remote systems.
+
+A problem that remains is the performance of the core when processing
+check results. Scaling Icinga 1.x beyond 25.000 services proves to be a
+challenging problem and usually involves setting up a cascade of Icinga
+1.x instances and dividing the service checks between those instances.
+This significantly increases the maintenance overhead when updating the
+configuration for such a setup.
+
+Icinga 2 natively supports setting up multiple Icinga 2 instances in a
+cluster to distribute work between those instances. Independent tasks
+(e.g. performing service checks, sending notifications, updating the
+history database, etc.) are implemented as components which can be
+loaded for each instance. Configuration as well as program state is
+automatically replicated between instances.
+
+In order to support using Icinga 2 in a partially trusted environment
+SSL is used for all network communication between individual instances.
+Objects (like hosts and services) can be grouped into security domains
+for which permissions can be specified on a per-instance basis (so e.g.
+you can have a separate API or checker instance for a specific domain).
+
+Agent-based Checks
+------------------
+
+Traditionally most service checks have been performed actively, meaning
+that check plugins are executed on the same server that is also running
+Icinga. This works great for checking most network-based services, e.g.
+PING and HTTP. However, there are a number of services which cannot be
+checked remotely either because they are not network-based or because
+firewall settings or network policies ("no unencrypted traffic")
+disallow accessing these services from the network where Icinga is
+running.
+
+To solve this problem two add-ons have emerged, namely NRPE and NSCA.
+NRPE can be thought of as a light-weight remote shell which allows the
+execution of a restricted set of commands while supporting some
+Nagios™-specific concepts like command timeouts. However unlike with the
+design of commonly used protocols like SSH security in NRPE is merely an
+afterthought.
+
+In most monitoring setups all NRPE agents share the same secret key
+which is embedded into the NRPE binary at compile time. This means that
+users can extract this secret key from their NRPE agent binary and use
+it to query sensitive monitoring information from other systems running
+the same NRPE binary. NSCA has similar problems.
+
+Based on Icinga 2’s code for check execution there will be an agent
+which can be used on \*NIX as well as on Windows platforms. The agent
+will be using the same configuration format like Icinga 2 itself and
+will support SSL and IPv4/IPv6 to communicate with Icinga 2.
+
+Business Processes
+------------------
+
+In most cases users don’t care about the availability of individual
+services but rather the aggregated state of multiple related services.
+For example one might have a database cluster that is used for a web
+shop. For an end-user the shop is available as long as at least one of
+the database servers is working.
+
+Icinga 1.x does not have any support for business processes out of the
+box. There are several add-ons which implement business process support
+for Icinga, however none of those are well-integrated into Icinga.
+
+Icinga 2 will have native support for business processes which are built
+right into the core and can be configured in a similar manner to
+Nagios™-style checks. Users can define their own services based on
+business rules which can be used as dependencies for other hosts or
+services.
+
+Logging
+-------
+
+Icinga 2 supports file-based logged as well as syslog (on \*NIX) and
+event log (on Windows). Additionally Icinga 2 supports remote logging to
+a central Icinga 2 instance.
+
+Icinga 2 Installation
+=====================
+
+Requirements
+------------
+
+Packages
+--------
+
+> **Note**
+>
+> Use packages whenever possible.
+
+ ------------------------------------ ------------------------------------
+ Distribution Package URL
+ Debian TBD
+ RHEL/CentOS TBD
+ SLES TBD
+ ------------------------------------ ------------------------------------
+
+In case you’re running a distribution for which Icinga 2 packages are
+not yet available download the source tarball and jump to Source Builds.
+
+Windows Installer
+-----------------
+
+TODO
+
+Source Builds
+-------------
+
+Download the source tarball and read the *INSTALL* file for details and
+requirements.
+
+### Linux Builds
+
+Building from source on specific linux distributions is described on the
+wiki:
+[https://wiki.icinga.org/display/icinga2/Linux+Builds](https://wiki.icinga.org/display/icinga2/Linux+Builds)
+
+### Windows Builds
+
+Icinga 2 ships a MS Visual Studio solution file. Requirements and
+compilation instructions can be found on the wiki:
+[https://wiki.icinga.org/display/icinga2/Windows+Builds](https://wiki.icinga.org/display/icinga2/Windows+Builds)
+
+Installation Locations
+----------------------
+
+ ------------------------------------ ------------------------------------
+ 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.
+ ------------------------------------ ------------------------------------
+
+/\* TODO \*/
+
+/\* vim: set syntax=asciidoc filetype=asciidoc: \*/
+
+Icinga 2 Migration
+==================
+
+Purpose
+-------
+
+Documentation on the general migration from Icinga 1.x to Icinga 2.
+
+Requirements
+------------
+
+Multi-core cpu, ram, fast disks.
+
+Installation
+------------
+
+Icinga 1.x and Icinga 2 may run side by side, but it’s recommended to
+backup your existing 1.x installation before installing Icinga 2 on the
+same host.
+
+Compatibility
+-------------
+
+> **Note**
+>
+> The configuration format changed from 1.x to 2.x. Don’t panic though.
+> A conversion script is shipped in *tools/configconvert* - please check
+> the *README* file.
+
+For details check the chapter [Compatibility](icinga2-compat.html).
+
+Changes
+-------
+
+For details check the chapter [Changes](icinga2-compat.html).
+
+TODO
+
+/\* vim: set syntax=asciidoc filetype=asciidoc: \*/
+
+Icinga 2 Compatibility
+======================
+
+Purpose
+-------
+
+Documentation on the compatibility and changes introduced with Icinga 2.
+
+Introduction
+------------
+
+Unlike Icinga 1.x, all used components (not only those for
+compatibility) run asynchronous and use queues, if required. That way
+Icinga 2 does not get blocked by any event, action or execution.
+
+Configuration
+-------------
+
+> **Note**
+>
+> If you are upgrading from Icinga 1.x (or Nagios 3.x+) please note that
+> Icinga 2 introduces a new configuration format.
+
+Details on the configuration can be found in chapter
+[Configuration](:icinga2-config.html)
+
+Icinga 2 ships a config conversion script which will help you migrating
+the existing configuration into the new format. Please look into the
+*tools/configconvert* directory and follow the *README* instructions.
+
+> **Tip**
+>
+> If you kept planning to clean up your existing configuration, it may
+> be a good shot to start fresh with a new configuration strategy based
+> on the Icinga 2 configuration logic.
+
+Check Plugins
+-------------
+
+All native check plugins can be used with Icinga 2. The configuration of
+check commands is changed due to the new configuration format.
+
+Classic status and log files
+----------------------------
+
+Icinga 2 will write status.dat and objects.cache in a given interval
+like known from Icinga 1.x - including the logs and their archives in
+the old format and naming syntax. That way you can point any existing
+Classic UI installation to the new locations (or any other addon/plugin
+using them).
+
+External Commands
+-----------------
+
+Like known from Icinga 1.x, Icinga 2 also provides an external command
+pipe allowing your scripts and guis to send commands to the core
+triggering various actions.
+
+Some commands are not supported though as their triggered functionality
+is not available in Icinga 2 anymore.
+
+For a detailed list, please check:
+[https://wiki.icinga.org/display/icinga2/External+Commands](https://wiki.icinga.org/display/icinga2/External+Commands)
+
+Performance Data
+----------------
+
+The Icinga 1.x Plugin API defines the performance data format. Icinga 2
+parses the check output accordingly and writes performance data files
+based on template macros. File rotation interval can be defined as well.
+
+Unlike Icinga 1.x you can define multiple performance data writers for
+all your graphing addons such as PNP, inGraph or graphite.
+
+IDO DB
+------
+
+Icinga 1.x uses an addon called *IDOUtils* to store core configuration,
+status and historical information in a database schema. Icinga Web and
+Reporting are using that database as their chosen backend.
+
+Icinga 2 is compatible to the IDO db schema but the the underlaying
+design of inserting, updating and deleting data is different -
+asynchronous queueing, database transactions and optimized queries for
+performance.
+
+Furthermore there is no seperated daemon to receive the data through a
+socket. Instead the IDO component queues the data and writes directly
+into the database using the native database driver library (e.g.
+libmysqlclient). Unlike Icinga 1.x libdbi as db abstraction layer is not
+used anymore.
+
+Livestatus
+----------
+
+Icinga 2 supports the livestatus api while using Icinga 1.x an addon
+named *mk\_livestatus* was required.
+
+Next to the GET functionality for retrieving configuration, status and
+historical data, Icinga 2 livestatus also supports the COMMANDS
+functionality.
+
+> **Tip**
+>
+> Icinga 2 supports tcp sockets natively while the Icinga 1.x addon only
+> provides unix socket support.
+
+Checkresult Reaper
+------------------
+
+Unlike Icinga 1.x Icinga 2 is a multithreaded application and processes
+check results in memory. The old checkresult reaper reading files from
+disk again is obviously not required anymore for native checks.
+
+Some popular addons have been injecting their checkresults into the
+Icinga 1.x checkresult spool directory bypassing the external command
+pipe and PROCESS\_SERVICE\_CHECK\_RESULT mainly for performance reasons.
+
+In order to support that functionality as well, Icinga 2 got its
+optional checkresult reaper.
+
+Changes
+-------
+
+This is a collection of known changes in behaviour, configuration and
+outputs.
+
+> **Note**
+>
+> May be incomplete, and requires updates in the future.
+
+TODO
+
+/\* vim: set syntax=asciidoc filetype=asciidoc: \*/
+
+Icinga 2 Tutorial
+=================
+
+Preface
+-------
+
+This tutorial is a step-by-step introduction to installing Icinga 2 and
+setting up your first couple of service checks. 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 the official Debian or RPM
+packages depending on which Linux distribution you are running.
+
+ ------------------------------------ ------------------------------------
+ Distribution Package URL
+
+ Debian [http://icingabuild.dus.dg-i.net:808
+ 0/job/icinga2/](http://icingabuild.d
+ us.dg-i.net:8080/job/icinga2/)
+
+ RHEL TBD
+ ------------------------------------ ------------------------------------
+
+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.
+ ------------------------------------ ------------------------------------
+
+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>
+
+ 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.
+We will discuss the Icinga Template Library (ITL) in more detail later
+on.
+
+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 defining the global macro *plugindir* which we’re
+going to use later on when referring to the path which contains our
+check plugins. Depending on where you’ve installed your check plugins
+you may need to update this path in your configuration file.
+
+You can verify that your configuration file works by starting Icinga 2:
+
+ $ /usr/bin/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 with 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. Modify your *icinga2.conf*
+configuration file by adding the following lines:
+
+ object CheckCommand "my-ping" inherits "plugin-check-command" {
+ command = [
+ "$plugindir$/check_ping",
+ "-H", "$address$",
+ "-w", "10,5%",
+ "-c", "25,10%"
+ ]
+ }
+
+ template Service "my-ping" inherits "plugin-service" {
+ check_command = "my-ping"
+ }
+
+ 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 command object called "my-ping" which inherits from the
+*plugin-check-command* template. The *plugin-check-command* template is
+provided as part of the Icinga Template Library and describes how checks
+are performed. In the case of plugin-based services this means that the
+command specified by the *command* property is executed.
+
+The *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 that the *my-ping* command object 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).
+
+We’re also defining a service template called *my-ping* which uses the
+command object we just created.
+
+Next we’re defining a *Host* object called *localhost*. We’re setting an
+optional display\_name which is used by the Icinga Classic UI when
+showing that host in the host overview.
+
+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 *command* setting
+earlier? Now we’re defining a value for this macro which is used for all
+services and their commands 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 specifying which of the services we’ve created 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 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. If you require the icinga.log for
+history views and/or reporting in Classic UI, this can be added
+seperately to the CompatComponent object definition by adding a
+CompatLog object.
+
+In order to enable this feature you will need to load the library
+*compat* by adding the following lines to your configuration file:
+
+ library "compat"
+
+ object CompatComponent "compat" { }
+ object CompatLog "my-log" { }
+
+After restarting Icinga 2 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.0/icinga-1.9.0.tar.gz
+ $ tar xzf icinga-1.9.0.tar.gz ; cd icinga-1.9.0
+ $ ./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 at the bottom (section
+"STANDALONE (ICINGA 2) OPTIONS"):
+
+ ------------------------------------ ------------------------------------
+ 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
+ ------------------------------------ ------------------------------------
+
+Depending on how you installed Icinga 2 some of those paths and options
+might be different.
+
+> **Note**
+>
+> You need to grant permissions for the apache user manually after
+> starting Icinga 2 for now.
+
+ # chmod o+rwx /var/run/icinga2/{icinga2.cmd,livestatus}
+
+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)
+
+Some More Templates
+-------------------
+
+Now that we’ve got our basic monitoring setup as well as the Icinga 1.x
+Classic UI to work 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 Classic UI for your new
+service’s state. Unless you have a low-latency network connection you
+will note that the service’s state is *CRITICAL*. This is because in the
+*my-ping* command object we have hard-coded the timeout as 25
+milliseconds.
+
+Ideally we’d be able to specify different timeouts for our new service.
+Using macros we can easily do this.
+
+> **Note**
+>
+> If you’ve used Icinga 1.x before you’re probably familiar with doing
+> this by passing ARGx macros to your check commands.
+
+Start by replacing your *my-ping* command object with this:
+
+ object CheckCommand "my-ping" inherits "plugin-check-command" {
+ 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. The object inherits the basic check command attributes from
+the ITL provided template *plugin-check-command*.
+
+In order to oderride some of these macros for a specific host we need to
+update our *icinga.org* host definition 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 add new key-value pairs to an
+existing dictionary. If we were to use the *=* operator instead we would
+have to provide values for all the macros that are used in the *my-ping*
+template overriding all values there.
+
+Icinga Template Library
+-----------------------
+
+The Icinga Template Library is a collection of configuration templates
+for commonly used services. By default it is installed in
+*/usr/share/icinga2/itl* and you can include it in your configuration
+files using the include directive:
+
+ include <itl/itl.conf>
+
+> **Note**
+>
+> Ordinarily you’d use double-quotes for the include path. This way only
+> paths relative to the current configuration file are considered. The
+> angle brackets tell Icinga 2 to search its list of global include
+> directories.
+
+One of the templates in the ITL is the *ping4* service template which is
+quite similar to our example objects:
+
+ object CheckCommand "ping4" 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
+ }
+ }
+
+ template Service "ping4" {
+ check_command = "ping4"
+ }
+
+Lets simplify our configuration file by removing our custom *my-ping*
+template and updating our service definitions to use the *ping4*
+template instead.
+
+Include Files
+-------------
+
+So far we’ve been using just one configuration file. However, once
+you’ve created a few more host objects and service templates this can
+get rather confusing.
+
+Icinga 2 lets you include other files from your configuration file. We
+can use this feature to make our configuration a bit more modular and
+easier to understand.
+
+Lets start by moving our two *Host* objects to a separate configuration
+file: hosts.conf
+
+We will also need to tell Icinga 2 that it should include our newly
+created configuration file when parsing the main configuration file.
+This can be done by adding the include directive to our *icinga2.conf*
+file:
+
+ include "hosts.conf"
+
+Depending on the number of hosts you have it might be useful to split
+your configuration files based on other criteria (e.g. device type,
+location, etc.).
+
+You can use wildcards in the include path in order to refer to multiple
+files. Assuming you’re keeping your host configuration files in a
+directory called *hosts* you could include them like this:
+
+ include "hosts/*.conf"
+
+Notifications
+-------------
+
+Icinga 2 can send you notifications when your services change state. In
+order to do this we’re going to write a shell script in
+*/etc/icinga2/mail-notification.sh* that sends e-mail based
+notifications:
+
+ #!/bin/sh
+
+ if [ -z "$1" ]; then
+ echo "Syntax: $0 <e-mail>"
+ echo
+ echo "Sends a mail notification to the specified e-mail address."
+ exit 1
+ fi
+
+ mail -s "** $NOTIFICATIONTYPE Service Alert: $HOSTALIAS/$SERVICEDESC is $SERVICESTATE **" $1 <<TEXT
+ ***** Icinga *****
+
+ Notification Type: $NOTIFICATIONTYPE
+
+ Service: $SERVICEDESC
+ Host: $HOSTALIAS
+ Address: $address
+ State: $SERVICESTATE
+
+ Date/Time: $LONGDATETIME
+
+ Additional Info:
+
+ $SERVICEOUTPUT
+ TEXT
+
+ exit 0
+
+Our shell script uses a couple of pre-defined macros (e.g. SERVICEDESC,
+HOSTALIAS, etc.) that are always available.
+
+Next we’re going to create a *Notification* template which tells Icinga
+how to invoke the shell script:
+
+ object NotificationCommand "mail-notification" inherits "plugin-notification-command" {
+ command = [
+ "/etc/icinga2/mail-notification.sh",
+ "$email$"
+ ],
+
+ export_macros = [
+ "NOTIFICATIONTYPE",
+ "HOSTALIAS",
+ "SERVICEDESC",
+ "SERVICESTATE",
+ "SERVICEDESC",
+ "address",
+ "LONGDATETIME",
+ "SERVICEOUTPUT"
+ ]
+ }
+
+ template Notification "mail-notification" {
+ notification_command = "mail-notification"
+ }
+
+> **Note**
+>
+> Rather than adding these templates to your main configuration file you
+> might want to create a separate file, e.g. *notifications.conf* and
+> include it in *icinga2.conf*.
+
+The *export\_macros* property tells Icinga which macros to export into
+the environment for the notification script.
+
+We also need to create a *User* object which Icinga can use to send
+notifications to specific people:
+
+ object User "tutorial-user" {
+ display_name = "Some User",
+
+ macros = {
+ email = "tutorial@example.org"
+ }
+ }
+
+Each time a notification is sent for a service the user’s macros are
+used when resolving the macros we used in the *Notification* template.
+
+In the next step we’re going to create a *Service* template which
+specifies who notifications should be sent to:
+
+ template Service "mail-notification-service" {
+ notifications["mail"] = {
+ templates = [ "mail-notification" ],
+
+ users = [ "tutorial-user" ]
+ },
+
+ notification_interval = 1m
+ }
+
+And finally we can assign this new service template to our services:
+
+ ...
+ services["ping"] = {
+ templates = [ "ping4", "mail-notification-service" ]
+ },
+ ...
+
+In addition to defining notifications for individual services it is also
+possible to assign notification templates to all services of a host. You
+can find more information about how to do that in the documentation.
+
+> **Note**
+>
+> Escalations in Icinga 2 are just a notification, only added a defined
+> begin and end time. Check the documentation for details.
+
+Time Periods
+------------
+
+Time periods allow you to specify when certain services should be
+checked and when notifications should be sent.
+
+Here is an example time period definition:
+
+ object TimePeriod "work-hours" inherits "legacy-timeperiod" {
+ ranges = {
+ monday = "9:00-17:00",
+ tuesday = "9:00-17:00",
+ wednesday = "9:00-17:00",
+ thursday = "9:00-17:00",
+ friday = "9:00-17:00",
+ }
+ }
+
+The *legacy-timeperiod* template is defined in the Icinga Template
+Library and supports Icinga 1.x time periods. A complete definition of
+the time Icinga 1.x time period syntax can be found at
+[http://docs.icinga.org/latest/en/objectdefinitions.html\#timeperiod](http://docs.icinga.org/latest/en/objectdefinitions.html#timeperiod).
+
+Using the *check\_period* attribute you can define when services should
+be checked:
+
+ ...
+ services["ping"] = {
+ templates = [ "ping4", "mail-notification-service" ],
+ check_period = "work-hours"
+ },
+ ...
+
+Also, using the *notification\_period* attribute you can define when
+notifications should be sent:
+
+ template Service "mail-notification-service" {
+ notifications["mail"] = {
+ templates = [ "mail-notification" ],
+
+ users = [ "tutorial-user" ]
+ },
+
+ notification_interval = 1m,
+ notification_period = "work-hours"
+ }
+
+The *notification\_period* attribute is also valid in *User* and
+*Notification* objects.
+
+Dependencies
+------------
+
+If you are familiar with Icinga 1.x host/service dependencies and
+parent/child relations on hosts, you might want to look at the
+conversion script in order to convert your existing configuration. There
+are no separate dependency objects anymore, and no separate parent
+attribute either.
+
+Using Icinga 2, we can directly define a dependency in the current host
+or service object to any other host or service object. If we want other
+objects to inherit those dependency attributes, we can also define them
+in a template.
+
+In the following example we’ve added a cluster host with the service
+*ping* which we are going to define a dependency for in another host.
+
+ template Service "my-cluster-ping" {
+ check_command = "my-ping",
+ }
+
+ object Host "my-cluster" {
+ ...
+ services["ping"] = {
+ templates = [ "my-cluster-ping" ],
+ }
+ ...
+ }
+
+We can now define a service dependency as new service template (or
+directly on the service definition):
+
+ template Service "my-cluster-dependency" {
+ servicedependencies = [
+ { host = "my-cluster", service = "ping" },
+ ],
+ }
+
+Now let’s use that template for the *ping* service we’ve defined
+previously and assign the servicedependencies to that service.
+
+ ...
+ services["ping"] = {
+ templates = [ "ping4", "mail-notification-service", "my-cluster-dependency" ],
+ },
+ ...
+
+Performance Data
+----------------
+
+Because there are no host checks in Icinga 2, the PerfdataWriter object
+will only write service performance data files. Creating the object will
+allow you to set the perfdata\_path, format\_template and
+rotation\_interval. The format template is similar to existing Icinga
+1.x configuration for PNP or inGraph using macro formatted strings.
+
+Details on the common Icinga 1.x macros can be found at
+[http://docs.icinga.org/latest/en/macrolist.html](http://docs.icinga.org/latest/en/macrolist.html)
+
+> **Note**
+>
+> You can define multiple PerfdataWriter objects with different
+> configuration settings, i.e. one for PNP, one for inGraph or your
+> preferred graphite collector.
+
+Let’s create a new PNP PerfdataWriter object:
+
+ object PerfdataWriter "pnp" {
+ perfdata_path = "/var/lib/icinga2/service-perfdata",
+ format_template = "DATATYPE::SERVICEPERFDATA\tTIMET::$TIMET$\tHOSTNAME::$HOSTNAME$\tSERVICEDESC::$SERVICEDESC$\tSERVICEPERFDATA::$SERVICEPERFDATA$\tSERVICECHECKCOMMAND::$SERVICECHECKCOMMAND$\tHOSTSTATE::$HOSTSTATE$\tHOSTSTATETYPE::$HOSTSTATETYPE$\tSERVICESTATE::$SERVICESTATE$\tSERVICESTATETYPE::$SERVICESTATETYPE$",
+ rotation_interval = 15s,
+ }
+
+You may need to reconfigure your NPCD daemon with the correct path for
+your performance data files. This can be done in the PNP configuration
+file npcd.cfg:
+
+ perfdata_spool_dir = /var/lib/icinga2/
+
+Livestatus Component
+--------------------
+
+The Livestatus component will provide access to Icinga 2 using the
+livestatus api. In addition to the unix socket Icinga 2 also service
+livestatus directly via tcp socket.
+
+> **Note**
+>
+> Only config and status tables are available at this time. History
+> tables such as log, statehist will follow.
+
+Once Icinga 2 is started, configure your gui (e.g. Thruk) using the
+livestatus backend.
+
+TCP Socket
+
+ library "livestatus"
+ object LivestatusComponent "livestatus-tcp" {
+ socket_type = "tcp",
+ host = "10.0.10.18",
+ port = "6558"
+ }
+
+Unix Socket
+
+ library "livestatus"
+ object LivestatusComponent "livestatus-unix" {
+ socket_type = "unix",
+ socket_path = "/var/run/icinga2/livestatus"
+ }
+
+> **Note**
+>
+> You need to grant permissions for the apache user manually after
+> starting Icinga 2 for now.
+
+ # chmod o+rwx /var/run/icinga2/{icinga2.cmd,livestatus}
+
+IDO Database Component
+----------------------
+
+The IDO component will write to the same database backend as known from
+Icinga 1.x IDOUtils. Therefore you’ll need to have your database schema
+and users already installed, like described in
+[http://docs.icinga.org/latest/en/quickstart-idoutils.html\#createidoutilsdatabase](http://docs.icinga.org/latest/en/quickstart-idoutils.html#createidoutilsdatabase)
+
+> **Note**
+>
+> Currently there’s only MySQL support in progress, Postgresql, Oracle
+> tbd.
+
+Configure the IDO MySQL component with the defined credentials and start
+Icinga 2.
+
+> **Note**
+>
+> Make sure to define a unique instance\_name. That way the Icinga 2 IDO
+> component will not interfere with your Icinga 1.x setup, if existing.
+
+ library "ido_mysql"
+ object IdoMysqlDbConnection "my-ido-mysql" {
+ host = "127.0.0.1",
+ port = "3306",
+ user = "icinga",
+ password = "icinga",
+ database = "icinga",
+ table_prefix = "icinga_",
+ instance_name = "icinga2",
+ instance_description = "icinga2 instance"
+ }
+
+Starting Icinga 2 in debug mode in foreground using -x will show all
+database queries.
+
+Custom Attributes
+-----------------
+
+In Icinga 1.x there were so-called "custom variables" available prefixed
+with an underscore, as well as plenty of other attributes such as
+action\_url, notes\_url, icon\_image, etc. To overcome the limitations
+of hardcoded custom attributes, Icinga 2 ships with the *custom*
+attribute as dictionary.
+
+For example, if you have PNP installed we could add a reference url to
+Icinga Classic UI by using the classic method of defining an
+action\_url.
+
+ template Service "my-pnp-svc" {
+ custom = {
+ action_url = "/pnp4nagios/graph?host=$HOSTNAME$&srv=$SERVICEDESC$' class='tips' rel='/pnp4nagios/popup?host=$HOSTNAME$&srv=$SERVICEDESC$",
+ }
+ }
+
+And add that template again to our service definition:
+
+ ...
+ services["ping"] = {
+ templates = [ "ping4", "mail-notification-service", "my-cluster-dependency", "my-pnp-svc" ],
+ },
+ ...
+
+While at it, our configuration tool will add its LDAP DN and a snmp
+community to the service too, using += for additive attributes:
+
+ ...
+ services["ping"] = {
+ templates = [ "ping4", "mail-notification-service", "my-cluster-dependency", "my-pnp-svc" ],
+ custom += {
+ DN = "cn=icinga2-dev-svc,ou=icinga,ou=main,ou=IcingaConfig,ou=LConf,dc=icinga,dc=org",
+ SNMPCOMMUNITY = "public"
+ }
+ },
+ ...
+
+/\* vim: set syntax=asciidoc filetype=asciidoc: \*/
+
+Icinga 2 Configuration
+======================
+
+Configuration Introduction
+--------------------------
+
+In Icinga 2 configuration is based on objects. There’s no difference in
+defining global settings for the core application or for a specific
+runtime configuration object.
+
+There are different types for the main application, its components and
+tools. The runtime configuration objects such as hosts, services, etc
+are defined using the same syntax.
+
+Each configuration object must be unique by its name. Otherwise Icinga 2
+will bail early on verifying the parsed configuration.
+
+Main Configuration
+------------------
+
+Starting Icinga 2 requires the main configuration file called
+"icinga2.conf". That’s the location where everything is defined or
+included. Icinga 2 will only know the content of that file and included
+configuration file snippets.
+
+ # /usr/bin/icinga2 -c /etc/icinga2/icinga2.conf
+
+> **Note**
+>
+> You can use just the main configuration file and put everything in
+> there. Though that is not advised because configuration may be
+> expanded over time. Rather organize runtime configuration objects into
+> their own files and/or directories and include that in the main
+> configuration file.
+
+Configuration Syntax
+--------------------
+
+/\* TODO \*/
+
+Details on the syntax can be found in the chapter
+icinga2-config-syntax.html[Configuration Syntax]
+
+Configuration Types
+-------------------
+
+/\* TODO \*/
+
+Details on the available types can be found in the chapter
+icinga2-config-types.html[Configuration Types]
+
+Configuration Templates
+-----------------------
+
+Icinga 2 ships with the **Icinga Template Library (ITL)**. This is a set
+of predefined templates and definitions available in your actual
+configuration.
+
+> **Note**
+>
+> Do not change the ITL’s files. They will be overridden on upgrade.
+> Submit a patch upstream or include your very own configuration
+> snippet.
+
+Include the basic ITL set in your main configuration like
+
+ include <itl/itl.conf>
+
+> **Note**
+>
+> Icinga 2 recognizes the ITL’s installation path and looks for that
+> specific file then.
+
+Having Icinga 2 installed in standalone mode make sure to include
+itl/standalone.conf as well (see sample configuration).
+
+ include <itl/standalone.conf>
+
+/\* vim: set syntax=asciidoc filetype=asciidoc: \*/
+
+Icinga 2 Configuration Syntax
+=============================
+
+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.
+
+> **Note**
+>
+> Colons (:) are not permitted in object names.
+
+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
+
+Icinga 2 Configuration Types
+============================
+
+Configuration Format
+--------------------
+
+### 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" {
+ alias = "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. No escape characters are supported at present though this will
+likely change.
+
+Example:
+
+ "Hello World!"
+
+#### Expression List
+
+A list of expressions that when executed has a dictionary as a result.
+
+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.
+
+### 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 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 expression lists. 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
+
+#### Value Shortcut
+
+Example:
+
+ {
+ "hello", "world"
+ }
+
+This is equivalent to writing:
+
+ {
+ _00000001 = "hello", _00000002 = "world"
+ }
+
+The item’s keys are monotonically increasing and the config compiler
+takes care of ensuring that all keys are unique (even when adding items
+to an existing attribute using +=).
+
+#### 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 (before 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:
+
+ abstract object Host "default-host" {
+ check_interval = 30,
+
+ macros = {
+ color = "red"
+ }
+ }
+
+ abstract object 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. Parent objects must already be defined by the time
+they’re used in an object definition.
+
+### 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" keyword:
+
+Example:
+
+ #include "some/other/file.conf"
+ #include "conf.d/*.conf"
+
+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 classes
+or methods.
+
+Example:
+
+ #library "snmphelper"
+
+> **Note**
+>
+> The "icinga" library is automatically loaded by Icinga.
+
+### 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
+
+Configuration Objects
+---------------------
+
+### Type: IcingaApplication
+
+The "IcingaApplication" type is used to specify global configuration
+parameters for Icinga. There must be exactly one application object in
+each Icinga 2 configuration. The object must have the "local" specifier.
+
+Example:
+
+ local object IcingaApplication "icinga" {
+ cert_path = "my-cert.pem",
+ ca_path = "ca.crt",
+
+ node = "192.168.0.1",
+ service = 7777,
+
+ pid_path = "/var/run/icinga2.pid",
+ state_path = "/var/lib/icinga2/icinga2.state",
+
+ macros = {
+ plugindir = "/usr/local/icinga/libexec"
+ }
+ }
+
+#### Attribute: cert\_path
+
+This is used to specify the SSL client certificate Icinga 2 will use
+when connecting to other Icinga 2 instances. This property is optional
+when you’re setting up a non-networked Icinga 2 instance.
+
+#### Attribute: ca\_path
+
+This is the public CA certificate that is used to verify connections
+from other Icinga 2 instances. This property is optional when you’re
+setting up a non-networked Icinga 2 instance.
+
+#### Attribute: node
+
+The externally visible IP address that is used by other Icinga 2
+instances to connect to this instance. This property is optional when
+you’re setting up a non-networked Icinga 2 instance.
+
+> **Note**
+>
+> Icinga does not bind to this IP address.
+
+#### Attribute: service
+
+The port this Icinga 2 instance should listen on. This property is
+optional when you’re setting up a non-networked Icinga 2 instance.
+
+#### Attribute: pid\_path
+
+Optional. The path to the PID file. Defaults to "icinga.pid" in the
+current working directory.
+
+#### Attribute: state\_path
+
+Optional. The path of the state file. This is the file Icinga 2 uses to
+persist objects between program runs. Defaults to "icinga2.state" in the
+current working directory.
+
+#### Attribute: macros
+
+Optional. Global macros that are used for service checks and
+notifications.
+
+### Type: Component
+
+Icinga 2 uses a number of components to implement its feature-set. The
+"Component" configuration object is used to load these components and
+specify additional parameters for them. "Component" objects must have
+the "local" specifier. The typical components to be loaded in the
+default configuration would be "checker", "delegation" and more.
+
+Example "compat":
+
+ local object Component "compat" {
+ status_path = "/var/cache/icinga2/status.dat",
+ objects_path = "/var/cache/icinga2/objects.cache",
+ }
+
+#### Attribute: status\_path
+
+Specifies where Icinga 2 Compat component will put the status.dat file,
+which can be read by Icinga 1.x Classic UI and other addons. If not set,
+it defaults to the localstatedir location.
+
+#### Attribute: objects\_path
+
+Specifies where Icinga 2 Compat component will put the objects.cache
+file, which can be read by Icinga 1.x Classic UI and other addons. If
+not set, it defaults to the localstatedir location.
+
+### Type: ConsoleLogger
+
+Specifies Icinga 2 logging to the console. Objects of this type must
+have the "local" specifier.
+
+Example:
+
+ local object ConsoleLogger "my-debug-console" {
+ severity = "debug"
+ }
+
+#### Attribute: severity
+
+The minimum severity for this log. Can be "debug", "information",
+"warning" or "critical". Defaults to "information".
+
+### Type: FileLogger
+
+Specifies Icinga 2 logging to a file. Objects of this type must have the
+"local" specifier.
+
+Example:
+
+ local object FileLogger "my-debug-file" {
+ severity = "debug",
+ path = "/var/log/icinga2/icinga2-debug.log"
+ }
+
+#### Attribute: path
+
+The log path.
+
+#### Attribute: severity
+
+The minimum severity for this log. Can be "debug", "information",
+"warning" or "critical". Defaults to "information".
+
+### Type: SyslogLogger
+
+Specifies Icinga 2 logging to syslog. Objects of this type must have the
+"local" specifier.
+
+Example:
+
+ local object SyslogLogger "my-crit-syslog" {
+ severity = "critical"
+ }
+
+#### Attribute: severity
+
+The minimum severity for this log. Can be "debug", "information",
+"warning" or "critical". Defaults to "information".
+
+### Type: Endpoint
+
+Endpoint objects are used to specify connection information for remote
+Icinga 2 instances. Objects of this type should not be local:
+
+ object Endpoint "icinga-c2" {
+ node = "192.168.5.46",
+ service = 7777,
+ }
+
+#### Attribute: node
+
+The hostname/IP address of the remote Icinga 2 instance.
+
+#### Attribute: service
+
+The service name/port of the remote Icinga 2 instance.
+
+### Type: CheckCommand
+
+A check command definition. Additional default command macros can be
+defined here.
+
+Example:
+
+ object CheckCommand "check_snmp" inherits "plugin-check-command" {
+ command = "$plugindir$/check_snmp -H $address$ -C $community$ -o $oid$",
+
+ macros = {2yy
+ plugindir = "/usr/lib/nagios/plugins",
+ address = "127.0.0.1",
+ community = "public",
+ }
+ }
+
+### Type: NotificationCommand
+
+A notification command definition.
+
+Example:
+
+ object NotificationCommand "mail-service-notification" inherits "plugin-notification-command" {
+ command = "/usr/bin/printf \"%b\" \"***** Icinga *****\n\nNotification Type: $NOTIFICATIONTYPE$\n\nService: $SERVICEDESC$\nHost: $HOSTALIAS$\nAddress: $HOSTADDRESS$\nState: $SERVICESTATE$\n\nDate/Time: $LONGDATETIME$\n\nAdditional Info: $SERVICEOUTPUT$\n\nComment: [$NOTIFICATIONAUTHORNAME$] $NOTIFICATIONCOMMENT$\n\n\" | /usr/bin/mail -s \"$NOTIFICATIONTYPE$ - $HOSTNAME$ - $SERVICEDESC$ - $SERVICESTATE$\" $CONTACTEMAIL$",
+ }
+
+Type: EventCommand
+
+ An event command definition.
+
+ NOTE: Similar to Icinga 1.x event handlers.
+
+ Example:
+
+ -------------------------------------------------------------------------------
+ object EventCommand "restart-httpd-event" inherits "plugin-event-command" {
+ command = "/usr/local/icinga/libexec/restart-httpd.sh",
+ }
+ -------------------------------------------------------------------------------
+
+
+ Type: Service
+
+Service objects describe network services and how they should be checked
+by Icinga 2.
+
+> **Note**
+>
+> Better create a service template and use that reference on the host
+> definition as shown below.
+
+Example:
+
+ object Service "localhost-uptime" {
+ host_name = "localhost",
+
+ alias = "localhost Uptime",
+
+ methods = {
+ check = "PluginCheck"
+ },
+
+ check_command = "check_snmp",
+
+ macros = {
+ plugindir = "/usr/lib/nagios/plugins",
+ address = "127.0.0.1",
+ community = "public",
+ oid = "DISMAN-EVENT-MIB::sysUpTimeInstance"
+ }
+
+ check_interval = 60s,
+ retry_interval = 15s,
+
+ servicegroups = { "all-services", "snmp" },
+
+ checkers = { "*" },
+ }
+
+#### Attribute: host\_name
+
+The host this service belongs to. There must be a "Host" object with
+that name.
+
+#### Attribute: alias
+
+Optional. A short description of the service.
+
+#### Attribute: methods - check
+
+The check type of the service. For now only external check plugins are
+supported ("PluginCheck").
+
+#### Attribute: check\_command
+
+Optional when not using the "external plugin" check type. The check
+command. May contain macros.
+
+#### Attribute: check\_interval
+
+Optional. The check interval (in seconds).
+
+#### Attribute: retry\_interval
+
+Optional. The retry interval (in seconds). This is used when the service
+is in a soft state.
+
+#### Attribute: servicegroups
+
+Optional. The service groups this service belongs to.
+
+#### Attribute: checkers
+
+Optional. A list of remote endpoints that may check this service.
+Wildcards can be used here.
+
+### Type: ServiceGroup
+
+A group of services.
+
+Example:
+
+ object ServiceGroup "snmp" {
+ alias = "SNMP services",
+
+ custom = {
+ notes_url = "http://www.example.org/",
+ action_url = "http://www.example.org/",
+ }
+ }
+
+#### Attribute: alias
+
+Optional. A short description of the service group.
+
+#### Attribute: notes\_url
+
+Optional. Notes URL. Used by the CGIs.
+
+#### Attribute: action\_url
+
+Optional. Action URL. Used by the CGIs.
+
+### Type: Host
+
+A host. Unlike in Icinga 1.x hosts are not checkable objects in Icinga
+2.
+
+Example:
+
+ object Host "localhost" {
+ alias = "The best host there is",
+
+ hostgroups = [ "all-hosts" ],
+
+ hostcheck = "ping",
+ dependencies = [ "router-ping" ]
+
+ services["ping"] = { templates = "ping" }
+ services["http"] = {
+ templates = "my-http",
+ macros = {
+ vhost = "test1.example.org",
+ port = 81
+ }
+ }
+
+ check_interval = 60m,
+ retry_interval = 15m,
+
+ servicegroups = [ "all-services" ],
+
+ checkers = { "*" },
+ }
+
+#### Attribute: alias
+
+Optional. A short description of the host.
+
+#### Attribute: hostgroups
+
+Optional. A list of host groups this host belongs to.
+
+#### Attribute: hostcheck
+
+Optional. A service that is used to determine whether the host is up or
+down.
+
+#### Attribute: hostdependencies
+
+Optional. A list of hosts that are used to determine whether the host is
+unreachable.
+
+#### Attribute: servicedependencies
+
+Optional. A list of services that are used to determine whether the host
+is unreachable.
+
+#### Attribute: services
+
+Inline definition of services. Each service name is defined in square
+brackets and got its own dictionary with attribute properties, such as
+the template service being used. All other service-related properties
+are additively copied into the new service object.
+
+The new service’s name is "hostname-service" - where "service" is the
+array key in the services array.
+
+The priority for service properties is (from highest to lowest):
+
+1. Properties specified in the dictionary of the inline service
+ definition
+
+2. Host properties
+
+3. Properties inherited from the new service’s parent object
+
+#### Attribute: check\_interval
+
+Optional. Copied into inline service definitions. The host itself does
+not have any checks.
+
+#### Attribute: retry\_interval
+
+Optional. Copied into inline service definitions. The host itself does
+not have any checks.
+
+#### Attribute: servicegroups
+
+Optional. Copied into inline service definitions. The host itself does
+not have any checks.
+
+#### Attribute: checkers
+
+Optional. Copied into inline service definitions. The host itself does
+not have any checks.
+
+### Type: HostGroup
+
+A group of hosts.
+
+Example
+
+ object HostGroup "my-hosts" {
+ alias = "My hosts",
+
+ notes_url = "http://www.example.org/",
+ action_url = "http://www.example.org/",
+ }
+
+#### Attribute: alias
+
+Optional. A short description of the host group.
+
+#### Attribute: notes\_url
+
+Optional. Notes URL. Used by the CGIs.
+
+#### Attribute: action\_url
+
+Optional. Action URL. Used by the CGIs.
+
+### Type: PerfdataWriter
+
+Write check result performance data to a defined path using macro
+pattern.
+
+Example
+
+ local object PerfdataWriter "pnp" {
+ perfdata_path = "/var/spool/icinga2/perfdata/service-perfdata",
+ format_template = "DATATYPE::SERVICEPERFDATA\tTIMET::$TIMET$\tHOSTNAME::$HOSTNAME$\tSERVICEDESC::$SERVICEDESC$\tSERVICEPERFDATA::$SERVICEPERFDATA$\tSERVICECHECKCOMMAND::$SERVICECHECKCOMMAND$\tHOSTSTATE::$HOSTSTATE$\tHOSTSTATETYPE::$HOSTSTATETYPE$\tSERVICESTATE::$SERVICESTATE$\tSERVICESTATETYPE::$SERVICESTATETYPE$",
+ rotation_interval = 15s,
+ }
+
+#### Attribute: perfdata\_path
+
+Path to the service perfdata file.
+
+> **Note**
+>
+> Will be automatically rotated with timestamp suffix.
+
+#### Attribute: format\_template
+
+Formatting of performance data output for graphing addons or other post
+processing.
+
+#### Attribute: rotation\_interval
+
+Rotation interval for the file defined in *perfdata\_path*.
+
+### Type: IdoMySqlConnection
+
+IDO DB schema compatible output into mysql database.
+
+Example
+
+ library "ido_mysql"
+ local object IdoMysqlDbConnection "mysql-ido" {
+ host = "127.0.0.1",
+ port = "3306",
+ user = "icinga",
+ password = "icinga",
+ database = "icinga",
+ table_prefix = "icinga_",
+ instance_name = "icinga2",
+ instance_description = "icinga2 dev instance"
+ }
+
+#### Attribute: host
+
+MySQL database host address. Default is *localhost*.
+
+#### Attribute: port
+
+MySQL database port. Default is *3306*.
+
+#### Attribute: user
+
+MySQL database user with read/write permission to the icinga database.
+Default is *icinga*.
+
+#### Attribute: password
+
+MySQL database user’s password. Default is *icinga*.
+
+#### Attribute: database
+
+MySQL database name. Default is *icinga*.
+
+#### Attribute: table\_prefix
+
+MySQL database table prefix. Default is *icinga\_*.
+
+#### Attribute: instance\_name
+
+Unique identifier for the local Icinga 2 instance.
+
+#### Attribute: instance\_description
+
+Optional. Description for the Icinga 2 instance.
+
+### Type: LiveStatusComponent
+
+Livestatus api interface available as tcp or unix socket.
+
+Example
+
+ library "livestatus"
+
+ local object LivestatusComponent "livestatus-tcp" {
+ socket_type = "tcp",
+ host = "127.0.0.1",
+ port = "6558"
+ }
+
+ local object LivestatusComponent "livestatus-unix" {
+ socket_type = "unix",
+ socket_path = "/var/run/icinga2/livestatus"
+ }
+
+#### Attribute: socket\_type
+
+*tcp* or *unix* socket. Default is *unix*.
+
+> **Note**
+>
+> *unix* sockets are not supported on Windows.
+
+#### Attribute: host
+
+Only valid when socket\_type="tcp". Host address to listen on for
+connections.
+
+#### Attribute: port
+
+Only valid when socket\_type="tcp". Port to listen on for connections.
+
+#### Attribute: socket\_path
+
+Only valid when socket\_type="unix". Local unix socket file. Not
+supported on Windows.
+
+Configuration Examples
+----------------------
+
+### Non-networked minimal example
+
+> **Note**
+>
+> Icinga 2 ITL provides itl/standalone.conf which loads all required
+> components, as well as itl/itl.conf includes many object templates
+> already for an easy start with Icinga 2.
+
+ local object IcingaApplication "icinga" {
+
+ }
+
+ local object Component "checker" {
+
+ }
+
+ local object Component "delegation" {
+
+ }
+
+ object CheckCommand "ping" {
+ command = "$plugindir$/check_ping -H $address$ -w $wrta$,$wpl$% -c $crta$,$cpl$%",
+ }
+
+ template Service "icinga-service" {
+ methods = {
+ check = "PluginCheck"
+ },
+
+ macros = {
+ plugindir = "/usr/lib/nagios/plugins"
+ }
+ }
+
+ template Service "ping-tmpl" inherits "icinga-service" {
+ check_command = "ping",
+ macros += {
+ wrta = 50,
+ wpl = 5,
+ crta = 100,
+ cpl = 10
+ }
+ }
+
+ object Host "localhost" {
+ services["ping"] = { templates = "ping-tmpl" },
+
+ macros = {
+ address = "127.0.0.1"
+ },
+
+ check_interval = 10m
+ }
+
+> **Note**
+>
+> You may also want to load the "compat" component if you want Icinga 2
+> to write status.dat and objects.cache files.
+
+/\* vim: set syntax=asciidoc filetype=asciidoc: \*/
+
+/\* vim: set syntax=asciidoc filetype=asciidoc: \*/
projects / icinga2 / commitdiff