tyler.durden/icinga2
1
0
Fork 0
mirror of https://github.com/Icinga/icinga2.git synced 2025-07-21 04:34:43 +02:00
Code Issues Packages Projects Releases Wiki Activity

Removed Markdown documentation. Added Docbook documentation.

Browse Source
This commit is contained in:
Gunnar Beutner 2012-08-15 15:44:01 +02:00
parent c1c109da7e
commit 95c0a49f42
2 changed files with 371 additions and 236 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

236
doc/icinga2-config.md
View File

@ -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"

371
doc/icinga2-config.xml Normal file
View File

@ -0,0 +1,371 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<article>
<articleinfo>
<title>Icinga 2 Configuration</title>
<author>
<firstname>Gunnar</firstname>
<surname>Beutner</surname>
<affiliation>
<orgname>Icinga Development Team</orgname>
</affiliation>
</author>
</articleinfo>
<section>
<title>Icinga 2 Configuration Format</title>
<para/>
<section>
<title>Object Definition</title>
<para>Icinga 2 features an object-based configuration format. In order
to define objects the „object“ keyword is used:</para>
<programlisting>object Host "host1.example.org" {
alias = "host1",
check_interval = 30,
retry_interval = 15,
macros = {
address = "192.168.0.1"
}
}</programlisting>
<para><emphasis role="bold">Note</emphasis>: The Icinga 2 configuration
format is agnostic to whitespaces and new-lines.</para>
<para>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:</para>
<table>
<title/>
<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</title>
<para>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:</para>
<para/>
<table>
<title/>
<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</title>
<para>The following shortcuts can be used in expression lists:</para>
<para/>
<table>
<title/>
<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</title>
<para>Objects can have specifiers that have special meaning. The
following specifiers can be used (before the "object" keyword):</para>
<para/>
<table>
<title/>
<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</title>
<para>Objects can inherit attributes from one or more other
objects.</para>
<para><programlisting>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"
}
}
</programlisting><emphasis role="bold">Note</emphasis>: 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.</para>
<para><emphasis role="bold">Note</emphasis>: 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“.</para>
<para>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.</para>
</section>
<section>
<title>Comments</title>
<para>The Icinga 2 configuration format supports C/C++-style
comments:</para>
<programlisting>/*
This is a comment.
*/
object Host "localhost" {
check_interval = 30, // this is also a comment.
retry_interval = 15
}</programlisting>
</section>
<section>
<title>Includes</title>
<para>Other configuration files can be included using the „#include“
directive. Paths must be relative to the configuration file that
contains the „#include“ keyword:</para>
<programlisting>#include "some/other/file.conf"</programlisting>
</section>
</section>
<section>
<title>Icinga 2 Configuration Objects</title>
<para/>
<section>
<title>Type: IcingaApplication</title>
<para>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:</para>
<programlisting>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"
}
}
</programlisting>
</section>
</section>
</article>