From: Gunnar Beutner Date: Wed, 15 Aug 2012 13:44:01 +0000 (+0200) Subject: Removed Markdown documentation. Added Docbook documentation. X-Git-Tag: v0.0.1~134 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=95c0a49f424afc04af4c17cc0e4167ebb83af18a;p=icinga2 Removed Markdown documentation. Added Docbook documentation. --- diff --git a/doc/icinga2-config.md b/doc/icinga2-config.md deleted file mode 100644 index f3df0a95f..000000000 --- a/doc/icinga2-config.md +++ /dev/null @@ -1,236 +0,0 @@ -[TOC] - -# Icinga 2 Configuration Syntax - -# 1.1 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 („localhost“). Objects can contain a comma-separated list of property declarations. - -## 1.2 Data Types - -### 1.2.1 Number - -A floating-point number. - -Examples: - - 27 - -27.3 - -### 1.2.2 String - -Example: - -A string. No escape characters are supported at present – though this will likely change. - - "Hello World!" - -### 1.2.3 Expression List - -A list of expressions that when executed has a dictionary as a result. - -Example: - - { - address = "192.168.0.1", - port = 443 - } - -## 1.3 Operators - -### 1.3.1 The = Operator - -Sets an attribute to the specified value. - -Example: - - { - a = 5, - a = 7 - } - -In this example "a" is 7 after executing this expression list. - -### 1.3.2 The += Operator - -Inserts additional items into a dictionary. Keys are overwritten if they already exist. - -Example: - - { - a = { "hello" }, - a += { "world" } - } - -In this example "a" is a dictionary that contains both "hello" and "world" as elements. - -The += operator is only applicable to dictionaries. Support for numbers might be added later on. - -### 1.3.3 The -= Operator - -Removes items from a dictionary. - -Example: - - { - a = { "hello", "world" }, - a -= { "world" } - } - -In this example "a" is a dictionary that only contains "hello" as an element. - -**Note**: The -= operator is not currently implemented. - -### 1.3.4 The *= Operator - -Multiplies an attribute with a number. - -Example: - - { - a = 60, - a *= 5 - } - -In this example "a" contains the value 300. - -**Note**: The *= operator is not currently implemented. - - -### 1.3.5 The /= Operator - -Divides an attribute with a number. - -Example: - - { - a = 300, - a /= 5 - } - -In this example "a" contains the value 60. - -**Note**: The /= operator is not currently implemented. - -## 1.4 Property Shortcuts - -### 1.4.1 Value Shortcut - -Example: - - { - "hello" - } - -This is equivalent to writing: - - { - hello = "hello" - } - -### 1.4.2 Index Shortcut - -Example: - - { - hello["key"] = "world" - } - -This is equivalent to writing: - - { - hello += { - key = "world" - } - } - -## 1.5 Specifiers - -### 1.5.1 The abstract specifier - -Identifies the object as a template which can be used by other object definitions. The object will not be instantiated on its own. - -Example: - - abstract object Host "test" { - - } - -### 1.5.2 The local specifier - -Disables replication for this object. The object will not be sent to remote Icinga instances. - -Example: - - local object Host "test" { - - } - -## 1.6 Inheritance - -Objects can inherit properties from one or more other objects: - - abstract object Host "default-host" { - check_interval = 30, - - macros = { - color = "red" - } - } - - abstract object Host "test-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 is 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. - -## 1.7 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 - } - -## 1.8 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" diff --git a/doc/icinga2-config.xml b/doc/icinga2-config.xml new file mode 100644 index 000000000..56a3dd057 --- /dev/null +++ b/doc/icinga2-config.xml @@ -0,0 +1,371 @@ + + +
+ + Icinga 2 Configuration + + + Gunnar + + Beutner + + + Icinga Development Team + + + + +
+ Icinga 2 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 + ("localhost"). Objects can contain a comma-separated list of property + declarations. The following data types are available for property + values: + + + + + <tgroup cols="3"> + <thead> + <row> + <entry align="center">Data Type</entry> + + <entry align="center">Example</entry> + + <entry align="center">Notes</entry> + </row> + </thead> + + <tbody> + <row> + <entry>Number</entry> + + <entry><programlisting>-27.3</programlisting></entry> + + <entry>A floating-point number.</entry> + </row> + + <row> + <entry>String</entry> + + <entry><programlisting>"Hello World!"</programlisting></entry> + + <entry>A string. No escape characters are supported at present + though this will likely change.</entry> + </row> + + <row> + <entry>Expression List</entry> + + <entry><programlisting>{ + address = "192.168.0.1", + port = 443 +} +</programlisting></entry> + + <entry>A list of expressions that when executed has a dictionary + as a result.</entry> + </row> + </tbody> + </tgroup> + </table> + </section> + + <section> + <title>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: + + + +
+ + + <tgroup cols="3"> + <thead> + <row> + <entry align="center">Operator</entry> + + <entry align="center">Example</entry> + + <entry align="center">Notes</entry> + </row> + </thead> + + <tbody> + <row> + <entry>=</entry> + + <entry><programlisting>{ + a = 5, + a = 7 +}</programlisting></entry> + + <entry>a is 7.</entry> + </row> + + <row> + <entry>+=</entry> + + <entry><programlisting>{ + a = { "hello" }, + a += { "world" } +}</programlisting></entry> + + <entry>a contains both "hello" and "world". This currently only + works for expression lists. Support for numbers might be added + later on.</entry> + </row> + + <row> + <entry>-=</entry> + + <entry><programlisting>{ + a = { "hello", "world" }, + a -= { "world" } +}</programlisting></entry> + + <entry>a contains "hello". Trying to remove an item that does + not exist is not an error. Not implemented yet.</entry> + </row> + + <row> + <entry>*=</entry> + + <entry><programlisting>{ + a = 60, + a *= 5 +}</programlisting></entry> + + <entry>a is 300. This only works for numbers. Not implemented + yet.</entry> + </row> + + <row> + <entry>/=</entry> + + <entry><programlisting>{ + a = 300, + a /= 5 +}</programlisting></entry> + + <entry>a is 60. This only works for numbers. Not implemented + yet.</entry> + </row> + </tbody> + </tgroup> + </table> + </section> + + <section> + <title>Attribute Shortcuts + + The following shortcuts can be used in expression lists: + + + +
+ + + <tgroup cols="2"> + <thead> + <row> + <entry align="center">Shortcut</entry> + + <entry align="center">Equivalent Code</entry> + </row> + </thead> + + <tbody> + <row> + <entry><programlisting>{ + "hello" +} +</programlisting></entry> + + <entry><programlisting>{ + hello = "hello" +}</programlisting></entry> + </row> + + <row> + <entry><programlisting>{ + hello["key"] = "world" +}</programlisting></entry> + + <entry><programlisting>{ + hello += { + key = "world" + } +}</programlisting></entry> + </row> + </tbody> + </tgroup> + </table> + </section> + + <section> + <title>Specifiers + + Objects can have specifiers that have special meaning. The + following specifiers can be used (before the "object" keyword): + + + +
+ + + <tgroup cols="2"> + <thead> + <row> + <entry align="center">Keyword</entry> + + <entry align="center">Usage</entry> + </row> + </thead> + + <tbody> + <row> + <entry>abstract</entry> + + <entry>Identifies the object as a template which can be used by + other object definitions. The object will not be instantiated on + its own.</entry> + </row> + + <row> + <entry>local</entry> + + <entry>Disabled replication for this object. The object will not + be sent to remote Icinga instances.</entry> + </row> + </tbody> + </tgroup> + </table> + </section> + + <section> + <title>Inheritance + + Objects can inherit attributes from one or more other + objects. + + abstract object Host "default-host" { + check_interval = 30, + + macros = { + color = "red" + } +} + +abstract object Host "test-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 is 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: + + /* + 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: + + #include "some/other/file.conf" +
+ + +
+ Icinga 2 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: + + local object IcingaApplication "icinga" { + cert = "my-cert.pem", + ca = "ca.crt", + + node = "192.168.0.1", + service = 7777, + + pidpath = "/var/run/icinga2.pid", + logpath = "/var/log/icinga2.log", + statepath = "/var/lib/icinga2.state", + + macros = { + plugindir = "/usr/local/icinga/libexec" + } +} + +
+
+