From 0e2e031c23e4ae6d2b850e0ff13a433b53f7c9e8 Mon Sep 17 00:00:00 2001 From: Michael Friedrich Date: Wed, 5 Feb 2014 14:27:06 +0100 Subject: [PATCH] Documentation: Emphasize on runtime vs configuration macros. Fixes #5457 Fixes #5458 --- doc/3.03-macros.md | 118 +++++++++++++++++++++++++++++--- doc/4-configuring-icinga.md | 2 +- doc/4.1-configuration-syntax.md | 48 ++++++------- 3 files changed, 134 insertions(+), 34 deletions(-) diff --git a/doc/3.03-macros.md b/doc/3.03-macros.md index 6eaaef271..84e1ad00b 100644 --- a/doc/3.03-macros.md +++ b/doc/3.03-macros.md @@ -1,8 +1,23 @@ ## 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`. + +### 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 (`$$`). +### 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" +where 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. + +### 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" where is the name of the custom variable. -### Service Macros +### 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" where is the name of the custom variable. -### User Macros +### 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" and -"_CONTACT" where is the name of the custom variable. +"_CONTACT" where is the name of the custom variable. "_CONTACT" -### Notification Macros + +### Notification Runtime Macros Custom variables are made available as macros with the name "_NOTIFICATION" where is the name of the custom variable. -### Global Macros +### 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` + +### 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" + ] + } + +### 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). \ No newline at end of file diff --git a/doc/4-configuring-icinga.md b/doc/4-configuring-icinga.md index 3e9b3a661..946dc91d6 100644 --- a/doc/4-configuring-icinga.md +++ b/doc/4-configuring-icinga.md @@ -1 +1 @@ -# Configuring Icinga \ No newline at end of file +# Configuring Icinga 2 \ No newline at end of file diff --git a/doc/4.1-configuration-syntax.md b/doc/4.1-configuration-syntax.md index 4550f49a4..d31a614c3 100644 --- a/doc/4.1-configuration-syntax.md +++ b/doc/4.1-configuration-syntax.md @@ -1,6 +1,6 @@ -## Configuration Syntax +## Configuration Syntax -### Object Definition +### 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 +#### Numeric Literals A floating-point number. @@ -35,7 +35,7 @@ Example: -27.3 -#### Duration Literals +#### 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 +#### 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 +#### 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 +#### Boolean Literals The keywords `true` and `false` are equivalent to 1 and 0 respectively. -#### Null Value +#### Null Value The `null` keyword can be used to specify an empty value. -#### Dictionary +#### 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 +#### 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 +### 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 = +#### 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 += +#### Operator += Modifies a dictionary or array by adding new elements to it. @@ -175,7 +175,7 @@ only works for dictionaries and arrays. -### Indexer +### Indexer The indexer syntax provides a convenient way to set dictionary elements. @@ -239,7 +239,7 @@ This is equivalent to writing: } } -### Inheritance +### 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 +### 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 +### 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 +### Constant Expressions Simple calculations can be performed using the constant expression syntax: @@ -357,7 +357,7 @@ Example: retry_interval = 15 } -### Includes +### 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 +### 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: