object Host "localhost" {
import "linux-server"
- macros.address = "127.0.0.1"
- macros.address6 = "::1"
+ vars.address = "127.0.0.1"
+ vars.address6 = "::1"
}
This defines the host `localhost`. The `import` keyword is used to import
`ping6` services for the host as well as adding the host to the `linux-servers`
host group.
-The `macros` attribute can be used to define macros that are available for all
-services which belong to this host. Most of the templates in the Icinga Template
-Library require an `address` macro.
+The `vars` attribute can be used to define custom attributes that are available
+for all services which belong to this host. Most of the templates in the Icinga
+Template Library require an `address` custom attribute defined in the `vars`
+dictionary.
apply Service "icinga" {
import "generic-service"
>
> Due to compatibility restrictions, not all features available in Icinga 1.x
> Classic UI will be available with Icinga 2. The different handling of
-> [commands](#differences-1x-2-commands) and [macros](#differences-1x-2-macros)
+> [commands](#differences-1x-2-commands) and [custom attributes](#differences-1x-2-macros)
> renders the command expander invalid for example.
Here is an example of a host object which defines two child services:
object Host "my-server1" {
- macros.address = "10.0.0.1"
+ vars.address = "10.0.0.1"
check = "ping4"
}
> **Note**
>
> Define the global `PluginDir` constant (located in
-> `/etc/icinga2/conf.d/macros.conf` by default) and use
+> `/etc/icinga2/constants.conf` by default) and use
> it in all your command object definitions.
> Put your plugins and scripts into the directory defined by the `PluginDir` constant
> and make sure they are executable by the Icinga 2 user.
-### <a id="environment-macros"></a> Environment Macros
+### <a id="command-environment-variables"></a> Environment Varialbes for Commands
-If your plugins require environment macros instead of command arguments you have
-to define all macros in the `export_macros` attribute as list.
-
- export_macros = [
- "HOSTNAME",
- "SERVICEDESC",
- "SERVICESTATE"
- ]
-
-> **Note**
->
-> Use templates to define global `export_macros` attributes for the three
-> command types and let each command object inherit the attribute.
+Please check [Runtime Custom Attributes as Environment Variables](#runtime-custom-attribute-env-vars).
### <a id="check-commands"></a> Check Commands
critical (`-c`) thresholds for the disk usage. Without any
partition defined (`-p`) it will check all local partitions.
-Define the default check command macros `wfree` and `cfree` (freely
+Define the default check command custom attribute `wfree` and `cfree` freely
definable naming schema) and their default threshold values. You can
-then use these macros on the command line.
+then use these custom attributes as runtime macros on the command line.
> **Note**
>
-> The default macros can be overridden by the macros defined in
-> the service using the check command `disk`. The macros can also
-> be inherited from a parent template using additive inheritance (`+=`).
+> The default custom attributes can be overridden by the custom attributes
+> defined in the service using the check command `disk`. The custom attributes
+> can also be inherited from a parent template using additive inheritance (`+=`).
object CheckCommand "disk" {
import "plugin-check-command"
"-c", "$cfree$%"
],
- macros.wfree = 20
- macros.cfree = 10
+ vars.wfree = 20
+ vars.cfree = 10
}
The host `localhost` with the service `disk` checks all disks with modified
-macros (warning thresholds at `10%`, critical thresholds at `5%` free disk
-space).
+custom attributes (warning thresholds at `10%`, critical thresholds at `5%`
+free disk space).
object Host "localhost" {
import "generic-host"
- macros.address = "127.0.0.1"
- macros.address6 = "::1"
+ vars.address = "127.0.0.1"
+ vars.address6 = "::1"
}
apply Service "disk" {
check_command = "disk"
- macros.wfree = 10
- macros.cfree = 5
+ vars.wfree = 10
+ vars.cfree = 5
}
Below is an example using runtime macros from Icinga 2 (such as `$SERVICEOUTPUT$` for
the current check output) sending an email to the user(s) associated with the
-notification itself (`email` macro attribute provided as `$USERMACRO$`).
+notification itself (`email` custom attribute provided as `$USERMACRO$`).
+
+If you require default custom attribute definitions, you can add a `vars` dictionary
+as shown for the `CheckCommand` object.
-If you require default macro definitions, you can add a macro dictionary as shown for the
-`CheckCommand` object.
+TODO
object NotificationCommand "mail-service-notification" {
import "plugin-notification-command"
Unlike notifications event commands are called on every service state change
if defined. Therefore the `EventCommand` object should define a command line
evaluating the current service state and other service runtime attributes
-available through runtime macros. Runtime macros such as `$SERVICESTATETYPE$`
+available through runtime vars. Runtime macros such as `$SERVICESTATETYPE$`
and `$SERVICESTATE$` will be processed by Icinga 2 helping on fine-granular
events being triggered.
-## <a id="macros"></a> Macros
+## <a id="custom-attributes"></a> Custom Attributes and Runtime Macros
> **Note**
>
> There is a limited set of special [global constants](#global-constants) which can be re-used and
> also partly overridden such as `IcingaEnableChecks`.
-### <a id="runtime-macros"></a> Runtime Macros
+### <a id="runtime-custom-attributes"></a> Using Custom Attributes at Runtime
-Macros may be used in command definitions to dynamically change how the command
+Custom attributes 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.
+using the available Custom attributes for output formatting.
+
+> **Tip**
+>
+> Custom attributes are identified by the 'vars' dictionary attribute as short name.
+> Accessing the different attribute keys is possible using the '.' accessor.
> **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.
+> Custom attributes in command definitions or performance data templates are evaluated at
+> runtime when executing a command. These custom attributes cannot be used/accessed 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:
+Here is an example of a command definition which uses user-defined custom attributes:
object CheckCommand "my-ping" {
import "plugin-check-command"
"-c", "$crta$,$cpl$%",
"-p", "$packets$",
"-t", "$timeout$"
- ],
-
- macros = {
- wrta = 100
- wpl = 5
-
- crta = 200
- cpl = 15
+ ]
- packets = 5
- timeout = 0
- }
+ vars.wrta = 100
+ vars.wpl = 5
+ vars.crta = 200
+ vars.cpl = 15
+ vars.packets = 5
+ vars.timeout = 0
}
> **Note**
>
> If you have previously used Icinga 1.x you may already be familiar with
-> user and argument macros (e.g., `USER1` or `ARG1`). Unlike in Icinga 1.x macros
-> may have arbitrary names and arguments are no longer specified in the
-> `check_command` setting.
+> user and argument macros (e.g., `USER1` or `ARG1`) and custom variables
+> (e.g., `_COMMUNITY public`). Unlike in Icinga 1.x macros may have arbitrary
+> names and arguments are no longer specified in the `check_command` setting.
+> Custom variables are available as custom attributes in the `vars` dictionary
+> without the `_` prefix.
-Macro names must be enclosed in two `$` signs, e.g. `$address$`. When using
-the `$` sign as single character, you need to escape it with an additional dollar
-sign (`$$`).
+Custom attribute names used at runtime must be enclosed in two `$` signs, e.g.
+`$address$`. 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
+### <a id="runtime-custom-attributes-evaluation-order"></a> Runtime Custom Attributes Evaluation Order
When executing commands Icinga 2 checks the following objects in this order to look
-up macros:
+up custom attributes and their respective values:
1. User object (only for notifications)
2. Service object
4. Command object
5. Global custom attributes in the IcingaVars constant
-This execution order allows you to define default values for macros in your
-command objects. The `my-ping` command shown above uses this to set default
-values for some of the latency thresholds and timeouts.
+This execution order allows you to define default values for custom attributes
+in your command objects. The `my-ping` command shown above uses this to set
+default values for some of the latency thresholds and timeouts.
-When using the `my-ping` command you can override all or some of the macros
-in the service definition like this:
+When using the `my-ping` command you can override all or some of the custom
+attributes in the service definition like this:
apply Service "ping" {
check_command = "my-ping"
- macros.packets = 10 // Overrides the default value of 5 given in the command
+ vars.packets = 10 // Overrides the default value of 5 given in the command
assign where host.name == "my-server1"
}
-If a macro isn't defined anywhere an empty value is used and a warning is
+If a custom attribute isn't defined anywhere an empty value is used and a warning is
emitted to the Icinga 2 log.
-> **Note**
->
-> Macros in capital letters (e.g. `HOSTNAME`) are reserved for use by Icinga 2
-> and should not be overwritten by users.
> **Best Practice**
>
-> By convention every host should have an `address` macro. Hosts
-> which have an IPv6 address should also have an `address6` macro.
+> By convention every host should have an `address` custom attribute. Hosts
+> which have an IPv6 address should also have an `address6` custom attribute.
+> This may also be mandatory requirement for using legacy interfaces, user interfaces
+> and addons.
+
+### <a id="runtime-custom-attribute-env-vars"></a> Runtime Custom Attributes as Environment Variables
+
+TODO
+
+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" {
+ import "plugin-check-command",
+
+ command = PluginDir + "/check_mysql -H $address$ -d $db$",
+ /* default custom attribute values */
+ vars = {
+ "MYSQLUSER" = "icinga_check",
+ "MYSQLPASS" = "1c1ng42r0xx"
+ },
+
+ export_macros = [
+ "MYSQLUSER",
+ "MYSQLPASS"
+ ]
+ }
+
+### <a id="configuration-macros"></a> Configuration Macros
+
+Icinga 2 allows you to define constants 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).
-#### 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.
+
+## <a id="runtime-macros"></a> Runtime Macros
+
+Next to custom attributes there are additional runtime macros made available by Icinga 2.
+These runtime macros reflect the current object state and may change over time while
+custom attributes are configured statically (but can be modified at runtime using
+external commands).
### <a id="host-runtime-macros"></a> Host Runtime Macros
-The following host macros are available in all commands that are executed for
+TODO
+
+The following host custom attributes are available in all commands that are executed for
hosts or services:
Name | Description
> **Note**
>
-> `HOSTADDRESS` and `HOSTADDRESS6` macros are available as legacy macros. The
+> `HOSTADDRESS` and `HOSTADDRESS6` macros are available as legacy vars. 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.
-
### <a id="service-runtime-macros"></a> Service Runtime Macros
+TODO
+
The following service macros are available in all commands that are executed for
services:
TOTALHOSTSERVICESUNKNOWN | Number of services associated with the host which are in an `UNKNOWN` state.
TOTALHOSTSERVICESCRITICAL | Number of services associated with the host which are in a `CRITICAL` state.
-Custom variables are made available as macros with the name "_SERVICE<name>"
-where <name> is the name of the custom variable.
+
### <a id="user-runtime-macros"></a> User Runtime Macros
-The following macros are available in all commands that are executed for
+TODO
+
+The following custom attributes are available in all commands that are executed for
users:
Name | Description
USEREMAIL | This is an alias for the `email` macro.
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>"
### <a id="notification-runtime-macros"></a> Notification Runtime Macros
### <a id="global-runtime-macros"></a> Global Runtime Macros
+TODO
+
The following macros are available in all executed commands:
Name | Description
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" {
- import "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 constants 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).
IRC, Twitter, etc. The default method for executing a notification command are
plugin scripts used for notifications.
These may either be shell commands to invoke a system call to the `mail` binary
-or your own script fetching available macro values and doing proper formatting
+or your own script fetching available custom attribute values and doing proper formatting
before sending the notification.
Other mechanism will require writing the notification string into an api processing
it there (for example ticket system integration).
[Icinga Wiki](https://wiki.icinga.org). Or you'll write your own and share it.
A notification requires one or more users (and/or user groups) who will be notified
-in case. These users must have all macro attributes defined which will be used in
-the `NotificationCommand` on execution, for example `email` as macro dictionary key
-is referenced as `$USEREMAIL$`.
+in case. These users must have all custom attributes defined which will be used in
+the `NotificationCommand` on execution.
+
+TODO
The user `icingaadmin` in the example below will get notified only on `WARNING` and
`CRITICAL` states and `problem` and `recovery` notification types.
StateFilterCritical)
notification_type_filter = (NotificationFilterProblem |
NotificationFilterRecovery)
- macros = {
- "email" = "icinga@localhost"
- "pager" = "+49123456789"
+ vars.email = "icinga@localhost"
+ vars.pager = "+49123456789"
}
}
> **Note**
>
-> The chain of attribute inheritance including the (additive) macro dictionary for
-> notifications will allow granular macros for every specific use case, such as
-> `$mail$` or `$mobile$` as `User` macros available in `NotificationCommand`.
+> The chain of attribute inheritance including the (additive) vars dictionary for
+> notifications will allow granular custom attributes for every specific use case.
- Service -> Notification -> Command -> User
-There are various macros available at runtime execution of the `NotificationCommand`.
-The example below may or may not fit your needs.
+There are various custom attributes available at runtime execution of the
+`NotificationCommand`. The example below may or may not fit your needs.
+
+TODO
object NotificationCommand "mail-service-notification" {
import "plugin-notification-command"
You can add all shared attributes to a `Notification` template which is inherited
to the defined notifications. That way you'll save duplicated attributes in each
`Notification` object. Attributes can be overridden locally.
-
+
+TODO
+
template Notification "generic-notification" {
notification_interval = 15m
display_name = "Icinga 2nd Level"
enable_notifications = true
- macros = {
- "mobile" = "+49123456781"
- }
+ vars.mobile = "+49123456781"
}
object User "icinga-oncall-1st-level" {
display_name = "Icinga 1st Level"
enable_notifications = true
- macros.mobile = "+49123456782"
+ vars.mobile = "+49123456782"
}
}
apply Service "ping4" {
import "generic-service"
check_command = "ping4"
- assign where host.macros.address
+ assign where host.vars.address
}
apply Service "ping6" {
import "generic-service"
check_command = "ping6"
- assign where host.macros.address6
+ assign where host.vars.address6
}
In this example both `ping4` and `ping6` services inherit properties from the
object Host "mssql-srv1" {
groups = [ "windows" ]
- macros.mssql_port = 1433
+ vars.mssql_port = 1433
}
object Host "mssql-srv2" {
groups = [ "windows" ]
- macros.mssql_port = 1433
+ vars.mssql_port = 1433
}
}
template Host "windows-mssql-template" {
groups = [ "windows" ]
- macros.mssql_port = 1433
+ vars.mssql_port = 1433
}
}
object User "win-mssql-noc" {
import "generic-windows-mssql-users"
- macros.email = "noc@example.com"
+ vars.email = "noc@example.com"
}
object User "win-mssql-ops" {
import "generic-windows-mssql-users"
- macros.email = "ops@example.com"
+ vars.email = "ops@example.com"
}
apply Service "ping4" {
## <a id="performance-data"></a> Performance Data
-When a service check is executed plugins should provide so-called
+When a host and service check is executed plugins should provide so-called
`performance data`. Next to that additional check performance data
can be fetched using Icinga 2 runtime macros such as the check latency
-or the current service state.
+or the current service state (or additional custom attributes).
The performance data may be passed to external applications which
then generate nice graphs for historical reporting and trending.
Therefore the Icinga 2 `PerfdataWriter` object allows you to define
the output template format for host and services backed with Icinga 2
-runtime macros.
+runtime vars.
host_format_template = "DATATYPE::HOSTPERFDATA\tTIMET::$TIMET$\tHOSTNAME::$HOSTNAME$\tHOSTPERFDATA::$HOSTPERFDATA$\tHOSTCHECKCOMMAND::$HOSTCHECKCOMMAND$\tHOSTSTATE::$HOSTSTATE$\tHOSTSTATETYPE::$HOSTSTATETYPE$"
service_format_template = "DATATYPE::SERVICEPERFDATA\tTIMET::$TIMET$\tHOSTNAME::$HOSTNAME$\tSERVICEDESC::$SERVICEDESC$\tSERVICEPERFDATA::$SERVICEPERFDATA$\tSERVICECHECKCOMMAND::$SERVICECHECKCOMMAND$\tHOSTSTATE::$HOSTSTATE$\tHOSTSTATETYPE::$HOSTSTATETYPE$\tSERVICESTATE::$SERVICESTATE$\tSERVICESTATETYPE::$SERVICESTATETYPE$"
for specific use cases already around, for example monitoring Cisco routers.
The following example uses the [SNMP ITL](#itl-snmp) `CheckCommand` and just
-overrides the `oid` macro. A service is created for all hosts which
-have the `community` macro set.
+overrides the `oid` custom attribute. A service is created for all hosts which
+have the `community` custom attribute set.
apply Service "uptime" {
import "generic-service"
templates = [ "generic-service" ]
check_command = "snmp"
- macros.oid = "1.3.6.1.2.1.1.3.0"
+ vars.oid = "1.3.6.1.2.1.1.3.0"
- assign where host.macros.community
+ assign where host.vars.community
}
#### SSH
apply Service "swap" {
import "generic-service"
check_command = "check_by_ssh_swap"
- macros = {
+ vars = {
"warn" = "50%"
"crit" = "75%"
}
import "generic-service"
check_command = "check_nrpe"
- macros.remote_nrpe_command = "check_users"
+ vars.remote_nrpe_command = "check_users"
assign where host.name == "remote-nrpe-host"
}
"-s", "$pass$"
]
- macros = {
+ vars = {
"port" = "12489"
"pass" = "supersecret"
}
check_command = "check_nscp"
- macros += {
+ vars += {
remote_nscp_command = "USEDDISKSPACE"
partition = "c"
warn = "70"
object Host "host1.example.org" {
display_name = "host1"
- macros = {
+ vars = {
address = "192.168.0.1"
address6 = "::1"
}
object Host "host1.example.org" {
display_name = "host1"
- macros = { address = "192.168.0.1"; address6 = "::1"; }
+ vars = { address = "192.168.0.1"; address6 = "::1"; }
}
The semi-colon after the last element (i.e. `address6`) may be omitted.
Example:
template Host "default-host" {
- macros.color = "red"
+ vars.color = "red"
}
template Host "test-host" {
import "default-host"
- macros.color = "blue"
+ vars.color = "blue"
}
object Host "localhost" {
import "test-host"
- macros.address = "127.0.0.1"
- macros.address6 = "::1"
+ vars.address = "127.0.0.1"
+ vars.address6 = "::1"
}
The `default-host` and `test-host` objects are marked as templates
> **Note**
>
-> The macros dictionary for the `localhost` object contains all three
-> macros and the macro `color` has the value `"blue"`.
+> The `vars` dictionary for the `localhost` object contains all three
+> custom attributes and the custom attribute `color` has the value `"blue"`.
Parent objects are resolved in the order they're specified using the
`import` keyword.
> **Note**
>
> Any valid config attribute can be accessed using the `host` and `service`
-> variables. For example, `host.macros.address` would return the host's
-> "address" macro - or null if it doesn't have that macro.
+> variables. For example, `host.vars.address` would return the host's
+> "address" custom attribute - or null if it doesn't have that custom attribute.
### <a id="boolean-values"></a> Boolean Values
display_name |**Optional.** A short description of the host.
check |**Optional.** A service that is used to determine whether the host is up or down. This must be a service short name of a service that belongs to the host.
groups |**Optional.** A list of host groups this host belongs to.
- macros |**Optional.** A dictionary containing macros that are specific to this host.
+ vars |**Optional.** A dictionary containing custom attributes that are specific to this host.
### <a id="objecttype-hostgroup"></a> HostGroup
check_command = "check_snmp"
- macros = {
+ vars = {
community = "public"
oid = "DISMAN-EVENT-MIB::sysUpTimeInstance"
}
host |**Required.** The host this service belongs to. There must be a `Host` object with that name.
short_name |**Required.** The service name. Must be unique on a per-host basis (Similar to the service_description attribute in Icinga 1.x).
display_name |**Optional.** A short description of the service.
- macros |**Optional.** A dictionary containing macros that are specific to this host.
+ vars |**Optional.** A dictionary containing custom attributes that are specific to this host.
check\_command |**Required.** The name of the check command.
max\_check\_attempts|**Optional.** The number of times a service is re-checked before changing into a hard state. Defaults to 3.
check\_period |**Optional.** The name of a time period which determines when this service should be checked. Not set by default.
----------------|----------------
host |**Required.** The name of the host this notification belongs to.
service |**Required.** The short name of the service this notification belongs to.
- macros |**Optional.** A dictionary containing macros that are specific to this notification object.
+ vars |**Optional.** A dictionary containing custom attributes that are specific to this notification object.
users |**Optional.** A list of user names who should be notified.
user_groups |**Optional.** A list of user group names who should be notified.
times |**Optional.** A dictionary containing `begin` and `end` attributes for the notification.
notification_type_filter = (NotificationFilterProblem |
NotificationFilterRecovery)
- macros = {
+ vars = {
name = "Icinga 2 Admin"
email = "icinga@localhost"
pager = "icingaadmin@localhost.localdomain"
Name |Description
----------------|----------------
display_name |**Optional.** A short description of the user.
- macros |**Optional.** A dictionary containing macros that are specific to this user.
- custom |**Optional.** A dictionary containing custom attributes that are specific to this user.
+ vars |**Optional.** A dictionary containing custom attributes that are specific to this user.
groups |**Optional.** An array of group names.
enable_notifications|**Optional.** Whether notifications are enabled for this user.
notification_period|**Optional.** The name of a time period which determines when this notification should be triggered. Not set by default.
### <a id="objecttype-checkcommand"></a> CheckCommand
-A check command definition. Additional default command macros can be
+A check command definition. Additional default command custom attributes can be
defined here.
Example:
"-o", "$oid$"
]
- macros = {
+ vars = {
address = "127.0.0.1"
community = "public"
}
command |**Required.** The command. This can either be an array of individual command arguments. Alternatively a string can be specified in which case the shell interpreter (usually /bin/sh) takes care of parsing the command.
export_macros |**Optional.** A list of macros which should be exported as environment variables prior to executing the command.
escape_macros |**Optional.** A list of macros which should be shell-escaped in the command.
- macros |**Optional.** A dictionary containing macros that are specific to this command.
+ vars |**Optional.** A dictionary containing custom attributes that are specific to this command.
timeout |**Optional.** The command timeout in seconds. Defaults to 5 minutes.
### <a id="objecttype-notificationcommand"></a> NotificationCommand
command |**Required.** The command. This can either be an array of individual command arguments. Alternatively a string can be specified in which case the shell interpreter (usually /bin/sh) takes care of parsing the command.
export_macros |**Optional.** A list of macros which should be exported as environment variables prior to executing the command.
escape_macros |**Optional.** A list of macros which should be shell-escaped in the command.
- macros |**Optional.** A dictionary containing macros that are specific to this command.
+ vars |**Optional.** A dictionary containing custom attributes that are specific to this command.
timeout |**Optional.** The command timeout in seconds. Defaults to 5 minutes.
### <a id="objecttype-eventcommand"></a> EventCommand
command |**Required.** The command. This can either be an array of individual command arguments. Alternatively a string can be specified in which case the shell interpreter (usually /bin/sh) takes care of parsing the command.
export_macros |**Optional.** A list of macros which should be exported as environment variables prior to executing the command.
escape_macros |**Optional.** A list of macros which should be shell-escaped in the command.
- macros |**Optional.** A dictionary containing macros that are specific to this command.
+ vars |**Optional.** A dictionary containing custom attributes that are specific to this command.
timeout |**Optional.** The command timeout in seconds. Defaults to 5 minutes.
### <a id="objecttype-perfdatawriter"></a> PerfdataWriter
Check command for the built-in `icinga` check. This check returns performance
data for the current Icinga instance.
-The `icinga` check command does not support any macros.
+The `icinga` check command does not support any vars.
be suppressed. This is achieved by setting the `disable_checks` attribute to `true`.
object Host "dsl-router" {
- macros.address = "192.168.1.1"
+ vars.address = "192.168.1.1"
}
object Host "google-dns" {
- macros.address = "8.8.8.8"
+ vars.address = "8.8.8.8"
}
apply Service "ping4" {
check_command = "ping4"
- assign where host.macros.address
+ assign where host.vars.address
}
apply Dependency "internet" {
## <a id="differences-1x-2-custom-attributes"></a> Custom Attributes
+Icinga 2 allows you to define custom attributes in the `vars` dictionary.
+
### <a id="differences-1x-2-action-url-notes-url-notes"></a> Action Url, Notes Url, Notes
Icinga 1.x objects support configuration attributes not required as runtime
attributes for host and service objects, additionally `statusmap_image` and
`2d_coords` for the host's representation in status maps.
-These attributes can be set using the `custom` dictionary in Icinga 2 `Host`
+These attributes can be set using the `vars` dictionary in Icinga 2 `Host`
or `Service` objects:
- custom = {
+ vars = {
notes = "Icinga 2 is the best!"
notes_url = "http://docs.icinga.org"
action_url = "http://dev.icinga.org"
### <a id="differences-1x-2-custom-variables"></a> Custom Variables
Icinga 1.x custom variable attributes must be prefixed using an underscore (`_`).
-In Icinga 2 these attributes must be added to the `custom`dictionary.
+In Icinga 2 these attributes must be added to the `vars` dictionary as custom attributes.
- custom = {
+ vars = {
DN = "cn=icinga2-dev-host,ou=icinga,ou=main,ou=IcingaConfig,ou=LConf,dc=icinga,dc=org"
CV = "my custom cmdb description"
}
+TODO
+
> **Note**
>
> If you are planning to access custom variables as runtime macros you may access
## <a id="differences-1x-2-users"></a> Users
Contacts have been renamed to Users (same for groups). A user does not
-only provide attributes and macros used for notifications, but is also
+only provide attributes and custom attributes used for notifications, but is also
used for authorization checks.
In Icinga 2 notification commands are not directly associated with users.
## <a id="differences-1x-2-macros"></a> Macros
-Various object attributes and runtime variables can be accessed as macros in
-commands in Icinga 1.x - Icinga 2 supports all required [macros](#macros).
-
-> **Note**
->
-> Due to the `contact`objects renamed to `user` objects the associated macros
-> have changed.
-> Furthermore an `alias` is now reflected as `display_name`. The Icinga 1.x
-> notation is still supported for compatibility reasons.
-
- Icinga 1.x Name | Icinga 2 Name
- -----------------------|--------------
- CONTACTNAME | USERNAME
- CONTACTALIAS | USERDISPLAYNAME
- CONTACTEMAIL | USEREMAIL
- CONTACTPAGER | USERPAGER
+TODO
+Various object attributes and runtime variables can be accessed as macros in
+commands in Icinga 1.x - Icinga 2 supports all required [custom attributes](#custom-attributes).
-### <a id="differences-1x-2-command-macros"></a> Command Macros
+### <a id="differences-1x-2-command-arguments"></a> Command Arguments
If you have previously used Icinga 1.x you may already be familiar with
-user and argument macros (e.g., `USER1` or `ARG1`). Unlike in Icinga 1.x macros
-may have arbitrary names and arguments are no longer specified in the
-`check_command` setting.
+user and argument definitions (e.g., `USER1` or `ARG1`). Unlike in Icinga 1.x
+the Icinga 2 custom attributes may have arbitrary names and arguments are no
+longer specified in the `check_command` setting.
-In Icinga 1.x argument macros are specified in the `check_command` attribute and
+In Icinga 1.x arguments are specified in the `check_command` attribute and
are separated from the command name using an exclamation mark (`!`).
define command {
check_command ping4!100.0,20%!500.0,60%
}
-With the freely definable macros in Icinga 2 it looks like this:
+With the freely definable custom attributes in Icinga 2 it looks like this:
object CheckCommand "ping4" {
command = PluginDir + "/check_ping -H $HOSTADDRESS$ -w $wrta$,$wpl%$ -c $crta$,$cpl%$"
object Service "PING" {
check_command = "ping4"
- macros = {
- wrta = 100
- wpl = 20
- crta = 500
- cpl = 60
- }
+ vars.wrta = 100
+ vars.wpl = 20
+ vars.crta = 500
+ vars.cpl = 60
}
> **Note**
>
> Tip: The above example uses the global `PluginDir` constant instead of the Icinga 1.x
> $USER1$ macro. It also replaces the Icinga 1.x notation with $ARGn$ with freely
-> definable macros.
+> definable custom attributes.
### <a id="differences-1x-2-environment-macros"></a> Environment Macros
+TODO
+
The global configuration setting `enable_environment_macros` does not exist in
Icinga 2.
## <a id="differences-1x-2-checks"></a> Checks
-### <a id="differences-1x-2-host-check"></a> Host Check
-
-Unlike in Icinga 1.x hosts are not checkable objects in Icinga 2. Instead hosts
-inherit their state from the service that is specified using the `check`
-attribute.
-
### <a id="differences-1x-2-check-output"></a> Check Output
Icinga 2 does not make a difference between `output` (first line) and
For example in Icinga 1.x it is possible to accidently use a notification
command as an event handler which might cause problems depending on which
-macros are used in the notification command.
+runtime macros are used in the notification command.
In Icinga 2 these command types are separated and will generate an error on
configuration validation if used in the wrong context.
also possible to encapsulate all arguments into double quotes and passing them
as array to the `command_line` attribute i.e. for better readability.
-It's also possible to define default macros for the command itself which can be
+It's also possible to define default custom attributes for the command itself which can be
overridden by a service macro.
## <a id="differences-1x-2-groups"></a> Groups
### <a id="differences-1x-2-notification-options"></a> Notification Options
+TODO
+
Unlike Icinga 1.x with the 'notification_options' attribute with comma-separated
state and type filters, Icinga 2 uses two configuration attributes for that.
All state and type filter use long names or'd with a pipe together
"-t", "$timeout$"
],
- vars.wrta = 100,
- vars.wpl = 5,
-
- vars.crta = 200,
- vars.cpl = 15,
-
- vars.packets = 5,
+ vars.wrta = 100
+ vars.wpl = 5
+ vars.crta = 200
+ vars.cpl = 15
+ vars.packets = 5
vars.timeout = 0
}
projects / icinga2 / commitdiff