Update documentation.

Refs #5878

doc/1-about.md

@@ -2,10 +2,10 @@
 
 ## <a id="what-is-icinga2"></a> What is Icinga 2?
 
-Icinga 2 is an enterprise-grade open source monitoring system which keeps watch over networks
+Icinga 2 is an open source monitoring system which keeps watch over network resources,
-and any conceivable network resource, notifies the user of errors and recoveries and generates
+notifies users of outages and recoveries and generates performance data for reporting.
-performance data for reporting. Scalable and extensible, Icinga 2 can monitor complex, large
+Scalable and extensible, Icinga 2 can monitor complex, large environments across
-environments across dispersed locations.
+multiple locations.
 
 ## <a id="licensing"></a> Licensing
 

doc/2.1-setting-up-icinga-2.md

@@ -131,65 +131,76 @@ The `conf.d/localhost.conf` file contains our first host definition:
      * files in this directory are included.
      */
     object Host "localhost" {
-      services["ping4"] = {
+      import "linux-server",
-        templates = [ "generic-service" ],
 
-        check_command = "ping4"
+      macros.address = "127.0.0.1",
-      },
+      macros.address6 = "::1"
-
-      services["ping6"] = {
-        templates = [ "generic-service" ],
-
-        check_command = "ping6"
-      },
-
-      services["http"] = {
-        templates = [ "generic-service" ],
-
-        check_command = "http_ip"
-      },
-
-      services["ssh"] = {
-        templates = [ "generic-service" ],
-
-        check_command = "ssh"
-      },
-
-      services["load"] = {
-        templates = [ "generic-service" ],
-
-        check_command = "load"
-      },
-
-      services["processes"] = {
-        templates = [ "generic-service" ],
-
-        check_command = "processes"
-      },
-
-      services["users"] = {
-        templates = [ "generic-service" ],
-
-        check_command = "users"
-      },
-
-      services["disk"] = {
-        templates = [ "generic-service" ],
-
-        check_command = "disk"
-      },
-
-      macros = {
-        address = "127.0.0.1",
-        address6 = "::1",
-      },
-
-      check = "ping4",
     }
 
+    apply Service "icinga" {
+      import "generic-service",
+
+      check_command = "icinga",
+
+      assign where host.name == "localhost"
+    }
+
+    apply Service "http" {
+      import "generic-service",
+
+      check_command = "http_ip",
+
+      assign where host.name == "localhost"
+    }
+
+    apply Service "ssh" {
+      import "generic-service",
+
+      check_command = "ssh",
+
+      assign where host.name == "localhost"
+    }
+
+    apply Service "load" {
+      import "generic-service",
+
+      check_command = "load",
+
+      assign where host.name == "localhost"
+    }
+
+    apply ScheduledDowntime "backup-downtime" {
+      import "backup-downtime",
+
+      assign where service.host == "localhost" && service.short_name == "load"
+    }
+
+    apply Service "processes" {
+      import "generic-service",
+
+      check_command = "processes",
+
+      assign where host.name == "localhost"
+    }
+
+    apply Service "users" {
+      import "generic-service",
+
+      check_command = "users",
+
+      assign where host.name == "localhost"
+    }
+
+    apply Service "disk" {
+      import "generic-service",
+
+      check_command = "disk",
+
+      assign where host.name == "localhost"
+    }
 
 This defines a host named "localhost" which has a couple of services. Services
-may inherit from one or more service templates.
+may import one or more service templates.
 
 The command objects `ping4`, `ping6`, `http_ip`, `ssh`, `load`, `processes`, `users`
 and `disk` are all provided by the Icinga Template Library (short ITL) which

doc/2.6-running-icinga-2.md

@@ -32,7 +32,7 @@ Icinga 2's init script is installed in `/etc/init.d/icinga2` by default:
       -V [ --version ]      show version information
       -l [ --library ] arg  load a library
       -I [ --include ] arg  add include search directory
-	  -D [ --define] args   define a constant
+      -D [ --define] args   define a constant
       -c [ --config ] arg   parse a configuration file
       -C [ --validate ]     exit after validating the configuration
       -Z [ --no-validate ]  skip validating the configuration

doc/3.01-hosts-and-services.md

@@ -15,17 +15,18 @@ on the same physical device.
 Here is an example of a host object which defines two child services:
 
     object Host "my-server1" {
-      services["ping4"] = {
+      macros.address = "10.0.0.1",
-        check_command = "ping4"
+      check = "ping4"
-      },
+    }
 
-      services["http"] = {
+    apply Service "ping4" {
-        check_command = "http_ip"
+      check_command = "ping4"
-      },
+      assign where host.name == "my-server1"
+    }
 
-      check = "ping4",
+    apply Service "http" {
-
+      check_command = "http_ip"
-      macros["address"] = "10.0.0.1"
+      assign where host.name == "my-server1"
     }
 
 The example host `my-server1` creates two services which belong to this host:

doc/3.02-commands.md

@@ -68,10 +68,8 @@ then use these macros on the command line.
         "-c", "$cfree$%"
       ],
 
-      macros += {
+      macros.wfree = 20,
-        wfree = 20,
+      macros.cfree = 10
-        cfree = 10,
-      }
     }
 
 The host `localhost` with the service `disk` checks all disks with modified
@@ -80,21 +78,18 @@ space).
 
     object Host "localhost" {
       import "generic-host",
+  
+      macros.address = "127.0.0.1",
+      macros.address6 = "::1"
+    }
 
-      services["disk"] = {
+    apply Service "disk" {
-        templates = [ "generic-service" ],
+      import "generic-service",
-
+ 
-        check_command = "disk",
+      check_command = "disk",
-        macros += {
+      
-          wfree = 10,
+      macros.wfree = 10,
-          cfree = 5
+      macros.cfree = 5
-        }
-      },
-
-      macros = {
-        address = "127.0.0.1",
-        address6 = "::1",
-      },
     }
     
 
@@ -209,5 +204,3 @@ information in the check output (`-o`).
         "Event Handler triggered in state '$SERVICESTATE$' with output '$SERVICEOUTPUT$'."
       ]       
     }
-    
-

doc/3.03-macros.md

@@ -75,14 +75,12 @@ 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:
 
-    object Host "my-server1" {
+    apply Service "ping" {
-      services["ping"] = {
+      check_command = "my-ping",
-        check_command = "my-ping",
 
-        macros["packets"] = 10 // Overrides the default value of 5 given in the command
+      macros.packets = 10 // Overrides the default value of 5 given in the command
-      },
 
-      macros["address"] = "10.0.0.1"
+      assign where host.name == "my-server1"
     }
 
 If a macro isn't defined anywhere an empty value is used and a warning is

doc/3.04-notifications.md

@@ -113,21 +113,17 @@ to the defined notifications. That way you'll save duplicated attributes in each
 >
 > The `TimePeriod` `24x7` is shipped as example configuration with Icinga 2.
 
-Use the `generic-notification` template for the `mail` notification defined
+Use the `apply` keyword to create `Notification` objects for your services:
-inline to the host's service `ping4` and assign the `icingaadmin` user. 
 
-    object Host "localhost" {
+    apply Notification "mail" {
-      services["ping4"] = {
+      import "generic-notification",
-        notifications["mail"] = {
+  
-          templates = [ "generic-notification" ],
+      notification_command = "mail-notification",
-          notification_command = "mail-notification",
+      users = [ "icingaadmin" ],
-          users = [ "icingaadmin" ],
+
-        }      
+      assign where service.short_name == "ping4"
-      }
     }
     
-Notifications can be defined in `Service` templates inherited to the objects.
-
 > **Note**
 >
 > Instead of assigning users to notifications, you can also add the `user_groups`
@@ -156,7 +152,7 @@ notifications between start and end time.
 
     object User "icinga-oncall-2nd-level" {
       display_name = "Icinga 2nd Level",
-      enable_notifications = 1,
+      enable_notifications = true,
 
       macros = {
         "mobile" = "+49123456781"
@@ -165,10 +161,9 @@ notifications between start and end time.
     
     object User "icinga-oncall-1st-level" {
       display_name = "Icinga 1st Level",
-      enable_notifications = 1,
+      enable_notifications = true,
 
-      macros = {
+      macros.mobile = "+49123456782"
-        "mobile" = "+49123456782"
       }
     }
     
@@ -200,35 +195,35 @@ If the problem does not get resolved or acknowledged preventing further notifica
 the `escalation-sms-1st-level` user will be escalated `1h` after the initial problem was
 notified, but only for one hour (`2h` as `end` key for the `times` dictionary). 
 
-    object Host "localhost" {
+    apply Notification "mail" {
-      services["ping4"] = {
+      import "generic-notification",
-        notifications["mail"] = {
+      notification_command = "mail-notification",
-          templates = [ "generic-notification" ],
+      users = [ "icingaadmin" ],
-          notification_command = "mail-notification",
+  
-          users = [ "icingaadmin" ],
+      assign where service.short_name == "ping4"
-        },
+    }
-        notifications["escalation-sms-2nd-level"] = {
+
-          templates = [ "generic-notification" ],
+    apply Notification "escalation-sms-2nd-level" {
-          notification_command = "sms-notification",
+      import "generic-notification",
-          users = [ "icinga-oncall-2nd-level" ],
+      notification_command = "sms-notification",
+      users = [ "icinga-oncall-2nd-level" ],
           
-          times = {
+      times = {
-            begin = 30m,
+        begin = 30m,
-            end = 1h
+        end = 1h
-          }
-        },
-        notifications["escalation-sms-1st-level"] = {
-          templates = [ "generic-notification" ],
-          notification_command = "sms-notification",
-          users = [ "icinga-oncall-1st-level" ],
-          
-          times = {
-            begin = 1h,
-            end = 2h
-          }
-        }        
       }
     }
+
+    apply Notification "escalation-sms-1st-level" {
+      import "generic-notification",
+      notification_command = "sms-notification",
+      users = [ "icinga-oncall-1st-level" ],
+          
+      times = {
+        begin = 1h,
+        end = 2h
+      }
+    }        
     
 > **Note**
 >
@@ -245,18 +240,12 @@ dictionary and set `begin = 15m` as key and value if you want to suppress notifi
 in the first 15 minutes. Leave out the `end` key - if not set, Icinga 2 will not check against any
 end time for this notification.
 
-    object Host "localhost" {
+    apply Notification "mail" {
-      services["ping4"] = {
+      import "generic-notification",
-        notifications["mail"] = {
+      notification_command = "mail-notification",
-          templates = [ "generic-notification" ],
+      users = [ "icingaadmin" ],
-          notification_command = "mail-notification",
-          users = [ "icingaadmin" ],
           
-          times = {
+      times.begin = 15m // delay first notification
-            begin = 15m // delay first notification
-          }
-        }
-      }
     }
     
 > **Note**

doc/3.05-using-templates.md

@@ -7,46 +7,28 @@ For example, rather than manually creating a `ping` service object for each of
 your hosts you can use templates to avoid having to copy & paste parts of your
 configuration:
 
-    template Host "linux-server" {
+    template Service "generic-service" {
-      services["ping"] = {
+      max_check_attempts = 3,
-        check_command = "ping4"
+      check_interval = 5m,
-      },
+      retry_interval = 1m,
-
+      enable_perfdata = true
-      check = "ping"
     }
 
-    object Host "my-server1" {
+    apply Service "ping4" {
-      import "linux-server",
+      import "generic-service",
-
+      check_command = "ping4",
-      macros["address"] = "10.0.0.1"
+      assign where host.macros.address
     }
 
-    object Host "my-server2" {
+    apply Service "ping6" {
-      import "linux-server",
+      import "generic-service",
-
+      check_command = "ping6",
-      macros["address"] = "10.0.0.2"
+      assign where host.macros.address6
     }
 
-In this example both `my-server1` and `my-server2` each get their own `ping`
+In this example both `ping4` and `ping6` services inherit properties from the
-service check. Each host gets its own host `check` defined as the `ping`
+template `generic-service`.
-service too.
 
-Objects as well as templates themselves can inherit from an arbitrary number of
+Objects as well as templates themselves can import an arbitrary number of
 templates. Attributes inherited from a template can be overridden in the
 object if necessary.
-
-Templates can also be used in service and notification definitions using the
-`templates` attribute:
-
-    template Service "weekend-service" {
-      check_interval = 0.5m,
-      check_period = "weekend"
-    }
-
-    object Host "my-server1" {
-      services["backup"] {
-        check_command = "backup-check",
-
-	templates = [ "weekend-service" ]
-      }
-    }

doc/3.06-groups.md

@@ -37,17 +37,16 @@ Then add your hosts to this hostgroup
 
     template Host "windows-mssql-template" {
       groups = [ "windows" ],
-      macros = {
+      macros.mssql_port = 1433
-        "mssql_port" = 1433
       }
     }
     
     object Host "mssql-srv1" {
-      templates = [ "windows-mssql-template" ]
+      import "windows-mssql-template"
     }
     
     object Host "mssql-srv2" {
-      templates = [ "windows-mssql-template" ]
+      import "windows-mssql-template"
     }    
 
 This can be done for service and user groups the same way. Additionally
@@ -64,25 +63,17 @@ the user groups are associated as attributes in `Notification` objects.
     object User "win-mssql-noc" {
       import "generic-windows-mssql-users",
 
-      macros = {
+      macros.email = "noc@example.com"
-        "email" = "noc@company.com"
-      }
     }
     
     object User "win-mssql-ops" {
       import "generic-windows-mssql-users",
 
-      macros = {
+      macros.email = "ops@example.com"
-        "email" = "ops@company.com"
-      }    
     }
 
-    object Host "localhost" {
+    apply Service "ping4" {
-      services["ping4"] = {
+      import "generic-notification",
-        notifications["mail"] = {
+      notification_command = "mail-notification",
-          templates = [ "generic-notification" ],
+      user_groups = [ "windows-admins" ],
-          notification_command = "mail-notification",
-          user_groups = [ "windows-admins" ],
-        }      
-      }
     }

doc/3.07-time-periods.md

@@ -66,13 +66,12 @@ create a new timeperiod named `workhours` defining a work day with
 Assign the timeperiod as `notification_period` to the `Notification`
 object then.
 
-    object Host "localhost" {
+    apply Notification "mail" {
-      services["ping4"] = {
+      import "generic-notification",
-        notifications["mail"] = {
+
-          templates = [ "generic-notification" ],
+      notification_command = "mail-notification",
-          notification_command = "mail-notification",
+      users = [ "icingaadmin" ],
-          users = [ "icingaadmin" ],
+      notification_period = "workhours"
-          notification_period = "workhours"
+      
-        }      
+      assign where host.name == "localhost"
-      }
     }

doc/3.14-check-result-files.md

@@ -17,5 +17,3 @@ on-demand in your Icinga 2 objects configuration.
       spool_dir = "/data/check-results"
     }
 
-
-

doc/3.15-monitoring-remote-clients.md

@@ -21,24 +21,18 @@ binaries. The [Monitoring Plugins package](#setting-up-check-plugins) ships
 the `check_snmp` plugin binary, but there are plenty of [existing plugins](#integrate-additional-plugins)
 for specific use cases already around, for example monitoring Cisco routers.
 
-The following example uses the [SNMP ITL](#itl-snmp) `CheckCommand` and only defines
+The following example uses the [SNMP ITL](#itl-snmp) `CheckCommand` and just
-additional macros (note the `+=` operator) as command parameters for the `oid`
+overrides the `oid` macro. A service is created for all hosts which
-(`community` is already set):
+have the `community` macro set.
 
-    object Host "remote-snmp-host" {
+    apply Service "uptime" {
-      import "generic-host",
+      import "generic-service",
 
-      ...
+      templates = [ "generic-service" ],
-      services["uptime"] = {
+      check_command = "snmp",
-          templates = [ "generic-service" ],
+      macros.oid = "1.3.6.1.2.1.1.3.0",
-          check_command = "snmp",
+  
-          macros += {
+      assign where host.macros.community
-            "oid" = "1.3.6.1.2.1.1.3.0"
-          }
-      },
-      macros = {
-        "address" = "192.168.1.101"
-      }
     }
 
 #### SSH
@@ -56,24 +50,17 @@ its return code and output. `check_by_ssh` is available in the [Monitoring Plugi
                 ]
     }
 
-    object Host "remote-ssh-host" {
+    apply Service "swap" {
-      import "generic-host",
+      import "generic-service",
-
+      check_command = "check_by_ssh_swap",
-      ...
+      macros = {
-      services["swap"] = {
-          templates = [ "generic-service" ],
-          check_command = "check_by_ssh_swap",
-          macros = {
             "warn" = "50%",
             "crit" = "75%"
-          }
-      },
-      macros = {
-        "address" = "192.168.1.102"
       }
+      
+      assign where host.name == "remote-ssh-host"
     }
 
-
 #### NRPE
 
 [NRPE](http://docs.icinga.org/latest/en/nrpe.html) runs as daemon on the remote client including
@@ -83,7 +70,7 @@ remote client.
 
 > **Note**
 >
-> The NRPE daemon uses its own proprietary configuration format in nrpe.cfg while `check_nrpe`
+> The NRPE daemon uses its own configuration format in nrpe.cfg while `check_nrpe`
 > can be embedded into the Icinga 2 `CheckCommand` configuration syntax.
 
 Example:
@@ -97,27 +84,19 @@ Example:
                 ],
     }
 
-    object Host "remote-nrpe-host" {
+    apply Service "users" {
-      import "generic-host",
+      import "generic-service",
+  
+      check_command = "check_nrpe",
+      macros.remote_nrpe_command = "check_users",
 
-      ...
+      assign where host.name == "remote-nrpe-host"
-      services["users"] = {
-          templates = [ "generic-service" ],
-          check_command = "check_nrpe",
-          macros = {
-            "remote_nrpe_command" = "check_users"
-          }
-      },
-      macros = {
-        "address" = "192.168.1.103"
-      }
     }
 
 nrpe.cfg:
 
     command[check_users]=/usr/local/icinga/libexec/check_users -w 5 -c 10
 
-
 #### NSClient++
 
 [NSClient++](http://nsclient.org) works on both Windows and Linux platforms and is well
@@ -150,23 +129,18 @@ Example:
       }
     }
 
-    object Host "remote-windows-host" {
+    apply Service "users" {
-      import "generic-host",
+      import "generic-service",
-
+  
-      ...
+      check_command = "check_nscp",
-      services["users"] = {
+      macros += {
-          templates = [ "generic-service" ],
+        "remote_nscp_command" = "USEDDISKSPACE",
-          check_command = "check_nscp",
+        "partition" = "c",
-          macros += {
+        "warn" = "70",
-            "remote_nscp_command" = "USEDDISKSPACE",
+        "crit" = "80"
-            "partition" = "c",
-            "warn" = "70",
-            "crit" = "80"
-          }
-      },
-      macros = {
-        "address" = "192.168.1.104"
       }
+
+      assign where host.name == "remote-windows-host"
     }
 
 For details on the `NSClient++` configuration please refer to the [official documentation](http://www.nsclient.org/nscp/wiki/doc/configuration/0.4.x).
@@ -180,13 +154,12 @@ For details on the `NSClient++` configuration please refer to the [official docu
 
 A dedicated Icinga 2 agent supporting all platforms and using the native
 Icinga 2 communication protocol supported with SSL certificates, IPv4/IPv6
-support, etc is on the [development roadmap](https://dev.icinga.org/projects/i2?jump=issues).
+support, etc. is on the [development roadmap](https://dev.icinga.org/projects/i2?jump=issues).
 Meanwhile remote checkers in a [Cluster](#cluster) setup could act as
 immediate replacement, but without any local configuration - or pushing
 their standalone configuration back to the master node including their check
 result messages.
 
-
 ### Passive Check Results and SNMP Traps
 
 > **Note**

doc/4.1-configuration-syntax.md

@@ -385,21 +385,29 @@ Constants cannot be changed once they are set.
 ### <a id="apply"></a> Apply
 
 The `apply` keyword can be used to associate a template with another group of
-objects. The exact effect of this association depends on the two object types.
+objects. The exact effect of this association depends on the object type.
 
-    template Service "ping-service" {
+    apply Service "ping" {
-      short_name = "ping",
+      import "generic-service",
-      check_command = "ping4"
+ 
+      check_command = "ping4",
+  
+      assign where host.name == "localhost"
     }
 
-    apply template Service "ping-service" to Host where host == "localhost"
+In this example the `assign where` condition is an expression which is
+evaluated for all objects of type Host and a new service with name "ping"
+is created for each matching host.
 
-In this example the `where` condition is a constant expression which is
+Depending on the object type used in the `apply` expression additional local
-evaluated for all objects of type Host and a new service is created for each
+variables may be available for use in the `where` condition:
-matching host.
 
-Depending on the object types used in the `apply` expression additional local
+  Type             |Variables
-variables may be available for use in the `where` condition.
+  -----------------|----------------
+  Dependency       |host, service
+  Notification     |host, service
+  Service          |host
+  ScheduledDowntime|host, service
 
 ### <a id="comments"></a> Comments
 
@@ -484,18 +492,18 @@ you can specify which attributes are allowed in an object definition.
 
 Example:
 
-    type Pizza {
+    %type Pizza {
             %require "radius",
-            %attribute number "radius",
+            %attribute %number "radius",
 
-            %attribute dictionary "ingredients" {
+            %attribute %dictionary "ingredients" {
                     %validator "ValidateIngredients",
 
-                    %attribute string "*",
+                    %attribute %string "*",
 
-                    %attribute dictionary "*" {
+                    %attribute %dictionary "*" {
-                            %attribute number "quantity",
+                            %attribute %number "quantity",
-                            %attribute string "name"
+                            %attribute %string "name"
                     }
             },
 
@@ -524,10 +532,11 @@ The Pizza definition provides the following validation rules:
 
 Valid types for type rules include:
 
-* any
+* %any
-* number
+* %number
-* string
+* %string
-* scalar (an alias for string)
+* %scalar (an alias for string)
-* dictionary
+* %dictionary
+* %array
 
 -->

doc/4.3-object-types.md

@@ -21,15 +21,6 @@ Example:
         templates = [ "ping" ]
       },
 
-      services["http"] = {
-        templates = [ "my-http" ],
-
-        macros = {
-          vhost = "test1.example.org",
-          port = 81
-        }
-      },
-
       check = "ping"
     }
 
@@ -40,8 +31,6 @@ 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.
-  services        |**Optional.** Inline definition of services. Each dictionary item specifies a service.<br /><br />The `templates` attribute can be used to specify an array of templates that should be inherited by the service.<br /><br />The new service's name is "hostname!service" - where "service" is the dictionary key in the services dictionary.<br /><br />The dictionary key is used as the service's short name.
-  dependencies    |**Optional.** Inline definition of dependencies. Each dictionary item specifies a dependency.<br /><br />The `templates` attribute can be used to specify an array of templates that should be inherited by the dependency object.<br /><br />The new dependency object's name is "hostname:service:dependency" - where "dependency" is the dictionary key in the dependencies dictionary.
   macros          |**Optional.** A dictionary containing macros that are specific to this host.
 
 ### <a id="objecttype-hostgroup"></a> HostGroup
@@ -68,8 +57,8 @@ by Icinga 2.
 > **Best Practice**
 >
 > Rather than creating a `Service` object for a specific host it is usually easier
-> to just create a `Service` template and use the `services` attribute in the `Host`
+> to just create a `Service` template and use the `apply` keyword to assign the
-> object to associate these templates with a host.
+> service to a number of hosts.
 
 Example:
 
@@ -115,8 +104,6 @@ Attributes:
   flapping\_threshold|**Optional.** The flapping threshold in percent when a service is considered to be flapping.
   volatile        |**Optional.** The volatile setting enables always `HARD` state types if `NOT-OK` state changes occur.
   groups          |**Optional.** The service groups this service belongs to.
-  notifications   |**Optional.** Inline definition of notifications. Each dictionary item specifies a notification.<br /><br />The `templates` attribute can be used to specify an array of templates that should be inherited by the notification object.<br /><br />The new notification object's name is "hostname:service:notification" - where "notification" is the dictionary key in the notifications dictionary.
-  dependencies    |**Optional.** Inline definition of dependencies. Each dictionary item specifies a dependency.<br /><br />The `templates` attribute can be used to specify an array of templates that should be inherited by the dependency object.<br /><br />The new dependency object's name is "hostname:service:dependency" - where "dependency" is the dictionary key in the dependencies dictionary.
   authorities     |**Optional.** A list of Endpoints on which this service check will be executed in a cluster scenario.
   domains         |**Optional.** A list of Domains for this service object in a cluster scenario.
 
@@ -144,8 +131,8 @@ of service state changes and other events.
 > **Best Practice**
 >
 > Rather than creating a `Notification` object for a specific service it is usually easier
-> to just create a `Notification` template and use the `notifications` attribute in the `Service`
+> to just create a `Notification` template and use the `apply` keyword to assign the
-> object to associate these templates with a service.
+> notification to a number of services.
 
 Example:
 
@@ -202,8 +189,8 @@ Dependency objects are used to specify dependencies between hosts and services.
 > **Best Practice**
 >
 > Rather than creating a `Dependency` object for a specific service it is usually easier
-> to just create a `Dependency` template and using the `dependencies` attribute in the `Service`
+> to just create a `Dependency` template and use the `apply` keyword to assign the
-> object to associate these templates with a service.
+> dependency to a number of services.
 
 Example:
 
@@ -360,8 +347,8 @@ ScheduledDowntime objects can be used to set up recurring downtimes for services
 > **Best Practice**
 >
 > Rather than creating a `ScheduledDowntime` object for a specific service it is usually easier
-> to just create a `ScheduledDowntime` template and use the `scheduled_downtimes` attribute in the `Service`
+> to just create a `ScheduledDowntime` template and use the `apply` keyword to assign the
-> object to associate these templates with a service.
+> scheduled downtime to a number of services.
 
 Example:
 

doc/4.5-best-practice.md

@@ -41,7 +41,6 @@ your configuration directory tree and files:
         vienna/
           hosts.conf
 
-
 If you're planning to create a [cluster](#cluster) setup with Icinga 2 and your
 configuration master should deploy specific configuration parts to slave nodes,
 it's reasonable not to confuse it with configuration below `conf.d`. Rather
@@ -54,8 +53,6 @@ create a dedicated directory and put all nodes into their own directories:
       node2/
       node99/
 
-
-
 If you are preferring to control what several parties drop into the configuration
 pool (for example different departments with their own standalone configuration),
 you can still deactivate the `conf.d` inclusion and use your own strategy.
@@ -90,8 +87,7 @@ unwanted values.
 ### <a id="best-practice-inline-objects-using-templates"></a> Inline Objects using Templates
 
 While it is reasonable to create single objects by your preferred configuration
-tool, using templates and inheriting their attributes in inline objects will
+tool, using templates and the `apply` keyword will save you a lot of typing extra work.
-save you a lot of typing extra work.
 
 For instance, you can still create a host object, then a service object linking
 to it, after that a notification object referencing the service object, and last
@@ -147,20 +143,17 @@ By doing that everytime for such a series of linked objects, your configuration
 will get bloated and unreadable. You've already read that [using templates](#best-practice-use-templates)
 will help here.
 
-The `Notification` and `ScheduledDowntime` templates will be referenced in the service template and
+Using the `apply` keyword you can create services, notifications, scheduled downtimes and dependencies
-inline definition (both locations are possible).
+for an arbitrary number of hosts and services respectively:
-The `Service` template is referenced within the inline service array for the `Host` template. In the end
-the `Host` object inherits from the `Host` template named `linux-server`.
-That way similar hosts may just inherit the host template and get all services, notifications, scheduled
-downtimes through the template automatism.
 
-    template Notification "mail-notification" {
+    apply Notification "mail-notification" {
       notification_command = "mail-service-notification",
-
       users = [ "user1", "user2" ]
+
+      assign where "generic-service" in service.templates
     }
 
-    template ScheduledDowntime "backup-downtime" {
+    apply ScheduledDowntime "backup-downtime" {
       author = "icingaadmin",
       comment = "Some comment",
 
@@ -170,6 +163,8 @@ downtimes through the template automatism.
       ranges = {
         "sunday" = "02:00-03:00"
       }
+ 
+      assign where "generic-service" in service.templates
     }
 
     template Service "generic-service" {
@@ -177,35 +172,24 @@ downtimes through the template automatism.
       check_interval = 5m,
       retry_interval = 1m,
       enable_perfdata = true,
+    }
 
-      notifications["mail"] = {
+    apply Service "ping4" {
-        templates = [ "mail-notification" ]
+      import "generic-service",
-      }
+ 
+      check_command = "ping4",
+
+      assign where "linux-server" in host.templates
     }
 
     template Host "linux-server" {
-      display_name = "The best host there is",
-
       groups = [ "all-hosts" ],
 
-      host_dependencies = [ "router" ],
-
-      services["ping4"] = {
-        templates = [ "generic-service" ],
-
-        check_command = "ping4",
-
-        scheduled_downtimes["backup"] = {
-          templates = [ "backup-downtime" ]
-        }
-      },
-
       check = "ping4"
     }
 
     object Host "localhost" {
       import "linux-server",
+
+      display_name = "The best host there is",
     }
-
-
-

doc/6.01-downtimes.md

@@ -73,7 +73,7 @@ recurring downtimes for services.
 
 Example:
 
-    template ScheduledDowntime "backup-downtime" {
+    apply ScheduledDowntime "backup-downtime" {
       author = "icingaadmin",
       comment = "Scheduled downtime for backup",
 
@@ -86,19 +86,7 @@ Example:
         saturday = "02:00-03:00",
         sunday = "02:00-03:00"
       }
+
+      assign where "backup" in service.groups
     }
 
-    object Host "localhost" {
-      import "generic-host",
-
-      ...
-      services["load"] = {
-        templates = [ "generic-service" ],
-
-        check_command = "load",
-
-        scheduled_downtimes["backup"] = {
-          templates = [ "backup-downtime" ]
-        }
-      },
-    }

doc/6.04-cluster.md

@@ -210,13 +210,12 @@ If you require specific services to be only executed by one or more checker node
 within the cluster, you must define `authorities` as additional service object
 attribute. Required Endpoints must be defined as array.
 
-    object Host "dmz-host1" {
+    apply Service "dmz-oracledb" {
-      import "generic-host",
+      import "generic-service",
 
-      services["dmz-oracledb"] = {
+      authorities = [ "icinga-node-1" ],
-        templates = [ "generic-service" ],
+
-        authorities = [ "icinga-node-1" ],
+      assign where "oracle" in host.groups
-      }
     }
 
 > **Tip**
@@ -234,15 +233,14 @@ one or more configured nodes are not connected.
 
 Example:
 
-    object Host "icinga2a" {
+    apply Service "cluster" {
-      import "generic-host",
+        import "generic-service",
 
-      services["cluster"] = {
-        templates = [ "generic-service" ],
         check_interval = 1m,
         check_command = "cluster",
-        authorities = [ "icinga2a" ]
+        authorities = [ "icinga2a" ],
-      },
+
+        assign where host.name = "icinga2a"
     }
 
 > **Note**

doc/6.06-dependencies.md

@@ -15,39 +15,30 @@ access by pinging the Google DNS server `google-dns` is a common method, but
 will fail in case the `dsl-router` host is down. Therefore the example below
 defines a host dependency which acts implicit as parent relation too.
 
-Furthermore the host may be reachable but ping samples are dropped by the
+Furthermore the host may be reachable but ping probes are dropped by the
 router's firewall. In case the `dsl-router``ping4` service check fails, all
-further checks for the `google-dns` `ping4` service should be suppressed.
+further checks for the `ping4` service on host `google-dns` service should
-This is achieved by setting the `disable_checks` attribute to `true`.
+be suppressed. This is achieved by setting the `disable_checks` attribute to `true`.
 
     object Host "dsl-router" {
-      services["ping4"] = {
+      macros.address = "192.168.1.1"
-        templates = "generic-service",
-        check_command = "ping4"
-      }
-
-      macros = {
-        address = "192.168.1.1",
-      },
     }
 
     object Host "google-dns" {
-      services["ping4"] = {
+      macros.address = "8.8.8.8",
-        templates = "generic-service",
+    }
-        check_command = "ping4",
-        dependencies["dsl-router-ping4"] = {
-          parent_host = "dsl-router",
-          parent_service = "ping4",
-          disable_checks = true
-        }
-      }
 
-      macros = {
+    apply Service "ping4" {
-        address = "8.8.8.8",
+      import "generic-service",
-      },
 
-      dependencies["dsl-router"] = {
+      check_command = "ping4"
-        parent_host = "dsl-router"
-      },
 
-    }
+      assign where host.macros.address
+    }
+
+    apply Dependency "internet" {
+      parent_host = "dsl-router",
+      disable_checks = true
+
+      assign where host.name != "dsl-router"
+    }

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

@@ -218,12 +218,8 @@ In Icinga 1.x a service object is associated with a host by defining the
 to `hostgroup_name` or behavior changing regular expression. It's not possible
 to define a service definition within a host definition.
 
-The preferred way of associating hosts with services in Icinga 2 are services
+The preferred way of associating hosts with services in Icinga 2 is by
-defined inline to the host object (or template) definition. Icinga 2 will
+using the `apply` keyword.
-implicitely create a new service object on configuration activation. These
-inline service definitions can reference service templates.
-Linking a service to a host is still possible with the 'host' attribute in
-a service object in Icinga 2.
 
 ## <a id="differences-1x-2-users"></a> Users
 
@@ -371,19 +367,22 @@ The preferred way of assigning objects to groups is by using a template:
 
     template Host "dev-host" {
       groups += [ "dev-hosts" ],
-
-      services["http"] = {
-        check_command = [ "http-ip" ]
-      }
     }
 
     object Host "web-dev" {
       import "dev-host"
     }
 
-Host groups in Icinga 2 cannot be used to associate services with all members
+In order to associate a service with all hosts in a host group the `apply`
-of that group. The example above shows how to use templates to accomplish
+keyword can be used:
-the same effect.
+
+    apply Service "ping" {
+      import "generic-service",
+
+      check_command = "ping4",
+
+      assign where "group" in host.groups
+    }
 
 ## <a id="differences-1x-2-notifications"></a> Notifications