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

Merge pull request #7339 from Icinga/feature/docs-rename-cv 

Docs: Rename 'custom attribute' to 'custom variable'
This commit is contained in:
Michael Friedrich 2019-07-19 14:39:39 +02:00 committed by GitHub
parent fbe732a447 5aa07b51a2
commit e9f61ef234
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
19 changed files with 395 additions and 375 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

188
doc/03-monitoring-basics.md
View File

@ -208,10 +208,10 @@ You can also import existing non-template objects.
### Multiple Templates <a id="object-inheritance-using-multiple-templates"></a>
The following example uses [custom attributes](03-monitoring-basics.md#custom-attributes) which
The following example uses [custom variables](03-monitoring-basics.md#custom-variables) which
are provided in each template. The `web-server` template is used as the
base template for any host providing web services. In addition to that it
specifies the custom attribute `webserver_type`, e.g. `apache`. Since this
specifies the custom variable `webserver_type`, e.g. `apache`. Since this
template is also the base template, we import the `generic-host` template here.
This provides the `check_command` attribute by default and we don't need
to set it anywhere later on.
@ -226,7 +226,7 @@ template Host "web-server" {
```
The `wp-server` host template specifies a Wordpress instance and sets
the `application_type` custom attribute. Please note the `+=` [operator](17-language-reference.md#dictionary-operators)
the `application_type` custom variable. Please note the `+=` [operator](17-language-reference.md#dictionary-operators)
which adds [dictionary](17-language-reference.md#dictionary) items,
but does not override any previous `vars` attribute.
@ -265,10 +265,22 @@ object Host "wp1.example.com" {
}
```
## Custom Attributes <a id="custom-attributes"></a>
<!-- Keep this for compatibility -->
<a id="custom-attributes"></a>
In addition to built-in attributes you can define your own attributes
inside the `vars` attribute:
## Custom Variables <a id="custom-variables"></a>
In addition to built-in object attributes you can define your own custom
attributes inside the `vars` attribute.
> **Tip**
>
> This is called `custom variables` throughout the documentation, backends and web interfaces.
>
> Older documentation versions referred to this as `custom attribute`.
The following example specifies the key `ssh_port` as custom
variable and assigns an integer value.
```
object Host "localhost" {
@ -295,17 +307,17 @@ or
vars["ssh_port"] = 2222
```
### Custom Attribute Values <a id="custom-attributes-values"></a>
### Custom Variable Values <a id="custom-variables-values"></a>
Valid values for custom attributes include:
Valid values for custom variables include:
* [Strings](17-language-reference.md#string-literals), [numbers](17-language-reference.md#numeric-literals) and [booleans](17-language-reference.md#boolean-literals)
* [Arrays](17-language-reference.md#array) and [dictionaries](17-language-reference.md#dictionary)
* [Functions](03-monitoring-basics.md#custom-attributes-functions)
* [Functions](03-monitoring-basics.md#custom-variables-functions)
You can also define nested values such as dictionaries in dictionaries.
This example defines the custom attribute `disks` as dictionary.
This example defines the custom variable `disks` as dictionary.
The first key is set to `disk /` is itself set to a dictionary
with one key-value pair.
@ -338,7 +350,7 @@ Another example which is shown in the example configuration:
}
```
This defines the `notification` custom attribute as dictionary
This defines the `notification` custom variable as dictionary
with the key `mail`. Its value is a dictionary with the key `groups`
which itself has an array as value. Note: This array is the exact
same as the `user_groups` attribute for [notification apply rules](#03-monitoring-basics.md#using-apply-notifications)
@ -354,11 +366,13 @@ expects.
}
```
<!-- Keep this for compatibility -->
<a id="custom-attributes-functions"></a>
### Functions as Custom Attributes <a id="custom-attributes-functions"></a>
### Functions as Custom Variables <a id="custom-variables-functions"></a>
Icinga 2 lets you specify [functions](17-language-reference.md#functions) for custom attributes.
The special case here is that whenever Icinga 2 needs the value for such a custom attribute it runs
Icinga 2 lets you specify [functions](17-language-reference.md#functions) for custom variables.
The special case here is that whenever Icinga 2 needs the value for such a custom variable it runs
the function and uses whatever value the function returns:
```
@ -430,22 +444,25 @@ Accessing object attributes at runtime inside these functions is described in th
## Runtime Macros <a id="runtime-macros"></a>
Macros can be used to access other objects' attributes at runtime. For example they
are used in command definitions to figure out which IP address a check should be
run against:
Macros can be used to access other objects' attributes and [custom variables](03-monitoring-basics.md#custom-variables)
at runtime. For example they are used in command definitions to figure out
which IP address a check should be run against:
```
object CheckCommand "my-ping" {
command = [ PluginDir + "/check_ping", "-H", "$ping_address$" ]
command = [ PluginDir + "/check_ping" ]
arguments = {
"-H" = "$ping_address$"
"-w" = "$ping_wrta$,$ping_wpl$%"
"-c" = "$ping_crta$,$ping_cpl$%"
"-p" = "$ping_packets$"
}
// Resolve from a host attribute, or custom variable.
vars.ping_address = "$address$"
// Default values
vars.ping_wrta = 100
vars.ping_wpl = 5
@ -464,7 +481,7 @@ object Host "router" {
In this example we are using the `$address$` macro to refer to the host's `address`
attribute.
We can also directly refer to custom attributes, e.g. by using `$ping_wrta$`. Icinga
We can also directly refer to custom variables, e.g. by using `$ping_wrta$`. Icinga
automatically tries to find the closest match for the attribute you specified. The
exact rules for this are explained in the next section.
@ -483,12 +500,12 @@ up macros and their respective values:
2. Service object
3. Host object
4. Command object
5. Global custom attributes in the `Vars` constant
5. Global custom variables in the `Vars` constant
This execution order allows you to define default values for custom attributes
This execution order allows you to define default values for custom variables
in your command objects.
Here's how you can override the custom attribute `ping_packets` from the previous
Here's how you can override the custom variable `ping_packets` from the previous
example:
```
@ -500,7 +517,7 @@ object Service "ping" {
}
```
If a custom attribute isn't defined anywhere, an empty value is used and a warning is
If a custom variable isn't defined anywhere, an empty value is used and a warning is
written to the Icinga 2 log.
You can also directly refer to a specific attribute -- thereby ignoring these evaluation
@ -510,14 +527,14 @@ rules -- by specifying the full attribute name:
$service.vars.ping_wrta$
```
This retrieves the value of the `ping_wrta` custom attribute for the service. This
returns an empty value if the service does not have such a custom attribute no matter
This retrieves the value of the `ping_wrta` custom variable for the service. This
returns an empty value if the service does not have such a custom variable no matter
whether another object such as the host has this attribute.
### Host Runtime Macros <a id="host-runtime-macros"></a>
The following host custom attributes are available in all commands that are executed for
The following host custom variables are available in all commands that are executed for
hosts or services:
Name | Description
@ -583,7 +600,7 @@ attributes can be accessed too.
### Command Runtime Macros <a id="command-runtime-macros"></a>
The following custom attributes are available in all commands:
The following custom variables are available in all commands:
Name | Description
-----------------------|--------------
@ -591,7 +608,7 @@ The following custom attributes are available in all commands:
### User Runtime Macros <a id="user-runtime-macros"></a>
The following custom attributes are available in all commands that are executed for
The following custom variables are available in all commands that are executed for
users:
Name | Description
@ -688,7 +705,7 @@ More explanations on assign where expressions can be found [here](03-monitoring-
Before you start with apply rules keep the following in mind:
* Define the best match.
* A set of unique [custom attributes](03-monitoring-basics.md#custom-attributes) for these hosts/services?
* A set of unique [custom variables](03-monitoring-basics.md#custom-variables) for these hosts/services?
* Or [group](03-monitoring-basics.md#groups) memberships, e.g. a host being a member of a hostgroup which should have a service set?
* A generic pattern [match](18-library-reference.md#global-functions-match) on the host/service name?
* [Multiple expressions combined](03-monitoring-basics.md#using-apply-expressions) with `&&` or `||` [operators](17-language-reference.md#expression-operators)
@ -710,12 +727,12 @@ objects in that scope (host and/or service objects).
vars.application_type = host.vars.application_type
```
[Custom attributes](03-monitoring-basics.md#custom-attributes) can also store
[Custom variables](03-monitoring-basics.md#custom-variables) can also store
nested dictionaries and arrays. That way you can use them for not only matching
for their existence or values in apply expressions, but also assign
("inherit") their values into the generated objected from apply rules.
Remember the examples shown for [custom attribute values](03-monitoring-basics.md#custom-attributes-values):
Remember the examples shown for [custom variable values](03-monitoring-basics.md#custom-variables-values):
```
vars.notification["mail"] = {
@ -725,7 +742,7 @@ Remember the examples shown for [custom attribute values](03-monitoring-basics.m
You can do two things here:
* Check for the existence of the `notification` custom attribute and its nested dictionary key `mail`.
* Check for the existence of the `notification` custom variable and its nested dictionary key `mail`.
If this is boolean true, the notification object will be generated.
* Assign the value of the `groups` key to the `user_groups` attribute.
@ -742,9 +759,9 @@ apply Notification "mail-icingaadmin" to Host {
A more advanced example is to use [apply rules with for loops on arrays or
dictionaries](03-monitoring-basics.md#using-apply-for) provided by
[custom atttributes](03-monitoring-basics.md#custom-attributes) or groups.
[custom atttributes](03-monitoring-basics.md#custom-variables) or groups.
Remember the examples shown for [custom attribute values](03-monitoring-basics.md#custom-attributes-values):
Remember the examples shown for [custom variable values](03-monitoring-basics.md#custom-variables-values):
```
vars.disks["disk /"] = {
@ -801,7 +818,7 @@ Assign a service to a specific host in a host group [array](18-library-reference
assign where "hostgroup-dev" in host.groups
```
Assign an object when a custom attribute is [equal](17-language-reference.md#expression-operators) to a value:
Assign an object when a custom variable is [equal](17-language-reference.md#expression-operators) to a value:
```
assign where host.vars.application_type == "database"
@ -827,8 +844,8 @@ Match the host name by using a [regular expression](18-library-reference.md#glob
assign where regex("^webserver-[\\d+]", host.name)
```
[Match](18-library-reference.md#global-functions-match) all `*mysql*` patterns in the host name and (`&&`) custom attribute `prod_mysql_db`
matches the `db-*` pattern. All hosts with the custom attribute `test_server` set to `true`
[Match](18-library-reference.md#global-functions-match) all `*mysql*` patterns in the host name and (`&&`) custom variable `prod_mysql_db`
matches the `db-*` pattern. All hosts with the custom variable `test_server` set to `true`
should be ignored, or any host name ending with `*internal` pattern.
```
@ -843,11 +860,11 @@ object HostGroup "mysql-server" {
Similar example for advanced notification apply rule filters: If the service
attribute `notes` [matches](18-library-reference.md#global-functions-match) the `has gold support 24x7` string `AND` one of the
two condition passes, either the `customer` host custom attribute is set to `customer-xy`
`OR` the host custom attribute `always_notify` is set to `true`.
two condition passes, either the `customer` host custom variable is set to `customer-xy`
`OR` the host custom variable `always_notify` is set to `true`.
The notification is ignored for services whose host name ends with `*internal`
`OR` the `priority` custom attribute is [less than](17-language-reference.md#expression-operators) `2`.
`OR` the `priority` custom variable is [less than](17-language-reference.md#expression-operators) `2`.
```
template Notification "cust-xy-notification" {
@ -871,7 +888,7 @@ The sample configuration already includes a detailed example in [hosts.conf](04-
and [services.conf](04-configuration.md#services-conf) for this use case.
The example for `ssh` applies a service object to all hosts with the `address`
attribute being defined and the custom attribute `os` set to the string `Linux` in `vars`.
attribute being defined and the custom variable `os` set to the string `Linux` in `vars`.
```
apply Service "ssh" {
@ -902,17 +919,17 @@ apply Notification "mail-noc" to Service {
```
In this example the `mail-noc` notification will be created as object for all services having the
`notification.mail` custom attribute defined. The notification command is set to `mail-service-notification`
`notification.mail` custom variable defined. The notification command is set to `mail-service-notification`
and all members of the user group `noc` will get notified.
It is also possible to generally apply a notification template and dynamically overwrite values from
the template by checking for custom attributes. This can be achieved by using [conditional statements](17-language-reference.md#conditional-statements):
the template by checking for custom variables. This can be achieved by using [conditional statements](17-language-reference.md#conditional-statements):
```
apply Notification "host-mail-noc" to Host {
import "mail-host-notification"
// replace interval inherited from `mail-host-notification` template with new notfication interval set by a host custom attribute
// replace interval inherited from `mail-host-notification` template with new notfication interval set by a host custom variable
if (host.vars.notification_interval) {
interval = host.vars.notification_interval
}
@ -922,7 +939,7 @@ apply Notification "host-mail-noc" to Host {
period = host.vars.notification_period
}
// Send SMS instead of email if the host's custom attribute `notification_type` is set to `sms`
// Send SMS instead of email if the host's custom variable `notification_type` is set to `sms`
if (host.vars.notification_type == "sms") {
command = "sms-host-notification"
} else {
@ -939,7 +956,7 @@ In the example above the notification template `mail-host-notification`
contains all relevant notification settings.
The apply rule is applied on all host objects where the `host.address` is defined.
If the host object has a specific custom attribute set, its value is inherited
If the host object has a specific custom variable set, its value is inherited
into the local notification object scope, e.g. `host.vars.notification_interval`,
`host.vars.notification_period` and `host.vars.notification_type`.
This overwrites attributes already specified in the imported `mail-host-notification`
@ -993,7 +1010,7 @@ object Host "router-v6" {
```
The idea is to create service objects for `if01` and `temp` but not `bgp`.
The oid value should also be used as service custom attribute `snmp_oid`.
The oid value should also be used as service custom variable `snmp_oid`.
This is the command argument required by the [snmp](10-icinga-template-library.md#plugin-check-command-snmp)
check command.
The service's `display_name` should be set to the identifier inside the dictionary,
@ -1009,7 +1026,7 @@ apply Service for (identifier => oid in host.vars.oids) {
}
```
Icinga 2 evaluates the `apply for` rule for all objects with the custom attribute
Icinga 2 evaluates the `apply for` rule for all objects with the custom variable
`oids` set.
It iterates over all dictionary items inside the `for` loop and evaluates the
`assign/ignore where` expressions. You can access the loop variable
@ -1026,13 +1043,15 @@ unwanted services. A different approach would be to match the `oid` value with a
> **Note**
>
> You don't need an `assign where` expression which checks for the existence of the
> `oids` custom attribute.
> `oids` custom variable.
This method saves you from creating multiple apply rules. It also moves
the attribute specification logic from the service to the host.
<!-- Keep this for compatibility -->
<a id="using-apply-for-custom-attribute-override"></a>
#### Apply For and Custom Attribute Override <a id="using-apply-for-custom-attribute-override"></a>
#### Apply For and Custom Variable Override <a id="using-apply-for-custom-variable-override"></a>
Imagine a different more advanced example: You are monitoring your network device (host)
with many interfaces (services). The following requirements/problems apply:
@ -1052,11 +1071,11 @@ dynamically generated.
const IftrafficSnmpCommunity = "public"
```
Define the `interfaces` [custom attribute](03-monitoring-basics.md#custom-attributes)
Define the `interfaces` [custom variable](03-monitoring-basics.md#custom-variables)
on the `cisco-catalyst-6509-34` host object and add three example interfaces as dictionary keys.
Specify additional attributes inside the nested dictionary
as learned with [custom attribute values](03-monitoring-basics.md#custom-attributes-values):
as learned with [custom variable values](03-monitoring-basics.md#custom-variables-values):
```
object Host "cisco-catalyst-6509-34" {
@ -1068,7 +1087,7 @@ object Host "cisco-catalyst-6509-34" {
* and key name in service apply for later on
*/
vars.interfaces["GigabitEthernet0/2"] = {
/* define all custom attributes with the
/* define all custom variables with the
* same name required for command parameters/arguments
* in service apply (look into your CheckCommand definition)
*/
@ -1141,17 +1160,17 @@ interface_config = {
```
Access the dictionary keys with the [indexer](17-language-reference.md#indexer) syntax
and assign them to custom attributes used as command parameters for the `iftraffic`
and assign them to custom variables used as command parameters for the `iftraffic`
check command.
```
/* map the custom attributes as command arguments */
/* map the custom variables as command arguments */
vars.iftraffic_units = interface_config.iftraffic_units
vars.iftraffic_community = interface_config.iftraffic_community
```
If you just want to inherit all attributes specified inside the `interface_config`
dictionary, add it to the generated service custom attributes like this:
dictionary, add it to the generated service custom variables like this:
```
/* the above can be achieved in a shorter fashion if the names inside host.vars.interfaces
@ -1161,7 +1180,7 @@ dictionary, add it to the generated service custom attributes like this:
vars += interface_config
```
If the user did not specify default values for required service custom attributes,
If the user did not specify default values for required service custom variables,
add them here. This also helps to avoid unwanted configuration validation errors or
runtime failures. Please read more about conditional statements [here](17-language-reference.md#conditional-statements).
@ -1211,7 +1230,7 @@ more object attributes which can be e.g. seen in external interfaces.
> after successful [configuration validation](11-cli-commands.md#config-validation).
Verify that the apply-for-rule successfully created the service objects with the
inherited custom attributes:
inherited custom variables:
```
# icinga2 daemon -C
@ -1292,7 +1311,7 @@ object Host "opennebula-host" {
}
```
`hosting` is a custom attribute with the Dictionary value type.
`hosting` is a custom variable with the Dictionary value type.
This is mandatory to iterate with the `key => value` notation
in the below apply for rule.
@ -1573,11 +1592,11 @@ already provides an example for this question.
> **Tip**
>
> Please make sure to read the [apply](03-monitoring-basics.md#using-apply) and
> [custom attribute values](03-monitoring-basics.md#custom-attributes-values) chapter to
> [custom variable values](03-monitoring-basics.md#custom-variables-values) chapter to
> fully understand these examples.
Specify the user and groups as nested custom attribute on the host object:
Specify the user and groups as nested custom variable on the host object:
```
object Host "icinga2-client1.localdomain" {
@ -1597,7 +1616,7 @@ As you can see, there is the option to use two different notification
apply rules here: One for `mail` and one for `sms`.
This example assigns the `users` and `groups` nested keys from the `notification`
custom attribute to the actual notification object attributes.
custom variable to the actual notification object attributes.
Since errors are hard to debug if host objects don't specify the required
configuration attributes, you can add a safety condition which logs which
@ -1904,7 +1923,7 @@ Please continue reading in the [plugins section](05-service-monitoring.md#servic
#### Passing Check Command Parameters from Host or Service <a id="command-passing-parameters"></a>
Check command parameters are defined as custom attributes which can be accessed as runtime macros
Check command parameters are defined as custom variables which can be accessed as runtime macros
by the executed check command.
The check command parameters for ITL provided plugin check command definitions are documented
@ -1915,9 +1934,9 @@ In order to practice passing command parameters you should [integrate your own p
The following example will use `check_mysql` provided by the [Monitoring Plugins installation](02-installation.md#setting-up-check-plugins).
Define the default check command custom attributes, for example `mysql_user` and `mysql_password`
Define the default check command custom variables, for example `mysql_user` and `mysql_password`
(freely definable naming schema) and optional their default threshold values. You can
then use these custom attributes as runtime macros for [command arguments](03-monitoring-basics.md#command-arguments)
then use these custom variables as runtime macros for [command arguments](03-monitoring-basics.md#command-arguments)
on the command line.
> **Tip**
@ -1926,8 +1945,8 @@ on the command line.
> readability. `mysql_user` helps understanding the context better than just
> `user` as argument.
The default custom attributes can be overridden by the custom attributes
defined in the host or service using the check command `my-mysql`. The custom attributes
The default custom variables can be overridden by the custom variables
defined in the host or service using the check command `my-mysql`. The custom variables
can also be inherited from a parent template using additive inheritance (`+=`).
```
@ -1998,7 +2017,7 @@ apply Service "mysql-icinga-db-health" {
Take a different example: The example host configuration in [hosts.conf](04-configuration.md#hosts-conf)
also applies an `ssh` service check. Your host's ssh port is not the default `22`, but set to `2022`.
You can pass the command parameter as custom attribute `ssh_port` directly inside the service apply rule
You can pass the command parameter as custom variable `ssh_port` directly inside the service apply rule
inside [services.conf](04-configuration.md#services-conf):
```
@ -2026,10 +2045,10 @@ object Host "icinga2-client1.localdomain {
The host `localhost` with the generated services from the `basic-partitions` dictionary (see
[apply for](03-monitoring-basics.md#using-apply-for) for details) checks a basic set of disk partitions
with modified custom attributes (warning thresholds at `10%`, critical thresholds at `5%`
with modified custom variables (warning thresholds at `10%`, critical thresholds at `5%`
free disk space).
The custom attribute `disk_partition` can either hold a single string or an array of
The custom variable `disk_partition` can either hold a single string or an array of
string values for passing multiple partitions to the `check_disk` check plugin.
```
@ -2055,8 +2074,8 @@ apply Service for (disk => config in host.vars.local_disks) {
```
More details on using arrays in custom attributes can be found in
[this chapter](03-monitoring-basics.md#custom-attributes).
More details on using arrays in custom variables can be found in
[this chapter](03-monitoring-basics.md#custom-variables).
#### Command Arguments <a id="command-arguments"></a>
@ -2107,7 +2126,7 @@ the value is not set. For example, if the service calling the check command
does not have `vars.http_port` set, it won't get added to the command
line.
If the `vars.http_ssl` custom attribute is set in the service, host or command
If the `vars.http_ssl` custom variable is set in the service, host or command
object definition, Icinga 2 will add the `-S` argument based on the `set_if`
numeric value to the command line. String values are not supported.
@ -2169,7 +2188,7 @@ References: [abbreviated lambda syntax](17-language-reference.md#nullary-lambdas
#### Environment Variables <a id="command-environment-variables"></a>
The `env` command object attribute specifies a list of environment variables with values calculated
from custom attributes which should be exported as environment variables prior to executing the command.
from custom variables 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:
@ -2203,7 +2222,7 @@ the database credentials in the user's environment.
> **Note**
>
> If the CheckCommand also supports setting the parameter in the command line,
> ensure to use a different name for the custom attribute. Otherwise Icinga 2
> ensure to use a different name for the custom variable. Otherwise Icinga 2
> adds the command line parameter.
If a specific CheckCommand object provided with the [Icinga Template Library](10-icinga-template-library.md#icinga-template-library)
@ -2221,7 +2240,7 @@ object CheckCommand "mysql_health_env" {
}
```
Specify the custom attributes `mysql_health_env_username` and `mysql_health_env_password`
Specify the custom variables `mysql_health_env_username` and `mysql_health_env_password`
in the service object then.
> **Note**
@ -2350,7 +2369,7 @@ account but all parents are inherited.
The `parent_host_name` and `parent_service_name` attributes are mandatory for
service dependencies, `parent_host_name` is required for host dependencies.
[Apply rules](03-monitoring-basics.md#using-apply) will allow you to
[determine these attributes](03-monitoring-basics.md#dependencies-apply-custom-attributes) in a more
[determine these attributes](03-monitoring-basics.md#dependencies-apply-custom-variables) in a more
dynamic fashion if required.
```
@ -2457,7 +2476,10 @@ apply Dependency "internet" to Service {
}
```
### Apply Dependencies based on Custom Attributes <a id="dependencies-apply-custom-attributes"></a>
<!-- Keep this for compatibility -->
<a id="dependencies-apply-custom-attríbutes"></a>
### Apply Dependencies based on Custom Variables <a id="dependencies-apply-custom-variables"></a>
You can use [apply rules](03-monitoring-basics.md#using-apply) to set parent or
child attributes, e.g. `parent_host_name` to other objects'
@ -2465,7 +2487,7 @@ attributes.
A common example are virtual machines hosted on a master. The object
name of that master is auto-generated from your CMDB or VMWare inventory
into the host's custom attributes (or a generic template for your
into the host's custom variables (or a generic template for your
cloud).
Define your master host object:
@ -2487,7 +2509,7 @@ template Host "generic-vm" {
```
Add a template for all hosts on your example.com cloud setting
custom attribute `vm_parent` to `master.example.com`:
custom variable `vm_parent` to `master.example.com`:
```
template Host "generic-vm-example.com" {
@ -2510,7 +2532,7 @@ object Host "www.example2.com" {
Apply the host dependency to all child hosts importing the
`generic-vm` template and set the `parent_host_name`
to the previously defined custom attribute `host.vars.vm_parent`.
to the previously defined custom variable `host.vars.vm_parent`.
```
apply Dependency "vm-host-to-parent-master" to Host {
@ -2957,7 +2979,7 @@ object EventCommand "event_by_ssh" {
```
The actual event command only passes the `event_by_ssh_command` attribute.
The `event_by_ssh_service` custom attribute takes care of passing the correct
The `event_by_ssh_service` custom variable takes care of passing the correct
daemon name, while `test $service.state_id$ -gt 0` makes sure that the daemon
is only restarted when the service is not in an `OK` state.
@ -2990,7 +3012,7 @@ apply Service "http" {
}
```
Specify the `httpd_name` custom attribute on the host to assign the
Specify the `httpd_name` custom variable on the host to assign the
service and set the event handler service.
```

22
doc/04-configuration.md
View File

@ -48,7 +48,7 @@ Consider these ideas:
In either way of choosing the right strategy you should additionally check the following:
* Are there any specific attributes describing the host/service you could set as `vars` custom attributes?
* Are there any specific attributes describing the host/service you could set as `vars` custom variables?
You can later use them for applying assign/ignore rules, or export them into external interfaces.
* Put hosts into hostgroups, services into servicegroups and use these attributes for your apply rules.
* Use templates to store generic attributes for your objects and apply rules making your configuration more readable.
@ -276,11 +276,11 @@ The `import` keyword is used to import the `generic-host` template which
takes care of setting up the host check command to `hostalive`. If you
require a different check command, you can override it in the object definition.
The `vars` attribute can be used to define custom attributes which are available
The `vars` attribute can be used to define custom variables which are available
for check and notification commands. Most of the [Plugin Check Commands](10-icinga-template-library.md#icinga-template-library)
in the Icinga Template Library require an `address` attribute.
The custom attribute `os` is evaluated by the `linux-servers` group in
The custom variable `os` is evaluated by the `linux-servers` group in
[groups.conf](04-configuration.md#groups-conf) making the local host a member.
The example host will show you how to:
@ -324,7 +324,7 @@ object Host NodeName {
address = "127.0.0.1"
address6 = "::1"
/* Set custom attribute `os` for hostgroup assignment in `groups.conf`. */
/* Set custom variable `os` for hostgroup assignment in `groups.conf`. */
vars.os = "Linux"
/* Define http vhost attributes for service apply rules in `services.conf`. */
@ -377,8 +377,8 @@ Service(s) | Applied on host(s)
`load`, `procs`, `swap`, `users`, `icinga` | The `NodeName` host only.
`ping4`, `ping6` | All hosts with `address` resp. `address6` attribute.
`ssh` | All hosts with `address` and `vars.os` set to `Linux`
`http`, optional: `Icinga Web 2` | All hosts with custom attribute `http_vhosts` defined as dictionary.
`disk`, `disk /` | All hosts with custom attribute `disks` defined as dictionary.
`http`, optional: `Icinga Web 2` | All hosts with custom variable `http_vhosts` defined as dictionary.
`disk`, `disk /` | All hosts with custom variable `disks` defined as dictionary.
The Debian packages also include an additional `apt` service check applied to the local host.
@ -407,7 +407,7 @@ The `apply` keyword can be used to create new objects which are associated with
another group of objects. You can `import` existing templates, define (custom)
attributes.
The custom attribute `backup_downtime` is defined to a specific timerange string.
The custom variable `backup_downtime` is defined to a specific timerange string.
This variable value will be used for applying a `ScheduledDowntime` object to
these services in [downtimes.conf](04-configuration.md#downtimes-conf).
@ -430,7 +430,7 @@ apply Service "ssh" {
```
In this example, the service `ssh` is applied to all hosts having the `address`
attribute defined `AND` having the custom attribute `os` set to the string
attribute defined `AND` having the custom variable `os` set to the string
`Linux`.
You can modify this condition to match multiple expressions by combining `AND`
and `OR` using `&&` and `||` [operators](17-language-reference.md#expression-operators), for example
@ -443,7 +443,7 @@ hosts, you can go one step further: Generate apply rules based on array items
or dictionary key-value pairs.
The idea is simple: Your host in [hosts.conf](04-configuration.md#hosts-conf) defines the
`disks` dictionary as custom attribute in `vars`.
`disks` dictionary as custom variable in `vars`.
Remember the example from [hosts.conf](04-configuration.md#hosts-conf):
@ -583,7 +583,7 @@ Read more on that topic [here](03-monitoring-basics.md#notification-commands).
#### groups.conf <a id="groups-conf"></a>
The example host defined in [hosts.conf](hosts-conf) already has the
custom attribute `os` set to `Linux` and is therefore automatically
custom variable `os` set to `Linux` and is therefore automatically
a member of the host group `linux-servers`.
This is done by using the [group assign](17-language-reference.md#group-assign) expressions similar
@ -681,7 +681,7 @@ More details on `Notification` object attributes can be found [here](09-object-t
#### downtimes.conf <a id="downtimes-conf"></a>
The `load` service apply rule defined in [services.conf](04-configuration.md#services-conf) defines
the `backup_downtime` custom attribute.
the `backup_downtime` custom variable.
The ScheduledDowntime apply rule uses this attribute to define the default value
for the time ranges required for recurring downtime slots.

2
doc/06-distributed-monitoring.md
View File

@ -2435,7 +2435,7 @@ Based on the [master with clients](06-distributed-monitoring.md#distributed-moni
scenario we'll now add a local nscp check which queries the NSClient++ API to check the free disk space.
Define a host object called `icinga2-client2.localdomain` on the master. Add the `nscp_api_password`
custom attribute and specify the drives to check.
custom variable and specify the drives to check.
```
[root@icinga2-master1.localdomain /]# cd /etc/icinga2/zones.d/master

4
doc/07-agent-based-monitoring.md
View File

@ -12,8 +12,8 @@ the `check_snmp` plugin binary, but there are plenty of [existing plugins](05-se
for specific use cases already around, for example monitoring Cisco routers.
The following example uses the [SNMP ITL](10-icinga-template-library.md#plugin-check-command-snmp) `CheckCommand` and just
overrides the `snmp_oid` custom attribute. A service is created for all hosts which
have the `snmp-community` custom attribute.
overrides the `snmp_oid` custom variable. A service is created for all hosts which
have the `snmp-community` custom variable.
```
apply Service "uptime" {

22
doc/08-advanced-topics.md
View File

@ -587,7 +587,7 @@ You might also want to add additional checks for SSL certificate expiration.
[Apply rules](03-monitoring-basics.md#using-apply) can be used to create a rule set which is
entirely based on host objects and their attributes.
In addition to that [apply for and custom attribute override](03-monitoring-basics.md#using-apply-for)
In addition to that [apply for and custom variable override](03-monitoring-basics.md#using-apply-for)
extend the possibilities.
The following example defines a dictionary on the host object which contains
@ -664,7 +664,7 @@ apply Service "webserver_url" for (instance => config in host.vars.webserver.ins
}
```
The variables defined in the host dictionary are not using the typical custom attribute
The variables defined in the host dictionary are not using the typical custom variable
prefix recommended for CheckCommand parameters. Instead they are re-used for multiple
service checks in this example.
In addition to defining check parameters this way, you can also enrich the `display_name`
@ -674,7 +674,7 @@ attribute with more details. This will be shown in in Icinga Web 2 for example.
There is a limited scope where functions can be used as object attributes such as:
* As value for [Custom Attributes](03-monitoring-basics.md#custom-attributes-functions)
* As value for [Custom Variables](03-monitoring-basics.md#custom-variables-functions)
* Returning boolean expressions for [set_if](08-advanced-topics.md#use-functions-command-arguments-setif) inside command arguments
* Returning a [command](08-advanced-topics.md#use-functions-command-attribute) array inside command objects
@ -683,7 +683,7 @@ The other way around you can create objects dynamically using your own global fu
> **Note**
>
> Functions called inside command objects share the same global scope as runtime macros.
> Therefore you can access host custom attributes like `host.vars.os`, or any other
> Therefore you can access host custom variables like `host.vars.os`, or any other
> object attribute from inside the function definition used for [set_if](08-advanced-topics.md#use-functions-command-arguments-setif) or [command](08-advanced-topics.md#use-functions-command-attribute).
Tips when implementing functions:
@ -850,7 +850,7 @@ object HostGroup "printers-lexmark" {
```
Take a different more complex example: All hosts with the
custom attribute `vars_app` as nested dictionary should be
custom variable `vars_app` as nested dictionary should be
added to the host group `ABAP-app-server`. But only if the
`app_type` for all entries is set to `ABAP`.
@ -875,7 +875,7 @@ object Host "appserver02" {
}
globals.check_app_type = function(host, type) {
/* ensure that other hosts without the custom attribute do not match */
/* ensure that other hosts without the custom variable do not match */
if (typeof(host.vars.vars_app) != Dictionary) {
return false
}
@ -924,7 +924,7 @@ The more significant problem was to only add the command parameter `--disk` to t
when the dictionary `compellent` contains the key `disks`, and omit it if not found.
By defining `set_if` as [abbreviated lambda function](17-language-reference.md#nullary-lambdas)
and evaluating the host custom attribute `compellent` containing the `disks` this problem was
and evaluating the host custom variable `compellent` containing the `disks` this problem was
solved like this:
```
@ -972,11 +972,11 @@ The more programmatic approach for `set_if` could look like this:
if (typeof(srv_vars.compellent) == Dictionary) {
return srv_vars.compellent.contains("disks")
} else {
log(LogInformationen, "checkcommand set_if", "custom attribute compellent_checks is not a dictionary, ignoring it.")
log(LogInformationen, "checkcommand set_if", "custom variable compellent_checks is not a dictionary, ignoring it.")
return false
}
} else {
log(LogWarning, "checkcommand set_if", "empty custom attributes")
log(LogWarning, "checkcommand set_if", "empty custom variables")
return false
}
}}
@ -990,7 +990,7 @@ or [EventCommands](09-object-types.md#objecttype-eventcommand) which does not re
a returned checkresult including state/output.
The following example was taken from the community support channels. The requirement was to
specify a custom attribute inside the notification apply rule and decide which notification
specify a custom variable inside the notification apply rule and decide which notification
script to call based on that.
```
@ -1013,7 +1013,7 @@ apply Notification "mail-admins-short" to Host {
The solution is fairly simple: The `command` attribute is implemented as function returning
an array required by the caller Icinga 2.
The local variable `mailscript` sets the default value for the notification scrip location.
If the notification custom attribute `short` is set, it will override the local variable `mailscript`
If the notification custom variable `short` is set, it will override the local variable `mailscript`
with a new value.
The `mailscript` variable is then used to compute the final notification command array being
returned.

20
doc/09-object-types.md
View File

@ -63,7 +63,7 @@ chapter.
### CheckCommand <a id="objecttype-checkcommand"></a>
A check command definition. Additional default command custom attributes can be
A check command definition. Additional default command custom variables can be
defined here.
Example:
@ -108,7 +108,7 @@ Configuration Attributes:
--------------------------|-----------------------|----------------------------------
command | Array | **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. When using the "arguments" attribute this must be an array. Can be specified as function for advanced implementations.
env | Dictionary | **Optional.** A dictionary of macros which should be exported as environment variables prior to executing the command.
vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this command.
vars | Dictionary | **Optional.** A dictionary containing custom variables that are specific to this command.
timeout | Duration | **Optional.** The command timeout in seconds. Defaults to `1m`.
arguments | Dictionary | **Optional.** A dictionary of command arguments.
@ -348,7 +348,7 @@ Configuration Attributes:
--------------------------|-----------------------|----------------------------------
command | Array | **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. When using the "arguments" attribute this must be an array. Can be specified as function for advanced implementations.
env | Dictionary | **Optional.** A dictionary of macros which should be exported as environment variables prior to executing the command.
vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this command.
vars | Dictionary | **Optional.** A dictionary containing custom variables that are specific to this command.
timeout | Duration | **Optional.** The command timeout in seconds. Defaults to `1m`.
arguments | Dictionary | **Optional.** A dictionary of command arguments.
@ -383,7 +383,7 @@ Configuration Attributes:
address | String | **Optional.** The host's IPv4 address. Available as command runtime macro `$address$` if set.
address6 | String | **Optional.** The host's IPv6 address. Available as command runtime macro `$address6$` if set.
groups | Array of object names | **Optional.** A list of host groups this host belongs to.
vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this host.
vars | Dictionary | **Optional.** A dictionary containing custom variables that are specific to this host.
check\_command | Object name | **Required.** The name of the check command.
max\_check\_attempts | Number | **Optional.** The number of times a host is re-checked before changing into a hard state. Defaults to 3.
check\_period | Object name | **Optional.** The name of a time period which determines when this host should be checked. Not set by default (effectively 24x7).
@ -511,7 +511,7 @@ Configuration Attributes:
--------------------------|-----------------------|----------------------------------
host\_name | Object name | **Required.** The name of the host this notification belongs to.
service\_name | Object name | **Optional.** The short name of the service this notification belongs to. If omitted, this notification object is treated as host notification.
vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this notification object.
vars | Dictionary | **Optional.** A dictionary containing custom variables that are specific to this notification object.
users | Array of object names | **Required.** A list of user names who should be notified. **Optional.** if the `user_groups` attribute is set.
user\_groups | Array of object names | **Required.** A list of user group names who should be notified. **Optional.** if the `users` attribute is set.
times | Dictionary | **Optional.** A dictionary containing `begin` and `end` attributes for the notification.
@ -648,7 +648,7 @@ Configuration Attributes:
--------------------------|-----------------------|----------------------------------
command | Array | **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. When using the "arguments" attribute this must be an array. Can be specified as function for advanced implementations.
env | Dictionary | **Optional.** A dictionary of macros which should be exported as environment variables prior to executing the command.
vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this command.
vars | Dictionary | **Optional.** A dictionary containing custom variables that are specific to this command.
timeout | Duration | **Optional.** The command timeout in seconds. Defaults to `1m`.
arguments | Dictionary | **Optional.** A dictionary of command arguments.
@ -746,7 +746,7 @@ Configuration Attributes:
display\_name | String | **Optional.** A short description of the service.
host\_name | Object name | **Required.** The host this service belongs to. There must be a `Host` object with that name.
groups | Array of object names | **Optional.** The service groups this service belongs to.
vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this service.
vars | Dictionary | **Optional.** A dictionary containing custom variables that are specific to this service.
check\_command | Object name | **Required.** The name of the check command.
max\_check\_attempts | Number | **Optional.** The number of times a service is re-checked before changing into a hard state. Defaults to 3.
check\_period | Object name | **Optional.** The name of a time period which determines when this service should be checked. Not set by default (effectively 24x7).
@ -952,7 +952,7 @@ Configuration Attributes:
display\_name | String | **Optional.** A short description of the user.
email | String | **Optional.** An email string for this user. Useful for notification commands.
pager | String | **Optional.** A pager string for this user. Useful for notification commands.
vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this user.
vars | Dictionary | **Optional.** A dictionary containing custom variables that are specific to this user.
groups | Array of object names | **Optional.** An array of group names.
enable\_notifications | Boolean | **Optional.** Whether notifications are enabled for this user. Defaults to true.
period | Object name | **Optional.** The name of a time period which determines when a notification for this user should be triggered. Not set by default (effectively 24x7).
@ -1414,7 +1414,7 @@ Configuration Attributes:
enable\_host\_checks | Boolean | **Optional.** Whether active host checks are globally enabled. Defaults to true.
enable\_service\_checks | Boolean | **Optional.** Whether active service checks are globally enabled. Defaults to true.
enable\_perfdata | Boolean | **Optional.** Whether performance data processing is globally enabled. Defaults to true.
vars | Dictionary | **Optional.** A dictionary containing custom attributes that are available globally.
vars | Dictionary | **Optional.** A dictionary containing custom variables that are available globally.
environment | String | **Optional.** Specify the Icinga environment. This overrides the `Environment` constant specified in the configuration or on the CLI with `--define`. Defaults to empty.
### IdoMySqlConnection <a id="objecttype-idomysqlconnection"></a>
@ -1746,7 +1746,7 @@ Configuration Attributes:
### PerfdataWriter <a id="objecttype-perfdatawriter"></a>
Writes check result performance data to a defined path using macro
pattern consisting of custom attributes and runtime macros.
pattern consisting of custom variables and runtime macros.
This configuration object is available as [perfdata feature](14-features.md#writing-performance-data-files).
Example:

446
doc/10-icinga-template-library.md
View File

File diff suppressed because it is too large Load Diff

6
doc/12-icinga2-api.md
View File

@ -246,7 +246,7 @@ filter expression has to be a [lambda function](17-language-reference.md#nullary
which must return a boolean value.
The following example allows the API user to query all hosts and services which have a
custom attribute `os` that matches the regular expression `^Linux`.
custom variable `os` that matches the regular expression `^Linux`.
The [regex function](18-library-reference.md#global-functions-regex) is available as global function.
```
@ -661,7 +661,7 @@ The following joins are available:
Zones | parent
Here's an example that retrieves all service objects for hosts which have had their `os`
custom attribute set to `Linux`. The result set contains the `display_name` and `check_command`
custom variable set to `Linux`. The result set contains the `display_name` and `check_command`
attributes for the service. The query also returns the host's `name` and `address` attribute
via a join:
@ -892,7 +892,7 @@ If attributes are of the [Dictionary](17-language-reference.md#dictionary) type,
"attrs": { "vars.os": "Linux" }
```
The following example updates the `address` attribute and the custom attribute `os` for the `example.localdomain` host:
The following example updates the `address` attribute and the custom variable `os` for the `example.localdomain` host:
```
$ curl -k -s -u root:icinga -H 'Accept: application/json' \

2
doc/13-addons.md
View File

@ -220,7 +220,7 @@ fix this:
* Pass the check command name inside the [format template configuration](14-features.md#writing-performance-data-files)
The latter becomes difficult with agent based checks like NRPE or SSH where the first command argument acts as
graph template identifier. There is the possibility to define the pnp template name as custom attribute
graph template identifier. There is the possibility to define the pnp template name as custom variable
and use that inside the formatting templates as `SERVICECHECKCOMMAND` for instance.
Example for services:

2
doc/15-troubleshooting.md
View File

@ -274,7 +274,7 @@ did not properly escape the single dollar sign preventing its usage as [runtime
critical/config: Error: Validation failed for Object 'ping4' (Type: 'Service') at /etc/icinga2/zones.d/global-templates/windows.conf:24: Closing $ not found in macro format string 'top-syntax=${list}'.
```
Correct the custom attribute value to
Correct the custom variable value to
```
"top-syntax=$${list}"

8
doc/17-language-reference.md
View File

@ -440,7 +440,7 @@ instantiated at run-time. Parent objects do not necessarily have to be
templates, however in general they are.
The `vars` dictionary for the `localhost` object contains all three
custom attributes and the custom attribute `colour` has the value `"blue"`.
custom variables and the custom variable `colour` has the value `"blue"`.
Parent objects are resolved in the order they're specified using the
`import` keyword.
@ -496,7 +496,7 @@ ZonesDir |**Read-only.** Contains the path of the zones.d directory.
Constant | Description
--------------------|-------------------
Vars |**Read-write.** Contains a dictionary with global custom attributes. Not set by default.
Vars |**Read-write.** Contains a dictionary with global custom variables. Not set by default.
NodeName |**Read-write.** Contains the cluster node name. Set to the local hostname by default.
ReloadTimeout |**Read-write.** Defines the reload timeout for child processes. Defaults to `300s`.
Environment |**Read-write.** The name of the Icinga environment. Included in the SNI host name for outbound connections. Not set by default.
@ -632,7 +632,7 @@ In this example all generated service object names consist of `prefix-` and
the value of the `key` iterator. The prefix string can be omitted if not required.
The `key` and `value` variables can be used for object attribute assignment, e.g. for
setting the `check_command` attribute or custom attributes as command parameters.
setting the `check_command` attribute or custom variables as command parameters.
`apply for` rules are first evaluated against all objects matching the `for loop` list
and afterwards the `assign where` and `ignore where` conditions are evaluated.
@ -1173,7 +1173,7 @@ log("Hello from '" + current_filename + "' in line " + current_line)
## Reserved Keywords <a id="reserved-keywords"></a>
These keywords are reserved and must not be used as constants or custom attributes.
These keywords are reserved and must not be used as constants or custom variables.
```
object

4
doc/18-library-reference.md
View File

@ -704,10 +704,10 @@ The returned value depends on the attribute value which is resolved
from the specified runtime macro.
This function is only available in runtime evaluated functions, e.g.
for [custom attributes](03-monitoring-basics.md#custom-attributes-functions) which
for [custom variables](03-monitoring-basics.md#custom-variables-functions) which
use the [abbreviated lambda syntax](17-language-reference.md#nullary-lambdas).
This example sets the `snmp_address` custom attribute
This example sets the `snmp_address` custom variable
based on `$address$` and `$address6$`.
```

6
doc/20-script-debugger.md
View File

@ -25,7 +25,7 @@ Here is a list of common errors which can be diagnosed with the script debugger:
## Debugging Configuration Errors <a id="script-debugger-config-errors"></a>
The following example illustrates the problem of a service [apply rule](03-monitoring-basics.md#using-apply-for)
which expects a dictionary value for `config`, but the host custom attribute only
which expects a dictionary value for `config`, but the host custom variable only
provides a string value:
```
@ -130,7 +130,7 @@ an internal error, they return an empty result to the caller.
In order to analyse these server-side errors, you can use the script debugger.
The following example tries filter for all host objects where the custom attribute
The following example tries filter for all host objects where the custom variable
`os` is set. There are various possibilities to check that, one of them would be
`host.vars.os != ""`. Another idea is to use the [contains](18-library-reference.md#dictionary-contains) method on the custom
attribute dictionary like this: `host.vars.contains("os")`.
@ -141,7 +141,7 @@ $ curl -k -s -u root:icinga -H 'Accept: application/json' -H 'X-HTTP-Method-Over
-d '{ "filter": "host.vars.contains(\"os\")", "attrs": [ "__name" ], "joins": [ "host.name", "host.vars" ], "pretty": true }'
```
This will fail on all hosts which don't have any custom attribute specified.
This will fail on all hosts which don't have any custom variable specified.
```
# icinga2 daemon -X

28
doc/23-migrating-from-icinga-1x.md
View File

@ -144,7 +144,7 @@ These assign rules can be applied for all groups: `HostGroup`, `ServiceGroup` an
> **Tip**
>
> Define custom attributes and assign/ignore members based on these attribute pattern matches.
> Define custom variables and assign/ignore members based on these attribute pattern matches.
@ -230,9 +230,9 @@ In Icinga 2 you'd just use the following macro to access all `address` attribute
$address$
```
#### Manual Config Migration Hints for Runtime Custom Attributes <a id="manual-config-migration-hints-runtime-custom-attributes"></a>
#### Manual Config Migration Hints for Runtime Custom Variables <a id="manual-config-migration-hints-runtime-custom-variables"></a>
Custom variables from Icinga 1.x are available as Icinga 2 custom attributes.
Custom variables from Icinga 1.x are available as Icinga 2 custom variables.
```
define command {
@ -282,7 +282,7 @@ while the service check command resolves its value to the service attribute attr
> **Note**
>
> Custom attributes in Icinga 2 are case-sensitive. `vars.CVTEST` is not the same as `vars.CvTest`.
> Custom variables in Icinga 2 are case-sensitive. `vars.CVTEST` is not the same as `vars.CvTest`.
#### Manual Config Migration Hints for Contacts (Users) <a id="manual-config-migration-hints-contacts-users"></a>
@ -968,29 +968,27 @@ The `alias` is used for group, timeperiod, etc. objects too.
Icinga 2 only supports the `display_name` attribute which is also taken into
account by Icinga web interfaces.
### Custom Attributes <a id="differences-1x-2-custom-attributes"></a>
### Custom Variables <a id="differences-1x-2-custom-variables"></a>
Icinga 2 allows you to define custom attributes in the `vars` dictionary.
Icinga 2 allows you to define custom variables in the `vars` dictionary.
The `notes`, `notes_url`, `action_url`, `icon_image`, `icon_image_alt`
attributes for host and service objects are still available in Icinga 2.
`2d_coords` and `statusmap_image` are not supported in Icinga 2.
#### Custom Variables <a id="differences-1x-2-custom-variables"></a>
Icinga 1.x custom variable attributes must be prefixed using an underscore (`_`).
In Icinga 2 these attributes must be added to the `vars` dictionary as custom attributes.
In Icinga 2 these attributes must be added to the `vars` dictionary as custom variables.
```
vars.dn = "cn=icinga2-dev-host,ou=icinga,ou=main,ou=IcingaConfig,ou=LConf,dc=icinga,dc=org"
vars.cv = "my custom cmdb description"
```
These custom attributes are also used as [command parameters](03-monitoring-basics.md#command-passing-parameters).
These custom variables are also used as [command parameters](03-monitoring-basics.md#command-passing-parameters).
While Icinga 1.x only supports numbers and strings as custom attribute values,
While Icinga 1.x only supports numbers and strings as custom variable values,
Icinga 2 extends that to arrays and (nested) dictionaries. For more details
look [here](03-monitoring-basics.md#custom-attributes).
look [here](03-monitoring-basics.md#custom-variables).
### Host Service Relation <a id="differences-1x-2-host-service-relation"></a>
@ -1026,13 +1024,13 @@ and their users.
### Macros <a id="differences-1x-2-macros"></a>
Various object attributes and runtime variables can be accessed as macros in
commands in Icinga 1.x -- Icinga 2 supports all required [custom attributes](03-monitoring-basics.md#custom-attributes).
commands in Icinga 1.x -- Icinga 2 supports all required [custom variables](03-monitoring-basics.md#custom-variables).
#### Command Arguments <a id="differences-1x-2-command-arguments"></a>
If you have previously used Icinga 1.x, you may already be familiar with
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
the Icinga 2 custom variables may have arbitrary names and arguments are no
longer specified in the `check_command` setting.
In Icinga 1.x arguments are specified in the `check_command` attribute and
@ -1056,7 +1054,7 @@ can be set using the `env` attribute in command objects.
#### Runtime Macros <a id="differences-1x-2-runtime-macros"></a>
Icinga 2 requires an object specific namespace when accessing configuration
and stateful runtime macros. Custom attributes can be accessed directly.
and stateful runtime macros. Custom variables can be accessed directly.
If a runtime macro from Icinga 1.x is not listed here, it is not supported
by Icinga 2.

2
doc/24-appendix.md
View File

@ -188,7 +188,7 @@ New columns:
{host,service}group | notes | TEXT | NULL | -
{host,service}group | notes_url | TEXT | NULL | -
{host,service}group | action_url | TEXT | NULL | -
customvariable* | is_json | integer | 0 | Defines whether `varvalue` is a json encoded string from custom attributes, or not
customvariable* | is_json | integer | 0 | Defines whether `varvalue` is a json encoded string from custom variables, or not
servicestatus | original_attributes | TEXT | NULL | JSON encoded dictionary of original attributes if modified at runtime.
hoststatus | original_attributes | TEXT | NULL | JSON encoded dictionary of original attributes if modified at runtime.

2
etc/icinga2/conf.d/hosts.conf
View File

@ -23,7 +23,7 @@ object Host NodeName {
address = "127.0.0.1"
address6 = "::1"
/* Set custom attribute `os` for hostgroup assignment in `groups.conf`. */
/* Set custom variable `os` for hostgroup assignment in `groups.conf`. */
vars.os = "Linux"
/* Define http vhost attributes for service apply rules in `services.conf`. */

2
etc/icinga2/conf.d/notifications.conf
View File

@ -2,7 +2,7 @@
* The example notification apply rules.
*
* Only applied if host/service objects have
* the custom attribute `notification` defined
* the custom variable `notification` defined
* and containing `mail` as key.
*
* Check `hosts.conf` for an example.

2
etc/icinga2/conf.d/services.conf
View File

@ -42,7 +42,7 @@ apply Service "ping6" {
/*
* Apply the `ssh` service to all hosts
* with the `address` attribute defined and
* the custom attribute `os` set to `Linux`.
* the custom variable `os` set to `Linux`.
*/
apply Service "ssh" {
import "generic-service"

2
etc/icinga2/conf.d/win32/hosts.conf
View File

@ -23,7 +23,7 @@ object Host NodeName {
address = "127.0.0.1"
address6 = "::1"
/* Set custom attribute `os` for hostgroup assignment in `groups.conf`. */
/* Set custom variable `os` for hostgroup assignment in `groups.conf`. */
vars.os = "Windows"
/* Define disks and attributes for service apply rules in `services.conf`. */