tyler.durden/icinga2
1
0
Fork 0
mirror of https://github.com/Icinga/icinga2.git synced 2025-04-08 17:05:25 +02:00
Code Issues Packages Projects Releases Wiki Activity

Update documentation reflecting current changes.

Browse Source 
Refs
This commit is contained in:
Michael Friedrich 2014-04-04 18:41:54 +02:00
parent 31d54b2760
commit fb038b3e4f
16 changed files with 229 additions and 244 deletions

11
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"

2
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.

2
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"
}

54
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.
### <a id="environment-macros"></a> Environment Macros
### <a id="command-environment-variables"></a> Environment Varialbes for Commands
If your plugins require environment macros instead of command arguments you have
to define all macros in the `export_macros` attribute as list.
export_macros = [
"HOSTNAME",
"SERVICEDESC",
"SERVICESTATE"
]
> **Note**
>
> Use templates to define global `export_macros` attributes for the three
> command types and let each command object inherit the attribute.
Please check [Runtime Custom Attributes as Environment Variables](#runtime-custom-attribute-env-vars).
### <a id="check-commands"></a> Check Commands
@ -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.

198
doc/3.03-macros.md → doc/3.03-custom-attributes-runtime-macros.md

@ -1,25 +1,30 @@
## <a id="macros"></a> Macros
## <a id="custom-attributes"></a> Custom Attributes and Runtime Macros
> **Note**
>
> There is a limited set of special [global constants](#global-constants) which can be re-used and
> also partly overridden such as `IcingaEnableChecks`.
### <a id="runtime-macros"></a> Runtime Macros
### <a id="runtime-custom-attributes"></a> Using Custom Attributes at Runtime
Macros may be used in command definitions to dynamically change how the command
Custom attributes may be used in command definitions to dynamically change how the command
is executed.
Additionally there are Icinga 2 features for example the `PerfDataWriter`
using the available runtime macros for output formatting.
using the available Custom attributes for output formatting.
> **Tip**
>
> Custom attributes are identified by the 'vars' dictionary attribute as short name.
> Accessing the different attribute keys is possible using the '.' accessor.
> **Note**
>
> Macros are evaluated at runtime when executing a command. These macros cannot be
> used inside the configuration objects to add references or similar unless
> stated otherwise.
> Custom attributes in command definitions or performance data templates are evaluated at
> runtime when executing a command. These custom attributes cannot be used/accessed inside
> the configuration objects to add references or similar unless stated otherwise.
Here is an example of a command definition which uses user-defined macros:
Here is an example of a command definition which uses user-defined custom attributes:
object CheckCommand "my-ping" {
import "plugin-check-command"
@ -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 (`$$`).
### <a id="runtime-macro-evaluation-order"></a> Runtime Macro Evaluation Order
### <a id="runtime-custom-attributes-evaluation-order"></a> Runtime Custom Attributes Evaluation Order
When executing commands Icinga 2 checks the following objects in this order to look
up macros:
up custom attributes and their respective values:
1. User object (only for notifications)
2. Service object
@ -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
### <a id="runtime-custom-attribute-env-vars"></a> 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<name>"
where <name> 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"
]
}
### <a id="configuration-macros"></a> Configuration Macros
Icinga 2 allows you to define constants which can be used in a limited
scope. For example, constant expressions can reference a pre-defined global constant
variable and calculate a value for the service check interval.
Example:
const MyCheckInterval = 10m
...
{
check_interval = MyCheckInterval / 2.5
}
More details in the chapter [Constant Expressions](#constant-expressions).
## <a id="runtime-macros"></a> Runtime Macros
Next to custom attributes there are additional runtime macros made available by Icinga 2.
These runtime macros reflect the current object state and may change over time while
custom attributes are configured statically (but can be modified at runtime using
external commands).
### <a id="host-runtime-macros"></a> Host Runtime Macros
The following host macros are available in all commands that are executed for
TODO
The following host custom attributes are available in all commands that are executed for
hosts or services:
Name | Description
@ -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<name>"
where <name> is the name of the custom variable.
### <a id="service-runtime-macros"></a> Service Runtime Macros
TODO
The following service macros are available in all commands that are executed for
services:
@ -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<name>"
where <name> is the name of the custom variable.
### <a id="user-runtime-macros"></a> User Runtime Macros
The following macros are available in all commands that are executed for
TODO
The following custom attributes are available in all commands that are executed for
users:
Name | Description
@ -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<name>" and
"_CONTACT<name>" where <name> is the name of the custom variable. "_CONTACT<name>"
### <a id="notification-runtime-macros"></a> Notification Runtime Macros
@ -196,6 +244,8 @@ where <name> is the name of the custom variable.
### <a id="global-runtime-macros"></a> 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`
### <a id="runtime-macros-env-vars"></a> Runtime Macros as Environment Variables
The `export_macros` command object attribute requires a list of macros which should
be exported as environment variables prior to executing the command.
This is useful for example for hiding sensitive information on the command line output
when passing credentials to database checks:
object CheckCommand "mysql-health" {
import "plugin-check-command",
command = PluginDir + "/check_mysql -H $address$ -d $db$",
/* default macro values */
macros = {
"MYSQLUSER" = "icinga_check",
"MYSQLPASS" = "1c1ng42r0xx"
},
export_macros = [
"MYSQLUSER",
"MYSQLPASS"
]
}
### <a id="configuration-macros"></a> Configuration Macros
Icinga 2 allows you to define constants which can be used in a limited
scope. For example, constant expressions can reference a pre-defined global constant
variable and calculate a value for the service check interval.
Example:
const MyCheckInterval = 10m
...
{
check_interval = MyCheckInterval / 2.5
}
More details in the chapter [Constant Expressions](#constant-expressions).

36
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"
}
}

4
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

10
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" {

6
doc/3.11-performance-data.md

@ -1,9 +1,9 @@
## <a id="performance-data"></a> Performance Data
When a service check is executed plugins should provide so-called
When a host and service check is executed plugins should provide so-called
`performance data`. Next to that additional check performance data
can be fetched using Icinga 2 runtime macros such as the check latency
or the current service state.
or the current service state (or additional custom attributes).
The performance data may be passed to external applications which
then generate nice graphs for historical reporting and trending.
@ -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$"

16
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"

20
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.
### <a id="boolean-values"></a> Boolean Values

23
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.
### <a id="objecttype-hostgroup"></a> 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:
### <a id="objecttype-checkcommand"></a> CheckCommand
A check command definition. Additional default command macros can be
A check command definition. Additional default command custom attributes can be
defined here.
Example:
@ -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.
### <a id="objecttype-notificationcommand"></a> 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.
### <a id="objecttype-eventcommand"></a> 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.
### <a id="objecttype-perfdatawriter"></a> PerfdataWriter

2
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.

6
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" {

71
doc/8-differences-between-icinga-1x-and-2.md

@ -170,6 +170,8 @@ account by Icinga 1.x Classic UI and Web.
## <a id="differences-1x-2-custom-attributes"></a> Custom Attributes
Icinga 2 allows you to define custom attributes in the `vars` dictionary.
### <a id="differences-1x-2-action-url-notes-url-notes"></a> Action Url, Notes Url, Notes
Icinga 1.x objects support configuration attributes not required as runtime
@ -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.
### <a id="differences-1x-2-custom-variables"></a> Custom Variables
Icinga 1.x custom variable attributes must be prefixed using an underscore (`_`).
In Icinga 2 these attributes must be added to the `custom`dictionary.
In Icinga 2 these attributes must be added to the `vars` dictionary as custom attributes.
custom = {
vars = {
DN = "cn=icinga2-dev-host,ou=icinga,ou=main,ou=IcingaConfig,ou=LConf,dc=icinga,dc=org"
CV = "my custom cmdb description"
}
TODO
> **Note**
>
> If you are planning to access custom variables as runtime macros you may access
@ -222,7 +226,7 @@ using the `apply` keyword.
## <a id="differences-1x-2-users"></a> Users
Contacts have been renamed to Users (same for groups). A user does not
only provide attributes and macros used for notifications, but is also
only provide attributes and custom attributes used for notifications, but is also
used for authorization checks.
In Icinga 2 notification commands are not directly associated with users.
@ -235,32 +239,19 @@ and their users.
## <a id="differences-1x-2-macros"></a> 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
### <a id="differences-1x-2-command-macros"></a> Command Macros
### <a id="differences-1x-2-command-arguments"></a> Command Arguments
If you have previously used Icinga 1.x you may already be familiar with
user and argument macros (e.g., `USER1` or `ARG1`). Unlike in Icinga 1.x macros
may have arbitrary names and arguments are no longer specified in the
`check_command` setting.
user and argument definitions (e.g., `USER1` or `ARG1`). Unlike in Icinga 1.x
the Icinga 2 custom attributes may have arbitrary names and arguments are no
longer specified in the `check_command` setting.
In Icinga 1.x argument macros are specified in the `check_command` attribute and
In Icinga 1.x arguments are specified in the `check_command` attribute and
are separated from the command name using an exclamation mark (`!`).
define command {
@ -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.
### <a id="differences-1x-2-environment-macros"></a> Environment Macros
TODO
The global configuration setting `enable_environment_macros` does not exist in
Icinga 2.
@ -307,12 +298,6 @@ attribute in command objects.
## <a id="differences-1x-2-checks"></a> Checks
### <a id="differences-1x-2-host-check"></a> Host Check
Unlike in Icinga 1.x hosts are not checkable objects in Icinga 2. Instead hosts
inherit their state from the service that is specified using the `check`
attribute.
### <a id="differences-1x-2-check-output"></a> Check Output
Icinga 2 does not make a difference between `output` (first line) and
@ -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.
## <a id="differences-1x-2-groups"></a> Groups
@ -452,6 +437,8 @@ object for the escalation itself.
### <a id="differences-1x-2-notification-options"></a> Notification Options
TODO
Unlike Icinga 1.x with the 'notification_options' attribute with comma-separated
state and type filters, Icinga 2 uses two configuration attributes for that.
All state and type filter use long names or'd with a pipe together

12
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
}