summaryrefslogtreecommitdiffstats
path: root/doc/23-migrating-from-icinga-1x.md
diff options
context:
space:
mode:
Diffstat (limited to 'doc/23-migrating-from-icinga-1x.md')
-rw-r--r--doc/23-migrating-from-icinga-1x.md1585
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.