Adding upstream version 2.13.6.upstream/2.13.6upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 1585 insertions, 0 deletions

diff --git a/doc/23-migrating-from-icinga-1x.md b/doc/23-migrating-from-icinga-1x.md
new file mode 100644
index 0000000..c9cfa50
--- /dev/null
+++ b/doc/23-migrating-from-icinga-1x.md
@@ -0,0 +1,1585 @@
+# Migration from Icinga 1.x <a id="migration"></a>
+
+## Configuration Migration <a id="configuration-migration"></a>
+
+The Icinga 2 configuration format introduces plenty of behavioural changes. In
+order to ease migration from Icinga 1.x, this section provides hints and tips
+on your migration requirements.
+
+
+### Automated Config Migration <a id="automated-config-migration"></a>
+
+Depending on your previous setup, you may have already used different sources
+for generating the 1.x configuration files. If this is the case,
+we strongly recommend to use these sources in combination with
+the [Icinga Director](https://icinga.com/docs/director/latest/doc/01-Introduction/).
+
+This can be for example:
+
+* A CMDB or RDBMS which provides host details and facts
+* PuppetDB
+* CSV/XSL/JSON files
+* Cloud resources (AWS, etc.)
+
+In case you have been using Icinga Web 1.x or an addon requiring
+the underlying IDO database, you can use this as database resource
+to import the host details.
+
+Talks:
+
+* [This talk from OSMC 2016](https://www.youtube.com/watch?v=T6GBsfeXIZI) shares more insights (German).
+* [Automated Monitoring in heterogeneous environments](https://www.youtube.com/watch?v=bkUlS5rlHzM&list=PLeoxx10paaAn_xHJ5wBhnBJyW_d5G7-Bl&index=8)
+
+Continue reading more about [Import Sources](https://icinga.com/docs/director/latest/doc/70-Import-and-Sync/)
+for the Icinga Director.
+
+### Manual Config Migration <a id="manual-config-migration"></a>
+
+For a long-term migration of your configuration you should consider re-creating
+your configuration based on the proposed Icinga 2 configuration paradigm.
+
+Please read the [next chapter](23-migrating-from-icinga-1x.md#differences-1x-2) to find out more about the differences
+between 1.x and 2.
+
+### Manual Config Migration Hints <a id="manual-config-migration-hints"></a>
+
+These hints should provide you with enough details for manually migrating your configuration,
+or to adapt your configuration export tool to dump Icinga 2 configuration instead of
+Icinga 1.x configuration.
+
+The examples are taken from Icinga 1.x test and production environments and converted
+straight into a possible Icinga 2 format. If you found a different strategy, please
+let us know!
+
+If you require in-depth explanations, please check the [next chapter](23-migrating-from-icinga-1x.md#differences-1x-2).
+
+#### Manual Config Migration Hints for Intervals <a id="manual-config-migration-hints-Intervals"></a>
+
+By default all intervals without any duration literal are interpreted as seconds. Therefore
+all existing Icinga 1.x `*_interval` attributes require an additional `m` duration literal.
+
+Icinga 1.x:
+
+```
+define service {
+  service_description             service1
+  host_name                       localhost1
+  check_command                   test_customvar
+  use                             generic-service
+  check_interval                  5
+  retry_interval                  1
+}
+```
+
+Icinga 2:
+
+```
+object Service "service1" {
+  import "generic-service"
+  host_name = "localhost1"
+  check_command = "test_customvar"
+  check_interval = 5m
+  retry_interval = 1m
+}
+```
+
+#### Manual Config Migration Hints for Services <a id="manual-config-migration-hints-services"></a>
+
+If you have used the `host_name` attribute in Icinga 1.x with one or more host names this service
+belongs to, you can migrate this to the [apply rules](03-monitoring-basics.md#using-apply) syntax.
+
+Icinga 1.x:
+
+```
+define service {
+  service_description             service1
+  host_name                       localhost1,localhost2
+  check_command                   test_check
+  use                             generic-service
+}
+```
+
+Icinga 2:
+
+```
+apply Service "service1" {
+  import "generic-service"
+  check_command = "test_check"
+
+  assign where host.name in [ "localhost1", "localhost2" ]
+}
+```
+
+In Icinga 1.x you would have organized your services with hostgroups using the `hostgroup_name` attribute
+like the following example:
+
+```
+define service {
+  service_description             servicewithhostgroups
+  hostgroup_name                  hostgroup1,hostgroup3
+  check_command                   test_check
+  use                             generic-service
+}
+```
+
+Using Icinga 2 you can migrate this to the [apply rules](03-monitoring-basics.md#using-apply) syntax:
+
+```
+apply Service "servicewithhostgroups" {
+  import "generic-service"
+  check_command = "test_check"
+
+  assign where "hostgroup1" in host.groups
+  assign where "hostgroup3" in host.groups
+}
+```
+
+#### Manual Config Migration Hints for Group Members <a id="manual-config-migration-hints-group-members"></a>
+
+The Icinga 1.x hostgroup `hg1` has two members `host1` and `host2`. The hostgroup `hg2` has `host3` as
+a member and includes all members of the `hg1` hostgroup.
+
+```
+define hostgroup {
+  hostgroup_name                  hg1
+  members                         host1,host2
+}
+
+define hostgroup {
+  hostgroup_name                  hg2
+  members                         host3
+  hostgroup_members               hg1
+}
+```
+
+This can be migrated to Icinga 2 and [using group assign](17-language-reference.md#group-assign). The additional nested hostgroup
+`hg1` is included into `hg2` with the `groups` attribute.
+
+```
+object HostGroup "hg1" {
+  groups = [ "hg2" ]
+  assign where host.name in [ "host1", "host2" ]
+}
+
+object HostGroup "hg2" {
+  assign where host.name == "host3"
+}
+```
+
+These assign rules can be applied for all groups: `HostGroup`, `ServiceGroup` and `UserGroup`
+(requires renaming from `contactgroup`).
+
+> **Tip**
+>
+> Define custom variables and assign/ignore members based on these attribute pattern matches.
+
+
+
+#### Manual Config Migration Hints for Check Command Arguments <a id="manual-config-migration-hints-check-command-arguments"></a>
+
+Host and service check command arguments are separated by a `!` in Icinga 1.x. Their order is important and they
+are referenced as `$ARGn$` where `n` is the argument counter.
+
+```
+define command {
+  command_name                      my-ping
+  command_line                      $USER1$/check_ping -H $HOSTADDRESS$ -w $ARG1$ -c $ARG2$ -p 5
+}
+
+define service {
+  use                               generic-service
+  host_name                         my-server
+  service_description               my-ping
+  check_command                     my-ping-check!100.0,20%!500.0,60%
+}
+```
+
+While you could manually migrate this like (please note the new generic command arguments and default argument values!):
+
+```
+object CheckCommand "my-ping-check" {
+  command = [
+    PluginDir + "/check_ping", "-4"
+  ]
+
+  arguments = {
+    "-H" = "$ping_address$"
+    "-w" = "$ping_wrta$,$ping_wpl$%"
+    "-c" = "$ping_crta$,$ping_cpl$%"
+    "-p" = "$ping_packets$"
+    "-t" = "$ping_timeout$"
+  }
+
+  vars.ping_address = "$address$"
+  vars.ping_wrta = 100
+  vars.ping_wpl = 5
+  vars.ping_crta = 200
+  vars.ping_cpl = 15
+}
+
+object Service "my-ping" {
+  import "generic-service"
+  host_name = "my-server"
+  check_command = "my-ping-check"
+
+  vars.ping_wrta = 100
+  vars.ping_wpl = 20
+  vars.ping_crta = 500
+  vars.ping_cpl = 60
+}
+```
+
+#### Manual Config Migration Hints for Runtime Macros <a id="manual-config-migration-hints-runtime-macros"></a>
+
+Runtime macros have been renamed. A detailed comparison table can be found [here](23-migrating-from-icinga-1x.md#differences-1x-2-runtime-macros).
+
+For example, accessing the service check output looks like the following in Icinga 1.x:
+
+```
+$SERVICEOUTPUT$
+```
+
+In Icinga 2 you will need to write:
+
+```
+$service.output$
+```
+
+Another example referencing the host's address attribute in Icinga 1.x:
+
+```
+$HOSTADDRESS$
+```
+
+In Icinga 2 you'd just use the following macro to access all `address` attributes (even overridden from the service objects):
+
+```
+$address$
+```
+
+#### Manual Config Migration Hints for Runtime Custom Variables <a id="manual-config-migration-hints-runtime-custom-variables"></a>
+
+Custom variables from Icinga 1.x are available as Icinga 2 custom variables.
+
+```
+define command {
+  command_name                    test_customvar
+  command_line                    echo "Host CV: $_HOSTCVTEST$ Service CV: $_SERVICECVTEST$\n"
+}
+
+define host {
+  host_name                       localhost1
+  check_command                   test_customvar
+  use                             generic-host
+  _CVTEST                         host cv value
+}
+
+define service {
+  service_description             service1
+  host_name                       localhost1
+  check_command                   test_customvar
+  use                             generic-service
+  _CVTEST                         service cv value
+}
+```
+
+Can be written as the following in Icinga 2:
+
+```
+object CheckCommand "test_customvar" {
+  command = "echo "Host CV: $host.vars.CVTEST$ Service CV: $service.vars.CVTEST$\n""
+}
+
+object Host "localhost1" {
+  import "generic-host"
+  check_command = "test_customvar"
+  vars.CVTEST = "host cv value"
+}
+
+object Service "service1" {
+  host_name = "localhost1"
+  check_command = "test_customvar"
+  vars.CVTEST = "service cv value"
+}
+```
+
+If you are just defining `$CVTEST$` in your command definition, its value depends on the
+execution scope -- the host check command will fetch the host attribute value of `vars.CVTEST`
+while the service check command resolves its value to the service attribute attribute `vars.CVTEST`.
+
+> **Note**
+>
+> Custom variables in Icinga 2 are case-sensitive. `vars.CVTEST` is not the same as `vars.CvTest`.
+
+#### Manual Config Migration Hints for Contacts (Users) <a id="manual-config-migration-hints-contacts-users"></a>
+
+Contacts in Icinga 1.x act as users in Icinga 2, but do not have any notification commands specified.
+This migration part is explained in the [next chapter](23-migrating-from-icinga-1x.md#manual-config-migration-hints-notifications).
+
+```
+define contact{
+  contact_name                    testconfig-user
+  use                             generic-user
+  alias                           Icinga Test User
+  service_notification_options    c,f,s,u
+  email                           icinga@localhost
+}
+```
+
+The `service_notification_options` can be [mapped](23-migrating-from-icinga-1x.md#manual-config-migration-hints-notification-filters)
+into generic `state` and `type` filters, if additional notification filtering is required. `alias` gets
+renamed to `display_name`.
+
+```
+object User "testconfig-user" {
+  import "generic-user"
+  display_name = "Icinga Test User"
+  email = "icinga@localhost"
+}
+```
+
+This user can be put into usergroups (former contactgroups) or referenced in newly migration notification
+objects.
+
+#### Manual Config Migration Hints for Notifications <a id="manual-config-migration-hints-notifications"></a>
+
+If you are migrating a host or service notification, you'll need to extract the following information from
+your existing Icinga 1.x configuration objects
+
+* host/service attribute `contacts` and `contact_groups`
+* host/service attribute `notification_options`
+* host/service attribute `notification_period`
+* host/service attribute `notification_interval`
+
+The clean approach is to refactor your current contacts and their notification command methods into a
+generic strategy
+
+* host or service has a notification type (for example mail)
+* which contacts (users) are notified by mail?
+* do the notification filters, periods, intervals still apply for them? (do a cleanup during migration)
+* assign users and groups to these notifications
+* Redesign the notifications into generic [apply rules](03-monitoring-basics.md#using-apply-notifications)
+
+
+The ugly workaround solution could look like this:
+
+Extract all contacts from the remaining groups, and create a unique list. This is required for determining
+the host and service notification commands involved.
+
+* contact attributes `host_notification_commands` and `service_notification_commands` (can be a comma separated list)
+* get the command line for each notification command and store them for later
+* create a new notification name and command name
+
+Generate a new notification object based on these values. Import the generic template based on the type (`host` or `service`).
+Assign it to the host or service and set the newly generated notification command name as `command` attribute.
+
+```
+object Notification "<notificationname>" {
+  import "mail-host-notification"
+  host_name = "<thishostname>"
+  command = "<notificationcommandname>"
+```
+
+Convert the `notification_options` attribute from Icinga 1.x to Icinga 2 `states` and `types`. Details
+[here](23-migrating-from-icinga-1x.md#manual-config-migration-hints-notification-filters). Add the notification period.
+
+```
+  states = [ OK, Warning, Critical ]
+  types = [ Recovery, Problem, Custom ]
+  period = "24x7"
+```
+
+The current contact acts as `users` attribute.
+
+```
+  users = [ "<contactwithnotificationcommand>" ]
+}
+```
+
+Do this in a loop for all notification commands (depending if host or service contact). Once done, dump the
+collected notification commands.
+
+The result of this migration are lots of unnecessary notification objects and commands but it will unroll
+the Icinga 1.x logic into the revamped Icinga 2 notification object schema. If you are looking for code
+examples, try [LConf](https://www.netways.org).
+
+
+
+#### Manual Config Migration Hints for Notification Filters <a id="manual-config-migration-hints-notification-filters"></a>
+
+Icinga 1.x defines all notification filters in an attribute called `notification_options`. Using Icinga 2 you will
+have to split these values into the `states` and `types` attributes.
+
+> **Note**
+>
+> `Recovery` type requires the `Ok` state.
+> `Custom` and `Problem` should always be set as `type` filter.
+
+  Icinga 1.x option     | Icinga 2 state        | Icinga 2 type
+  ----------------------|-----------------------|-------------------
+  o                     | OK (Up for hosts)     |
+  w                     | Warning               | Problem
+  c                     | Critical              | Problem
+  u                     | Unknown               | Problem
+  d                     | Down                  | Problem
+  s                     | .                     | DowntimeStart / DowntimeEnd / DowntimeRemoved
+  r                     | Ok                    | Recovery
+  f                     | .                     | FlappingStart / FlappingEnd
+  n                     | 0  (none)             | 0 (none)
+  .                     | .                     | Custom
+
+
+
+#### Manual Config Migration Hints for Escalations <a id="manual-config-migration-hints-escalations"></a>
+
+Escalations in Icinga 1.x are a bit tricky. By default service escalations can be applied to hosts and
+hostgroups and require a defined service object.
+
+The following example applies a service escalation to the service `dep_svc01` and all hosts in the `hg_svcdep2`
+hostgroup. The default `notification_interval` is set to `10` minutes notifying the `cg_admin` contact.
+After 20 minutes (`10*2`, notification_interval * first_notification) the notification is escalated to the
+`cg_ops` contactgroup until 60 minutes (`10*6`) have passed.
+
+```
+define service {
+  service_description             dep_svc01
+  host_name                       dep_hostsvc01,dep_hostsvc03
+  check_command                   test2
+  use                             generic-service
+  notification_interval           10
+  contact_groups                  cg_admin
+}
+
+define hostgroup {
+  hostgroup_name                  hg_svcdep2
+  members                         dep_hostsvc03
+}
+
+# with hostgroup_name and service_description
+define serviceescalation {
+  hostgroup_name                  hg_svcdep2
+  service_description             dep_svc01
+  first_notification              2
+  last_notification               6
+  contact_groups                  cg_ops
+}
+```
+
+In Icinga 2 the service and hostgroup definition will look quite the same. Save the `notification_interval`
+and `contact_groups` attribute for an additional notification.
+
+```
+apply Service "dep_svc01" {
+  import "generic-service"
+
+  check_command = "test2"
+
+  assign where host.name == "dep_hostsvc01"
+  assign where host.name == "dep_hostsvc03"
+}
+
+object HostGroup "hg_svcdep2" {
+  assign where host.name == "dep_hostsvc03"
+}
+
+apply Notification "email" to Service {
+  import "service-mail-notification"
+
+  interval = 10m
+  user_groups = [ "cg_admin" ]
+
+  assign where service.name == "dep_svc01" && (host.name == "dep_hostsvc01" || host.name == "dep_hostsvc03")
+}
+```
+
+Calculate the begin and end time for the newly created escalation notification:
+
+* begin = first_notification * notification_interval = 2 * 10m = 20m
+* end = last_notification * notification_interval = 6 * 10m = 60m = 1h
+
+Assign the notification escalation to the service `dep_svc01` on all hosts in the hostgroup `hg_svcdep2`.
+
+```
+apply Notification "email-escalation" to Service {
+  import "service-mail-notification"
+
+  interval = 10m
+  user_groups = [ "cg_ops" ]
+
+  times = {
+    begin = 20m
+    end = 1h
+  }
+
+  assign where service.name == "dep_svc01" && "hg_svcdep2" in host.groups
+}
+```
+
+The assign rule could be made more generic and the notification be applied to more than
+just this service belonging to hosts in the matched hostgroup.
+
+
+> **Note**
+>
+> When the notification is escalated, Icinga 1.x suppresses notifications to the default contacts.
+> In Icinga 2 an escalation is an additional notification with a defined begin and end time. The
+> `email` notification will continue as normal.
+
+
+
+#### Manual Config Migration Hints for Dependencies <a id="manual-config-migration-hints-dependencies"></a>
+
+There are some dependency examples already in the [basics chapter](03-monitoring-basics.md#dependencies). Dependencies in
+Icinga 1.x can be confusing in terms of which host/service is the parent and which host/service acts
+as the child.
+
+While Icinga 1.x defines `notification_failure_criteria` and `execution_failure_criteria` as dependency
+filters, this behaviour has changed in Icinga 2. There is no 1:1 migration but generally speaking
+the state filter defined in the `execution_failure_criteria` defines the Icinga 2 `state` attribute.
+If the state filter matches, you can define whether to disable checks and notifications or not.
+
+The following example describes service dependencies. If you migrate from Icinga 1.x, you will only
+want to use the classic `Host-to-Host` and `Service-to-Service` dependency relationships.
+
+```
+define service {
+  service_description             dep_svc01
+  hostgroup_name                  hg_svcdep1
+  check_command                   test2
+  use                             generic-service
+}
+
+define service {
+  service_description             dep_svc02
+  hostgroup_name                  hg_svcdep2
+  check_command                   test2
+  use                             generic-service
+}
+
+define hostgroup {
+  hostgroup_name                  hg_svcdep2
+  members                         host2
+}
+
+define host{
+  use                             linux-server-template
+  host_name                       host1
+  address                         192.168.1.10
+}
+
+# with hostgroup_name and service_description
+define servicedependency {
+  host_name                       host1
+  dependent_hostgroup_name        hg_svcdep2
+  service_description             dep_svc01
+  dependent_service_description   *
+  execution_failure_criteria      u,c
+  notification_failure_criteria   w,u,c
+  inherits_parent                 1
+}
+```
+
+Map the dependency attributes accordingly.
+
+  Icinga 1.x            | Icinga 2
+  ----------------------|---------------------
+  host_name             | parent_host_name
+  dependent_host_name   | child_host_name (used in assign/ignore)
+  dependent_hostgroup_name | all child hosts in group (used in assign/ignore)
+  service_description   | parent_service_name
+  dependent_service_description | child_service_name (used in assign/ignore)
+
+And migrate the host and services.
+
+```
+object Host "host1" {
+  import "linux-server-template"
+  address = "192.168.1.10"
+}
+
+object HostGroup "hg_svcdep2" {
+  assign where host.name == "host2"
+}
+
+apply Service "dep_svc01" {
+  import "generic-service"
+  check_command = "test2"
+
+  assign where "hp_svcdep1" in host.groups
+}
+
+apply Service "dep_svc02" {
+  import "generic-service"
+  check_command = "test2"
+
+  assign where "hp_svcdep2" in host.groups
+}
+```
+
+When it comes to the `execution_failure_criteria` and `notification_failure_criteria` attribute migration,
+you will need to map the most common values, in this example `u,c` (`Unknown` and `Critical` will cause the
+dependency to fail). Therefore the `Dependency` should be ok on Ok and Warning. `inherits_parents` is always
+enabled.
+
+```
+apply Dependency "all-svc-for-hg-hg_svcdep2-on-host1-dep_svc01" to Service {
+  parent_host_name = "host1"
+  parent_service_name = "dep_svc01"
+
+  states = [ Ok, Warning ]
+  disable_checks = true
+  disable_notifications = true
+
+  assign where "hg_svcdep2" in host.groups
+}
+```
+
+Host dependencies are explained in the [next chapter](23-migrating-from-icinga-1x.md#manual-config-migration-hints-host-parents).
+
+
+
+#### Manual Config Migration Hints for Host Parents <a id="manual-config-migration-hints-host-parents"></a>
+
+Host parents from Icinga 1.x are migrated into `Host-to-Host` dependencies in Icinga 2.
+
+The following example defines the `vmware-master` host as parent host for the guest
+virtual machines `vmware-vm1` and `vmware-vm2`.
+
+By default all hosts in the hostgroup `vmware` should get the parent assigned. This isn't really
+solvable with Icinga 1.x parents, but only with host dependencies.
+
+```
+define host{
+  use                             linux-server-template
+  host_name                       vmware-master
+  hostgroups                      vmware
+  address                         192.168.1.10
+}
+
+define host{
+  use                             linux-server-template
+  host_name                       vmware-vm1
+  hostgroups                      vmware
+  address                         192.168.27.1
+  parents                         vmware-master
+}
+
+define host{
+  use                             linux-server-template
+  host_name                       vmware-vm2
+  hostgroups                      vmware
+  address                         192.168.28.1
+  parents                         vmware-master
+}
+```
+
+By default all hosts in the hostgroup `vmware` should get the parent assigned (but not the `vmware-master`
+host itself). This isn't really solvable with Icinga 1.x parents, but only with host dependencies as shown
+below:
+
+```
+define hostdependency {
+  dependent_hostgroup_name        vmware
+  dependent_host_name             !vmware-master
+  host_name                       vmware-master
+  inherits_parent                 1
+  notification_failure_criteria   d,u
+  execution_failure_criteria      d,u
+  dependency_period               testconfig-24x7
+}
+```
+
+When migrating to Icinga 2, the parents must be changed to a newly created host dependency.
+
+
+Map the following attributes
+
+  Icinga 1.x            | Icinga 2
+  ----------------------|---------------------
+  host_name             | parent_host_name
+  dependent_host_name   | child_host_name (used in assign/ignore)
+  dependent_hostgroup_name | all child hosts in group (used in assign/ignore)
+
+The Icinga 2 configuration looks like this:
+
+```
+object Host "vmware-master" {
+  import "linux-server-template"
+  groups += [ "vmware" ]
+  address = "192.168.1.10"
+  vars.is_vmware_master = true
+}
+
+object Host "vmware-vm1" {
+  import "linux-server-template"
+  groups += [ "vmware" ]
+  address = "192.168.27.1"
+}
+
+object Host "vmware-vm2" {
+  import "linux-server-template"
+  groups += [ "vmware" ]
+  address = "192.168.28.1"
+}
+
+apply Dependency "vmware-master" to Host {
+  parent_host_name = "vmware-master"
+
+  assign where "vmware" in host.groups
+  ignore where host.vars.is_vmware_master
+  ignore where host.name == "vmware-master"
+}
+```
+
+For easier identification you could add the `vars.is_vmware_master` attribute to the `vmware-master`
+host and let the dependency ignore that instead of the hardcoded host name. That's different
+to the Icinga 1.x example and a best practice hint only.
+
+
+Another way to express the same configuration would be something like:
+
+```
+object Host "vmware-master" {
+  import "linux-server-template"
+  groups += [ "vmware" ]
+  address = "192.168.1.10"
+}
+
+object Host "vmware-vm1" {
+  import "linux-server-template"
+  groups += [ "vmware" ]
+  address = "192.168.27.1"
+  vars.parents = [ "vmware-master" ]
+}
+
+object Host "vmware-vm2" {
+  import "linux-server-template"
+  groups += [ "vmware" ]
+  address = "192.168.28.1"
+  vars.parents = [ "vmware-master" ]
+}
+
+apply Dependency "host-to-parent-" for (parent in host.vars.parents) to Host {
+  parent_host_name = parent
+}
+```
+
+This example allows finer grained host-to-host dependency, as well as multiple dependency support.
+
+#### Manual Config Migration Hints for Distributed Setups <a id="manual-config-migration-hints-distributed-setup"></a>
+
+* Icinga 2 does not use active/passive instances calling OSCP commands and requiring the NSCA
+daemon for passing check results between instances.
+* Icinga 2 does not support any 1.x NEB addons for check load distribution
+
+* If your current setup consists of instances distributing the check load, you should consider
+building a [load distribution](06-distributed-monitoring.md#distributed-monitoring-scenarios) setup with Icinga 2.
+* If your current setup includes active/passive clustering with external tools like Pacemaker/DRBD,
+consider the [High Availability](06-distributed-monitoring.md#distributed-monitoring-scenarios) setup.
+* If you have build your own custom configuration deployment and check result collecting mechanism,
+you should re-design your setup and re-evaluate your requirements, and how they may be fulfilled
+using the Icinga 2 cluster capabilities.
+
+
+## Differences between Icinga 1.x and 2 <a id="differences-1x-2"></a>
+
+### Configuration Format <a id="differences-1x-2-configuration-format"></a>
+
+Icinga 1.x supports two configuration formats: key-value-based settings in the
+`icinga.cfg` configuration file and object-based in included files (`cfg_dir`,
+`cfg_file`). The path to the `icinga.cfg` configuration file must be passed to
+the Icinga daemon at startup.
+
+icinga.cfg:
+
+```
+enable_notifications=1
+```
+
+objects.cfg:
+
+```
+define service {
+   notifications_enabled    0
+}
+```
+
+Icinga 2 supports objects and (global) variables, but does not make a difference 
+between the main configuration file or any other included file.
+
+icinga2.conf:
+
+```
+const EnableNotifications = true
+
+object Service "test" {
+    enable_notifications = false
+}
+```
+
+#### Sample Configuration and ITL <a id="differences-1x-2-sample-configuration-itl"></a>
+
+While Icinga 1.x ships sample configuration and templates spread in various
+object files, Icinga 2 moves all templates into the Icinga Template Library (ITL)
+and includes them in the sample configuration.
+
+Additional plugin check commands are shipped with Icinga 2 as well.
+
+The ITL will be updated on every release and must not be edited by the user.
+
+There are still generic templates available for your convenience which may or may
+not be re-used in your configuration. For instance, `generic-service` includes
+all required attributes except `check_command` for a service.
+
+Sample configuration files are located in the `conf.d/` directory which is
+included in `icinga2.conf` by default.
+
+> **Note**
+>
+> Add your own custom templates in the `conf.d/` directory as well, e.g. inside
+> the [templates.conf](04-configuration.md#templates-conf) file.
+
+### Main Config File <a id="differences-1x-2-main-config"></a>
+
+In Icinga 1.x there are many global configuration settings available in `icinga.cfg`.
+Icinga 2 only uses a small set of [global constants](17-language-reference.md#constants) allowing
+you to specify certain different setting such as the `NodeName` in a cluster scenario.
+
+Aside from that, the [icinga2.conf](04-configuration.md#icinga2-conf) should take care of including
+global constants, enabled [features](11-cli-commands.md#enable-features) and the object configuration.
+
+### Include Files and Directories <a id="differences-1x-2-include-files-dirs"></a>
+
+In Icinga 1.x the `icinga.cfg` file contains `cfg_file` and `cfg_dir`
+directives. The `cfg_dir` directive recursively includes all files with a `.cfg`
+suffix in the given directory. Only absolute paths may be used. The `cfg_file`
+and `cfg_dir` directives can include the same file twice which leads to
+configuration errors in Icinga 1.x.
+
+```
+cfg_file=/etc/icinga/objects/commands.cfg
+cfg_dir=/etc/icinga/objects
+```
+
+Icinga 2 supports wildcard includes and relative paths, e.g. for including
+`conf.d/*.conf` in the same directory.
+
+```
+include "conf.d/*.conf"
+```
+
+If you want to include files and directories recursively, you need to define
+a separate option and add the directory and an optional pattern.
+
+```
+include_recursive "conf.d"
+```
+
+A global search path for includes is available for advanced features like
+the Icinga Template Library (ITL) or additional monitoring plugins check
+command configuration.
+
+```
+include <itl>
+include <plugins>
+```
+
+By convention the `.conf` suffix is used for Icinga 2 configuration files.
+
+### Resource File and Global Macros <a id="differences-1x-2-resource-file-global-macros"></a>
+
+Global macros such as for the plugin directory, usernames and passwords can be
+set in the `resource.cfg` configuration file in Icinga 1.x. By convention the
+`USER1` macro is used to define the directory for the plugins.
+
+Icinga 2 uses global constants instead. In the default config these are
+set in the `constants.conf` configuration file:
+
+```
+/**
+ * This file defines global constants which can be used in
+ * the other configuration files. At a minimum the
+ * PluginDir constant should be defined.
+ */
+
+const PluginDir = "/usr/lib/nagios/plugins"
+```
+
+[Global macros](17-language-reference.md#constants) can only be defined once. Trying to modify a
+global constant will result in an error.
+
+### Configuration Comments <a id="differences-1x-2-configuration-comments"></a>
+
+In Icinga 1.x comments are made using a leading hash (`#`) or a semi-colon (`;`)
+for inline comments.
+
+In Icinga 2 comments can either be encapsulated by `/*` and `*/` (allowing for
+multi-line comments) or starting with two slashes (`//`). A leading hash (`#`)
+could also be used.
+
+### Object Names <a id="differences-1x-2-object-names"></a>
+
+Object names must not contain an exclamation mark (`!`). Use the `display_name` attribute
+to specify user-friendly names which should be shown in UIs (supported by
+Icinga Web 2 for example).
+
+Object names are not specified using attributes (e.g. `service_description` for
+services) like in Icinga 1.x but directly after their type definition.
+
+```
+define service {
+    host_name  localhost
+    service_description  ping4
+}
+
+object Service "ping4" {
+  host_name = "localhost"
+}
+```
+
+### Templates <a id="differences-1x-2-templates"></a>
+
+In Icinga 1.x templates are identified using the `register 0` setting. Icinga 2
+uses the `template` identifier:
+
+```
+template Service "ping4-template" { }
+```
+
+Icinga 1.x objects inherit from templates using the `use` attribute.
+Icinga 2 uses the keyword `import` with template names in double quotes.
+
+```
+define service {
+    service_description testservice
+    use                 tmpl1,tmpl2,tmpl3
+}
+
+object Service "testservice" {
+  import "tmpl1"
+  import "tmpl2"
+  import "tmpl3"
+}
+```
+
+The last template overrides previously set values.
+
+### Object attributes <a id="differences-1x-2-object-attributes"></a>
+
+Icinga 1.x separates attribute and value pairs with whitespaces/tabs. Icinga 2
+requires an equal sign (=) between them.
+
+```
+define service {
+    check_interval  5
+}
+
+object Service "test" {
+    check_interval = 5m
+}
+```
+
+Please note that the default time value is seconds if no duration literal
+is given. `check_interval = 5` behaves the same as `check_interval = 5s`.
+
+All strings require double quotes in Icinga 2. Therefore a double quote
+must be escaped by a backslash (e.g. in command line).
+If an attribute identifier starts with a number, it must be enclosed
+in double quotes as well.
+
+#### Alias vs. Display Name <a id="differences-1x-2-alias-display-name"></a>
+
+In Icinga 1.x a host can have an `alias` and a `display_name` attribute used
+for a more descriptive name. A service only can have a `display_name` attribute.
+The `alias` is used for group, timeperiod, etc. objects too.
+Icinga 2 only supports the `display_name` attribute which is also taken into
+account by Icinga web interfaces.
+
+### Custom Variables <a id="differences-1x-2-custom-variables"></a>
+
+Icinga 2 allows you to define custom variables in the `vars` dictionary.
+The `notes`, `notes_url`, `action_url`, `icon_image`, `icon_image_alt`
+attributes for host and service objects are still available in Icinga 2.
+
+`2d_coords` and `statusmap_image` are not supported in Icinga 2.
+
+Icinga 1.x custom variable attributes must be prefixed using an underscore (`_`).
+In Icinga 2 these attributes must be added to the `vars` dictionary as custom variables.
+
+```
+vars.dn = "cn=icinga2-dev-host,ou=icinga,ou=main,ou=IcingaConfig,ou=LConf,dc=icinga,dc=org"
+vars.cv = "my custom cmdb description"
+```
+
+These custom variables are also used as [command parameters](03-monitoring-basics.md#command-passing-parameters).
+
+While Icinga 1.x only supports numbers and strings as custom variable values,
+Icinga 2 extends that to arrays and (nested) dictionaries. For more details
+look [here](03-monitoring-basics.md#custom-variables).
+
+### Host Service Relation <a id="differences-1x-2-host-service-relation"></a>
+
+In Icinga 1.x a service object is associated with a host by defining the
+`host_name` attribute in the service definition. Alternate methods refer
+to `hostgroup_name` or behaviour changing regular expression.
+
+The preferred way of associating hosts with services in Icinga 2 is by
+using the [apply](03-monitoring-basics.md#using-apply) keyword.
+
+Direct object relations between a service and a host still allow you to use
+the `host_name` [Service](09-object-types.md#objecttype-service) object attribute.
+
+### Users <a id="differences-1x-2-users"></a>
+
+Contacts have been renamed to users (same for groups). A contact does not
+only provide (custom) attributes and notification commands used for notifications,
+but is also used for authorization checks in Icinga 1.x.
+
+Icinga 2 changes that behavior and makes the user an attribute provider only.
+These attributes can be accessed using [runtime macros](03-monitoring-basics.md#runtime-macros)
+inside notification command definitions.
+
+In Icinga 2 notification commands are not directly associated with users.
+Instead the notification command is specified inside `Notification` objects next to
+user and user group relations.
+
+The `StatusDataWriter`, `IdoMySqlConnection` and `LivestatusListener` types will
+provide the contact and contactgroups attributes for services for compatibility
+reasons. These values are calculated from all services, their notifications,
+and their users.
+
+### Macros <a id="differences-1x-2-macros"></a>
+
+Various object attributes and runtime variables can be accessed as macros in
+commands in Icinga 1.x -- Icinga 2 supports all required [custom variables](03-monitoring-basics.md#custom-variables).
+
+#### Command Arguments <a id="differences-1x-2-command-arguments"></a>
+
+If you have previously used Icinga 1.x, you may already be familiar with
+user and argument definitions (e.g., `USER1` or `ARG1`). Unlike in Icinga 1.x
+the Icinga 2 custom variables may have arbitrary names and arguments are no
+longer specified in the `check_command` setting.
+
+In Icinga 1.x arguments are specified in the `check_command` attribute and
+are separated from the command name using an exclamation mark (`!`).
+
+Please check the migration hints for a detailed
+[migration example](23-migrating-from-icinga-1x.md#manual-config-migration-hints-check-command-arguments).
+
+> **Note**
+>
+> The Icinga 1.x feature named `Command Expander` does not work with Icinga 2.
+
+#### Environment Macros <a id="differences-1x-2-environment-macros"></a>
+
+The global configuration setting `enable_environment_macros` does not exist in
+Icinga 2.
+
+Macros exported into the [environment](03-monitoring-basics.md#command-environment-variables)
+can be set using the `env` attribute in command objects.
+
+#### Runtime Macros <a id="differences-1x-2-runtime-macros"></a>
+
+Icinga 2 requires an object specific namespace when accessing configuration
+and stateful runtime macros. Custom variables can be accessed directly.
+
+If a runtime macro from Icinga 1.x is not listed here, it is not supported
+by Icinga 2.
+
+Changes to user (contact) runtime macros
+
+  Icinga 1.x             | Icinga 2
+  -----------------------|----------------------
+  CONTACTNAME            | user.name
+  CONTACTALIAS           | user.display_name
+  CONTACTEMAIL           | user.email
+  CONTACTPAGER           | user.pager
+
+`CONTACTADDRESS*` is not supported but can be accessed as `$user.vars.address1$`
+if set.
+
+Changes to service runtime macros
+
+  Icinga 1.x             | Icinga 2
+  -----------------------|----------------------
+  SERVICEDESC            | service.name
+  SERVICEDISPLAYNAME     | service.display_name
+  SERVICECHECKCOMMAND    | service.check_command
+  SERVICESTATE           | service.state
+  SERVICESTATEID         | service.state_id
+  SERVICESTATETYPE       | service.state_type
+  SERVICEATTEMPT         | service.check_attempt
+  MAXSERVICEATTEMPT      | service.max_check_attempts
+  LASTSERVICESTATE       | service.last_state
+  LASTSERVICESTATEID     | service.last_state_id
+  LASTSERVICESTATETYPE   | service.last_state_type
+  LASTSERVICESTATECHANGE | service.last_state_change
+  SERVICEDOWNTIME 	 | service.downtime_depth
+  SERVICEDURATIONSEC     | service.duration_sec
+  SERVICELATENCY         | service.latency
+  SERVICEEXECUTIONTIME   | service.execution_time
+  SERVICEOUTPUT          | service.output
+  SERVICEPERFDATA        | service.perfdata
+  LASTSERVICECHECK       | service.last_check
+  SERVICENOTES           | service.notes
+  SERVICENOTESURL        | service.notes_url
+  SERVICEACTIONURL       | service.action_url
+
+
+Changes to host runtime macros
+
+  Icinga 1.x             | Icinga 2
+  -----------------------|----------------------
+  HOSTNAME               | host.name
+  HOSTADDRESS            | host.address
+  HOSTADDRESS6           | host.address6
+  HOSTDISPLAYNAME        | host.display_name
+  HOSTALIAS              | (use `host.display_name` instead)
+  HOSTCHECKCOMMAND       | host.check_command
+  HOSTSTATE              | host.state
+  HOSTSTATEID            | host.state_id
+  HOSTSTATETYPE          | host.state_type
+  HOSTATTEMPT            | host.check_attempt
+  MAXHOSTATTEMPT         | host.max_check_attempts
+  LASTHOSTSTATE          | host.last_state
+  LASTHOSTSTATEID        | host.last_state_id
+  LASTHOSTSTATETYPE      | host.last_state_type
+  LASTHOSTSTATECHANGE    | host.last_state_change
+  HOSTDOWNTIME  	 | host.downtime_depth
+  HOSTDURATIONSEC        | host.duration_sec
+  HOSTLATENCY            | host.latency
+  HOSTEXECUTIONTIME      | host.execution_time
+  HOSTOUTPUT             | host.output
+  HOSTPERFDATA           | host.perfdata
+  LASTHOSTCHECK          | host.last_check
+  HOSTNOTES              | host.notes
+  HOSTNOTESURL           | host.notes_url
+  HOSTACTIONURL          | host.action_url
+  TOTALSERVICES          | host.num_services
+  TOTALSERVICESOK        | host.num_services_ok
+  TOTALSERVICESWARNING   | host.num_services_warning
+  TOTALSERVICESUNKNOWN   | host.num_services_unknown
+  TOTALSERVICESCRITICAL  | host.num_services_critical
+
+Changes to command runtime macros
+
+  Icinga 1.x             | Icinga 2
+  -----------------------|----------------------
+  COMMANDNAME            | command.name
+
+Changes to notification runtime macros
+
+  Icinga 1.x             | Icinga 2
+  -----------------------|----------------------
+  NOTIFICATIONTYPE       | notification.type
+  NOTIFICATIONAUTHOR     | notification.author
+  NOTIFICATIONCOMMENT    | notification.comment
+  NOTIFICATIONAUTHORNAME | (use `notification.author`)
+  NOTIFICATIONAUTHORALIAS   | (use `notification.author`)
+
+
+Changes to global runtime macros:
+
+  Icinga 1.x             | Icinga 2
+  -----------------------|----------------------
+  TIMET                  | icinga.timet
+  LONGDATETIME           | icinga.long_date_time
+  SHORTDATETIME          | icinga.short_date_time
+  DATE                   | icinga.date
+  TIME                   | icinga.time
+  PROCESSSTARTTIME       | icinga.uptime
+
+Changes to global statistic macros:
+
+  Icinga 1.x                        | Icinga 2
+  ----------------------------------|----------------------
+  TOTALHOSTSUP                      | icinga.num_hosts_up
+  TOTALHOSTSDOWN                    | icinga.num_hosts_down
+  TOTALHOSTSUNREACHABLE             | icinga.num_hosts_unreachable
+  TOTALHOSTSDOWNUNHANDLED           | --
+  TOTALHOSTSUNREACHABLEUNHANDLED    | --
+  TOTALHOSTPROBLEMS                 | down
+  TOTALHOSTPROBLEMSUNHANDLED        | down-(downtime+acknowledged)
+  TOTALSERVICESOK                   | icinga.num_services_ok
+  TOTALSERVICESWARNING              | icinga.num_services_warning
+  TOTALSERVICESCRITICAL             | icinga.num_services_critical
+  TOTALSERVICESUNKNOWN              | icinga.num_services_unknown
+  TOTALSERVICESWARNINGUNHANDLED     | --
+  TOTALSERVICESCRITICALUNHANDLED    | --
+  TOTALSERVICESUNKNOWNUNHANDLED     | --
+  TOTALSERVICEPROBLEMS              | ok+warning+critical+unknown
+  TOTALSERVICEPROBLEMSUNHANDLED     | warning+critical+unknown-(downtime+acknowledged)
+
+
+
+
+### External Commands <a id="differences-1x-2-external-commands"></a>
+
+`CHANGE_CUSTOM_CONTACT_VAR` was renamed to `CHANGE_CUSTOM_USER_VAR`.
+
+The following external commands are not supported:
+
+```
+CHANGE_*MODATTR
+CHANGE_CONTACT_HOST_NOTIFICATION_TIMEPERIOD
+CHANGE_HOST_NOTIFICATION_TIMEPERIOD
+CHANGE_SVC_NOTIFICATION_TIMEPERIOD
+DEL_DOWNTIME_BY_HOSTGROUP_NAME
+DEL_DOWNTIME_BY_START_TIME_COMMENT
+DISABLE_ALL_NOTIFICATIONS_BEYOND_HOST
+DISABLE_CONTACT_HOST_NOTIFICATIONS
+DISABLE_CONTACT_SVC_NOTIFICATIONS
+DISABLE_CONTACTGROUP_HOST_NOTIFICATIONS
+DISABLE_CONTACTGROUP_SVC_NOTIFICATIONS
+DISABLE_FAILURE_PREDICTION
+DISABLE_HOST_AND_CHILD_NOTIFICATIONS
+DISABLE_HOST_FRESHNESS_CHECKS
+DISABLE_NOTIFICATIONS_EXPIRE_TIME
+DISABLE_SERVICE_FRESHNESS_CHECKS
+ENABLE_ALL_NOTIFICATIONS_BEYOND_HOST
+ENABLE_CONTACT_HOST_NOTIFICATIONS
+ENABLE_CONTACT_SVC_NOTIFICATIONS
+ENABLE_CONTACTGROUP_HOST_NOTIFICATIONS
+ENABLE_CONTACTGROUP_SVC_NOTIFICATIONS
+ENABLE_FAILURE_PREDICTION
+ENABLE_HOST_AND_CHILD_NOTIFICATIONS
+ENABLE_HOST_FRESHNESS_CHECKS
+ENABLE_SERVICE_FRESHNESS_CHECKS
+READ_STATE_INFORMATION
+SAVE_STATE_INFORMATION
+SET_HOST_NOTIFICATION_NUMBER
+SET_SVC_NOTIFICATION_NUMBER
+START_ACCEPTING_PASSIVE_HOST_CHECKS
+START_ACCEPTING_PASSIVE_SVC_CHECKS
+START_OBSESSING_OVER_HOST
+START_OBSESSING_OVER_HOST_CHECKS
+START_OBSESSING_OVER_SVC
+START_OBSESSING_OVER_SVC_CHECKS
+STOP_ACCEPTING_PASSIVE_HOST_CHECKS
+STOP_ACCEPTING_PASSIVE_SVC_CHECKS
+STOP_OBSESSING_OVER_HOST
+STOP_OBSESSING_OVER_HOST_CHECKS
+STOP_OBSESSING_OVER_SVC
+STOP_OBSESSING_OVER_SVC_CHECKS
+```
+
+### Asynchronous Event Execution <a id="differences-1x-2-async-event-execution"></a>
+
+Unlike Icinga 1.x, Icinga 2 does not block when it's waiting for a command
+being executed -- whether if it's a check, a notification, an event
+handler, a performance data writing update, etc. That way you'll
+recognize low to zero (check) latencies with Icinga 2.
+
+### Checks <a id="differences-1x-2-checks"></a>
+
+#### Check Output <a id="differences-1x-2-check-output"></a>
+
+Icinga 2 does not make a difference between `output` (first line) and
+`long_output` (remaining lines) like in Icinga 1.x. Performance Data is
+provided separately.
+
+There is no output length restriction as known from Icinga 1.x using an
+[8KB static buffer](https://docs.icinga.com/latest/en/pluginapi.html#outputlengthrestrictions).
+
+The `StatusDataWriter`, `IdoMysqlConnection` and `LivestatusListener` types
+split the raw output into `output` (first line) and `long_output` (remaining
+lines) for compatibility reasons.
+
+#### Initial State <a id="differences-1x-2-initial-state"></a>
+
+Icinga 1.x uses the `max_service_check_spread` setting to specify a timerange
+where the initial state checks must have happened. Icinga 2 will use the
+`retry_interval` setting instead and `check_interval` divided by 5 if
+`retry_interval` is not defined.
+
+### Comments <a id="differences-1x-2-comments"></a>
+
+Icinga 2 doesn't support non-persistent comments.
+
+### Commands <a id="differences-1x-2-commands"></a>
+
+Unlike in Icinga 1.x there are three different command types in Icinga 2:
+`CheckCommand`, `NotificationCommand`, and `EventCommand`.
+
+For example in Icinga 1.x it is possible to accidentally use a notification
+command as an event handler which might cause problems depending on which
+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.
+
+While Icinga 2 still supports the complete command line in command objects, it's
+recommended to use [command arguments](03-monitoring-basics.md#command-arguments)
+with optional and conditional command line parameters instead.
+
+It's also possible to define default argument values for the command itself
+which can be overridden by the host or service then.
+
+#### Command Timeouts <a id="differences-1x-2-commands-timeouts"></a>
+
+In Icinga 1.x there were two global options defining a host and service check
+timeout. This was essentially bad when there only was a couple of check plugins
+requiring some command timeouts to be extended.
+
+Icinga 2 allows you to specify the command timeout directly on the command. So,
+if your VMVware check plugin takes 15 minutes, [increase the timeout](09-object-types.md#objecttype-checkcommand)
+accordingly.
+
+
+### Groups <a id="differences-1x-2-groups"></a>
+
+In Icinga 2 hosts, services, and users are added to groups using the `groups`
+attribute in the object. The old way of listing all group members in the group's
+`members` attribute is available through `assign where` and `ignore where`
+expressions by using [group assign](03-monitoring-basics.md#group-assign-intro).
+
+```
+object Host "web-dev" {
+  import "generic-host"
+}
+
+object HostGroup "dev-hosts" {
+  display_name = "Dev Hosts"
+  assign where match("*-dev", host.name)
+}
+```
+
+#### Add Service to Hostgroup where Host is Member <a id="differences-1x-2-service-hostgroup-host"></a>
+
+In order to associate a service with all hosts in a host group the [apply](03-monitoring-basics.md#using-apply)
+keyword can be used:
+
+```
+apply Service "ping4" {
+  import "generic-service"
+
+  check_command = "ping4"
+
+  assign where "dev-hosts" in host.groups
+}
+```
+
+### Notifications <a id="differences-1x-2-notifications"></a>
+
+Notifications are a new object type in Icinga 2. Imagine the following
+notification configuration problem in Icinga 1.x:
+
+* Service A should notify contact X via SMS
+* Service B should notify contact X via Mail
+* Service C should notify contact Y via Mail and SMS
+* Contact X and Y should also be used for authorization
+
+The only way achieving a semi-clean solution is to
+
+* Create contact X-sms, set service_notification_command for sms, assign contact
+  to service A
+* Create contact X-mail, set service_notification_command for mail, assign
+  contact to service B
+* Create contact Y, set service_notification_command for sms and mail, assign
+  contact to service C
+* Create contact X without notification commands, assign to service A and B
+
+Basically you are required to create duplicated contacts for either each
+notification method or used for authorization only.
+
+Icinga 2 attempts to solve that problem in this way
+
+* Create user X, set SMS and Mail attributes, used for authorization
+* Create user Y, set SMS and Mail attributes, used for authorization
+* Create notification A-SMS, set command for sms, add user X,
+  assign notification A-SMS to service A
+* Create notification B-Mail, set command for mail, add user X,
+  assign notification Mail to service B
+* Create notification C-SMS, set command for sms, add user Y,
+  assign notification C-SMS to service C
+* Create notification C-Mail, set command for mail, add user Y,
+  assign notification C-Mail to service C
+
+Previously in Icinga 1.x it looked like this:
+
+```
+service -> (contact, contactgroup) -> notification command
+```
+
+In Icinga 2 it will look like this:
+
+```
+Service -> Notification -> NotificationCommand
+                        -> User, UserGroup
+```
+
+#### Escalations <a id="differences-1x-2-escalations"></a>
+
+Escalations in Icinga 1.x require a separated object matching on existing
+objects. Escalations happen between a defined start and end time which is
+calculated from the notification_interval:
+
+```
+start = notification start + (notification_interval * first_notification)
+end = notification start + (notification_interval * last_notification)
+```
+
+In theory first_notification and last_notification can be set to readable
+numbers. In practice users are manipulating those attributes in combination
+with notification_interval in order to get a start and end time.
+
+In Icinga 2 the notification object can be used as notification escalation
+if the start and end times are defined within the 'times' attribute using
+duration literals (e.g. 30m).
+
+The Icinga 2 escalation does not replace the current running notification.
+In Icinga 1.x it's required to copy the contacts from the service notification
+to the escalation to guarantee the normal notifications once an escalation
+happens.
+That's not necessary with Icinga 2 only requiring an additional notification
+object for the escalation itself.
+
+#### Notification Options <a id="differences-1x-2-notification-options"></a>
+
+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
+
+```
+notification_options w,u,c,r,f,s
+
+states = [ Warning, Unknown, Critical ]
+types = [ Problem, Recovery, FlappingStart, FlappingEnd, DowntimeStart, DowntimeEnd, DowntimeRemoved ]
+```
+
+Icinga 2 adds more fine-grained type filters for acknowledgements, downtime,
+and flapping type (start, end, ...).
+
+### Dependencies and Parents <a id="differences-1x-2-dependencies-parents"></a>
+
+In Icinga 1.x it's possible to define host parents to determine network reachability
+and keep a host's state unreachable rather than down.
+Furthermore there are host and service dependencies preventing unnecessary checks and
+notifications. A host must not depend on a service, and vice versa. All dependencies
+are configured as separate objects and cannot be set directly on the host or service
+object.
+
+A service can now depend on a host, and vice versa. A service has an implicit dependency
+(parent) to its host. A host to host dependency acts implicitly as host parent relation.
+
+The former `host_name` and `dependent_host_name` have been renamed to `parent_host_name`
+and `child_host_name` (same for the service attribute). When using apply rules the
+child attributes may be omitted.
+
+For detailed examples on how to use the dependencies please check the [dependencies](03-monitoring-basics.md#dependencies)
+chapter.
+
+Dependencies can be applied to hosts or services using the [apply rules](17-language-reference.md#apply).
+
+The `StatusDataWriter`, `IdoMysqlConnection` and `LivestatusListener` types
+support the Icinga 1.x schema with dependencies and parent attributes for
+compatibility reasons.
+
+### Flapping <a id="differences-1x-2-flapping"></a>
+
+The Icinga 1.x flapping detection uses the last 21 states of a service. This
+value is hardcoded and cannot be changed. The algorithm on determining a flapping state
+is as follows:
+
+```
+flapping value = (number of actual state changes / number of possible state changes)
+```
+
+The flapping value is then compared to the low and high flapping thresholds.
+
+The algorithm used in Icinga 2 does not store the past states but calculates the flapping
+threshold from a single value based on counters and half-life values. Icinga 2 compares
+the value with a single flapping threshold configuration attribute.
+
+### Check Result Freshness <a id="differences-1x-2-check-result-freshness"></a>
+
+Freshness of check results must be enabled explicitly in Icinga 1.x. The attribute
+`freshness_threshold` defines the threshold in seconds. Once the threshold is triggered, an
+active freshness check is executed defined by the `check_command` attribute. Both check
+methods (active and passive) use the same freshness check method.
+
+In Icinga 2 active check freshness is determined by the `check_interval` attribute and no
+incoming check results in that period of time (last check + check interval). Passive check
+freshness is calculated from the `check_interval` attribute if set. There is no extra
+`freshness_threshold` attribute in Icinga 2. If the freshness checks are invalid, a new
+service check is forced.
+
+### Real Reload <a id="differences-1x-2-real-reload"></a>
+
+In Nagios / Icinga 1.x a daemon reload does the following:
+
+* receive reload signal SIGHUP
+* stop all events (checks, notifications, etc.)
+* read the configuration from disk and validate all config objects in a single threaded fashion
+* validation NOT ok: stop the daemon (cannot restore old config state)
+* validation ok: start with new objects, dump status.dat / ido
+
+Unlike Icinga 1.x the Icinga 2 daemon reload does not block any event
+execution during config validation:
+
+* receive reload signal SIGHUP
+* fork a child process, start configuration validation in parallel work queues
+* parent process continues with old configuration objects and the event scheduling
+(doing checks, replicating cluster events, triggering alert notifications, etc.)
+* validation NOT ok: child process terminates, parent process continues with old configuration state
+(this is **essential** for the [cluster config synchronisation](06-distributed-monitoring.md#distributed-monitoring-top-down-config-sync))
+* validation ok: child process signals parent process to terminate and save its current state
+(all events until now) into the icinga2 state file
+* parent process shuts down writing icinga2.state file
+* child process waits for parent process gone, reads the icinga2 state file and synchronizes all historical and status data
+* child becomes the new session leader
+
+The DB IDO configuration dump and status/historical event updates use a queue
+not blocking event execution. Same goes for any other enabled feature.
+The configuration validation itself runs in parallel allowing fast verification checks.
+
+That way your monitoring does not stop during a configuration reload.
+
+
+### State Retention <a id="differences-1x-2-state-retention"></a>
+
+Icinga 1.x uses the `retention.dat` file to save its state in order to be able
+to reload it after a restart. In Icinga 2 this file is called `icinga2.state`.
+
+The format is **not** compatible with Icinga 1.x.
+
+### Logging <a id="differences-1x-2-logging"></a>
+
+Icinga 1.x supports syslog facilities and writes its own `icinga.log` log file
+and archives. These logs are used in Icinga 1.x to generate
+historical reports.
+
+Icinga 2 compat library provides the CompatLogger object which writes the icinga.log and archive
+in Icinga 1.x format in order to stay compatible with addons.
+
+The native Icinga 2 logging facilities are split into three configuration objects: SyslogLogger,
+FileLogger, StreamLogger. Each of them has their own severity and target configuration.
+
+The Icinga 2 daemon log does not log any alerts but is considered an application log only.
+
+### Broker Modules and Features <a id="differences-1x-2-broker-modules-features"></a>
+
+Icinga 1.x broker modules are incompatible with Icinga 2.
+
+In order to provide compatibility with Icinga 1.x the functionality of several
+popular broker modules was implemented for Icinga 2:
+
+* IDOUtils
+* Livestatus
+* Cluster (allows for high availability and load balancing)
+
+
+### Distributed Monitoring <a id="differences-1x-2-distributed-monitoring"></a>
+
+Icinga 1.x uses the native "obsess over host/service" method which requires the NSCA addon
+passing the slave's check results passively onto the master's external command pipe.
+While this method may be used for check load distribution, it does not provide any configuration
+distribution out-of-the-box. Furthermore comments, downtimes, and other stateful runtime data is
+not synced between the master and slave nodes. There are addons available solving the check
+and configuration distribution problems Icinga 1.x distributed monitoring currently suffers from.
+
+Icinga 2 implements a new built-in
+[distributed monitoring architecture](06-distributed-monitoring.md#distributed-monitoring-scenarios),
+including config and check distribution, IPv4/IPv6 support, TLS certificates and zone support for DMZ.
+High Availability and load balancing are also part of the Icinga 2 Cluster feature, next to local replay
+logs on connection loss ensuring that the event history is kept in sync.