1# Migration from Icinga 1.x <a id="migration"></a> 2 3## Configuration Migration <a id="configuration-migration"></a> 4 5The Icinga 2 configuration format introduces plenty of behavioural changes. In 6order to ease migration from Icinga 1.x, this section provides hints and tips 7on your migration requirements. 8 9 10### Automated Config Migration <a id="automated-config-migration"></a> 11 12Depending on your previous setup, you may have already used different sources 13for generating the 1.x configuration files. If this is the case, 14we strongly recommend to use these sources in combination with 15the [Icinga Director](https://icinga.com/docs/director/latest/doc/01-Introduction/). 16 17This can be for example: 18 19* A CMDB or RDBMS which provides host details and facts 20* PuppetDB 21* CSV/XSL/JSON files 22* Cloud resources (AWS, etc.) 23 24In case you have been using Icinga Web 1.x or an addon requiring 25the underlying IDO database, you can use this as database resource 26to import the host details. 27 28Talks: 29 30* [This talk from OSMC 2016](https://www.youtube.com/watch?v=T6GBsfeXIZI) shares more insights (German). 31* [Automated Monitoring in heterogeneous environments](https://www.youtube.com/watch?v=bkUlS5rlHzM&list=PLeoxx10paaAn_xHJ5wBhnBJyW_d5G7-Bl&index=8) 32 33Continue reading more about [Import Sources](https://icinga.com/docs/director/latest/doc/70-Import-and-Sync/) 34for the Icinga Director. 35 36### Manual Config Migration <a id="manual-config-migration"></a> 37 38For a long-term migration of your configuration you should consider re-creating 39your configuration based on the proposed Icinga 2 configuration paradigm. 40 41Please read the [next chapter](23-migrating-from-icinga-1x.md#differences-1x-2) to find out more about the differences 42between 1.x and 2. 43 44### Manual Config Migration Hints <a id="manual-config-migration-hints"></a> 45 46These hints should provide you with enough details for manually migrating your configuration, 47or to adapt your configuration export tool to dump Icinga 2 configuration instead of 48Icinga 1.x configuration. 49 50The examples are taken from Icinga 1.x test and production environments and converted 51straight into a possible Icinga 2 format. If you found a different strategy, please 52let us know! 53 54If you require in-depth explanations, please check the [next chapter](23-migrating-from-icinga-1x.md#differences-1x-2). 55 56#### Manual Config Migration Hints for Intervals <a id="manual-config-migration-hints-Intervals"></a> 57 58By default all intervals without any duration literal are interpreted as seconds. Therefore 59all existing Icinga 1.x `*_interval` attributes require an additional `m` duration literal. 60 61Icinga 1.x: 62 63``` 64define service { 65 service_description service1 66 host_name localhost1 67 check_command test_customvar 68 use generic-service 69 check_interval 5 70 retry_interval 1 71} 72``` 73 74Icinga 2: 75 76``` 77object Service "service1" { 78 import "generic-service" 79 host_name = "localhost1" 80 check_command = "test_customvar" 81 check_interval = 5m 82 retry_interval = 1m 83} 84``` 85 86#### Manual Config Migration Hints for Services <a id="manual-config-migration-hints-services"></a> 87 88If you have used the `host_name` attribute in Icinga 1.x with one or more host names this service 89belongs to, you can migrate this to the [apply rules](03-monitoring-basics.md#using-apply) syntax. 90 91Icinga 1.x: 92 93``` 94define service { 95 service_description service1 96 host_name localhost1,localhost2 97 check_command test_check 98 use generic-service 99} 100``` 101 102Icinga 2: 103 104``` 105apply Service "service1" { 106 import "generic-service" 107 check_command = "test_check" 108 109 assign where host.name in [ "localhost1", "localhost2" ] 110} 111``` 112 113In Icinga 1.x you would have organized your services with hostgroups using the `hostgroup_name` attribute 114like the following example: 115 116``` 117define service { 118 service_description servicewithhostgroups 119 hostgroup_name hostgroup1,hostgroup3 120 check_command test_check 121 use generic-service 122} 123``` 124 125Using Icinga 2 you can migrate this to the [apply rules](03-monitoring-basics.md#using-apply) syntax: 126 127``` 128apply Service "servicewithhostgroups" { 129 import "generic-service" 130 check_command = "test_check" 131 132 assign where "hostgroup1" in host.groups 133 assign where "hostgroup3" in host.groups 134} 135``` 136 137#### Manual Config Migration Hints for Group Members <a id="manual-config-migration-hints-group-members"></a> 138 139The Icinga 1.x hostgroup `hg1` has two members `host1` and `host2`. The hostgroup `hg2` has `host3` as 140a member and includes all members of the `hg1` hostgroup. 141 142``` 143define hostgroup { 144 hostgroup_name hg1 145 members host1,host2 146} 147 148define hostgroup { 149 hostgroup_name hg2 150 members host3 151 hostgroup_members hg1 152} 153``` 154 155This can be migrated to Icinga 2 and [using group assign](17-language-reference.md#group-assign). The additional nested hostgroup 156`hg1` is included into `hg2` with the `groups` attribute. 157 158``` 159object HostGroup "hg1" { 160 groups = [ "hg2" ] 161 assign where host.name in [ "host1", "host2" ] 162} 163 164object HostGroup "hg2" { 165 assign where host.name == "host3" 166} 167``` 168 169These assign rules can be applied for all groups: `HostGroup`, `ServiceGroup` and `UserGroup` 170(requires renaming from `contactgroup`). 171 172> **Tip** 173> 174> Define custom variables and assign/ignore members based on these attribute pattern matches. 175 176 177 178#### Manual Config Migration Hints for Check Command Arguments <a id="manual-config-migration-hints-check-command-arguments"></a> 179 180Host and service check command arguments are separated by a `!` in Icinga 1.x. Their order is important and they 181are referenced as `$ARGn$` where `n` is the argument counter. 182 183``` 184define command { 185 command_name my-ping 186 command_line $USER1$/check_ping -H $HOSTADDRESS$ -w $ARG1$ -c $ARG2$ -p 5 187} 188 189define service { 190 use generic-service 191 host_name my-server 192 service_description my-ping 193 check_command my-ping-check!100.0,20%!500.0,60% 194} 195``` 196 197While you could manually migrate this like (please note the new generic command arguments and default argument values!): 198 199``` 200object CheckCommand "my-ping-check" { 201 command = [ 202 PluginDir + "/check_ping", "-4" 203 ] 204 205 arguments = { 206 "-H" = "$ping_address$" 207 "-w" = "$ping_wrta$,$ping_wpl$%" 208 "-c" = "$ping_crta$,$ping_cpl$%" 209 "-p" = "$ping_packets$" 210 "-t" = "$ping_timeout$" 211 } 212 213 vars.ping_address = "$address$" 214 vars.ping_wrta = 100 215 vars.ping_wpl = 5 216 vars.ping_crta = 200 217 vars.ping_cpl = 15 218} 219 220object Service "my-ping" { 221 import "generic-service" 222 host_name = "my-server" 223 check_command = "my-ping-check" 224 225 vars.ping_wrta = 100 226 vars.ping_wpl = 20 227 vars.ping_crta = 500 228 vars.ping_cpl = 60 229} 230``` 231 232#### Manual Config Migration Hints for Runtime Macros <a id="manual-config-migration-hints-runtime-macros"></a> 233 234Runtime macros have been renamed. A detailed comparison table can be found [here](23-migrating-from-icinga-1x.md#differences-1x-2-runtime-macros). 235 236For example, accessing the service check output looks like the following in Icinga 1.x: 237 238``` 239$SERVICEOUTPUT$ 240``` 241 242In Icinga 2 you will need to write: 243 244``` 245$service.output$ 246``` 247 248Another example referencing the host's address attribute in Icinga 1.x: 249 250``` 251$HOSTADDRESS$ 252``` 253 254In Icinga 2 you'd just use the following macro to access all `address` attributes (even overridden from the service objects): 255 256``` 257$address$ 258``` 259 260#### Manual Config Migration Hints for Runtime Custom Variables <a id="manual-config-migration-hints-runtime-custom-variables"></a> 261 262Custom variables from Icinga 1.x are available as Icinga 2 custom variables. 263 264``` 265define command { 266 command_name test_customvar 267 command_line echo "Host CV: $_HOSTCVTEST$ Service CV: $_SERVICECVTEST$\n" 268} 269 270define host { 271 host_name localhost1 272 check_command test_customvar 273 use generic-host 274 _CVTEST host cv value 275} 276 277define service { 278 service_description service1 279 host_name localhost1 280 check_command test_customvar 281 use generic-service 282 _CVTEST service cv value 283} 284``` 285 286Can be written as the following in Icinga 2: 287 288``` 289object CheckCommand "test_customvar" { 290 command = "echo "Host CV: $host.vars.CVTEST$ Service CV: $service.vars.CVTEST$\n"" 291} 292 293object Host "localhost1" { 294 import "generic-host" 295 check_command = "test_customvar" 296 vars.CVTEST = "host cv value" 297} 298 299object Service "service1" { 300 host_name = "localhost1" 301 check_command = "test_customvar" 302 vars.CVTEST = "service cv value" 303} 304``` 305 306If you are just defining `$CVTEST$` in your command definition, its value depends on the 307execution scope -- the host check command will fetch the host attribute value of `vars.CVTEST` 308while the service check command resolves its value to the service attribute attribute `vars.CVTEST`. 309 310> **Note** 311> 312> Custom variables in Icinga 2 are case-sensitive. `vars.CVTEST` is not the same as `vars.CvTest`. 313 314#### Manual Config Migration Hints for Contacts (Users) <a id="manual-config-migration-hints-contacts-users"></a> 315 316Contacts in Icinga 1.x act as users in Icinga 2, but do not have any notification commands specified. 317This migration part is explained in the [next chapter](23-migrating-from-icinga-1x.md#manual-config-migration-hints-notifications). 318 319``` 320define contact{ 321 contact_name testconfig-user 322 use generic-user 323 alias Icinga Test User 324 service_notification_options c,f,s,u 325 email icinga@localhost 326} 327``` 328 329The `service_notification_options` can be [mapped](23-migrating-from-icinga-1x.md#manual-config-migration-hints-notification-filters) 330into generic `state` and `type` filters, if additional notification filtering is required. `alias` gets 331renamed to `display_name`. 332 333``` 334object User "testconfig-user" { 335 import "generic-user" 336 display_name = "Icinga Test User" 337 email = "icinga@localhost" 338} 339``` 340 341This user can be put into usergroups (former contactgroups) or referenced in newly migration notification 342objects. 343 344#### Manual Config Migration Hints for Notifications <a id="manual-config-migration-hints-notifications"></a> 345 346If you are migrating a host or service notification, you'll need to extract the following information from 347your existing Icinga 1.x configuration objects 348 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` 353 354The clean approach is to refactor your current contacts and their notification command methods into a 355generic strategy 356 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](03-monitoring-basics.md#using-apply-notifications) 362 363 364The ugly workaround solution could look like this: 365 366Extract all contacts from the remaining groups, and create a unique list. This is required for determining 367the host and service notification commands involved. 368 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 372 373Generate a new notification object based on these values. Import the generic template based on the type (`host` or `service`). 374Assign it to the host or service and set the newly generated notification command name as `command` attribute. 375 376``` 377object Notification "<notificationname>" { 378 import "mail-host-notification" 379 host_name = "<thishostname>" 380 command = "<notificationcommandname>" 381``` 382 383Convert the `notification_options` attribute from Icinga 1.x to Icinga 2 `states` and `types`. Details 384[here](23-migrating-from-icinga-1x.md#manual-config-migration-hints-notification-filters). Add the notification period. 385 386``` 387 states = [ OK, Warning, Critical ] 388 types = [ Recovery, Problem, Custom ] 389 period = "24x7" 390``` 391 392The current contact acts as `users` attribute. 393 394``` 395 users = [ "<contactwithnotificationcommand>" ] 396} 397``` 398 399Do this in a loop for all notification commands (depending if host or service contact). Once done, dump the 400collected notification commands. 401 402The result of this migration are lots of unnecessary notification objects and commands but it will unroll 403the Icinga 1.x logic into the revamped Icinga 2 notification object schema. If you are looking for code 404examples, try [LConf](https://www.netways.org). 405 406 407 408#### Manual Config Migration Hints for Notification Filters <a id="manual-config-migration-hints-notification-filters"></a> 409 410Icinga 1.x defines all notification filters in an attribute called `notification_options`. Using Icinga 2 you will 411have to split these values into the `states` and `types` attributes. 412 413> **Note** 414> 415> `Recovery` type requires the `Ok` state. 416> `Custom` and `Problem` should always be set as `type` filter. 417 418 Icinga 1.x option | Icinga 2 state | Icinga 2 type 419 ----------------------|-----------------------|------------------- 420 o | OK (Up for hosts) | 421 w | Warning | Problem 422 c | Critical | Problem 423 u | Unknown | Problem 424 d | Down | Problem 425 s | . | DowntimeStart / DowntimeEnd / DowntimeRemoved 426 r | Ok | Recovery 427 f | . | FlappingStart / FlappingEnd 428 n | 0 (none) | 0 (none) 429 . | . | Custom 430 431 432 433#### Manual Config Migration Hints for Escalations <a id="manual-config-migration-hints-escalations"></a> 434 435Escalations in Icinga 1.x are a bit tricky. By default service escalations can be applied to hosts and 436hostgroups and require a defined service object. 437 438The following example applies a service escalation to the service `dep_svc01` and all hosts in the `hg_svcdep2` 439hostgroup. The default `notification_interval` is set to `10` minutes notifying the `cg_admin` contact. 440After 20 minutes (`10*2`, notification_interval * first_notification) the notification is escalated to the 441`cg_ops` contactgroup until 60 minutes (`10*6`) have passed. 442 443``` 444define service { 445 service_description dep_svc01 446 host_name dep_hostsvc01,dep_hostsvc03 447 check_command test2 448 use generic-service 449 notification_interval 10 450 contact_groups cg_admin 451} 452 453define hostgroup { 454 hostgroup_name hg_svcdep2 455 members dep_hostsvc03 456} 457 458# with hostgroup_name and service_description 459define serviceescalation { 460 hostgroup_name hg_svcdep2 461 service_description dep_svc01 462 first_notification 2 463 last_notification 6 464 contact_groups cg_ops 465} 466``` 467 468In Icinga 2 the service and hostgroup definition will look quite the same. Save the `notification_interval` 469and `contact_groups` attribute for an additional notification. 470 471``` 472apply Service "dep_svc01" { 473 import "generic-service" 474 475 check_command = "test2" 476 477 assign where host.name == "dep_hostsvc01" 478 assign where host.name == "dep_hostsvc03" 479} 480 481object HostGroup "hg_svcdep2" { 482 assign where host.name == "dep_hostsvc03" 483} 484 485apply Notification "email" to Service { 486 import "service-mail-notification" 487 488 interval = 10m 489 user_groups = [ "cg_admin" ] 490 491 assign where service.name == "dep_svc01" && (host.name == "dep_hostsvc01" || host.name == "dep_hostsvc03") 492} 493``` 494 495Calculate the begin and end time for the newly created escalation notification: 496 497* begin = first_notification * notification_interval = 2 * 10m = 20m 498* end = last_notification * notification_interval = 6 * 10m = 60m = 1h 499 500Assign the notification escalation to the service `dep_svc01` on all hosts in the hostgroup `hg_svcdep2`. 501 502``` 503apply Notification "email-escalation" to Service { 504 import "service-mail-notification" 505 506 interval = 10m 507 user_groups = [ "cg_ops" ] 508 509 times = { 510 begin = 20m 511 end = 1h 512 } 513 514 assign where service.name == "dep_svc01" && "hg_svcdep2" in host.groups 515} 516``` 517 518The assign rule could be made more generic and the notification be applied to more than 519just this service belonging to hosts in the matched hostgroup. 520 521 522> **Note** 523> 524> When the notification is escalated, Icinga 1.x suppresses notifications to the default contacts. 525> In Icinga 2 an escalation is an additional notification with a defined begin and end time. The 526> `email` notification will continue as normal. 527 528 529 530#### Manual Config Migration Hints for Dependencies <a id="manual-config-migration-hints-dependencies"></a> 531 532There are some dependency examples already in the [basics chapter](03-monitoring-basics.md#dependencies). Dependencies in 533Icinga 1.x can be confusing in terms of which host/service is the parent and which host/service acts 534as the child. 535 536While Icinga 1.x defines `notification_failure_criteria` and `execution_failure_criteria` as dependency 537filters, this behaviour has changed in Icinga 2. There is no 1:1 migration but generally speaking 538the state filter defined in the `execution_failure_criteria` defines the Icinga 2 `state` attribute. 539If the state filter matches, you can define whether to disable checks and notifications or not. 540 541The following example describes service dependencies. If you migrate from Icinga 1.x, you will only 542want to use the classic `Host-to-Host` and `Service-to-Service` dependency relationships. 543 544``` 545define service { 546 service_description dep_svc01 547 hostgroup_name hg_svcdep1 548 check_command test2 549 use generic-service 550} 551 552define service { 553 service_description dep_svc02 554 hostgroup_name hg_svcdep2 555 check_command test2 556 use generic-service 557} 558 559define hostgroup { 560 hostgroup_name hg_svcdep2 561 members host2 562} 563 564define host{ 565 use linux-server-template 566 host_name host1 567 address 192.168.1.10 568} 569 570# with hostgroup_name and service_description 571define servicedependency { 572 host_name host1 573 dependent_hostgroup_name hg_svcdep2 574 service_description dep_svc01 575 dependent_service_description * 576 execution_failure_criteria u,c 577 notification_failure_criteria w,u,c 578 inherits_parent 1 579} 580``` 581 582Map the dependency attributes accordingly. 583 584 Icinga 1.x | Icinga 2 585 ----------------------|--------------------- 586 host_name | parent_host_name 587 dependent_host_name | child_host_name (used in assign/ignore) 588 dependent_hostgroup_name | all child hosts in group (used in assign/ignore) 589 service_description | parent_service_name 590 dependent_service_description | child_service_name (used in assign/ignore) 591 592And migrate the host and services. 593 594``` 595object Host "host1" { 596 import "linux-server-template" 597 address = "192.168.1.10" 598} 599 600object HostGroup "hg_svcdep2" { 601 assign where host.name == "host2" 602} 603 604apply Service "dep_svc01" { 605 import "generic-service" 606 check_command = "test2" 607 608 assign where "hp_svcdep1" in host.groups 609} 610 611apply Service "dep_svc02" { 612 import "generic-service" 613 check_command = "test2" 614 615 assign where "hp_svcdep2" in host.groups 616} 617``` 618 619When it comes to the `execution_failure_criteria` and `notification_failure_criteria` attribute migration, 620you will need to map the most common values, in this example `u,c` (`Unknown` and `Critical` will cause the 621dependency to fail). Therefore the `Dependency` should be ok on Ok and Warning. `inherits_parents` is always 622enabled. 623 624``` 625apply Dependency "all-svc-for-hg-hg_svcdep2-on-host1-dep_svc01" to Service { 626 parent_host_name = "host1" 627 parent_service_name = "dep_svc01" 628 629 states = [ Ok, Warning ] 630 disable_checks = true 631 disable_notifications = true 632 633 assign where "hg_svcdep2" in host.groups 634} 635``` 636 637Host dependencies are explained in the [next chapter](23-migrating-from-icinga-1x.md#manual-config-migration-hints-host-parents). 638 639 640 641#### Manual Config Migration Hints for Host Parents <a id="manual-config-migration-hints-host-parents"></a> 642 643Host parents from Icinga 1.x are migrated into `Host-to-Host` dependencies in Icinga 2. 644 645The following example defines the `vmware-master` host as parent host for the guest 646virtual machines `vmware-vm1` and `vmware-vm2`. 647 648By default all hosts in the hostgroup `vmware` should get the parent assigned. This isn't really 649solvable with Icinga 1.x parents, but only with host dependencies. 650 651``` 652define host{ 653 use linux-server-template 654 host_name vmware-master 655 hostgroups vmware 656 address 192.168.1.10 657} 658 659define host{ 660 use linux-server-template 661 host_name vmware-vm1 662 hostgroups vmware 663 address 192.168.27.1 664 parents vmware-master 665} 666 667define host{ 668 use linux-server-template 669 host_name vmware-vm2 670 hostgroups vmware 671 address 192.168.28.1 672 parents vmware-master 673} 674``` 675 676By default all hosts in the hostgroup `vmware` should get the parent assigned (but not the `vmware-master` 677host itself). This isn't really solvable with Icinga 1.x parents, but only with host dependencies as shown 678below: 679 680``` 681define hostdependency { 682 dependent_hostgroup_name vmware 683 dependent_host_name !vmware-master 684 host_name vmware-master 685 inherits_parent 1 686 notification_failure_criteria d,u 687 execution_failure_criteria d,u 688 dependency_period testconfig-24x7 689} 690``` 691 692When migrating to Icinga 2, the parents must be changed to a newly created host dependency. 693 694 695Map the following attributes 696 697 Icinga 1.x | Icinga 2 698 ----------------------|--------------------- 699 host_name | parent_host_name 700 dependent_host_name | child_host_name (used in assign/ignore) 701 dependent_hostgroup_name | all child hosts in group (used in assign/ignore) 702 703The Icinga 2 configuration looks like this: 704 705``` 706object Host "vmware-master" { 707 import "linux-server-template" 708 groups += [ "vmware" ] 709 address = "192.168.1.10" 710 vars.is_vmware_master = true 711} 712 713object Host "vmware-vm1" { 714 import "linux-server-template" 715 groups += [ "vmware" ] 716 address = "192.168.27.1" 717} 718 719object Host "vmware-vm2" { 720 import "linux-server-template" 721 groups += [ "vmware" ] 722 address = "192.168.28.1" 723} 724 725apply Dependency "vmware-master" to Host { 726 parent_host_name = "vmware-master" 727 728 assign where "vmware" in host.groups 729 ignore where host.vars.is_vmware_master 730 ignore where host.name == "vmware-master" 731} 732``` 733 734For easier identification you could add the `vars.is_vmware_master` attribute to the `vmware-master` 735host and let the dependency ignore that instead of the hardcoded host name. That's different 736to the Icinga 1.x example and a best practice hint only. 737 738 739Another way to express the same configuration would be something like: 740 741``` 742object Host "vmware-master" { 743 import "linux-server-template" 744 groups += [ "vmware" ] 745 address = "192.168.1.10" 746} 747 748object Host "vmware-vm1" { 749 import "linux-server-template" 750 groups += [ "vmware" ] 751 address = "192.168.27.1" 752 vars.parents = [ "vmware-master" ] 753} 754 755object Host "vmware-vm2" { 756 import "linux-server-template" 757 groups += [ "vmware" ] 758 address = "192.168.28.1" 759 vars.parents = [ "vmware-master" ] 760} 761 762apply Dependency "host-to-parent-" for (parent in host.vars.parents) to Host { 763 parent_host_name = parent 764} 765``` 766 767This example allows finer grained host-to-host dependency, as well as multiple dependency support. 768 769#### Manual Config Migration Hints for Distributed Setups <a id="manual-config-migration-hints-distributed-setup"></a> 770 771* Icinga 2 does not use active/passive instances calling OSCP commands and requiring the NSCA 772daemon for passing check results between instances. 773* Icinga 2 does not support any 1.x NEB addons for check load distribution 774 775* If your current setup consists of instances distributing the check load, you should consider 776building a [load distribution](06-distributed-monitoring.md#distributed-monitoring-scenarios) setup with Icinga 2. 777* If your current setup includes active/passive clustering with external tools like Pacemaker/DRBD, 778consider the [High Availability](06-distributed-monitoring.md#distributed-monitoring-scenarios) setup. 779* If you have build your own custom configuration deployment and check result collecting mechanism, 780you should re-design your setup and re-evaluate your requirements, and how they may be fulfilled 781using the Icinga 2 cluster capabilities. 782 783 784## Differences between Icinga 1.x and 2 <a id="differences-1x-2"></a> 785 786### Configuration Format <a id="differences-1x-2-configuration-format"></a> 787 788Icinga 1.x supports two configuration formats: key-value-based settings in the 789`icinga.cfg` configuration file and object-based in included files (`cfg_dir`, 790`cfg_file`). The path to the `icinga.cfg` configuration file must be passed to 791the Icinga daemon at startup. 792 793icinga.cfg: 794 795``` 796enable_notifications=1 797``` 798 799objects.cfg: 800 801``` 802define service { 803 notifications_enabled 0 804} 805``` 806 807Icinga 2 supports objects and (global) variables, but does not make a difference 808between the main configuration file or any other included file. 809 810icinga2.conf: 811 812``` 813const EnableNotifications = true 814 815object Service "test" { 816 enable_notifications = false 817} 818``` 819 820#### Sample Configuration and ITL <a id="differences-1x-2-sample-configuration-itl"></a> 821 822While Icinga 1.x ships sample configuration and templates spread in various 823object files, Icinga 2 moves all templates into the Icinga Template Library (ITL) 824and includes them in the sample configuration. 825 826Additional plugin check commands are shipped with Icinga 2 as well. 827 828The ITL will be updated on every release and must not be edited by the user. 829 830There are still generic templates available for your convenience which may or may 831not be re-used in your configuration. For instance, `generic-service` includes 832all required attributes except `check_command` for a service. 833 834Sample configuration files are located in the `conf.d/` directory which is 835included in `icinga2.conf` by default. 836 837> **Note** 838> 839> Add your own custom templates in the `conf.d/` directory as well, e.g. inside 840> the [templates.conf](04-configuration.md#templates-conf) file. 841 842### Main Config File <a id="differences-1x-2-main-config"></a> 843 844In Icinga 1.x there are many global configuration settings available in `icinga.cfg`. 845Icinga 2 only uses a small set of [global constants](17-language-reference.md#constants) allowing 846you to specify certain different setting such as the `NodeName` in a cluster scenario. 847 848Aside from that, the [icinga2.conf](04-configuration.md#icinga2-conf) should take care of including 849global constants, enabled [features](11-cli-commands.md#enable-features) and the object configuration. 850 851### Include Files and Directories <a id="differences-1x-2-include-files-dirs"></a> 852 853In Icinga 1.x the `icinga.cfg` file contains `cfg_file` and `cfg_dir` 854directives. The `cfg_dir` directive recursively includes all files with a `.cfg` 855suffix in the given directory. Only absolute paths may be used. The `cfg_file` 856and `cfg_dir` directives can include the same file twice which leads to 857configuration errors in Icinga 1.x. 858 859``` 860cfg_file=/etc/icinga/objects/commands.cfg 861cfg_dir=/etc/icinga/objects 862``` 863 864Icinga 2 supports wildcard includes and relative paths, e.g. for including 865`conf.d/*.conf` in the same directory. 866 867``` 868include "conf.d/*.conf" 869``` 870 871If you want to include files and directories recursively, you need to define 872a separate option and add the directory and an optional pattern. 873 874``` 875include_recursive "conf.d" 876``` 877 878A global search path for includes is available for advanced features like 879the Icinga Template Library (ITL) or additional monitoring plugins check 880command configuration. 881 882``` 883include <itl> 884include <plugins> 885``` 886 887By convention the `.conf` suffix is used for Icinga 2 configuration files. 888 889### Resource File and Global Macros <a id="differences-1x-2-resource-file-global-macros"></a> 890 891Global macros such as for the plugin directory, usernames and passwords can be 892set in the `resource.cfg` configuration file in Icinga 1.x. By convention the 893`USER1` macro is used to define the directory for the plugins. 894 895Icinga 2 uses global constants instead. In the default config these are 896set in the `constants.conf` configuration file: 897 898``` 899/** 900 * This file defines global constants which can be used in 901 * the other configuration files. At a minimum the 902 * PluginDir constant should be defined. 903 */ 904 905const PluginDir = "/usr/lib/nagios/plugins" 906``` 907 908[Global macros](17-language-reference.md#constants) can only be defined once. Trying to modify a 909global constant will result in an error. 910 911### Configuration Comments <a id="differences-1x-2-configuration-comments"></a> 912 913In Icinga 1.x comments are made using a leading hash (`#`) or a semi-colon (`;`) 914for inline comments. 915 916In Icinga 2 comments can either be encapsulated by `/*` and `*/` (allowing for 917multi-line comments) or starting with two slashes (`//`). A leading hash (`#`) 918could also be used. 919 920### Object Names <a id="differences-1x-2-object-names"></a> 921 922Object names must not contain an exclamation mark (`!`). Use the `display_name` attribute 923to specify user-friendly names which should be shown in UIs (supported by 924Icinga Web 2 for example). 925 926Object names are not specified using attributes (e.g. `service_description` for 927services) like in Icinga 1.x but directly after their type definition. 928 929``` 930define service { 931 host_name localhost 932 service_description ping4 933} 934 935object Service "ping4" { 936 host_name = "localhost" 937} 938``` 939 940### Templates <a id="differences-1x-2-templates"></a> 941 942In Icinga 1.x templates are identified using the `register 0` setting. Icinga 2 943uses the `template` identifier: 944 945``` 946template Service "ping4-template" { } 947``` 948 949Icinga 1.x objects inherit from templates using the `use` attribute. 950Icinga 2 uses the keyword `import` with template names in double quotes. 951 952``` 953define service { 954 service_description testservice 955 use tmpl1,tmpl2,tmpl3 956} 957 958object Service "testservice" { 959 import "tmpl1" 960 import "tmpl2" 961 import "tmpl3" 962} 963``` 964 965The last template overrides previously set values. 966 967### Object attributes <a id="differences-1x-2-object-attributes"></a> 968 969Icinga 1.x separates attribute and value pairs with whitespaces/tabs. Icinga 2 970requires an equal sign (=) between them. 971 972``` 973define service { 974 check_interval 5 975} 976 977object Service "test" { 978 check_interval = 5m 979} 980``` 981 982Please note that the default time value is seconds if no duration literal 983is given. `check_interval = 5` behaves the same as `check_interval = 5s`. 984 985All strings require double quotes in Icinga 2. Therefore a double quote 986must be escaped by a backslash (e.g. in command line). 987If an attribute identifier starts with a number, it must be enclosed 988in double quotes as well. 989 990#### Alias vs. Display Name <a id="differences-1x-2-alias-display-name"></a> 991 992In Icinga 1.x a host can have an `alias` and a `display_name` attribute used 993for a more descriptive name. A service only can have a `display_name` attribute. 994The `alias` is used for group, timeperiod, etc. objects too. 995Icinga 2 only supports the `display_name` attribute which is also taken into 996account by Icinga web interfaces. 997 998### Custom Variables <a id="differences-1x-2-custom-variables"></a> 999 1000Icinga 2 allows you to define custom variables in the `vars` dictionary. 1001The `notes`, `notes_url`, `action_url`, `icon_image`, `icon_image_alt` 1002attributes for host and service objects are still available in Icinga 2. 1003 1004`2d_coords` and `statusmap_image` are not supported in Icinga 2. 1005 1006Icinga 1.x custom variable attributes must be prefixed using an underscore (`_`). 1007In Icinga 2 these attributes must be added to the `vars` dictionary as custom variables. 1008 1009``` 1010vars.dn = "cn=icinga2-dev-host,ou=icinga,ou=main,ou=IcingaConfig,ou=LConf,dc=icinga,dc=org" 1011vars.cv = "my custom cmdb description" 1012``` 1013 1014These custom variables are also used as [command parameters](03-monitoring-basics.md#command-passing-parameters). 1015 1016While Icinga 1.x only supports numbers and strings as custom variable values, 1017Icinga 2 extends that to arrays and (nested) dictionaries. For more details 1018look [here](03-monitoring-basics.md#custom-variables). 1019 1020### Host Service Relation <a id="differences-1x-2-host-service-relation"></a> 1021 1022In Icinga 1.x a service object is associated with a host by defining the 1023`host_name` attribute in the service definition. Alternate methods refer 1024to `hostgroup_name` or behaviour changing regular expression. 1025 1026The preferred way of associating hosts with services in Icinga 2 is by 1027using the [apply](03-monitoring-basics.md#using-apply) keyword. 1028 1029Direct object relations between a service and a host still allow you to use 1030the `host_name` [Service](09-object-types.md#objecttype-service) object attribute. 1031 1032### Users <a id="differences-1x-2-users"></a> 1033 1034Contacts have been renamed to users (same for groups). A contact does not 1035only provide (custom) attributes and notification commands used for notifications, 1036but is also used for authorization checks in Icinga 1.x. 1037 1038Icinga 2 changes that behavior and makes the user an attribute provider only. 1039These attributes can be accessed using [runtime macros](03-monitoring-basics.md#runtime-macros) 1040inside notification command definitions. 1041 1042In Icinga 2 notification commands are not directly associated with users. 1043Instead the notification command is specified inside `Notification` objects next to 1044user and user group relations. 1045 1046The `StatusDataWriter`, `IdoMySqlConnection` and `LivestatusListener` types will 1047provide the contact and contactgroups attributes for services for compatibility 1048reasons. These values are calculated from all services, their notifications, 1049and their users. 1050 1051### Macros <a id="differences-1x-2-macros"></a> 1052 1053Various object attributes and runtime variables can be accessed as macros in 1054commands in Icinga 1.x -- Icinga 2 supports all required [custom variables](03-monitoring-basics.md#custom-variables). 1055 1056#### Command Arguments <a id="differences-1x-2-command-arguments"></a> 1057 1058If you have previously used Icinga 1.x, you may already be familiar with 1059user and argument definitions (e.g., `USER1` or `ARG1`). Unlike in Icinga 1.x 1060the Icinga 2 custom variables may have arbitrary names and arguments are no 1061longer specified in the `check_command` setting. 1062 1063In Icinga 1.x arguments are specified in the `check_command` attribute and 1064are separated from the command name using an exclamation mark (`!`). 1065 1066Please check the migration hints for a detailed 1067[migration example](23-migrating-from-icinga-1x.md#manual-config-migration-hints-check-command-arguments). 1068 1069> **Note** 1070> 1071> The Icinga 1.x feature named `Command Expander` does not work with Icinga 2. 1072 1073#### Environment Macros <a id="differences-1x-2-environment-macros"></a> 1074 1075The global configuration setting `enable_environment_macros` does not exist in 1076Icinga 2. 1077 1078Macros exported into the [environment](03-monitoring-basics.md#command-environment-variables) 1079can be set using the `env` attribute in command objects. 1080 1081#### Runtime Macros <a id="differences-1x-2-runtime-macros"></a> 1082 1083Icinga 2 requires an object specific namespace when accessing configuration 1084and stateful runtime macros. Custom variables can be accessed directly. 1085 1086If a runtime macro from Icinga 1.x is not listed here, it is not supported 1087by Icinga 2. 1088 1089Changes to user (contact) runtime macros 1090 1091 Icinga 1.x | Icinga 2 1092 -----------------------|---------------------- 1093 CONTACTNAME | user.name 1094 CONTACTALIAS | user.display_name 1095 CONTACTEMAIL | user.email 1096 CONTACTPAGER | user.pager 1097 1098`CONTACTADDRESS*` is not supported but can be accessed as `$user.vars.address1$` 1099if set. 1100 1101Changes to service runtime macros 1102 1103 Icinga 1.x | Icinga 2 1104 -----------------------|---------------------- 1105 SERVICEDESC | service.name 1106 SERVICEDISPLAYNAME | service.display_name 1107 SERVICECHECKCOMMAND | service.check_command 1108 SERVICESTATE | service.state 1109 SERVICESTATEID | service.state_id 1110 SERVICESTATETYPE | service.state_type 1111 SERVICEATTEMPT | service.check_attempt 1112 MAXSERVICEATTEMPT | service.max_check_attempts 1113 LASTSERVICESTATE | service.last_state 1114 LASTSERVICESTATEID | service.last_state_id 1115 LASTSERVICESTATETYPE | service.last_state_type 1116 LASTSERVICESTATECHANGE | service.last_state_change 1117 SERVICEDOWNTIME | service.downtime_depth 1118 SERVICEDURATIONSEC | service.duration_sec 1119 SERVICELATENCY | service.latency 1120 SERVICEEXECUTIONTIME | service.execution_time 1121 SERVICEOUTPUT | service.output 1122 SERVICEPERFDATA | service.perfdata 1123 LASTSERVICECHECK | service.last_check 1124 SERVICENOTES | service.notes 1125 SERVICENOTESURL | service.notes_url 1126 SERVICEACTIONURL | service.action_url 1127 1128 1129Changes to host runtime macros 1130 1131 Icinga 1.x | Icinga 2 1132 -----------------------|---------------------- 1133 HOSTNAME | host.name 1134 HOSTADDRESS | host.address 1135 HOSTADDRESS6 | host.address6 1136 HOSTDISPLAYNAME | host.display_name 1137 HOSTALIAS | (use `host.display_name` instead) 1138 HOSTCHECKCOMMAND | host.check_command 1139 HOSTSTATE | host.state 1140 HOSTSTATEID | host.state_id 1141 HOSTSTATETYPE | host.state_type 1142 HOSTATTEMPT | host.check_attempt 1143 MAXHOSTATTEMPT | host.max_check_attempts 1144 LASTHOSTSTATE | host.last_state 1145 LASTHOSTSTATEID | host.last_state_id 1146 LASTHOSTSTATETYPE | host.last_state_type 1147 LASTHOSTSTATECHANGE | host.last_state_change 1148 HOSTDOWNTIME | host.downtime_depth 1149 HOSTDURATIONSEC | host.duration_sec 1150 HOSTLATENCY | host.latency 1151 HOSTEXECUTIONTIME | host.execution_time 1152 HOSTOUTPUT | host.output 1153 HOSTPERFDATA | host.perfdata 1154 LASTHOSTCHECK | host.last_check 1155 HOSTNOTES | host.notes 1156 HOSTNOTESURL | host.notes_url 1157 HOSTACTIONURL | host.action_url 1158 TOTALSERVICES | host.num_services 1159 TOTALSERVICESOK | host.num_services_ok 1160 TOTALSERVICESWARNING | host.num_services_warning 1161 TOTALSERVICESUNKNOWN | host.num_services_unknown 1162 TOTALSERVICESCRITICAL | host.num_services_critical 1163 1164Changes to command runtime macros 1165 1166 Icinga 1.x | Icinga 2 1167 -----------------------|---------------------- 1168 COMMANDNAME | command.name 1169 1170Changes to notification runtime macros 1171 1172 Icinga 1.x | Icinga 2 1173 -----------------------|---------------------- 1174 NOTIFICATIONTYPE | notification.type 1175 NOTIFICATIONAUTHOR | notification.author 1176 NOTIFICATIONCOMMENT | notification.comment 1177 NOTIFICATIONAUTHORNAME | (use `notification.author`) 1178 NOTIFICATIONAUTHORALIAS | (use `notification.author`) 1179 1180 1181Changes to global runtime macros: 1182 1183 Icinga 1.x | Icinga 2 1184 -----------------------|---------------------- 1185 TIMET | icinga.timet 1186 LONGDATETIME | icinga.long_date_time 1187 SHORTDATETIME | icinga.short_date_time 1188 DATE | icinga.date 1189 TIME | icinga.time 1190 PROCESSSTARTTIME | icinga.uptime 1191 1192Changes to global statistic macros: 1193 1194 Icinga 1.x | Icinga 2 1195 ----------------------------------|---------------------- 1196 TOTALHOSTSUP | icinga.num_hosts_up 1197 TOTALHOSTSDOWN | icinga.num_hosts_down 1198 TOTALHOSTSUNREACHABLE | icinga.num_hosts_unreachable 1199 TOTALHOSTSDOWNUNHANDLED | -- 1200 TOTALHOSTSUNREACHABLEUNHANDLED | -- 1201 TOTALHOSTPROBLEMS | down 1202 TOTALHOSTPROBLEMSUNHANDLED | down-(downtime+acknowledged) 1203 TOTALSERVICESOK | icinga.num_services_ok 1204 TOTALSERVICESWARNING | icinga.num_services_warning 1205 TOTALSERVICESCRITICAL | icinga.num_services_critical 1206 TOTALSERVICESUNKNOWN | icinga.num_services_unknown 1207 TOTALSERVICESWARNINGUNHANDLED | -- 1208 TOTALSERVICESCRITICALUNHANDLED | -- 1209 TOTALSERVICESUNKNOWNUNHANDLED | -- 1210 TOTALSERVICEPROBLEMS | ok+warning+critical+unknown 1211 TOTALSERVICEPROBLEMSUNHANDLED | warning+critical+unknown-(downtime+acknowledged) 1212 1213 1214 1215 1216### External Commands <a id="differences-1x-2-external-commands"></a> 1217 1218`CHANGE_CUSTOM_CONTACT_VAR` was renamed to `CHANGE_CUSTOM_USER_VAR`. 1219 1220The following external commands are not supported: 1221 1222``` 1223CHANGE_*MODATTR 1224CHANGE_CONTACT_HOST_NOTIFICATION_TIMEPERIOD 1225CHANGE_HOST_NOTIFICATION_TIMEPERIOD 1226CHANGE_SVC_NOTIFICATION_TIMEPERIOD 1227DEL_DOWNTIME_BY_HOSTGROUP_NAME 1228DEL_DOWNTIME_BY_START_TIME_COMMENT 1229DISABLE_ALL_NOTIFICATIONS_BEYOND_HOST 1230DISABLE_CONTACT_HOST_NOTIFICATIONS 1231DISABLE_CONTACT_SVC_NOTIFICATIONS 1232DISABLE_CONTACTGROUP_HOST_NOTIFICATIONS 1233DISABLE_CONTACTGROUP_SVC_NOTIFICATIONS 1234DISABLE_FAILURE_PREDICTION 1235DISABLE_HOST_AND_CHILD_NOTIFICATIONS 1236DISABLE_HOST_FRESHNESS_CHECKS 1237DISABLE_NOTIFICATIONS_EXPIRE_TIME 1238DISABLE_SERVICE_FRESHNESS_CHECKS 1239ENABLE_ALL_NOTIFICATIONS_BEYOND_HOST 1240ENABLE_CONTACT_HOST_NOTIFICATIONS 1241ENABLE_CONTACT_SVC_NOTIFICATIONS 1242ENABLE_CONTACTGROUP_HOST_NOTIFICATIONS 1243ENABLE_CONTACTGROUP_SVC_NOTIFICATIONS 1244ENABLE_FAILURE_PREDICTION 1245ENABLE_HOST_AND_CHILD_NOTIFICATIONS 1246ENABLE_HOST_FRESHNESS_CHECKS 1247ENABLE_SERVICE_FRESHNESS_CHECKS 1248READ_STATE_INFORMATION 1249SAVE_STATE_INFORMATION 1250SET_HOST_NOTIFICATION_NUMBER 1251SET_SVC_NOTIFICATION_NUMBER 1252START_ACCEPTING_PASSIVE_HOST_CHECKS 1253START_ACCEPTING_PASSIVE_SVC_CHECKS 1254START_OBSESSING_OVER_HOST 1255START_OBSESSING_OVER_HOST_CHECKS 1256START_OBSESSING_OVER_SVC 1257START_OBSESSING_OVER_SVC_CHECKS 1258STOP_ACCEPTING_PASSIVE_HOST_CHECKS 1259STOP_ACCEPTING_PASSIVE_SVC_CHECKS 1260STOP_OBSESSING_OVER_HOST 1261STOP_OBSESSING_OVER_HOST_CHECKS 1262STOP_OBSESSING_OVER_SVC 1263STOP_OBSESSING_OVER_SVC_CHECKS 1264``` 1265 1266### Asynchronous Event Execution <a id="differences-1x-2-async-event-execution"></a> 1267 1268Unlike Icinga 1.x, Icinga 2 does not block when it's waiting for a command 1269being executed -- whether if it's a check, a notification, an event 1270handler, a performance data writing update, etc. That way you'll 1271recognize low to zero (check) latencies with Icinga 2. 1272 1273### Checks <a id="differences-1x-2-checks"></a> 1274 1275#### Check Output <a id="differences-1x-2-check-output"></a> 1276 1277Icinga 2 does not make a difference between `output` (first line) and 1278`long_output` (remaining lines) like in Icinga 1.x. Performance Data is 1279provided separately. 1280 1281There is no output length restriction as known from Icinga 1.x using an 1282[8KB static buffer](https://docs.icinga.com/latest/en/pluginapi.html#outputlengthrestrictions). 1283 1284The `StatusDataWriter`, `IdoMysqlConnection` and `LivestatusListener` types 1285split the raw output into `output` (first line) and `long_output` (remaining 1286lines) for compatibility reasons. 1287 1288#### Initial State <a id="differences-1x-2-initial-state"></a> 1289 1290Icinga 1.x uses the `max_service_check_spread` setting to specify a timerange 1291where the initial state checks must have happened. Icinga 2 will use the 1292`retry_interval` setting instead and `check_interval` divided by 5 if 1293`retry_interval` is not defined. 1294 1295### Comments <a id="differences-1x-2-comments"></a> 1296 1297Icinga 2 doesn't support non-persistent comments. 1298 1299### Commands <a id="differences-1x-2-commands"></a> 1300 1301Unlike in Icinga 1.x there are three different command types in Icinga 2: 1302`CheckCommand`, `NotificationCommand`, and `EventCommand`. 1303 1304For example in Icinga 1.x it is possible to accidentally use a notification 1305command as an event handler which might cause problems depending on which 1306runtime macros are used in the notification command. 1307 1308In Icinga 2 these command types are separated and will generate an error on 1309configuration validation if used in the wrong context. 1310 1311While Icinga 2 still supports the complete command line in command objects, it's 1312recommended to use [command arguments](03-monitoring-basics.md#command-arguments) 1313with optional and conditional command line parameters instead. 1314 1315It's also possible to define default argument values for the command itself 1316which can be overridden by the host or service then. 1317 1318#### Command Timeouts <a id="differences-1x-2-commands-timeouts"></a> 1319 1320In Icinga 1.x there were two global options defining a host and service check 1321timeout. This was essentially bad when there only was a couple of check plugins 1322requiring some command timeouts to be extended. 1323 1324Icinga 2 allows you to specify the command timeout directly on the command. So, 1325if your VMVware check plugin takes 15 minutes, [increase the timeout](09-object-types.md#objecttype-checkcommand) 1326accordingly. 1327 1328 1329### Groups <a id="differences-1x-2-groups"></a> 1330 1331In Icinga 2 hosts, services, and users are added to groups using the `groups` 1332attribute in the object. The old way of listing all group members in the group's 1333`members` attribute is available through `assign where` and `ignore where` 1334expressions by using [group assign](03-monitoring-basics.md#group-assign-intro). 1335 1336``` 1337object Host "web-dev" { 1338 import "generic-host" 1339} 1340 1341object HostGroup "dev-hosts" { 1342 display_name = "Dev Hosts" 1343 assign where match("*-dev", host.name) 1344} 1345``` 1346 1347#### Add Service to Hostgroup where Host is Member <a id="differences-1x-2-service-hostgroup-host"></a> 1348 1349In order to associate a service with all hosts in a host group the [apply](03-monitoring-basics.md#using-apply) 1350keyword can be used: 1351 1352``` 1353apply Service "ping4" { 1354 import "generic-service" 1355 1356 check_command = "ping4" 1357 1358 assign where "dev-hosts" in host.groups 1359} 1360``` 1361 1362### Notifications <a id="differences-1x-2-notifications"></a> 1363 1364Notifications are a new object type in Icinga 2. Imagine the following 1365notification configuration problem in Icinga 1.x: 1366 1367* Service A should notify contact X via SMS 1368* Service B should notify contact X via Mail 1369* Service C should notify contact Y via Mail and SMS 1370* Contact X and Y should also be used for authorization 1371 1372The only way achieving a semi-clean solution is to 1373 1374* Create contact X-sms, set service_notification_command for sms, assign contact 1375 to service A 1376* Create contact X-mail, set service_notification_command for mail, assign 1377 contact to service B 1378* Create contact Y, set service_notification_command for sms and mail, assign 1379 contact to service C 1380* Create contact X without notification commands, assign to service A and B 1381 1382Basically you are required to create duplicated contacts for either each 1383notification method or used for authorization only. 1384 1385Icinga 2 attempts to solve that problem in this way 1386 1387* Create user X, set SMS and Mail attributes, used for authorization 1388* Create user Y, set SMS and Mail attributes, used for authorization 1389* Create notification A-SMS, set command for sms, add user X, 1390 assign notification A-SMS to service A 1391* Create notification B-Mail, set command for mail, add user X, 1392 assign notification Mail to service B 1393* Create notification C-SMS, set command for sms, add user Y, 1394 assign notification C-SMS to service C 1395* Create notification C-Mail, set command for mail, add user Y, 1396 assign notification C-Mail to service C 1397 1398Previously in Icinga 1.x it looked like this: 1399 1400``` 1401service -> (contact, contactgroup) -> notification command 1402``` 1403 1404In Icinga 2 it will look like this: 1405 1406``` 1407Service -> Notification -> NotificationCommand 1408 -> User, UserGroup 1409``` 1410 1411#### Escalations <a id="differences-1x-2-escalations"></a> 1412 1413Escalations in Icinga 1.x require a separated object matching on existing 1414objects. Escalations happen between a defined start and end time which is 1415calculated from the notification_interval: 1416 1417``` 1418start = notification start + (notification_interval * first_notification) 1419end = notification start + (notification_interval * last_notification) 1420``` 1421 1422In theory first_notification and last_notification can be set to readable 1423numbers. In practice users are manipulating those attributes in combination 1424with notification_interval in order to get a start and end time. 1425 1426In Icinga 2 the notification object can be used as notification escalation 1427if the start and end times are defined within the 'times' attribute using 1428duration literals (e.g. 30m). 1429 1430The Icinga 2 escalation does not replace the current running notification. 1431In Icinga 1.x it's required to copy the contacts from the service notification 1432to the escalation to guarantee the normal notifications once an escalation 1433happens. 1434That's not necessary with Icinga 2 only requiring an additional notification 1435object for the escalation itself. 1436 1437#### Notification Options <a id="differences-1x-2-notification-options"></a> 1438 1439Unlike Icinga 1.x with the 'notification_options' attribute with comma-separated 1440state and type filters, Icinga 2 uses two configuration attributes for that. 1441All state and type filter use long names OR'd with a pipe together 1442 1443``` 1444notification_options w,u,c,r,f,s 1445 1446states = [ Warning, Unknown, Critical ] 1447types = [ Problem, Recovery, FlappingStart, FlappingEnd, DowntimeStart, DowntimeEnd, DowntimeRemoved ] 1448``` 1449 1450Icinga 2 adds more fine-grained type filters for acknowledgements, downtime, 1451and flapping type (start, end, ...). 1452 1453### Dependencies and Parents <a id="differences-1x-2-dependencies-parents"></a> 1454 1455In Icinga 1.x it's possible to define host parents to determine network reachability 1456and keep a host's state unreachable rather than down. 1457Furthermore there are host and service dependencies preventing unnecessary checks and 1458notifications. A host must not depend on a service, and vice versa. All dependencies 1459are configured as separate objects and cannot be set directly on the host or service 1460object. 1461 1462A service can now depend on a host, and vice versa. A service has an implicit dependency 1463(parent) to its host. A host to host dependency acts implicitly as host parent relation. 1464 1465The former `host_name` and `dependent_host_name` have been renamed to `parent_host_name` 1466and `child_host_name` (same for the service attribute). When using apply rules the 1467child attributes may be omitted. 1468 1469For detailed examples on how to use the dependencies please check the [dependencies](03-monitoring-basics.md#dependencies) 1470chapter. 1471 1472Dependencies can be applied to hosts or services using the [apply rules](17-language-reference.md#apply). 1473 1474The `StatusDataWriter`, `IdoMysqlConnection` and `LivestatusListener` types 1475support the Icinga 1.x schema with dependencies and parent attributes for 1476compatibility reasons. 1477 1478### Flapping <a id="differences-1x-2-flapping"></a> 1479 1480The Icinga 1.x flapping detection uses the last 21 states of a service. This 1481value is hardcoded and cannot be changed. The algorithm on determining a flapping state 1482is as follows: 1483 1484``` 1485flapping value = (number of actual state changes / number of possible state changes) 1486``` 1487 1488The flapping value is then compared to the low and high flapping thresholds. 1489 1490The algorithm used in Icinga 2 does not store the past states but calculates the flapping 1491threshold from a single value based on counters and half-life values. Icinga 2 compares 1492the value with a single flapping threshold configuration attribute. 1493 1494### Check Result Freshness <a id="differences-1x-2-check-result-freshness"></a> 1495 1496Freshness of check results must be enabled explicitly in Icinga 1.x. The attribute 1497`freshness_threshold` defines the threshold in seconds. Once the threshold is triggered, an 1498active freshness check is executed defined by the `check_command` attribute. Both check 1499methods (active and passive) use the same freshness check method. 1500 1501In Icinga 2 active check freshness is determined by the `check_interval` attribute and no 1502incoming check results in that period of time (last check + check interval). Passive check 1503freshness is calculated from the `check_interval` attribute if set. There is no extra 1504`freshness_threshold` attribute in Icinga 2. If the freshness checks are invalid, a new 1505service check is forced. 1506 1507### Real Reload <a id="differences-1x-2-real-reload"></a> 1508 1509In Nagios / Icinga 1.x a daemon reload does the following: 1510 1511* receive reload signal SIGHUP 1512* stop all events (checks, notifications, etc.) 1513* read the configuration from disk and validate all config objects in a single threaded fashion 1514* validation NOT ok: stop the daemon (cannot restore old config state) 1515* validation ok: start with new objects, dump status.dat / ido 1516 1517Unlike Icinga 1.x the Icinga 2 daemon reload does not block any event 1518execution during config validation: 1519 1520* receive reload signal SIGHUP 1521* fork a child process, start configuration validation in parallel work queues 1522* parent process continues with old configuration objects and the event scheduling 1523(doing checks, replicating cluster events, triggering alert notifications, etc.) 1524* validation NOT ok: child process terminates, parent process continues with old configuration state 1525(this is **essential** for the [cluster config synchronisation](06-distributed-monitoring.md#distributed-monitoring-top-down-config-sync)) 1526* validation ok: child process signals parent process to terminate and save its current state 1527(all events until now) into the icinga2 state file 1528* parent process shuts down writing icinga2.state file 1529* child process waits for parent process gone, reads the icinga2 state file and synchronizes all historical and status data 1530* child becomes the new session leader 1531 1532The DB IDO configuration dump and status/historical event updates use a queue 1533not blocking event execution. Same goes for any other enabled feature. 1534The configuration validation itself runs in parallel allowing fast verification checks. 1535 1536That way your monitoring does not stop during a configuration reload. 1537 1538 1539### State Retention <a id="differences-1x-2-state-retention"></a> 1540 1541Icinga 1.x uses the `retention.dat` file to save its state in order to be able 1542to reload it after a restart. In Icinga 2 this file is called `icinga2.state`. 1543 1544The format is **not** compatible with Icinga 1.x. 1545 1546### Logging <a id="differences-1x-2-logging"></a> 1547 1548Icinga 1.x supports syslog facilities and writes its own `icinga.log` log file 1549and archives. These logs are used in Icinga 1.x to generate 1550historical reports. 1551 1552Icinga 2 compat library provides the CompatLogger object which writes the icinga.log and archive 1553in Icinga 1.x format in order to stay compatible with addons. 1554 1555The native Icinga 2 logging facilities are split into three configuration objects: SyslogLogger, 1556FileLogger, StreamLogger. Each of them has their own severity and target configuration. 1557 1558The Icinga 2 daemon log does not log any alerts but is considered an application log only. 1559 1560### Broker Modules and Features <a id="differences-1x-2-broker-modules-features"></a> 1561 1562Icinga 1.x broker modules are incompatible with Icinga 2. 1563 1564In order to provide compatibility with Icinga 1.x the functionality of several 1565popular broker modules was implemented for Icinga 2: 1566 1567* IDOUtils 1568* Livestatus 1569* Cluster (allows for high availability and load balancing) 1570 1571 1572### Distributed Monitoring <a id="differences-1x-2-distributed-monitoring"></a> 1573 1574Icinga 1.x uses the native "obsess over host/service" method which requires the NSCA addon 1575passing the slave's check results passively onto the master's external command pipe. 1576While this method may be used for check load distribution, it does not provide any configuration 1577distribution out-of-the-box. Furthermore comments, downtimes, and other stateful runtime data is 1578not synced between the master and slave nodes. There are addons available solving the check 1579and configuration distribution problems Icinga 1.x distributed monitoring currently suffers from. 1580 1581Icinga 2 implements a new built-in 1582[distributed monitoring architecture](06-distributed-monitoring.md#distributed-monitoring-scenarios), 1583including config and check distribution, IPv4/IPv6 support, TLS certificates and zone support for DMZ. 1584High Availability and load balancing are also part of the Icinga 2 Cluster feature, next to local replay 1585logs on connection loss ensuring that the event history is kept in sync. 1586