icinga2/doc/4.1-configuration-syntax.md

451 lines
9.9 KiB
Markdown
Raw Normal View History

2013-09-27 07:19:13 +02:00
## Configuration Syntax
2013-09-26 08:59:29 +02:00
2013-09-27 07:19:13 +02:00
### Object Definition
2013-09-26 08:59:29 +02:00
Icinga 2 features an object-based configuration format. In order to
2013-10-07 09:35:44 +02:00
define objects the `object` keyword is used:
2013-09-26 08:59:29 +02:00
object Host "host1.example.org" {
display_name = "host1",
macros = {
address = "192.168.0.1"
}
}
> **Note**
>
2013-10-10 16:55:59 +02:00
> The Icinga 2 configuration format is agnostic to white space characters and
2013-09-26 08:59:29 +02:00
> new-lines.
> **Note**
>
> Exclamation marks (!) are not permitted in object names.
2013-09-26 08:59:29 +02:00
2013-10-07 09:35:44 +02:00
Each object is uniquely identified by its type (`Host`) and name
(`host1.example.org`). Objects can contain a comma-separated list of
2013-09-26 08:59:29 +02:00
property declarations. The following data types are available for
property values:
2013-09-27 07:19:13 +02:00
#### Numeric Literals
2013-09-26 08:59:29 +02:00
A floating-point number.
Example:
-27.3
2013-09-27 07:19:13 +02:00
#### Duration Literals
2013-09-26 08:59:29 +02:00
Similar to floating-point numbers except for the fact that they support
suffixes to help with specifying time durations.
Example:
2.5m
2013-09-27 16:39:35 +02:00
Supported suffixes include ms (milliseconds), s (seconds), m (minutes),
h (hours) and d (days).
2013-09-26 08:59:29 +02:00
2013-09-27 07:19:13 +02:00
#### String Literals
2013-09-26 08:59:29 +02:00
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.
2013-10-10 16:55:59 +02:00
#### Multi-line String Literals
2013-09-26 08:59:29 +02:00
Strings spanning multiple lines can be specified by enclosing them in
{{{ and }}}.
Example.
{{{This
is
a multi-line
string.}}}
2013-10-01 16:09:34 +02:00
> **Note**
>
> Unlike in ordinary strings special characters to not have to be escaped
> in multi-line string literals.
2013-09-27 07:19:13 +02:00
#### Boolean Literals
2013-09-26 08:59:29 +02:00
2013-10-07 09:35:44 +02:00
The keywords `true` and `false` are equivalent to 1 and 0 respectively.
2013-09-26 08:59:29 +02:00
2013-09-27 07:19:13 +02:00
#### Null Value
2013-09-26 08:59:29 +02:00
2013-10-07 09:35:44 +02:00
The `null` keyword can be used to specify an empty value.
2013-09-26 08:59:29 +02:00
2013-09-27 07:19:13 +02:00
#### Dictionary
2013-09-26 08:59:29 +02:00
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 and its value to be
> removed from the dictionary.
2013-09-27 07:19:13 +02:00
#### Array
2013-09-26 08:59:29 +02:00
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:
2013-09-27 07:19:13 +02:00
[ "hello", 42 ]
2013-09-26 08:59:29 +02:00
> **Note**
>
2013-09-27 07:19:13 +02:00
> An array may simultaneously contain values of different types, such as
2013-09-26 08:59:29 +02:00
> strings and numbers.
2013-09-27 07:19:13 +02:00
### Operators
2013-09-26 08:59:29 +02:00
2013-10-07 09:35:44 +02:00
In addition to the `=` operator shown above a number of other operators
2013-09-26 14:01:29 +02:00
to manipulate configuration objects are supported. Here's a list of all
2013-09-26 08:59:29 +02:00
available operators:
2013-09-27 07:19:13 +02:00
#### Operator =
2013-09-26 08:59:29 +02:00
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.
2013-09-27 07:19:13 +02:00
#### Operator +=
2013-09-26 08:59:29 +02:00
Modifies a dictionary or array by adding new elements to it.
Example:
{
a = [ "hello" ],
a += [ "world" ]
}
2013-10-07 09:35:44 +02:00
In this example a contains both `"hello"` and `"world"`. This currently
2013-09-26 08:59:29 +02:00
only works for dictionaries and arrays.
<!--
2013-09-26 14:01:29 +02:00
2013-09-27 07:19:13 +02:00
#### Operator -=
2013-09-26 08:59:29 +02:00
Removes elements from a dictionary.
Example:
{
a = { "hello", "world" },
a -= [ "world" ]
}
2013-10-07 09:35:44 +02:00
In this example a contains `"hello"`. Trying to remove an item that does
2013-09-26 08:59:29 +02:00
not exist is not an error. Not implemented yet.
2013-09-27 07:19:13 +02:00
#### Operator \*=
2013-09-26 08:59:29 +02:00
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.
2013-09-27 07:19:13 +02:00
#### Operator /=
2013-09-26 08:59:29 +02:00
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.
2013-09-26 14:01:29 +02:00
2013-09-26 08:59:29 +02:00
-->
2013-09-27 07:19:13 +02:00
### Indexer
2013-09-26 08:59:29 +02:00
2013-09-27 07:19:13 +02:00
The indexer syntax provides a convenient way to set dictionary elements.
2013-09-26 08:59:29 +02:00
Example:
{
hello["key"] = "world"
}
This is equivalent to writing:
{
hello += {
key = "world"
}
}
2013-09-27 07:19:13 +02:00
### Inheritance
2013-09-26 08:59:29 +02:00
Objects can inherit attributes from other objects.
Example:
template Host "default-host" {
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",
macros["address6"] = "::1"
}
2013-10-07 09:35:44 +02:00
The `default-host` and `test-host` objects are marked as templates
using the `template` keyword. Unlike ordinary objects templates are not
2013-10-10 16:55:59 +02:00
instantiated at run-time. Parent objects do not necessarily have to be
2013-09-26 08:59:29 +02:00
templates though in general they are.
> **Note**
>
> The final macros dictionary contains all 3 macros and the macro
2013-10-07 09:35:44 +02:00
> `color` has the value `"blue"`.
2013-09-26 08:59:29 +02:00
2013-09-26 14:01:29 +02:00
Parent objects are resolved in the order they're specified using the
2013-10-07 09:35:44 +02:00
`inherits` keyword.
2013-09-26 08:59:29 +02:00
2013-09-27 07:19:13 +02:00
### Variables
2013-09-26 08:59:29 +02:00
Global variables can be set using the `var` and `const` keywords:
2013-09-26 08:59:29 +02:00
var VarName = "some value"
2013-09-26 08:59:29 +02:00
The value can be a string, number, array or a dictionary.
Variables can be set multiple times unless they were introduced using
the `const` keyword.
> **Note**
>
> The `set` keyword is an alias for the `var` keyword and is available
> in order to provide compatibility with older versions. Its use is
> deprecated.
2013-09-27 07:19:13 +02:00
### Constant Expressions
2013-09-26 08:59:29 +02:00
Simple calculations can be performed using the constant expression syntax:
{
check_interval = (15 * 60)
}
Valid operators include ~, +, -, * and /. The default precedence rules can be
2013-10-10 16:55:59 +02:00
overridden by grouping expressions using parentheses:
2013-09-26 08:59:29 +02:00
{
check_interval ((15 * 60) / 2)
}
Global variables may be used in constant expressions.
var MyCheckInterval = 10m
2013-09-26 08:59:29 +02:00
...
{
check_interval = (MyCheckInterval / 2.5)
}
> **Note**
>
> Constant expressions are evaluated as soon as they're encountered in
> the configuration file.
### <a id="comments"></a> Comments
2013-09-26 08:59:29 +02:00
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
}
2013-09-27 07:19:13 +02:00
### Includes
2013-09-26 08:59:29 +02:00
2013-10-07 09:35:44 +02:00
Other configuration files can be included using the `include` directive.
2013-09-26 08:59:29 +02:00
Paths must be relative to the configuration file that contains the
2013-10-07 09:35:44 +02:00
`include` directive.
2013-09-26 08:59:29 +02:00
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
2013-09-27 13:56:11 +02:00
paths. Additional include search paths can be added using
[command-line options](#cmdline).
2013-09-26 08:59:29 +02:00
Wildcards are not permitted when using angle brackets.
### Recursive Includes
The `include_recursive` directive can be used to recursively include all
files in a directory which match a certain pattern.
Example:
include_recursive "conf.d" "*.conf"
include_recursive "templates"
The first parameter specifies the directory from which files should be
recursively included.
The file names need to match the pattern given in the second parameter.
When no pattern is specified the default pattern "*.conf" is used.
2013-09-27 13:56:11 +02:00
### <a id="library"></a> Library directive
2013-09-26 08:59:29 +02:00
2013-10-07 09:35:44 +02:00
The `library` directive can be used to manually load additional
2013-09-26 08:59:29 +02:00
libraries. Libraries can be used to provide additional object types and
methods.
Example:
library "snmphelper"
> **Note**
>
2013-10-07 15:02:12 +02:00
> The `icinga` library is automatically loaded at startup. You don't need
> to load it manually.
2013-09-26 14:01:29 +02:00
<!--
2013-09-27 07:19:13 +02:00
### Type Definition
2013-09-26 08:59:29 +02:00
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:
2013-10-07 09:35:44 +02:00
- Pizza objects must contain an attribute `radius` which has to be a
2013-09-26 08:59:29 +02:00
number.
2013-10-07 09:35:44 +02:00
- Pizza objects may contain an attribute `ingredients` which has to be
2013-09-26 08:59:29 +02:00
a dictionary.
- Elements in the ingredients dictionary can be either a string or a
dictionary.
2013-10-07 09:35:44 +02:00
- If they're a dictionary they may contain attributes `quantity` (of
type number) and `name` (of type string).
2013-09-26 08:59:29 +02:00
2013-10-07 09:35:44 +02:00
- The script function `ValidateIngredients` is run to perform further
2013-09-26 08:59:29 +02:00
validation of the ingredients dictionary.
- Pizza objects may contain attribute matching the pattern
2013-10-07 15:02:12 +02:00
`custom::*` of any type.
2013-09-26 08:59:29 +02:00
2013-10-07 15:02:12 +02:00
Valid types for type rules include:
* any
* number
* string
* scalar (an alias for string)
* dictionary
2013-09-26 14:01:29 +02:00
-->