From 5a41a2c2c0ea680fdc88c1b0c398707972fdac22 Mon Sep 17 00:00:00 2001 From: Gunnar Beutner Date: Fri, 11 Apr 2014 12:40:20 +0200 Subject: [PATCH] Update documentation. Refs #5909 --- doc/2.1-setting-up-icinga-2.md | 4 +- doc/3.01-hosts-and-services.md | 6 +-- doc/3.02-commands.md | 35 +++++++++--------- doc/3.03-custom-attributes-runtime-macros.md | 12 +++--- doc/3.04-notifications.md | 39 ++++++++++---------- doc/4.1-configuration-syntax.md | 18 ++++----- doc/4.3-object-types.md | 14 +++---- doc/6.06-dependencies.md | 6 +-- 8 files changed, 62 insertions(+), 72 deletions(-) diff --git a/doc/2.1-setting-up-icinga-2.md b/doc/2.1-setting-up-icinga-2.md index e49bbcfea..7c1cd0ccf 100644 --- a/doc/2.1-setting-up-icinga-2.md +++ b/doc/2.1-setting-up-icinga-2.md @@ -133,8 +133,8 @@ The `conf.d/localhost.conf` file contains our first host definition: object Host "localhost" { import "linux-server" - vars.address = "127.0.0.1" - vars.address6 = "::1" + address = "127.0.0.1" + address6 = "::1" } This defines the host `localhost`. The `import` keyword is used to import diff --git a/doc/3.01-hosts-and-services.md b/doc/3.01-hosts-and-services.md index 6a9b88c86..38c120a9c 100644 --- a/doc/3.01-hosts-and-services.md +++ b/doc/3.01-hosts-and-services.md @@ -15,7 +15,7 @@ on the same physical device. Here is an example of a host object which defines two child services: object Host "my-server1" { - vars.address = "10.0.0.1" + address = "10.0.0.1" check_command = "hostalive" } @@ -40,8 +40,7 @@ address is associated with the host object. ### Host States -Hosts inherit their state from the host check service that is specified using -the `check` attribute. +Hosts can be in any of the following states: Hosts can be in any of the following states: @@ -49,7 +48,6 @@ Hosts can be in any of the following states: ------------|-------------- UP | The host is available. DOWN | The host is unavailable. - UNREACHABLE | At least one of the host's dependencies (e.g. its upstream router) is unavailable causing the host to be unreachable. ### Service States diff --git a/doc/3.02-commands.md b/doc/3.02-commands.md index 945fc2134..f206bd51a 100644 --- a/doc/3.02-commands.md +++ b/doc/3.02-commands.md @@ -55,8 +55,8 @@ free disk space). object Host "localhost" { import "generic-host" - vars.address = "127.0.0.1" - vars.address6 = "::1" + address = "127.0.0.1" + address6 = "::1" } object Service "disk" { @@ -78,12 +78,12 @@ interfaces (E-Mail, XMPP, IRC, Twitter, etc). `NotificationCommand` objects require the ITL template `plugin-notification-command` to support native plugin-based notifications. -Below is an example using runtime macros from Icinga 2 (such as `$SERVICEOUTPUT$` for +Below is an example using runtime macros from Icinga 2 (such as `$service.output$` for the current check output) sending an email to the user(s) associated with the -notification itself (`email` custom attribute provided as `$USERMACRO$`). +notification itself (`$user.email$`). -If you require default custom attribute definitions, you can add a `vars` dictionary -as shown for the `CheckCommand` object. +If you want to specify default values for some of the custom attribute definitions, +you can add a `vars` dictionary as shown for the `CheckCommand` object. TODO @@ -94,17 +94,17 @@ TODO env = { "NOTIFICATIONTYPE" = "$notification.type$" - "SERVICEDESC" = "$service.description$" - "HOSTALIAS" = "$host.displayname$", - "HOSTADDRESS" = "$host.vars.address$", + "SERVICEDESC" = "$service.name$" + "HOSTALIAS" = "$host.display_name$", + "HOSTADDRESS" = "$address$", "SERVICESTATE" = "$service.state$", - "LONGDATETIME" = "$icinga.longdatetime$", + "LONGDATETIME" = "$icinga.long_date_time$", "SERVICEOUTPUT" = "$service.output$", "NOTIFICATIONAUTHORNAME" = "$notification.author$", "NOTIFICATIONCOMMENT" = "$notification.comment$", - "HOSTDISPLAYNAME" = "$host.displayname$", - "SERVICEDISPLAYNAME" = "$service.displayname$", - "USEREMAIL" = "$user.vars.email$" + "HOSTDISPLAYNAME" = "$host.display_name$", + "SERVICEDISPLAYNAME" = "$service.display_name$", + "USEREMAIL" = "$user.email$" } } @@ -154,7 +154,6 @@ a restart upon detection. `EventCommand` objects require the ITL template `plugin-event-command` to support native plugin based checks. -The example below is fictive and not necessarily meant for production use. When the event command is triggered on a service state change, it will send a check result using the `process_check_result` script forcibly changing the service state back to `OK` (`-r 0`) providing some debug @@ -166,9 +165,9 @@ information in the check output (`-o`). command = [ PluginDir + "/process_check_result", "-H", "$host.name$", - "-S", "$service.description$", - "-c", "/var/run/icinga2/cmd/icinga2.cmd", + "-S", "$service.name$", + "-c", LocalStateDir + "/run/icinga2/cmd/icinga2.cmd", "-r", "0", - "-o", "Event Handler triggered in state '$SERVICESTATE$' with output '$SERVICEOUTPUT$'." - ] + "-o", "Event Handler triggered in state '$service.state$' with output '$service.output$'." + ] } diff --git a/doc/3.03-custom-attributes-runtime-macros.md b/doc/3.03-custom-attributes-runtime-macros.md index c60b6c5bd..4da4c36cf 100644 --- a/doc/3.03-custom-attributes-runtime-macros.md +++ b/doc/3.03-custom-attributes-runtime-macros.md @@ -1,4 +1,3 @@ - ## Custom Attributes ### Using Custom Attributes at Runtime @@ -73,12 +72,10 @@ attributes in the service definition like this: If a custom attribute isn't defined anywhere an empty value is used and a warning is emitted to the Icinga 2 log. - > **Best Practice** > -> 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 user interfaces and addons. +> By convention every host should have an `address` attribute. Hosts +> which have an IPv6 address should also have an `address6` attribute. ### Runtime Custom Attributes as Environment Variables @@ -95,6 +92,7 @@ when passing credentials to database checks: import "plugin-check-command", command = PluginDir + "/check_mysql -H $address$ -d $db$", + /* default custom attribute values */ vars = { mysql_user = "icinga_check", @@ -124,8 +122,8 @@ hosts or services: host.name | The name of the host object. host.display_name | The value of the `display_name` attribute. host.state | The host's current state. Can be one of `UNREACHABLE`, `UP` and `DOWN`. - host.stateid | The host's current state. Can be one of `0` (up), `1` (down) and `2` (unreachable). - host.statetype | The host's current state type. Can be one of `SOFT` and `HARD`. + host.state_id | The host's current state. Can be one of `0` (up), `1` (down) and `2` (unreachable). + host.state_type | The host's current state type. Can be one of `SOFT` and `HARD`. host.check_attempt | The current check attempt number. host.max_check_attempts | The maximum number of checks which are executed before changing to a hard state. host.last_state | The host's previous state. Can be one of `UNREACHABLE`, `UP` and `DOWN`. diff --git a/doc/3.04-notifications.md b/doc/3.04-notifications.md index 556d7d415..33e0113eb 100644 --- a/doc/3.04-notifications.md +++ b/doc/3.04-notifications.md @@ -42,17 +42,17 @@ There are various custom attributes available at runtime execution of the env = { "NOTIFICATIONTYPE" = "$notification.type$" - "SERVICEDESC" = "$service.description$" - "HOSTALIAS" = "$host.displayname$", - "HOSTADDRESS" = "$host.vars.address$", + "SERVICEDESC" = "$service.name$" + "HOSTALIAS" = "$host.display_name$", + "HOSTADDRESS" = "$address$", "SERVICESTATE" = "$service.state$", - "LONGDATETIME" = "$icinga.longdatetime$", + "LONGDATETIME" = "$icinga.long_date_time$", "SERVICEOUTPUT" = "$service.output$", "NOTIFICATIONAUTHORNAME" = "$notification.author$", "NOTIFICATIONCOMMENT" = "$notification.comment$", - "HOSTDISPLAYNAME" = "$host.displayname$", - "SERVICEDISPLAYNAME" = "$service.displayname$", - "USEREMAIL" = "$user.vars.email$" + "HOSTDISPLAYNAME" = "$host.display_name$", + "SERVICEDISPLAYNAME" = "$service.display_name$", + "USEREMAIL" = "$user.email$" } } @@ -70,11 +70,11 @@ TODO template Notification "generic-notification" { interval = 15m - _command = "mail-service-notification" + command = "mail-service-notification" states = [ Warning, Critical, Unknown ] types = [ Problem, Acknowledgement, Recovery, Custom, FlappingStart, - FlappingEnd, DowntimeStart,DowntimeEnd, DowntimeRemoved ] + FlappingEnd, DowntimeStart,DowntimeEnd, DowntimeRemoved ] period = "24x7" } @@ -94,7 +94,7 @@ Use the `apply` keyword to create `Notification` objects for your services: Instead of assigning users to notifications, you can also add the `user_groups` attribute with a list of user groups to the `Notification` object. Icinga 2 will -resolve all group members and send notifications to all of them. +send notifications to all group members. ### Notification Escalations @@ -113,17 +113,14 @@ notifications between start and end time. object User "icinga-oncall-2nd-level" { display_name = "Icinga 2nd Level" - enable_notifications = true vars.mobile = "+1 555 424642" } object User "icinga-oncall-1st-level" { display_name = "Icinga 1st Level" - enable_notifications = true vars.mobile = "+1 555 424642" - } } Define an additional `NotificationCommand` for SMS notifications. @@ -132,10 +129,13 @@ Define an additional `NotificationCommand` for SMS notifications. > > The example is not complete as there are many different SMS providers. > Please note that sending SMS notifications will require an SMS provider -> or local hardware with a sim card active. +> or local hardware with a SIM card active. object NotificationCommand "sms-notification" { - command = PluginDir + "/send_sms_notification $mobile$ ..." + command = [ + PluginDir + "/send_sms_notification", + "$mobile$", + "..." } The two new notification escalations are added onto the host `localhost` @@ -156,6 +156,7 @@ notified, but only for one hour (`2h` as `end` key for the `times` dictionary). apply Notification "mail" to Service { import "generic-notification" + command = "mail-notification" users = [ "icingaadmin" ] @@ -164,6 +165,7 @@ notified, but only for one hour (`2h` as `end` key for the `times` dictionary). apply Notification "escalation-sms-2nd-level" to Service { import "generic-notification" + command = "sms-notification" users = [ "icinga-oncall-2nd-level" ] @@ -177,6 +179,7 @@ notified, but only for one hour (`2h` as `end` key for the `times` dictionary). apply Notification "escalation-sms-1st-level" to Service { import "generic-notification" + command = "sms-notification" users = [ "icinga-oncall-1st-level" ] @@ -187,11 +190,6 @@ notified, but only for one hour (`2h` as `end` key for the `times` dictionary). assign where service.name == "ping4" } - -Instead of assigning users to notifications, you can also add the `user_groups` -attribute with a list of user groups to the `Notification` object. Icinga 2 will -resolve all group members and send notifications and notification escalations to -all of them. ### First Notification Delay @@ -203,6 +201,7 @@ end time for this notification. apply Notification "mail" to Service { import "generic-notification" + command = "mail-notification" users = [ "icingaadmin" ] diff --git a/doc/4.1-configuration-syntax.md b/doc/4.1-configuration-syntax.md index 0e2eeae5f..0a4bfd611 100644 --- a/doc/4.1-configuration-syntax.md +++ b/doc/4.1-configuration-syntax.md @@ -8,10 +8,8 @@ objects using the `object` keyword: object Host "host1.example.org" { display_name = "host1" - vars = { - address = "192.168.0.1" - address6 = "::1" - } + address = "192.168.0.1" + address6 = "::1" } In general you need to write each statement on a new line. Expressions started @@ -24,11 +22,9 @@ them with a semi-colon: object Host "host1.example.org" { display_name = "host1" - vars = { address = "192.168.0.1"; address6 = "::1"; } + address = "192.168.0.1"; address6 = "::1" } -The semi-colon after the last element (i.e. `address6`) may be omitted. - Each object is uniquely identified by its type (`Host`) and name (`host1.example.org`). Some types have composite names, e.g. the `Service` type which uses the `host_name` attribute and the name @@ -339,8 +335,8 @@ Example: object Host "localhost" { import "test-host" - vars.address = "127.0.0.1" - vars.address6 = "::1" + address = "127.0.0.1" + address6 = "::1" } The `default-host` and `test-host` objects are marked as templates @@ -397,8 +393,8 @@ ScheduledDowntime | Host | host ScheduledDowntime | Service | host, service Any valid config attribute can be accessed using the `host` and `service` -variables. For example, `host.vars.address` would return the host's -"address" custom attribute - or null if it doesn't have that custom attribute. +variables. For example, `host.address` would return the value of the host's +"address" attribute - or null if that attribute isn't set. ### Boolean Values diff --git a/doc/4.3-object-types.md b/doc/4.3-object-types.md index 334d63062..a8ffb608d 100644 --- a/doc/4.3-object-types.md +++ b/doc/4.3-object-types.md @@ -461,17 +461,17 @@ Example: env = { "NOTIFICATIONTYPE" = "$notification.type$" - "SERVICEDESC" = "$service.description$" - "HOSTALIAS" = "$host.displayname$", - "HOSTADDRESS" = "$host.vars.address$", + "SERVICEDESC" = "$service.name$" + "HOSTALIAS" = "$host.display_name$", + "HOSTADDRESS" = "$address$", "SERVICESTATE" = "$service.state$", - "LONGDATETIME" = "$icinga.longdatetime$", + "LONGDATETIME" = "$icinga.long_date_time$", "SERVICEOUTPUT" = "$service.output$", "NOTIFICATIONAUTHORNAME" = "$notification.author$", "NOTIFICATIONCOMMENT" = "$notification.comment$", - "HOSTDISPLAYNAME" = "$host.displayname$", - "SERVICEDISPLAYNAME" = "$service.displayname$", - "USEREMAIL" = "$user.vars.email$" + "HOSTDISPLAYNAME" = "$host.display_name$", + "SERVICEDISPLAYNAME" = "$service.display_name$", + "USEREMAIL" = "$user.email$" } } diff --git a/doc/6.06-dependencies.md b/doc/6.06-dependencies.md index a74ccb404..4ff173a92 100644 --- a/doc/6.06-dependencies.md +++ b/doc/6.06-dependencies.md @@ -20,11 +20,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" { - vars.address = "192.168.1.1" + address = "192.168.1.1" } object Host "google-dns" { - vars.address = "8.8.8.8" + address = "8.8.8.8" } apply Service "ping4" { @@ -32,7 +32,7 @@ be suppressed. This is achieved by setting the `disable_checks` attribute to `tr check_command = "ping4" - assign where host.vars.address + assign where host.address } apply Dependency "internet" to Service {