tyler.durden
/
icinga2
mirror of https://github.com/Icinga/icinga2.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Documentation: Emphasize on runtime vs configuration macros. 

Fixes #5457
Fixes #5458
This commit is contained in:
Michael Friedrich 2014-02-05 14:27:06 +01:00
parent 9116c58b24
commit 0e2e031c23
3 changed files with 134 additions and 34 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

118
doc/3.03-macros.md
View File

@ -1,8 +1,23 @@
## <a id="macros"></a> Macros
> **Note**
>
> There is a limited set of special [global variables](#global-variables) which can be re-used and
> also partly overridden such as `IcingaEnableChecks`.
### <a id="runtime-macros"></a> Runtime Macros
Macros may be used in command definitions to dynamically change how the command
is executed.
Additionally there are Icinga 2 features for example the `PerfDataWriter`
using the available runtime macros for output formatting.
> **Note**
>
> Macros are evaluated at runtime when executing a command. These macros cannot be
> used inside the configuration objects to add references or similar unless
> stated otherwise.
Here is an example of a command definition which uses user-defined macros:
@ -40,6 +55,8 @@ Macro names must be enclosed in two `$` signs, e.g. `$plugindir$`. When using
the `$` sign as single character, you need to escape it with an additional dollar
sign (`$$`).
### <a id="runtime-macro-evaluation-order"></a> Runtime Macro Evaluation Order
When executing commands Icinga 2 checks the following objects in this order to look
up macros:
@ -74,14 +91,50 @@ emitted to the Icinga 2 log.
> Macros in capital letters (e.g. `HOSTNAME`) are reserved for use by Icinga 2
> and should not be overwritten by users.
By convention every host should have an `address` macro. Hosts
which have an IPv6 address should also have an `address6` macro.
> **Best Practice**
>
> By convention every host should have an `address` macro. Hosts
> which have an IPv6 address should also have an `address6` macro.
The `plugindir` macro should be set to the path of your check plugins. The
`/etc/icinga2/conf.d/macros.conf` file is usually used to define global macros
including this one.
### Host Macros
#### Custom Variables as Runtime Macros
Custom variables are made available as macros using an underscore and the object type
in uppercase characters as additional prefix. For example `_HOST`name "_HOST<name>"
where <name> is the name of the custom variable.
#### Runtime Macro Evaluation Order in Cluster Mode
These macros are evaluated and calculated upon command execution on each node. If a
cluster node defines additional macros overriding the default tuples, the calculated
macro values will be different and affect only the node executing the command.
Node 1:
const IcingaMacros = {
plugindir = "/usr/lib/icinga/plugins"
}
Node 2:
const IcingaMacros = {
plugindir = "/usr/lib/monitoring/plugins"
}
CheckCommand definition:
object CheckCommand "whatever" inherits "plugin-check-command" {
command = "$plugindir$/check_whatever"
}
On Node 1, this will be evaluated into `/usr/lib/icinga/plugins/check_whatever`.
On Node 2, Icinga 2 will attempt to execute `/usr/lib/icinga/monitoring/check_whatever`
instead.
### <a id="host-runtime-macros"></a> Host Runtime Macros
The following host macros are available in all commands that are executed for
hosts or services:
@ -109,10 +162,16 @@ hosts or services:
HOSTADDRESS | This is an alias for the `address` macro. If the `address` macro is not defined the host object's name is used instead.
HOSTADDRESS6 | This is an alias for the `address6` macro. If the `address` macro is not defined the host object's name is used instead.
> **Note**
>
> `HOSTADDRESS` and `HOSTADDRESS6` macros are available as legacy macros. The
> Icinga 2 Template Library (`ITL`) examples use the `$address$` macro instead
> requiring that macro key to be defined.
Custom variables are made available as macros with the name "_HOST<name>"
where <name> is the name of the custom variable.
### Service Macros
### <a id="service-runtime-macros"></a> Service Runtime Macros
The following service macros are available in all commands that are executed for
services:
@ -146,7 +205,7 @@ services:
Custom variables are made available as macros with the name "_SERVICE<name>"
where <name> is the name of the custom variable.
### User Macros
### <a id="user-runtime-macros"></a> User Runtime Macros
The following service macros are available in all commands that are executed for
users:
@ -159,16 +218,17 @@ users:
USERPAGER | This is an alias for the `pager` macro.
Custom variables are made available as macros with the name "_USER<name>" and
"_CONTACT<name>" where <name> is the name of the custom variable.
"_CONTACT<name>" where <name> is the name of the custom variable. "_CONTACT<name>"
### Notification Macros
### <a id="notification-runtime-macros"></a> Notification Runtime Macros
Custom variables are made available as macros with the name "_NOTIFICATION<name>"
where <name> is the name of the custom variable.
### Global Macros
### <a id="global-runtime-macros"></a> Global Runtime Macros
The following macros are available in all commands:
The following macros are available in all executed commands:
Name | Description
-----------------------|--------------
@ -177,3 +237,43 @@ The following macros are available in all commands:
SHORTDATETIME | Current date and time. Example: `2014-01-0311:23:08`
DATE | Current date. Example: `2014-01-03`
TIME | Current time including timezone information. Example: `11:23:08+0000`
### <a id="runtime-macros-env-vars"></a> Runtime Macros as Environment Variables
The `export_macros` command object attribute requires a list of macros which should
be exported as environment variables prior to executing the command.
This is useful for example for hiding sensitive information on the command line output
when passing credentials to database checks:
object CheckCommand "mysql-health" inherits "plugin-check-command" {
command = "$plugindir$/check_mysql -H $address$ -d $db$",
/* default macro values */
macros = {
"MYSQLUSER" = "icinga_check",
"MYSQLPASS" = "1c1ng42r0xx"
},
export_macros = [
"MYSQLUSER",
"MYSQLPASS"
]
}
### <a id="configuration-macros"></a> Configuration Macros
Icinga 2 allows you to define constant variables which can be used in a limited
scope. For example, constant expressions can reference a pre-defined global constant
variable and calculate a value for the service check interval.
Example:
const MyCheckInterval = 10m
...
{
check_interval = (MyCheckInterval / 2.5)
}
More details in the chapter [Constant Expressions](#constant-expressions).

2
doc/4-configuring-icinga.md
View File

@ -1 +1 @@
# Configuring Icinga
# <a id="configuring-icinga2"></a> Configuring Icinga 2

48
doc/4.1-configuration-syntax.md
View File

@ -1,6 +1,6 @@
## Configuration Syntax
## <a id="configuration-syntax"></a> Configuration Syntax
### Object Definition
### <a id="object-definition"></a> Object Definition
Icinga 2 features an object-based configuration format. In order to
define objects the `object` keyword is used:
@ -27,7 +27,7 @@ Each object is uniquely identified by its type (`Host`) and name
property declarations. The following data types are available for
property values:
#### Numeric Literals
#### <a id="numeric-literals"></a> Numeric Literals
A floating-point number.
@ -35,7 +35,7 @@ Example:
-27.3
#### Duration Literals
#### <a id="duration-literals"></a> Duration Literals
Similar to floating-point numbers except for the fact that they support
suffixes to help with specifying time durations.
@ -47,7 +47,7 @@ Example:
Supported suffixes include ms (milliseconds), s (seconds), m (minutes),
h (hours) and d (days).
#### String Literals
#### <a id="string-literals"></a> String Literals
A string.
@ -72,7 +72,7 @@ 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.
#### Multi-line String Literals
#### <a id="multiline-string-literals"></a> Multi-line String Literals
Strings spanning multiple lines can be specified by enclosing them in
{{{ and }}}.
@ -89,15 +89,15 @@ Example.
> Unlike in ordinary strings special characters to not have to be escaped
> in multi-line string literals.
#### Boolean Literals
#### <a id="boolean-literals"></a> Boolean Literals
The keywords `true` and `false` are equivalent to 1 and 0 respectively.
#### Null Value
#### <a id="null-value"></a> Null Value
The `null` keyword can be used to specify an empty value.
#### Dictionary
#### <a id="dictionary"></a> Dictionary
An unordered list of key-value pairs. Keys must be unique and are
compared in a case-insensitive manner.
@ -124,7 +124,7 @@ Example:
> Setting a dictionary key to null causes the key and its value to be
> removed from the dictionary.
#### Array
#### <a id="array"></a> Array
An ordered list of values.
@ -140,13 +140,13 @@ Example:
> An array may simultaneously contain values of different types, such as
> strings and numbers.
### Operators
### <a id="operators"></a> 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 =
#### <a id="operator-assignment"></a> Operator =
Sets a dictionary element to the specified value.
@ -159,7 +159,7 @@ Example:
In this example a has the value 7 after both instructions are executed.
#### Operator +=
#### <a id="operator-additive-assignment"></a> Operator +=
Modifies a dictionary or array by adding new elements to it.
@ -175,7 +175,7 @@ only works for dictionaries and arrays.
<!--
#### Operator -=
#### <a id="operator-substractive-assignment"></a> Operator -=
Removes elements from a dictionary.
@ -189,7 +189,7 @@ Example:
In this example a contains `"hello"`. Trying to remove an item that does
not exist is not an error. Not implemented yet.
#### Operator \*=
#### <a id="operator-multiply-assignment"></a> Operator \*=
Multiplies an existing dictionary element with the specified number. If
the dictionary element does not already exist 0 is used as its value.
@ -204,7 +204,7 @@ Example:
In this example a is 300. This only works for numbers. Not implemented
yet.
#### Operator /=
#### <a id="operator-dividing-assignment"></a> Operator /=
Divides an existing dictionary element by the specified number. If the
dictionary element does not already exist 0 is used as its value.
@ -221,7 +221,7 @@ yet.
-->
### Indexer
### <a id="indexer"></a> Indexer
The indexer syntax provides a convenient way to set dictionary elements.
@ -239,7 +239,7 @@ This is equivalent to writing:
}
}
### Inheritance
### <a id="object-inheritance"></a> Object Inheritance
Objects can inherit attributes from other objects.
@ -271,7 +271,7 @@ templates though in general they are.
Parent objects are resolved in the order they're specified using the
`inherits` keyword.
### Disable/Override Objects and Attributes
### <a id="disable-override-objects-attributes"></a> Disable/Override Objects and Attributes
Object attributes can be overridden by defining the additional changed attribute
directly on the object. Use the `+=` operator for the inline services dictionary.
@ -296,7 +296,7 @@ dictionary by exiplicitely overriding their value with `null`.
services["ping6"] = null
### Variables
### <a id="variables"></a> Variables
Global variables can be set using the `var` and `const` keywords:
@ -313,7 +313,7 @@ the `const` keyword.
> in order to provide compatibility with older versions. Its use is
> deprecated.
### Constant Expressions
### <a id="constant-expressions"></a> Constant Expressions
Simple calculations can be performed using the constant expression syntax:
@ -357,7 +357,7 @@ Example:
retry_interval = 15
}
### Includes
### <a id="includes"></a> Includes
Other configuration files can be included using the `include` directive.
Paths must be relative to the configuration file that contains the
@ -385,7 +385,7 @@ paths. Additional include search paths can be added using
Wildcards are not permitted when using angle brackets.
### Recursive Includes
### <a id="recursive-includes"></a> Recursive Includes
The `include_recursive` directive can be used to recursively include all
files in a directory which match a certain pattern.
@ -418,7 +418,7 @@ Example:
<!--
### Type Definition
### <a id="type-definition"></a> Type Definition
By default Icinga has no way of semantically verifying its configuration
objects. This is where type definitions come in. Using type definitions