Update documentation.

Refs #5909

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

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,16 +40,14 @@ address is associated with the host object.
 
 ### <a id="host-states"></a> 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:
 
   Name        | Description
   ------------|--------------
   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.
 
 ### <a id="service-states"></a> Service States
 

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$'."
+      ]
     }

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

@@ -1,4 +1,3 @@
-
 ## <a id="custom-attributes"></a> Custom Attributes
 
 ### <a id="runtime-custom-attributes"></a> 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.
 
 ### <a id="runtime-custom-attribute-env-vars"></a> 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`.

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.
 
 ### <a id="notification-escalations"></a> 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.
 
 ### <a id="first-notification-delay"></a> 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" ]
           

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

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

doc/6.06-dependencies.md

@@ -20,19 +20,19 @@ 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" {
       import "generic-service"
 
       check_command = "ping4"
 
-      assign where host.vars.address
+      assign where host.address
     }
 
     apply Dependency "internet" to Service {