diff --git a/doc/2.1-setting-up-icinga-2.md b/doc/2.1-setting-up-icinga-2.md index 0196c8cf2..1db541be2 100644 --- a/doc/2.1-setting-up-icinga-2.md +++ b/doc/2.1-setting-up-icinga-2.md @@ -138,8 +138,8 @@ The `conf.d/localhost.conf` file contains our first host definition: 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 @@ -147,9 +147,10 @@ the `linux-server` template which takes care of setting up the `ping4` and `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" diff --git a/doc/2.5-setting-up-icinga2-uis.md b/doc/2.5-setting-up-icinga2-uis.md index bf088b972..2cd2fa7f7 100644 --- a/doc/2.5-setting-up-icinga2-uis.md +++ b/doc/2.5-setting-up-icinga2-uis.md @@ -57,7 +57,7 @@ UI installation URL: > > 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. diff --git a/doc/3.01-hosts-and-services.md b/doc/3.01-hosts-and-services.md index 2e386c0df..c82abb35b 100644 --- a/doc/3.01-hosts-and-services.md +++ b/doc/3.01-hosts-and-services.md @@ -15,7 +15,7 @@ on the same physical device. 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" } diff --git a/doc/3.02-commands.md b/doc/3.02-commands.md index c3b033cb1..ed76d3c6d 100644 --- a/doc/3.02-commands.md +++ b/doc/3.02-commands.md @@ -7,26 +7,14 @@ events should be handled. > **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. -### Environment Macros +### 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). ### Check Commands @@ -49,15 +37,15 @@ all available options. Our example defines warning (`-w`) and 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" @@ -68,19 +56,19 @@ then use these macros on the command line. "-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" { @@ -88,8 +76,8 @@ space). check_command = "disk" - macros.wfree = 10 - macros.cfree = 5 + vars.wfree = 10 + vars.cfree = 5 } @@ -105,10 +93,12 @@ interfaces (E-Mail, XMPP, IRC, Twitter, etc). 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 macro definitions, you can add a macro dictionary as shown for the -`CheckCommand` object. +If you require default custom attribute definitions, you can add a `vars` dictionary +as shown for the `CheckCommand` object. + +TODO object NotificationCommand "mail-service-notification" { import "plugin-notification-command" @@ -168,7 +158,7 @@ as environment variables and can be used in the notification script: 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. diff --git a/doc/3.03-macros.md b/doc/3.03-custom-attributes-runtime-macros.md similarity index 72% rename from doc/3.03-macros.md rename to doc/3.03-custom-attributes-runtime-macros.md index 25488fca4..7d4f1fac0 100644 --- a/doc/3.03-macros.md +++ b/doc/3.03-custom-attributes-runtime-macros.md @@ -1,25 +1,30 @@ -## Macros +## 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`. -### Runtime Macros +### 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" @@ -32,35 +37,33 @@ Here is an example of a command definition which uses user-defined macros: "-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 (`$$`). -### Runtime Macro Evaluation Order +### 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 @@ -68,43 +71,90 @@ up macros: 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. -#### Custom Variables as Runtime Macros +### Runtime Custom Attributes as Environment Variables -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. +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" + ] + } + +### 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). + + + +## 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). ### 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 @@ -132,15 +182,14 @@ hosts or services: > **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" -where is the name of the custom variable. - ### Service Runtime Macros +TODO + The following service macros are available in all commands that are executed for services: @@ -170,12 +219,13 @@ 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" -where is the name of the custom variable. + ### 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 @@ -185,8 +235,6 @@ users: 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" and -"_CONTACT" where is the name of the custom variable. "_CONTACT" ### Notification Runtime Macros @@ -196,6 +244,8 @@ where is the name of the custom variable. ### Global Runtime Macros +TODO + The following macros are available in all executed commands: Name | Description @@ -206,45 +256,5 @@ The following macros are available in all executed commands: 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" { - 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" - ] - } - -### 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). diff --git a/doc/3.04-notifications.md b/doc/3.04-notifications.md index 638477ec9..6608432ee 100644 --- a/doc/3.04-notifications.md +++ b/doc/3.04-notifications.md @@ -5,7 +5,7 @@ There are many ways of getting a notification to the actual receiver - Email, XM 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). @@ -15,9 +15,10 @@ example on the [MonitoringExchange](http://www.monitoringexchange.org) or the [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. @@ -30,9 +31,8 @@ The user `icingaadmin` in the example below will get notified only on `WARNING` StateFilterCritical) notification_type_filter = (NotificationFilterProblem | NotificationFilterRecovery) - macros = { - "email" = "icinga@localhost" - "pager" = "+49123456789" + vars.email = "icinga@localhost" + vars.pager = "+49123456789" } } @@ -49,14 +49,14 @@ your environment. > **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" @@ -87,7 +87,9 @@ variables and can be used in the notification script. 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 @@ -154,16 +156,14 @@ notifications between start and end time. 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" } } diff --git a/doc/3.05-using-templates.md b/doc/3.05-using-templates.md index b99d76eea..6ce8ee924 100644 --- a/doc/3.05-using-templates.md +++ b/doc/3.05-using-templates.md @@ -17,13 +17,13 @@ configuration: 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 diff --git a/doc/3.06-groups.md b/doc/3.06-groups.md index 2b993183d..252674947 100644 --- a/doc/3.06-groups.md +++ b/doc/3.06-groups.md @@ -17,12 +17,12 @@ Then add your hosts to this hostgroup 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 } } @@ -34,7 +34,7 @@ Then add your hosts to this hostgroup template Host "windows-mssql-template" { groups = [ "windows" ] - macros.mssql_port = 1433 + vars.mssql_port = 1433 } } @@ -60,13 +60,13 @@ the user groups are associated as attributes in `Notification` objects. 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" { diff --git a/doc/3.11-performance-data.md b/doc/3.11-performance-data.md index c8a8cbe57..cf8253e24 100644 --- a/doc/3.11-performance-data.md +++ b/doc/3.11-performance-data.md @@ -1,9 +1,9 @@ ## 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. @@ -23,7 +23,7 @@ the current performance files for their backend updates. 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$" diff --git a/doc/3.15-monitoring-remote-clients.md b/doc/3.15-monitoring-remote-clients.md index b0a8901e6..3c947c494 100644 --- a/doc/3.15-monitoring-remote-clients.md +++ b/doc/3.15-monitoring-remote-clients.md @@ -22,17 +22,17 @@ the `check_snmp` plugin binary, but there are plenty of [existing plugins](#inte 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 @@ -53,7 +53,7 @@ its return code and output. `check_by_ssh` is available in the [Monitoring Plugi apply Service "swap" { import "generic-service" check_command = "check_by_ssh_swap" - macros = { + vars = { "warn" = "50%" "crit" = "75%" } @@ -89,7 +89,7 @@ Example: 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" } @@ -126,7 +126,7 @@ Example: "-s", "$pass$" ] - macros = { + vars = { "port" = "12489" "pass" = "supersecret" } @@ -137,7 +137,7 @@ Example: check_command = "check_nscp" - macros += { + vars += { remote_nscp_command = "USEDDISKSPACE" partition = "c" warn = "70" diff --git a/doc/4.1-configuration-syntax.md b/doc/4.1-configuration-syntax.md index 3b1fa5e19..529a74fdb 100644 --- a/doc/4.1-configuration-syntax.md +++ b/doc/4.1-configuration-syntax.md @@ -8,7 +8,7 @@ objects using the `object` keyword: object Host "host1.example.org" { display_name = "host1" - macros = { + vars = { address = "192.168.0.1" address6 = "::1" } @@ -24,7 +24,7 @@ them with a semi-colon: 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. @@ -333,20 +333,20 @@ Objects can import attributes from other objects. 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 @@ -356,8 +356,8 @@ templates, however in general they are. > **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. @@ -401,8 +401,8 @@ ScheduledDowntime| Service | host, service > **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. ### Boolean Values diff --git a/doc/4.3-object-types.md b/doc/4.3-object-types.md index b3306659c..1d114f35b 100644 --- a/doc/4.3-object-types.md +++ b/doc/4.3-object-types.md @@ -27,7 +27,7 @@ Attributes: 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. ### HostGroup @@ -66,7 +66,7 @@ Example: check_command = "check_snmp" - macros = { + vars = { community = "public" oid = "DISMAN-EVENT-MIB::sysUpTimeInstance" } @@ -84,7 +84,7 @@ Attributes: 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. @@ -147,7 +147,7 @@ Attributes: ----------------|---------------- 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. @@ -242,7 +242,7 @@ Example: notification_type_filter = (NotificationFilterProblem | NotificationFilterRecovery) - macros = { + vars = { name = "Icinga 2 Admin" email = "icinga@localhost" pager = "icingaadmin@localhost.localdomain" @@ -280,8 +280,7 @@ Attributes: 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. @@ -413,7 +412,7 @@ Attributes: ### 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: @@ -428,7 +427,7 @@ Example: "-o", "$oid$" ] - macros = { + vars = { address = "127.0.0.1" community = "public" } @@ -442,7 +441,7 @@ Attributes: 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. ### NotificationCommand @@ -482,7 +481,7 @@ Attributes: 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. ### EventCommand @@ -510,7 +509,7 @@ Attributes: 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. ### PerfdataWriter diff --git a/doc/5-icinga-template-library.md b/doc/5-icinga-template-library.md index d7c4b2c6e..1169d12c9 100644 --- a/doc/5-icinga-template-library.md +++ b/doc/5-icinga-template-library.md @@ -249,4 +249,4 @@ community | **Optional.** The SNMP community. Defaults to "public". 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. diff --git a/doc/6.06-dependencies.md b/doc/6.06-dependencies.md index b0a018799..929a2bad0 100644 --- a/doc/6.06-dependencies.md +++ b/doc/6.06-dependencies.md @@ -21,11 +21,11 @@ further checks for the `ping4` service on host `google-dns` service should 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" { @@ -33,7 +33,7 @@ be suppressed. This is achieved by setting the `disable_checks` attribute to `tr check_command = "ping4" - assign where host.macros.address + assign where host.vars.address } apply Dependency "internet" { diff --git a/doc/8-differences-between-icinga-1x-and-2.md b/doc/8-differences-between-icinga-1x-and-2.md index 8d14da876..ff674e21d 100644 --- a/doc/8-differences-between-icinga-1x-and-2.md +++ b/doc/8-differences-between-icinga-1x-and-2.md @@ -170,6 +170,8 @@ account by Icinga 1.x Classic UI and Web. ## Custom Attributes +Icinga 2 allows you to define custom attributes in the `vars` dictionary. + ### Action Url, Notes Url, Notes Icinga 1.x objects support configuration attributes not required as runtime @@ -178,10 +180,10 @@ The `notes`, `notes_url`, `action_url`, `icon_image`, `icon_image_alt` 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" @@ -196,13 +198,15 @@ External interfaces will recognize and display these attributes accordingly. ### 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 @@ -222,7 +226,7 @@ using the `apply` keyword. ## 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. @@ -235,32 +239,19 @@ and their users. ## Macros +TODO + Various object attributes and runtime variables can be accessed as macros in -commands in Icinga 1.x - Icinga 2 supports all required [macros](#macros). +commands in Icinga 1.x - Icinga 2 supports all required [custom attributes](#custom-attributes). -> **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 - - -### Command Macros +### 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 { @@ -275,7 +266,7 @@ are separated from the command name using an exclamation mark (`!`). 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%$" @@ -283,22 +274,22 @@ With the freely definable macros in Icinga 2 it looks like this: 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. ### Environment Macros +TODO + The global configuration setting `enable_environment_macros` does not exist in Icinga 2. @@ -307,12 +298,6 @@ attribute in command objects. ## Checks -### 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. - ### Check Output Icinga 2 does not make a difference between `output` (first line) and @@ -337,7 +322,7 @@ Unlike in Icinga 1.x there are 3 different command types in Icinga 2: 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. @@ -346,7 +331,7 @@ While Icinga 2 still supports the complete command line in command objects, it's 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. ## Groups @@ -452,6 +437,8 @@ object for the escalation itself. ### 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 diff --git a/itl/command-common.conf b/itl/command-common.conf index b1761d8fe..4a2138c0c 100644 --- a/itl/command-common.conf +++ b/itl/command-common.conf @@ -30,13 +30,11 @@ object CheckCommand "ping4" { "-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 }