1 # <a id="migration"></a> Migration from Icinga 1.x
3 ## <a id="configuration-migration"></a> Configuration Migration
5 The Icinga 2 configuration format introduces plenty of behavioural changes. In
6 order to ease migration from Icinga 1.x, Icinga 2 ships its own config migration
9 ### <a id="configuration-migration-script"></a> Configuration Migration Script
11 A standalone configuration migration script is available at
12 https://github.com/Icinga/icinga2-migration. All further
13 details on the command line parameters are documented there too.
15 This script will be merged back upstream into the Icinga Web 2 CLI once there
16 is a final stable release.
18 Please note that not each configuration detail, trick or attribute will work.
19 Some specific migration steps will be still required to be done manually,
20 especially if you want to preserve your existing file layout, or any other
21 object specific policies.
23 If you encounter a bug, please open an issue at https://dev.icinga.org.
25 ### <a id="manual-config-migration"></a> Manual Config Migration
27 For a long-term migration of your configuration you should consider re-creating
28 your configuration based on the proposed Icinga 2 configuration paradigm.
30 Please read the [next chapter](9-migrating-from-icinga-1x.md#differences-1x-2) to find out more about the differences
33 ### <a id="manual-config-migration-hints"></a> Manual Config Migration Hints
35 These hints should provide you with enough details for manually migrating your configuration,
36 or to adapt your configuration export tool to dump Icinga 2 configuration instead of
37 Icinga 1.x configuration.
39 The examples are taken from Icinga 1.x test and production environments and converted
40 straight into a possible Icinga 2 format. If you found a different strategy, send a patch!
42 If you require in-depth explanations, please check the [next chapter](9-migrating-from-icinga-1x.md#differences-1x-2).
44 #### <a id="manual-config-migration-hints-Intervals"></a> Manual Config Migration Hints for Intervals
46 By default all intervals without any duration literal are interpreted as seconds. Therefore
47 all existing Icinga 1.x `*_interval` attributes require an additional `m` duration literal.
52 service_description service1
54 check_command test_customvar
62 object Service "service1" {
63 import "generic-service"
64 host_name = "localhost1"
65 check_command = "test_customvar"
70 #### <a id="manual-config-migration-hints-services"></a> Manual Config Migration Hints for Services
72 If you have used the `host_name` attribute in Icinga 1.x with one or more host names this service
73 belongs to, you can migrate this to the [apply rules](3-monitoring-basics.md#using-apply) syntax.
78 service_description service1
79 host_name localhost1,localhost2
80 check_command test_check
86 apply Service "service1" {
87 import "generic-service"
88 check_command = "test_check"
90 assign where host.name in [ "localhost1", "localhost2" ]
93 In Icinga 1.x you would have organized your services with hostgroups using the `hostgroup_name` attribute
94 like the following example:
97 service_description servicewithhostgroups
98 hostgroup_name hostgroup1,hostgroup3
99 check_command test_check
103 Using Icinga 2 you can migrate this to the [apply rules](3-monitoring-basics.md#using-apply) syntax:
105 apply Service "servicewithhostgroups" {
106 import "generic-service"
107 check_command = "test_check"
109 assign where "hostgroup1" in host.groups
110 assign where "hostgroup3" in host.groups
114 #### <a id="manual-config-migration-hints-group-members"></a> Manual Config Migration Hints for Group Members
116 The Icinga 1.x hostgroup `hg1` has two members `host1` and `host2`. The hostgroup `hg2` has `host3` as
117 a member and includes all members of the `hg1` hostgroup.
127 hostgroup_members hg1
130 This can be migrated to Icinga 2 and [using group assign](10-language-reference.md#group-assign). The additional nested hostgroup
131 `hg1` is included into `hg2` with the `groups` attribute.
134 object HostGroup "hg1" {
135 assign where host.name in [ "host1", "host2" ]
138 object HostGroup "hg2" {
140 assign where host.name == "host3"
143 These assign rules can be applied for all groups: `HostGroup`, `ServiceGroup` and `UserGroup`
144 (requires renaming from `contactgroup`).
148 > Define custom attributes and assign/ignore members based on these attribute pattern matches.
152 #### <a id="manual-config-migration-hints-check-command-arguments"></a> Manual Config Migration Hints for Check Command Arguments
154 Host and service check command arguments are separated by a `!` in Icinga 1.x. Their order is important and they
155 are referenced as `$ARGn$` where `n` is the argument counter.
159 command_line $USER1$/check_ping -H $HOSTADDRESS$ -w $ARG1$ -c $ARG2$ -p 5
165 service_description my-ping
166 check_command my-ping-check!100.0,20%!500.0,60%
169 While you could manually migrate this like (please note the new generic command arguments and default argument values!):
171 object CheckCommand "my-ping-check" {
172 import "plugin-check-command"
175 PluginDir + "/check_ping", "-4"
179 "-H" = "$ping_address$"
180 "-w" = "$ping_wrta$,$ping_wpl$%"
181 "-c" = "$ping_crta$,$ping_cpl$%"
182 "-p" = "$ping_packets$"
183 "-t" = "$ping_timeout$"
186 vars.ping_address = "$address$"
193 object Service "my-ping" {
194 import "generic-service"
195 host_name = "my-server"
196 check_command = "my-ping-check"
204 There also is a quick programmatical workaround for this (example exported from LConf). Define a generic
205 check command importing the basic template, and also setting the `$USER1$` macro. Assign it to the global
206 `PluginDir` constant.
208 template CheckCommand "generic-check-command" {
209 import "plugin-check-command"
211 vars.USER1 = PluginDir
214 Every check command importing the `generic-check-command` template will now automatically set the new plugin
215 directory - one major problem solved.
217 For the check command it is required to
219 * Escape all double quotes with an additional `\`.
220 * Replace all [runtime macros](9-migrating-from-icinga-1x.md#manual-config-migration-hints-runtime-macros), e.g. `$HOSTADDRESS$` with `$address$`.
221 * Replace [custom variable macros](9-migrating-from-icinga-1x.md#manual-config-migration-hints-runtime-custom-attributes) if any.
222 * Keep `$ARGn$` macros.
224 The final check command looks like this in Icinga2:
226 object CheckCommand "ping4" {
227 import "generic-check-command"
229 command = "$USER1$/check_ping -H $address$ -w $ARG1$ -c $ARG2$ -p 5"
232 The service object will now set the command arguments as `ARGn` custom attributes.
234 check_command ping4!100.0,20%!500.0,60%
236 This command line can be split by the `!` separator into
238 * `ping4` (command name, keep it for Icinga 2)
239 * `100.0,20%` as `vars.ARG1`
240 * `500.0,60%` as `vars.ARG2`
242 The final service could look like:
244 apply Service "ping4" {
245 import "generic-service"
247 check_command = "ping4"
249 vars.ARG1 = "100.0,20%"
250 vars.ARG2 = "500.0,60%"
252 assign where host.name == "my-server"
255 That way the old command arguments fashion can be applied for Icinga 2, although it's not recommended.
258 #### <a id="manual-config-migration-hints-runtime-macros"></a> Manual Config Migration Hints for Runtime Macros
260 Runtime macros have been renamed. A detailed comparison table can be found [here](9-migrating-from-icinga-1x.md#differences-1x-2-runtime-macros).
262 For example, accessing the service check output looks like the following in Icinga 1.x:
266 In Icinga 2 you will need to write:
271 #### <a id="manual-config-migration-hints-runtime-custom-attributes"></a> Manual Config Migration Hints for Runtime Custom Attributes
273 Custom variables from Icinga 1.x are available as Icinga 2 custom attributes.
276 command_name test_customvar
277 command_line echo "Host CV: $_HOSTCVTEST$ Service CV: $_SERVICECVTEST$\n"
282 check_command test_customvar
284 _CVTEST host cv value
288 service_description service1
290 check_command test_customvar
292 _CVTEST service cv value
295 Can be written as the following in Icinga 2:
297 object CheckCommand "test_customvar" {
298 import "plugin-check-command"
299 command = "echo "Host CV: $host.vars.CVTEST$ Service CV: $service.vars.CVTEST$\n""
302 object Host "localhost1" {
303 import "generic-host"
304 check_command = "test_customvar"
305 vars.CVTEST = "host cv value"
308 object Service "service1" {
309 host_name = "localhost1"
310 check_command = "test_customvar"
311 vars.CVTEST = "service cv value"
314 If you are just defining `$CVTEST$` in your command definition its value depends on the
315 execution scope - the host check command will fetch the host attribute value of `vars.CVTEST`
316 while the service check command resolves its value to the service attribute attribute `vars.CVTEST`.
318 #### <a id="manual-config-migration-hints-contacts-users"></a> Manual Config Migration Hints for Contacts (Users)
320 Contacts in Icinga 1.x act as users in Icinga 2, but do not have any notification commands specified.
321 This migration part is explained in the [next chapter](9-migrating-from-icinga-1x.md#manual-config-migration-hints-notifications).
324 contact_name testconfig-user
326 alias Icinga Test User
327 service_notification_options c,f,s,u
328 email icinga@localhost
331 The `service_notification_options` can be [mapped](9-migrating-from-icinga-1x.md#manual-config-migration-hints-notification-filters)
332 into generic `state` and `type` filters, if additional notification filtering is required. `alias` gets
333 renamed to `display_name`.
335 object User "testconfig-user" {
336 import "generic-user"
337 display_name = "Icinga Test User"
338 email = "icinga@localhost"
341 This user can be put into usergroups (former contactgroups) or referenced in newly migration notification
344 #### <a id="manual-config-migration-hints-notifications"></a> Manual Config Migration Hints for Notifications
346 If you are migrating a host or service notification, you'll need to extract the following information from
347 your existing Icinga 1.x configuration objects
349 * host/service attribute `contacts` and `contact_groups`
350 * host/service attribute `notification_options`
351 * host/service attribute `notification_period`
352 * host/service attribute `notification_interval`
354 The clean approach is to refactor your current contacts and their notification command methods into a
357 * host or service has a notification type (for example mail)
358 * which contacts (users) are notified by mail?
359 * do the notification filters, periods, intervals still apply for them? (do a cleanup during migration)
360 * assign users and groups to these notifications
361 * Redesign the notifications into generic [apply rules](3-monitoring-basics.md#using-apply-notifications)
364 The ugly workaround solution could look like this:
366 Extract all contacts from the remaining groups, and create a unique list. This is required for determining
367 the host and service notification commands involved.
369 * contact attributes `host_notification_commands` and `service_notification_commands` (can be a comma separated list)
370 * get the command line for each notification command and store them for later
371 * create a new notification name and command name
373 Generate a new notification object based on these values. Import the generic template based on the type (`host` or `service`).
374 Assign it to the host or service and set the newly generated notification command name as `command` attribute.
376 object Notification "<notificationname>" {
377 import "mail-host-notification"
378 host_name = "<thishostname>"
379 command = "<notificationcommandname>"
382 Convert the `notification_options` attribute from Icinga 1.x to Icinga 2 `states` and `types`. Details
383 [here](9-migrating-from-icinga-1x.md#manual-config-migration-hints-notification-filters). Add the notification period.
385 states = [ OK, Warning, Critical ]
386 types = [ Recovery, Problem, Custom ]
389 The current contact acts as `users` attribute.
391 users = [ "<contactwithnotificationcommand>" ]
394 Do this in a loop for all notification commands (depending if host or service contact). Once done, dump the
395 collected notification commands.
397 The result of this migration are lots of unnecessary notification objects and commands but it will unroll
398 the Icinga 1.x logic into the revamped Icinga 2 notification object schema. If you are looking for code
399 examples, try [LConf](https://www.netways.org).
403 #### <a id="manual-config-migration-hints-notification-filters"></a> Manual Config Migration Hints for Notification Filters
405 Icinga 1.x defines all notification filters in an attribute called `notification_options`. Using Icinga 2 you will
406 have to split these values into the `states` and `types` attributes.
410 > `Recovery` type requires the `Ok` state.
411 > `Custom` and `Problem` should always be set as `type` filter.
413 Icinga 1.x option | Icinga 2 state | Icinga 2 type
414 ----------------------|-----------------------|-------------------
415 o | OK (Up for hosts) |
416 w | Warning | Problem
417 c | Critical | Problem
418 u | Unknown | Problem
420 s | . | DowntimeStart / DowntimeEnd / DowntimeRemoved
422 f | . | FlappingStart / FlappingEnd
423 n | 0 (none) | 0 (none)
428 #### <a id="manual-config-migration-hints-escalations"></a> Manual Config Migration Hints for Escalations
430 Escalations in Icinga 1.x are a bit tricky. By default service escalations can be applied to hosts and
431 hostgroups and require a defined service object.
433 The following example applies a service escalation to the service `dep_svc01` and all hosts in the `hg_svcdep2`
434 hostgroup. The default `notification_interval` is set to `10` minutes notifying the `cg_admin` contact.
435 After 20 minutes (`10*2`, notification_interval * first_notification) the notification is escalated to the
436 `cg_ops` contactgroup until 60 minutes (`10*6`) have passed.
439 service_description dep_svc01
440 host_name dep_hostsvc01,dep_hostsvc03
443 notification_interval 10
444 contact_groups cg_admin
448 hostgroup_name hg_svcdep2
449 members dep_hostsvc03
452 # with hostgroup_name and service_description
453 define serviceescalation {
454 hostgroup_name hg_svcdep2
455 service_description dep_svc01
458 contact_groups cg_ops
461 In Icinga 2 the service and hostgroup definition will look quite the same. Save the `notification_interval`
462 and `contact_groups` attribute for an additional notification.
464 apply Service "dep_svc01" {
465 import "generic-service"
467 check_command = "test2"
469 assign where host.name == "dep_hostsvc01"
470 assign where host.name == "dep_hostsvc03"
473 object HostGroup "hg_svcdep2" {
474 assign where host.name == "dep_hostsvc03"
477 apply Notification "email" to Service {
478 import "service-mail-notification"
481 user_groups = [ "cg_admin" ]
483 assign where service.name == "dep_svc01" && (host.name == "dep_hostsvc01" || host.name == "dep_hostsvc03")
486 Calculate the begin and end time for the newly created escalation notification:
488 * begin = first_notification * notification_interval = 2 * 10m = 20m
489 * end = last_notification * notification_interval = 6 * 10m = 60m = 1h
491 Assign the notification escalation to the service `dep_svc01` on all hosts in the hostgroup `hg_svcdep2`.
493 apply Notification "email-escalation" to Service {
494 import "service-mail-notification"
497 user_groups = [ "cg_ops" ]
504 assign where service.name == "dep_svc01" && "hg_svcdep2" in host.groups
507 The assign rule could be made more generic and the notification be applied to more than
508 just this service belonging to hosts in the matched hostgroup.
513 > When the notification is escalated, Icinga 1.x suppresses notifications to the default contacts.
514 > In Icinga 2 an escalation is an additional notification with a defined begin and end time. The
515 > `email` notification will continue as normal.
519 #### <a id="manual-config-migration-hints-dependencies"></a> Manual Config Migration Hints for Dependencies
521 There are some dependency examples already in the [basics chapter](3-monitoring-basics.md#dependencies). Dependencies in
522 Icinga 1.x can be confusing in terms of which host/service is the parent and which host/service acts
525 While Icinga 1.x defines `notification_failure_criteria` and `execution_failure_criteria` as dependency
526 filters, this behaviour has changed in Icinga 2. There is no 1:1 migration but generally speaking
527 the state filter defined in the `execution_failure_criteria` defines the Icinga 2 `state` attribute.
528 If the state filter matches, you can define whether to disable checks and notifications or not.
530 The following example describes service dependencies. If you migrate from Icinga 1.x you will only
531 want to use the classic `Host-to-Host` and `Service-to-Service` dependency relationships.
534 service_description dep_svc01
535 hostgroup_name hg_svcdep1
541 service_description dep_svc02
542 hostgroup_name hg_svcdep2
548 hostgroup_name hg_svcdep2
553 use linux-server-template
558 # with hostgroup_name and service_description
559 define servicedependency {
561 dependent_hostgroup_name hg_svcdep2
562 service_description dep_svc01
563 dependent_service_description *
564 execution_failure_criteria u,c
565 notification_failure_criteria w,u,c
569 Map the dependency attributes accordingly.
571 Icinga 1.x | Icinga 2
572 ----------------------|---------------------
573 host_name | parent_host_name
574 dependent_host_name | child_host_name (used in assign/ignore)
575 dependent_hostgroup_name | all child hosts in group (used in assign/ignore)
576 service_description | parent_service_name
577 dependent_service_description | child_service_name (used in assign/ignore)
579 And migrate the host and services.
581 object Host "host1" {
582 import "linux-server-template"
583 address = "192.168.1.10"
586 object HostGroup "hg_svcdep2" {
587 assign where host.name == "host2"
590 apply Service "dep_svc01" {
591 import "generic-service"
592 check_command = "test2"
594 assign where "hp_svcdep1" in host.groups
597 apply Service "dep_svc02" {
598 import "generic-service"
599 check_command = "test2"
601 assign where "hp_svcdep2" in host.groups
604 When it comes to the `execution_failure_criteria` and `notification_failure_criteria` attribute migration,
605 you will need to map the most common values, in this example `u,c` (`Unknown` and `Critical` will cause the
606 dependency to fail). Therefore the `Dependency` should be ok on Ok and Warning. `inherits_parents` is always
609 apply Dependency "all-svc-for-hg-hg_svcdep2-on-host1-dep_svc01" to Service {
610 parent_host_name = "host1"
611 parent_service_name = "dep_svc01"
613 states = [ Ok, Warning ]
614 disable_checks = true
615 disable_notifications = true
617 assign where "hg_svcdep2" in host.groups
620 Host dependencies are explained in the [next chapter](9-migrating-from-icinga-1x.md#manual-config-migration-hints-host-parents).
624 #### <a id="manual-config-migration-hints-host-parents"></a> Manual Config Migration Hints for Host Parents
626 Host parents from Icinga 1.x are migrated into `Host-to-Host` dependencies in Icinga 2.
628 The following example defines the `vmware-master` host as parent host for the guest
629 virtual machines `vmware-vm1` and `vmware-vm2`.
631 By default all hosts in the hostgroup `vmware` should get the parent assigned. This isn't really
632 solvable with Icinga 1.x parents, but only with host dependencies.
635 use linux-server-template
636 host_name vmware-master
642 use linux-server-template
646 parents vmware-master
650 use linux-server-template
654 parents vmware-master
657 By default all hosts in the hostgroup `vmware` should get the parent assigned (but not the `vmware-master`
658 host itself). This isn't really solvable with Icinga 1.x parents, but only with host dependencies as shown
661 define hostdependency {
662 dependent_hostgroup_name vmware
663 dependent_host_name !vmware-master
664 host_name vmware-master
666 notification_failure_criteria d,u
667 execution_failure_criteria d,u
668 dependency_period testconfig-24x7
671 When migrating to Icinga 2, the parents must be changed to a newly created host dependency.
674 Map the following attributes
676 Icinga 1.x | Icinga 2
677 ----------------------|---------------------
678 host_name | parent_host_name
679 dependent_host_name | child_host_name (used in assign/ignore)
680 dependent_hostgroup_name | all child hosts in group (used in assign/ignore)
682 The Icinga 2 configuration looks like this:
685 object Host "vmware-master" {
686 import "linux-server-template"
687 groups += [ "vmware" ]
688 address = "192.168.1.10"
689 vars.is_vmware_master = true
692 object Host "vmware-vm1" {
693 import "linux-server-template"
694 groups += [ "vmware" ]
695 address = "192.168.27.1"
698 object Host "vmware-vm2" {
699 import "linux-server-template"
700 groups += [ "vmware" ]
701 address = "192.168.28.1"
704 apply Dependency "vmware-master" to Host {
705 parent_host_name = "vmware-master"
707 assign where "vmware" in host.groups
708 ignore where host.vars.is_vmware_master
709 ignore where host.name == "vmware-master"
712 For easier identification you could add the `vars.is_vmware_master` attribute to the `vmware-master`
713 host and let the dependency ignore that instead of the hardcoded host name. That's different
714 to the Icinga 1.x example and a best practice hint only.
717 #### <a id="manual-config-migration-hints-distributed-setup"></a> Manual Config Migration Hints for Distributed Setups
719 * Icinga 2 does not use active/passive instances calling OSCP commands and requiring the NSCA
720 daemon for passing check results between instances.
721 * Icinga 2 does not support any 1.x NEB addons for check load distribution
723 * If your current setup consists of instances distributing the check load, you should consider
724 building a [load distribution](4-monitoring-remote-systems.md#cluster-scenarios-load-distribution) setup with Icinga 2.
725 * If your current setup includes active/passive clustering with external tools like Pacemaker/DRBD
726 consider the [High Availability](4-monitoring-remote-systems.md#cluster-scenarios-high-availability) setup.
727 * If you have build your own custom configuration deployment and check result collecting mechanism
728 you should re-design your setup and re-evaluate your requirements, and how they may be fulfilled
729 using the Icinga 2 cluster capabilities.
732 ## <a id="differences-1x-2"></a> Differences between Icinga 1.x and 2
734 ### <a id="differences-1x-2-configuration-format"></a> Configuration Format
736 Icinga 1.x supports two configuration formats: key-value-based settings in the
737 `icinga.cfg` configuration file and object-based in included files (`cfg_dir`,
738 `cfg_file`). The path to the `icinga.cfg` configuration file must be passed to
739 the Icinga daemon at startup.
741 enable_notifications=1
744 notifications_enabled 0
747 Icinga 2 supports objects and (global) variables, but does not make a difference
748 if it's the main configuration file, or any included file.
750 const EnableNotifications = true
752 object Service "test" {
753 enable_notifications = 0
756 #### <a id="differences-1x-2-sample-configuration-itl"></a> Sample Configuration and ITL
758 While Icinga 1.x ships sample configuration and templates spread in various
759 object files, Icinga 2 moves all templates into the Icinga Template Library (ITL)
760 and includes them in the sample configuration.
762 Additional plugin check commands are shipped with Icinga 2 as well.
764 The ITL will be updated on every release and should not be edited by the user.
766 There are still generic templates available for your convenience which may or may
767 not be re-used in your configuration. For instance, `generic-service` includes
768 all required attributes except `check_command` for a service.
770 Sample configuration files are located in the `conf.d/` directory which is
771 included in `icinga2.conf` by default.
773 ### <a id="differences-1x-2-main-config"></a> Main Config File
775 In Icinga 1.x there are many global configuration settings available in `icinga.cfg`.
776 Icinga 2 only uses a small set of [global constants](10-language-reference.md#constants) allowing
777 you to specify certain different setting such as the `NodeName` in a cluster scenario.
779 Aside from that, the [icinga2.conf](2-getting-started.md#icinga2-conf) should take care of including
780 global constants, enabled [features](5-cli-commands.md#features) and the object configuration.
782 ### <a id="differences-1x-2-include-files-dirs"></a> Include Files and Directories
784 In Icinga 1.x the `icinga.cfg` file contains `cfg_file` and `cfg_dir`
785 directives. The `cfg_dir` directive recursively includes all files with a `.cfg`
786 suffix in the given directory. Only absolute paths may be used. The `cfg_file`
787 and `cfg_dir` directives can include the same file twice which leads to
788 configuration errors in Icinga 1.x.
790 cfg_file=/etc/icinga/objects/commands.cfg
791 cfg_dir=/etc/icinga/objects
793 Icinga 2 supports wildcard includes and relative paths, e.g. for including
794 `conf.d/*.conf` in the same directory.
796 include "conf.d/*.conf"
798 If you want to include files and directories recursively, you need to define
799 a separate option and add the directory and an optional pattern.
801 include_recursive "conf.d"
803 A global search path for includes is available for advanced features like
804 the Icinga Template Library (ITL) or additional monitoring plugins check
805 command configuration.
810 By convention the `.conf` suffix is used for Icinga 2 configuration files.
812 ### <a id="differences-1x-2-resource-file-global-macros"></a> Resource File and Global Macros
814 Global macros such as for the plugin directory, usernames and passwords can be
815 set in the `resource.cfg` configuration file in Icinga 1.x. By convention the
816 `USER1` macro is used to define the directory for the plugins.
818 Icinga 2 uses global constants instead. In the default config these are
819 set in the `constants.conf` configuration file:
822 * This file defines global constants which can be used in
823 * the other configuration files. At a minimum the
824 * PluginDir constant should be defined.
827 const PluginDir = "/usr/lib/nagios/plugins"
829 [Global macros](10-language-reference.md#constants) can only be defined once. Trying to modify a
830 global constant will result in an error.
832 ### <a id="differences-1x-2-configuration-comments"></a> Configuration Comments
834 In Icinga 1.x comments are made using a leading hash (`#`) or a semi-colon (`;`)
837 In Icinga 2 comments can either be encapsulated by `/*` and `*/` (allowing for
838 multi-line comments) or starting with two slashes (`//`). A leading hash (`#`)
841 ### <a id="differences-1x-2-object-names"></a> Object names
843 Object names must not contain an exclamation mark (`!`). Use the `display_name` attribute
844 to specify user-friendly names which should be shown in UIs (supported by
845 Icinga 1.x Classic UI and Web).
847 Object names are not specified using attributes (e.g. `service_description` for
848 services) like in Icinga 1.x but directly after their type definition.
852 service_description ping4
855 object Service "ping4" {
856 host_name = "localhost"
859 ### <a id="differences-1x-2-templates"></a> Templates
861 In Icinga 1.x templates are identified using the `register 0` setting. Icinga 2
862 uses the `template` identifier:
864 template Service "ping4-template" { }
866 Icinga 1.x objects inherit from templates using the `use` attribute.
867 Icinga 2 uses the keyword `import` with template names in double quotes.
870 service_description testservice
871 use tmpl1,tmpl2,tmpl3
874 object Service "testservice" {
880 The last template overrides previously set values.
882 ### <a id="differences-1x-2-object-attributes"></a> Object attributes
884 Icinga 1.x separates attribute and value pairs with whitespaces/tabs. Icinga 2
885 requires an equal sign (=) between them.
891 object Service "test" {
895 Please note that the default time value is seconds, if no duration literal
896 is given. `check_interval = 5` behaves the same as `check_interval = 5s`.
898 All strings require double quotes in Icinga 2. Therefore a double quote
899 must be escaped by a backslash (e.g. in command line).
900 If an attribute identifier starts with a number, it must be enclosed
901 in double quotes as well.
903 #### <a id="differences-1x-2-alias-display-name"></a> Alias vs. Display Name
905 In Icinga 1.x a host can have an `alias` and a `display_name` attribute used
906 for a more descriptive name. A service only can have a `display_name` attribute.
907 The `alias` is used for group, timeperiod, etc. objects too.
908 Icinga 2 only supports the `display_name` attribute which is also taken into
909 account by Icinga web interfaces.
911 ### <a id="differences-1x-2-custom-attributes"></a> Custom Attributes
913 Icinga 2 allows you to define custom attributes in the `vars` dictionary.
914 The `notes`, `notes_url`, `action_url`, `icon_image`, `icon_image_alt`
915 attributes for host and service objects are still available in Icinga 2.
917 `2d_coords` and `statusmap_image` are not supported in Icinga 2.
919 #### <a id="differences-1x-2-custom-variables"></a> Custom Variables
921 Icinga 1.x custom variable attributes must be prefixed using an underscore (`_`).
922 In Icinga 2 these attributes must be added to the `vars` dictionary as custom attributes.
924 vars.dn = "cn=icinga2-dev-host,ou=icinga,ou=main,ou=IcingaConfig,ou=LConf,dc=icinga,dc=org"
925 vars.cv = "my custom cmdb description"
927 These custom attributes are also used as [command parameters](3-monitoring-basics.md#command-passing-parameters).
929 ### <a id="differences-1x-2-host-service-relation"></a> Host Service Relation
931 In Icinga 1.x a service object is associated with a host by defining the
932 `host_name` attribute in the service definition. Alternate methods refer
933 to `hostgroup_name` or behaviour changing regular expression.
935 The preferred way of associating hosts with services in Icinga 2 is by
936 using the [apply](3-monitoring-basics.md#using-apply) keyword.
938 ### <a id="differences-1x-2-users"></a> Users
940 Contacts have been renamed to users (same for groups). A user does not
941 only provide attributes and custom attributes used for notifications, but is also
942 used for authorization checks.
944 In Icinga 2 notification commands are not directly associated with users.
945 Instead the notification command is specified using `Notification` objects.
947 The `StatusDataWriter`, `IdoMySqlConnection` and `LivestatusListener` types will
948 provide the contact and contactgroups attributes for services for compatibility
949 reasons. These values are calculated from all services, their notifications,
952 ### <a id="differences-1x-2-macros"></a> Macros
954 Various object attributes and runtime variables can be accessed as macros in
955 commands in Icinga 1.x - Icinga 2 supports all required [custom attributes](3-monitoring-basics.md#custom-attributes).
957 #### <a id="differences-1x-2-command-arguments"></a> Command Arguments
959 If you have previously used Icinga 1.x you may already be familiar with
960 user and argument definitions (e.g., `USER1` or `ARG1`). Unlike in Icinga 1.x
961 the Icinga 2 custom attributes may have arbitrary names and arguments are no
962 longer specified in the `check_command` setting.
964 In Icinga 1.x arguments are specified in the `check_command` attribute and
965 are separated from the command name using an exclamation mark (`!`).
969 command_line $USER1$/check_ping -H $address$ -w $ARG1$ -c $ARG2$ -p 5
975 service_description PING
976 check_command ping4!100.0,20%!500.0,60%
979 With the freely definable custom attributes in Icinga 2 it looks like this:
981 object CheckCommand "ping4" {
982 command = PluginDir + "/check_ping -H $address$ -w $wrta$,$wpl%$ -c $crta$,$cpl%$"
985 object Service "PING" {
986 check_command = "ping4"
995 > For better maintainability you should consider using [command arguments](3-monitoring-basics.md#command-arguments)
996 > for your check commands.
1000 > The Classic UI feature named `Command Expander` does not work with Icinga 2.
1002 #### <a id="differences-1x-2-environment-macros"></a> Environment Macros
1004 The global configuration setting `enable_environment_macros` does not exist in
1007 Macros exported into the [environment](3-monitoring-basics.md#runtime-custom-attribute-env-vars)
1008 must be set using the `env` attribute in command objects.
1010 #### <a id="differences-1x-2-runtime-macros"></a> Runtime Macros
1012 Icinga 2 requires an object specific namespace when accessing configuration
1013 and stateful runtime macros. Custom attributes can be accessed directly.
1015 Changes to user (contact) runtime macros
1017 Icinga 1.x | Icinga 2
1018 -----------------------|----------------------
1019 CONTACTNAME | user.name
1020 CONTACTALIAS | user.display_name
1021 CONTACTEMAIL | user.email
1022 CONTACTPAGER | user.pager
1024 `CONTACTADDRESS*` is not supported but can be accessed as `$user.vars.address1$`
1027 Changes to service runtime macros
1029 Icinga 1.x | Icinga 2
1030 -----------------------|----------------------
1031 SERVICEDESC | service.name
1032 SERVICEDISPLAYNAME | service.display_name
1033 SERVICECHECKCOMMAND | service.check_command
1034 SERVICESTATE | service.state
1035 SERVICESTATEID | service.state_id
1036 SERVICESTATETYPE | service.state_type
1037 SERVICEATTEMPT | service.check_attempt
1038 MAXSERVICEATTEMPT | service.max_check_attempts
1039 LASTSERVICESTATE | service.last_state
1040 LASTSERVICESTATEID | service.last_state_id
1041 LASTSERVICESTATETYPE | service.last_state_type
1042 LASTSERVICESTATECHANGE | service.last_state_change
1043 SERVICEDURATIONSEC | service.duration_sec
1044 SERVICELATENCY | service.latency
1045 SERVICEEXECUTIONTIME | service.execution_time
1046 SERVICEOUTPUT | service.output
1047 SERVICEPERFDATA | service.perfdata
1048 LASTSERVICECHECK | service.last_check
1049 SERVICENOTES | service.notes
1050 SERVICENOTESURL | service.notes_url
1051 SERVICEACTIONURL | service.action_url
1054 Changes to host runtime macros
1056 Icinga 1.x | Icinga 2
1057 -----------------------|----------------------
1058 HOSTNAME | host.name
1059 HOSTADDRESS | host.address
1060 HOSTADDRESS6 | host.address6
1061 HOSTDISPLAYNAME | host.display_name
1062 HOSTALIAS | (use `host.display_name` instead)
1063 HOSTCHECKCOMMAND | host.check_command
1064 HOSTSTATE | host.state
1065 HOSTSTATEID | host.state_id
1066 HOSTSTATETYPE | host.state_type
1067 HOSTATTEMPT | host.check_attempt
1068 MAXHOSTATTEMPT | host.max_check_attempts
1069 LASTHOSTSTATE | host.last_state
1070 LASTHOSTSTATEID | host.last_state_id
1071 LASTHOSTSTATETYPE | host.last_state_type
1072 LASTHOSTSTATECHANGE | host.last_state_change
1073 HOSTDURATIONSEC | host.duration_sec
1074 HOSTLATENCY | host.latency
1075 HOSTEXECUTIONTIME | host.execution_time
1076 HOSTOUTPUT | host.output
1077 HOSTPERFDATA | host.perfdata
1078 LASTHOSTCHECK | host.last_check
1079 HOSTNOTES | host.notes
1080 HOSTNOTESURL | host.notes_url
1081 HOSTACTIONURL | host.action_url
1082 TOTALSERVICES | host.num_services
1083 TOTALSERVICESOK | host.num_services_ok
1084 TOTALSERVICESWARNING | host.num_services_warning
1085 TOTALSERVICESUNKNOWN | host.num_services_unknown
1086 TOTALSERVICESCRITICAL | host.num_services_critical
1088 Changes to command runtime macros
1090 Icinga 1.x | Icinga 2
1091 -----------------------|----------------------
1092 COMMANDNAME | command.name
1094 Changes to notification runtime macros
1096 Icinga 1.x | Icinga 2
1097 -----------------------|----------------------
1098 NOTIFICATIONTYPE | notification.type
1099 NOTIFICATIONAUTHOR | notification.author
1100 NOTIFICATIONCOMMENT | notification.comment
1101 NOTIFICATIONAUTHORNAME | (use `notification.author`)
1102 NOTIFICATIONAUTHORALIAS | (use `notification.author`)
1105 Changes to global runtime macros:
1107 Icinga 1.x | Icinga 2
1108 -----------------------|----------------------
1109 TIMET | icinga.timet
1110 LONGDATETIME | icinga.long_date_time
1111 SHORTDATETIME | icinga.short_date_time
1114 PROCESSSTARTTIME | icinga.uptime
1116 Changes to global statistic macros:
1118 Icinga 1.x | Icinga 2
1119 ----------------------------------|----------------------
1120 TOTALHOSTSUP | icinga.num_hosts_up
1121 TOTALHOSTSDOWN | icinga.num_hosts_down
1122 TOTALHOSTSUNREACHABLE | icinga.num_hosts_unreachable
1123 TOTALHOSTSDOWNUNHANDLED | --
1124 TOTALHOSTSUNREACHABLEUNHANDLED | --
1125 TOTALHOSTPROBLEMS | down
1126 TOTALHOSTPROBLEMSUNHANDLED | down-(downtime+acknowledged)
1127 TOTALSERVICESOK | icinga.num_services_ok
1128 TOTALSERVICESWARNING | icinga.num_services_warning
1129 TOTALSERVICESCRITICAL | icinga.num_services_critical
1130 TOTALSERVICESUNKNOWN | icinga.num_services_unknown
1131 TOTALSERVICESWARNINGUNHANDLED | --
1132 TOTALSERVICESCRITICALUNHANDLED | --
1133 TOTALSERVICESUNKNOWNUNHANDLED | --
1134 TOTALSERVICEPROBLEMS | ok+warning+critical+unknown
1135 TOTALSERVICEPROBLEMSUNHANDLED | warning+critical+unknown-(downtime+acknowledged)
1140 ### <a id="differences-1x-2-external-commands"></a> External Commands
1142 `CHANGE_CUSTOM_CONTACT_VAR` was renamed to `CHANGE_CUSTOM_USER_VAR`.
1143 `CHANGE_CONTACT_MODATTR` was renamed to `CHANGE_USER_MODATTR`.
1145 The following external commands are not supported:
1147 CHANGE_CONTACT_HOST_NOTIFICATION_TIMEPERIOD
1148 CHANGE_HOST_NOTIFICATION_TIMEPERIOD
1149 CHANGE_SVC_NOTIFICATION_TIMEPERIOD
1150 DEL_DOWNTIME_BY_HOSTGROUP_NAME
1151 DEL_DOWNTIME_BY_START_TIME_COMMENT
1152 DISABLE_ALL_NOTIFICATIONS_BEYOND_HOST
1153 DISABLE_CONTACT_HOST_NOTIFICATIONS
1154 DISABLE_CONTACT_SVC_NOTIFICATIONS
1155 DISABLE_CONTACTGROUP_HOST_NOTIFICATIONS
1156 DISABLE_CONTACTGROUP_SVC_NOTIFICATIONS
1157 DISABLE_FAILURE_PREDICTION
1158 DISABLE_HOST_AND_CHILD_NOTIFICATIONS
1159 DISABLE_HOST_FRESHNESS_CHECKS
1160 DISABLE_HOST_SVC_NOTIFICATIONS
1161 DISABLE_NOTIFICATIONS_EXPIRE_TIME
1162 DISABLE_SERVICE_FRESHNESS_CHECKS
1163 ENABLE_ALL_NOTIFICATIONS_BEYOND_HOST
1164 ENABLE_CONTACT_HOST_NOTIFICATIONS
1165 ENABLE_CONTACT_SVC_NOTIFICATIONS
1166 ENABLE_CONTACTGROUP_HOST_NOTIFICATIONS
1167 ENABLE_CONTACTGROUP_SVC_NOTIFICATIONS
1168 ENABLE_FAILURE_PREDICTION
1169 ENABLE_HOST_AND_CHILD_NOTIFICATIONS
1170 ENABLE_HOST_FRESHNESS_CHECKS
1171 ENABLE_HOST_SVC_NOTIFICATIONS
1172 ENABLE_SERVICE_FRESHNESS_CHECKS
1173 READ_STATE_INFORMATION
1174 SAVE_STATE_INFORMATION
1175 SCHEDULE_AND_PROPAGATE_HOST_DOWNTIME
1176 SCHEDULE_AND_PROPAGATE_TRIGGERED_HOST_DOWNTIME
1177 SET_HOST_NOTIFICATION_NUMBER
1178 SET_SVC_NOTIFICATION_NUMBER
1179 START_ACCEPTING_PASSIVE_HOST_CHECKS
1180 START_ACCEPTING_PASSIVE_SVC_CHECKS
1181 START_OBSESSING_OVER_HOST
1182 START_OBSESSING_OVER_HOST_CHECKS
1183 START_OBSESSING_OVER_SVC
1184 START_OBSESSING_OVER_SVC_CHECKS
1185 STOP_ACCEPTING_PASSIVE_HOST_CHECKS
1186 STOP_ACCEPTING_PASSIVE_SVC_CHECKS
1187 STOP_OBSESSING_OVER_HOST
1188 STOP_OBSESSING_OVER_HOST_CHECKS
1189 STOP_OBSESSING_OVER_SVC
1190 STOP_OBSESSING_OVER_SVC_CHECKS
1192 ### <a id="differences-1x-2-async-event-execution"></a> Asynchronous Event Execution
1194 Unlike Icinga 1.x, Icinga 2 does not block when it waits for a check command
1195 being executed. Similar when a notification or event handler is triggered - they
1196 run asynchronously in their own thread.
1198 Writing performance data files or status data and log files doesn't block either.
1199 Last but not least the external command pipe runs asynchronously and accepts
1200 multiple connections at once.
1202 ### <a id="differences-1x-2-checks"></a> Checks
1204 #### <a id="differences-1x-2-check-output"></a> Check Output
1206 Icinga 2 does not make a difference between `output` (first line) and
1207 `long_output` (remaining lines) like in Icinga 1.x. Performance Data is
1208 provided separately.
1210 There is no output length restriction as known from Icinga 1.x using an
1211 [8KB static buffer](http://docs.icinga.org/latest/en/pluginapi.html#outputlengthrestrictions).
1213 The `StatusDataWriter`, `IdoMysqlConnection` and `LivestatusListener` types
1214 split the raw output into `output` (first line) and `long_output` (remaining
1215 lines) for compatibility reasons.
1217 #### <a id="differences-1x-2-initial-state"></a> Initial State
1219 Icinga 1.x uses the `max_service_check_spread` setting to specify a timerange
1220 where the initial state checks must have happened. Icinga 2 will use the
1221 `retry_interval` setting instead and `check_interval` divided by 5 if
1222 `retry_interval` is not defined.
1224 ### <a id="differences-1x-2-comments"></a> Comments
1226 Icinga 2 doesn't support non-persistent comments.
1228 ### <a id="differences-1x-2-commands"></a> Commands
1230 Unlike in Icinga 1.x there are three different command types in Icinga 2:
1231 `CheckCommand`, `NotificationCommand`, and `EventCommand`.
1233 For example in Icinga 1.x it is possible to accidently use a notification
1234 command as an event handler which might cause problems depending on which
1235 runtime macros are used in the notification command.
1237 In Icinga 2 these command types are separated and will generate an error on
1238 configuration validation if used in the wrong context.
1240 While Icinga 2 still supports the complete command line in command objects, it's
1241 also possible to encapsulate all arguments into double quotes and passing them
1242 as array to the `command_line` attribute i.e. for better readability.
1244 It's also possible to define default custom attributes for the command itself which can be
1245 overridden by a service macro.
1247 #### <a id="differences-1x-2-commands-timeouts"></a> Command Timeouts
1249 In Icinga 1.x there were two global options defining a host and service check
1250 timeout. This was essentially bad when there only was a couple of check plugins
1251 requiring some command timeouts to be extended.
1253 Icinga 2 allows you to specify the command timeout directly on the command. So
1254 if your VMVware check plugin takes 15 minutes, [increase the timeout](12-object-types.md#objecttype-checkcommand)
1258 ### <a id="differences-1x-2-groups"></a> Groups
1260 In Icinga 2 hosts, services, and users are added to groups using the `groups`
1261 attribute in the object. The old way of listing all group members in the group's
1262 `members` attribute is available through `assign where` and `ignore where`
1265 object Host "web-dev" {
1266 import "generic-host"
1269 object HostGroup "dev-hosts" {
1270 display_name = "Dev Hosts"
1271 assign where match("*-dev", host.name)
1274 #### <a id="differences-1x-2-service-hostgroup-host"></a> Add Service to Hostgroup where Host is Member
1276 In order to associate a service with all hosts in a host group the `apply`
1277 keyword can be used:
1279 apply Service "ping4" {
1280 import "generic-service"
1282 check_command = "ping4"
1284 assign where "dev-hosts" in host.groups
1287 ### <a id="differences-1x-2-notifications"></a> Notifications
1289 Notifications are a new object type in Icinga 2. Imagine the following
1290 notification configuration problem in Icinga 1.x:
1292 * Service A should notify contact X via SMS
1293 * Service B should notify contact X via Mail
1294 * Service C should notify contact Y via Mail and SMS
1295 * Contact X and Y should also be used for authorization (e.g. in Classic UI)
1297 The only way achieving a semi-clean solution is to
1299 * Create contact X-sms, set service_notification_command for sms, assign contact
1301 * Create contact X-mail, set service_notification_command for mail, assign
1302 contact to service B
1303 * Create contact Y, set service_notification_command for sms and mail, assign
1304 contact to service C
1305 * Create contact X without notification commands, assign to service A and B
1307 Basically you are required to create duplicated contacts for either each
1308 notification method or used for authorization only.
1310 Icinga 2 attempts to solve that problem in this way
1312 * Create user X, set SMS and Mail attributes, used for authorization
1313 * Create user Y, set SMS and Mail attributes, used for authorization
1314 * Create notification A-SMS, set command for sms, add user X,
1315 assign notification A-SMS to service A
1316 * Create notification B-Mail, set command for mail, add user X,
1317 assign notification Mail to service B
1318 * Create notification C-SMS, set command for sms, add user Y,
1319 assign notification C-SMS to service C
1320 * Create notification C-Mail, set command for mail, add user Y,
1321 assign notification C-Mail to service C
1323 Previously in Icinga 1.x it looked like this:
1325 service -> (contact, contactgroup) -> notification command
1327 In Icinga 2 it will look like this:
1329 Service -> Notification -> NotificationCommand
1332 #### <a id="differences-1x-2-escalations"></a> Escalations
1334 Escalations in Icinga 1.x require a separated object matching on existing
1335 objects. Escalations happen between a defined start and end time which is
1336 calculated from the notification_interval:
1338 start = notification start + (notification_interval * first_notification)
1339 end = notification start + (notification_interval * last_notification)
1341 In theory first_notification and last_notification can be set to readable
1342 numbers. In practice users are manipulating those attributes in combination
1343 with notification_interval in order to get a start and end time.
1345 In Icinga 2 the notification object can be used as notification escalation
1346 if the start and end times are defined within the 'times' attribute using
1347 duration literals (e.g. 30m).
1349 The Icinga 2 escalation does not replace the current running notification.
1350 In Icinga 1.x it's required to copy the contacts from the service notification
1351 to the escalation to guarantee the normal notifications once an escalation
1353 That's not necessary with Icinga 2 only requiring an additional notification
1354 object for the escalation itself.
1356 #### <a id="differences-1x-2-notification-options"></a> Notification Options
1358 Unlike Icinga 1.x with the 'notification_options' attribute with comma-separated
1359 state and type filters, Icinga 2 uses two configuration attributes for that.
1360 All state and type filter use long names OR'd with a pipe together
1362 notification_options w,u,c,r,f,s
1364 states = [ Warning, Unknown, Critical ]
1365 filters = [ Problem, Recovery, FlappingStart, FlappingEnd, DowntimeStart, DowntimeEnd, DowntimeRemoved ]
1367 Icinga 2 adds more fine-grained type filters for acknowledgements, downtime,
1368 and flapping type (start, end, ...).
1370 ### <a id="differences-1x-2-dependencies-parents"></a> Dependencies and Parents
1372 In Icinga 1.x it's possible to define host parents to determine network reachability
1373 and keep a host's state unreachable rather than down.
1374 Furthermore there are host and service dependencies preventing unnecessary checks and
1375 notifications. A host must not depend on a service, and vice versa. All dependencies
1376 are configured as separate objects and cannot be set directly on the host or service
1379 A service can now depend on a host, and vice versa. A service has an implicit dependency
1380 (parent) to its host. A host to host dependency acts implicitly as host parent relation.
1382 The former `host_name` and `dependent_host_name` have been renamed to `parent_host_name`
1383 and `child_host_name` (same for the service attribute). When using apply rules the
1384 child attributes may be omitted.
1386 For detailed examples on how to use the dependencies please check the [dependencies](3-monitoring-basics.md#dependencies)
1389 Dependencies can be applied to hosts or services using the [apply rules](10-language-reference.md#apply).
1391 The `StatusDataWriter`, `IdoMysqlConnection` and `LivestatusListener` types
1392 support the Icinga 1.x schema with dependencies and parent attributes for
1393 compatibility reasons.
1395 ### <a id="differences-1x-2-flapping"></a> Flapping
1397 The Icinga 1.x flapping detection uses the last 21 states of a service. This
1398 value is hardcoded and cannot be changed. The algorithm on determining a flapping state
1401 flapping value = (number of actual state changes / number of possible state changes)
1403 The flapping value is then compared to the low and high flapping thresholds.
1405 The algorithm used in Icinga 2 does not store the past states but calculcates the flapping
1406 threshold from a single value based on counters and half-life values. Icinga 2 compares
1407 the value with a single flapping threshold configuration attribute.
1409 ### <a id="differences-1x-2-check-result-freshness"></a> Check Result Freshness
1411 Freshness of check results must be enabled explicitly in Icinga 1.x. The attribute
1412 `freshness_threshold` defines the threshold in seconds. Once the threshold is triggered, an
1413 active freshness check is executed defined by the `check_command` attribute. Both check
1414 methods (active and passive) use the same freshness check method.
1416 In Icinga 2 active check freshness is determined by the `check_interval` attribute and no
1417 incoming check results in that period of time (last check + check interval). Passive check
1418 freshness is calculated from the `check_interval` attribute if set. There is no extra
1419 `freshness_threshold` attribute in Icinga 2. If the freshness checks are invalid, a new
1420 service check is forced.
1422 ### <a id="differences-1x-2-real-reload"></a> Real Reload
1424 In Nagios / Icinga 1.x a daemon reload happens like this
1426 * receive reload signal SIGHUP
1427 * stop all events (checks, notifications, etc)
1428 * read the configuration from disk and validate all config objects in a single threaded fashion
1429 * validation NOT ok: stop the daemon (cannot restore old config state)
1430 * validation ok: start with new objects, dump status.dat / ido
1432 Unlike Icinga 1.x the Icinga 2 daemon reload happens asynchronously.
1434 * receive reload signal SIGHUP
1435 * fork a child process, start configuration validation in parallel work queues
1436 * parent process continues with old configuration objects and the event scheduling
1437 (doing checks, replicating cluster events, triggering alert notifications, etc.)
1438 * validation NOT ok: child process terminates, parent process continues with old configuration state
1439 (this is ESSENTIAL for the [cluster config synchronisation](4-monitoring-remote-systems.md#cluster-zone-config-sync))
1440 * validation ok: child process signals parent process to terminate and save its current state
1441 (all events until now) into the icinga2 state file
1442 * parent process shuts down writing icinga2.state file
1443 * child process waits for parent process gone, reads the icinga2 state file and synchronizes all historical and status data
1444 * child becomes the new session leader
1446 The DB IDO configuration dump and status/historical event updates also runs asynchronously in a queue not blocking the core anymore. Same goes for any other enabled feature running in its own thread.
1447 The configuration validation itself runs in parallel allowing fast verification checks.
1449 That way you are not blind (anymore) during a configuration reload and benefit from a real scalable architecture.
1452 ### <a id="differences-1x-2-state-retention"></a> State Retention
1454 Icinga 1.x uses the `retention.dat` file to save its state in order to be able
1455 to reload it after a restart. In Icinga 2 this file is called `icinga2.state`.
1457 The format objects are stored in is not compatible with Icinga 1.x.
1459 ### <a id="differences-1x-2-logging"></a> Logging
1461 Icinga 1.x supports syslog facilities and writes its own `icinga.log` log file
1462 and archives. These logs are used in Icinga 1.x Classic UI to generate
1465 Icinga 2 compat library provides the CompatLogger object which writes the icinga.log and archive
1466 in Icinga 1.x format in order to stay compatible with Classic UI and other addons.
1468 The native Icinga 2 logging facilities are split into three configuration objects: SyslogLogger,
1469 FileLogger, StreamLogger. Each of them has their own severity and target configuration.
1471 The Icinga 2 daemon log does not log any alerts but is considered an application log only.
1473 ### <a id="differences-1x-2-broker-modules-features"></a> Broker Modules and Features
1475 Icinga 1.x broker modules are incompatible with Icinga 2.
1477 In order to provide compatibility with Icinga 1.x the functionality of several
1478 popular broker modules was implemented for Icinga 2:
1482 * Cluster (allows for high availability and load balancing)
1485 ### <a id="differences-1x-2-distributed-monitoring"></a> Distributed Monitoring
1487 Icinga 1.x uses the native "obsess over host/service" method which requires the NSCA addon
1488 passing the slave's check results passively onto the master's external command pipe.
1489 While this method may be used for check load distribution, it does not provide any configuration
1490 distribution out-of-the-box. Furthermore comments, downtimes, and other stateful runtime data is
1491 not synced between the master and slave nodes. There are addons available solving the check
1492 and configuration distribution problems Icinga 1.x distributed monitoring currently suffers from.
1494 Icinga 2 implements a new built-in [distributed monitoring architecture](4-monitoring-remote-systems.md#distributed-monitoring-high-availability),
1495 including config and check distribution, IPv4/IPv6 support, SSL certificates and zone support for DMZ.
1496 High Availability and load balancing are also part of the Icinga 2 Cluster setup.