1 # <a id="differences-1x-2"></a> Differences between Icinga 1.x and 2
3 ## <a id="differences-1x-2-configuration-format"></a> Configuration Format
5 Icinga 1.x supports two configuration formats: key-value-based settings in the
6 `icinga.cfg` configuration file and object-based in included files (`cfg_dir`,
7 `cfg_file`). The path to the `icinga.cfg` configuration file must be passed to
8 the Icinga daemon at startup.
10 enable_notifications=1
13 notifications_enabled 0
16 Icinga 2 supports objects and (global) variables, but does not make a difference
17 if it's the main configuration file, or any included file.
19 const EnableNotifications = true
21 object Service "test" {
22 enable_notifications = 0
25 ### <a id="differences-1x-2-sample-configuration-itl"></a> Sample Configuration and ITL
27 While Icinga 1.x ships sample configuration and templates spread in various
28 object files Icinga 2 moves all templates into the Icinga Template Library (ITL)
29 and includes that in the sample configuration.
31 The ITL will be updated on every release and should not be edited by the user.
33 There are still generic templates available for your convenience which may or may
34 not be re-used in your configuration. For instance, `generic-service` includes
35 all required attributes except `check_command` for an inline service.
37 Sample configuration files are located in the `conf.d/` directory which is
38 included in `icinga2.conf` by default.
40 ### <a id="differences-1x-2-include-files-dirs"></a> Include Files and Directories
42 In Icinga 1.x the `icinga.cfg` file contains `cfg_file` and `cfg_dir`
43 directives. The `cfg_dir` directive recursively includes all files with a `.cfg`
44 suffix in the given directory. Only absolute paths may be used. The `cfg_file`
45 and `cfg_dir` directives can include the same file twice which leads to
46 configuration errors in Icinga 1.x.
48 cfg_file=/etc/icinga/objects/commands.cfg
49 cfg_dir=/etc/icinga/objects
51 Icinga 2 supports wildcard includes and relative paths, e.g. for including
52 `conf.d/*.conf` in the same directory.
54 include "conf.d/*.conf"
56 If you want to include files and directories recursively, you need to define
57 a separate option and add the directory and an option pattern.
59 include_recursive "conf.d" "*.conf"
61 A global search path for includes is available for advanced features like
62 the Icinga Template Library (ITL). The file suffix does not matter as long
63 as it matches the (wildcard) include expression.
65 include <itl/itl.conf>
67 By convention the `.conf` suffix is used for Icinga 2 configuration files.
69 ## <a id="differences-1x-2-resource-file-global-macros"></a> Resource File and Global Macros
71 Global macros such as for the plugin directory, usernames and passwords can be
72 set in the `resource.cfg` configuration file in Icinga 1.x. By convention the
73 `USER1` macro is used to define the directory for the plugins.
75 Icinga 2 uses global constants instead. In the default config these are
76 set in the `constants.conf` configuration file:
79 * This file defines global constants which can be used in
80 * the other configuration files. At a minimum the
81 * PluginDir constant should be defined.
84 const PluginDir = "/usr/lib/nagios/plugins"
86 [Global macros](#global-constants) can only be defined once. Trying to modify a
87 global constant will result in an error.
89 ## <a id="differences-1x-2-comments"></a> Comments
91 In Icinga 1.x comments are made using a leading hash (`#`) or a semi-colon (`;`)
94 In Icinga 2 comments can either be encapsulated by `/*` and `*/` (allowing for
95 multi-line comments) or starting with two slashes (`//`).
97 ## <a id="differences-1x-2-object-names"></a> Object names
99 Object names must not contain a colon (`!`). Use the `display_name` attribute
100 to specify user-friendly names which should be shown in UIs (supported by
101 Icinga 1.x Classic UI and Web).
103 Object names are not specified using attributes (e.g. `service_description` for
104 services) like in Icinga 1.x but directly after their type definition.
108 service_description ping4
111 object Service "ping4" {
112 host_name = "localhost"
115 ## <a id="differences-1x-2-templates"></a> Templates
117 In Icinga 1.x templates are identified using the `register 0` setting. Icinga 2
118 uses the `template` identifier:
120 template Service "ping4-template" { }
122 Icinga 1.x objects inherit from templates using the `use` attribute.
123 Icinga 2 uses the keyword `import` with template names in double quotes.
126 service_description testservice
127 use tmpl1,tmpl2,tmpl3
130 object Service "testservice" {
136 ## <a id="differences-1x-2-object-attributes"></a> Object attributes
138 Icinga 1.x separates attribute and value with whitespaces/tabs. Icinga 2
139 requires an equal sign (=) between them.
145 object Service "test" {
149 Please note that the default time value is seconds, if no duration literal
150 is given. `check_interval = 5` behaves the same as `check_interval = 5s`.
152 All strings require double quotes in Icinga 2. Therefore a double-quote
153 must be escaped with a backslash (e.g. in command line).
154 If an attribute identifier starts with a number, it must be encapsulated
155 with double quotes as well.
157 ### <a id="differences-1x-2-alias-display-name"></a> Alias vs. Display Name
159 In Icinga 1.x a host can have an `alias` and a `display_name` attribute used
160 for a more descriptive name. A service only can have a `display_name` attribute.
161 The `alias` is used for group, timeperiod, etc. objects too.
162 Icinga 2 only supports the `display_name` attribute which is also taken into
163 account by Icinga 1.x Classic UI and Web.
165 ## <a id="differences-1x-2-custom-attributes"></a> Custom Attributes
167 Icinga 2 allows you to define custom attributes in the `vars` dictionary.
169 ### <a id="differences-1x-2-action-url-notes-url-notes"></a> Action Url, Notes Url, Notes
171 Icinga 1.x objects support configuration attributes not required as runtime
172 values but for external resources such as Icinga 1.x Classic UI or Web.
173 The `notes`, `notes_url`, `action_url`, `icon_image`, `icon_image_alt`
174 attributes for host and service objects, additionally `statusmap_image` and
175 `2d_coords` for the host's representation in status maps.
177 These attributes can be set using the `vars` dictionary in Icinga 2 `Host`
178 or `Service` objects:
181 notes = "Icinga 2 is the best!"
182 notes_url = "http://docs.icinga.org"
183 action_url = "http://dev.icinga.org"
184 icon_image = "../../images/logos/Stats2.png"
185 icon_image_alt = "icinga2 alt icon text"
187 statusmap_image = "../../images/logos/icinga.gif"
190 External interfaces will recognize and display these attributes accordingly.
192 ### <a id="differences-1x-2-custom-variables"></a> Custom Variables
194 Icinga 1.x custom variable attributes must be prefixed using an underscore (`_`).
195 In Icinga 2 these attributes must be added to the `vars` dictionary as custom attributes.
198 DN = "cn=icinga2-dev-host,ou=icinga,ou=main,ou=IcingaConfig,ou=LConf,dc=icinga,dc=org"
199 CV = "my custom cmdb description"
204 ## <a id="differences-1x-2-host-service-relation"></a> Host Service Relation
206 In Icinga 1.x a service object is associated with a host by defining the
207 `host_name` attribute in the service definition. Alternate methods refer
208 to `hostgroup_name` or behavior changing regular expression. It's not possible
209 to define a service definition within a host definition.
211 The preferred way of associating hosts with services in Icinga 2 is by
212 using the `apply` keyword.
214 ## <a id="differences-1x-2-users"></a> Users
216 Contacts have been renamed to Users (same for groups). A user does not
217 only provide attributes and custom attributes used for notifications, but is also
218 used for authorization checks.
220 In Icinga 2 notification commands are not directly associated with users.
221 Instead the notification command is specified using `Notification` objects.
223 The `StatusDataWriter`, `IdoMySqlConnection` and `LivestatusListener` types will
224 provide the contact and contactgroups attributes for services for compatibility
225 reasons. These values are calculated from all services, their notifications,
228 ## <a id="differences-1x-2-macros"></a> Macros
232 Various object attributes and runtime variables can be accessed as macros in
233 commands in Icinga 1.x - Icinga 2 supports all required [custom attributes](#custom-attributes).
235 ### <a id="differences-1x-2-command-arguments"></a> Command Arguments
237 If you have previously used Icinga 1.x you may already be familiar with
238 user and argument definitions (e.g., `USER1` or `ARG1`). Unlike in Icinga 1.x
239 the Icinga 2 custom attributes may have arbitrary names and arguments are no
240 longer specified in the `check_command` setting.
242 In Icinga 1.x arguments are specified in the `check_command` attribute and
243 are separated from the command name using an exclamation mark (`!`).
247 command_line $USER1$/check_ping -H $address$ -w $ARG1$ -c $ARG2$ -p 5
253 service_description PING
254 check_command ping4!100.0,20%!500.0,60%
257 With the freely definable custom attributes in Icinga 2 it looks like this:
259 object CheckCommand "ping4" {
260 command = PluginDir + "/check_ping -H $address$ -w $wrta$,$wpl%$ -c $crta$,$cpl%$"
263 object Service "PING" {
264 check_command = "ping4"
271 ### <a id="differences-1x-2-environment-macros"></a> Environment Macros
275 The global configuration setting `enable_environment_macros` does not exist in
278 Macros exported into the environment must be set using the `env`
279 attribute in command objects.
281 ### <a id="differences-1x-2-runtime-macros"></a> Runtime Macros
283 Icinga 2 requires an object specific namespace when accessing configuration
284 and stateful runtime macros. Custom attributes can be access directly.
286 Changes to host runtime macros
288 Icinga 1.x | Icinga 2
289 -----------------------|----------------------
291 USERDISPLAYNAME | user.displayname
292 USEREMAIL | email if set as `email` custom attribute.
293 USERPAGER | pager if set as `pager` custom attribute.
296 Changes to service runtime macros
298 Icinga 1.x | Icinga 2
299 -----------------------|----------------------
300 SERVICEDESC | service.description
301 SERVICEDISPLAYNAME | service.displayname
302 SERVICECHECKCOMMAND | service.checkcommand
303 SERVICESTATE | service.state
304 SERVICESTATEID | service.stateid
305 SERVICESTATETYPE | service.statetype
306 SERVICEATTEMPT | service.attempt
307 MAXSERVICEATTEMPT | service.maxattempt
308 LASTSERVICESTATE | service.laststate
309 LASTSERVICESTATEID | service.laststateid
310 LASTSERVICESTATETYPE | service.laststatetype
311 LASTSERVICESTATECHANGE | service.laststatechange
312 SERVICEDURATIONSEC | service.durationsec
313 SERVICELATENCY | service.latency
314 SERVICEEXECUTIONTIME | service.executiontime
315 SERVICEOUTPUT | service.output
316 SERVICEPERFDATA | service.perfdata
317 LASTSERVICECHECK | service.lastcheck
320 Changes to user (contact) runtime macros
322 Icinga 1.x | Icinga 2
323 -----------------------|----------------------
325 HOSTDISPLAYNAME | host.displayname
327 HOSTSTATE | host.state
328 HOSTSTATEID | host.stateid
329 HOSTSTATETYPE | host.statetype
330 HOSTATTEMPT | host.attempt
331 MAXHOSTATTEMPT | host.maxattempt
332 LASTHOSTSTATE | host.laststate
333 LASTHOSTSTATEID | host.laststateid
334 LASTHOSTSTATETYPE | host.laststatetype
335 LASTHOSTSTATECHANGE | host.laststatechange
336 HOSTDURATIONSEC | host.durationsec
337 HOSTLATENCY | host.latency
338 HOSTEXECUTIONTIME | host.executiontime
339 HOSTOUTPUT | host.output
340 HOSTPERFDATA | host.perfdata
341 LASTHOSTCHECK | host.lastcheck
345 Changes to global runtime macros:
347 Icinga 1.x | Icinga 2
348 -----------------------|----------------------
350 LONGDATETIME | icinga.longdatetime
351 SHORTDATETIME | icinga.shortdatetime
356 ## <a id="differences-1x-2-checks"></a> Checks
358 ### <a id="differences-1x-2-check-output"></a> Check Output
360 Icinga 2 does not make a difference between `output` (first line) and
361 `long_output` (remaining lines) like in Icinga 1.x. Performance Data is
364 The `StatusDataWriter`, `IdoMysqlConnection` and `LivestatusListener` types
365 split the raw output into `output` (first line) and `long_output` (remaining
366 lines) for compatibility reasons.
368 ### <a id="differences-1x-2-initial-state"></a> Initial State
370 Icinga 1.x uses the `max_service_check_spread` setting to specify a timerange
371 where the initial state checks must have happened. Icinga 2 will use the
372 `retry_interval` setting instead and `check_interval` divided by 5 if
373 `retry_interval` is not defined.
375 ## <a id="differences-1x-2-commands"></a> Commands
377 Unlike in Icinga 1.x there are 3 different command types in Icinga 2:
378 `CheckCommand`, `NotificationCommand` and EventCommand`.
380 For example in Icinga 1.x it is possible to accidently use a notification
381 command as an event handler which might cause problems depending on which
382 runtime macros are used in the notification command.
384 In Icinga 2 these command types are separated and will generate an error on
385 configuration validation if used in the wrong context.
387 While Icinga 2 still supports the complete command line in command objects, it's
388 also possible to encapsulate all arguments into double quotes and passing them
389 as array to the `command_line` attribute i.e. for better readability.
391 It's also possible to define default custom attributes for the command itself which can be
392 overridden by a service macro.
394 ## <a id="differences-1x-2-groups"></a> Groups
396 In Icinga 2 hosts, services and users are added to groups using the `groups`
397 attribute in the object. The old way of listing all group members in the group's
398 `members` attribute is not supported.
400 The preferred way of assigning objects to groups is by using a template:
402 template Host "dev-host" {
403 groups += [ "dev-hosts" ]
406 object Host "web-dev" {
410 In order to associate a service with all hosts in a host group the `apply`
413 apply Service "ping" {
414 import "generic-service"
416 check_command = "ping4"
418 assign where "group" in host.groups
421 ## <a id="differences-1x-2-notifications"></a> Notifications
423 Notifications are a new object type in Icinga 2. Imagine the following
424 notification configuration problem in Icinga 1.x:
426 * Service A should notify contact X via SMS
427 * Service B should notify contact X via Mail
428 * Service C should notify contact Y via Mail and SMS
429 * Contact X and Y should also be used for authorization (e.g. in Classic UI)
431 The only way achieving a semi-clean solution is to
433 * Create contact X-sms, set service_notification_command for sms, assign contact
435 * Create contact X-mail, set service_notification_command for mail, assign
437 * Create contact Y, set service_notification_command for sms and mail, assign
439 * Create contact X without notification commands, assign to service A and B
441 Basically you are required to create duplicated contacts for either each
442 notification method or used for authorization only.
444 Icinga 2 attempts to solve that problem in this way
446 * Create user X, set SMS and Mail attributes, used for authorization
447 * Create user Y, set SMS and Mail attributes, used for authorization
448 * Create notification A-SMS, set command for sms, add user X,
449 assign notification A-SMS to service A
450 * Create notification B-Mail, set command for mail, add user X,
451 assign notification Mail to service B
452 * Create notification C-SMS, set command for sms, add user Y,
453 assign notification C-SMS to service C
454 * Create notification C-Mail, set command for mail, add user Y,
455 assign notification C-Mail to service C
457 Previously in Icinga 1.x it looked like this:
459 service -> (contact, contactgroup) -> notification command
461 In Icinga 2 it will look like this:
463 Service -> Notification -> NotificationCommand
466 ### <a id="differences-1x-2-escalations"></a> Escalations
468 Escalations in Icinga 1.x require a separated object matching on existing
469 objects. Escalations happen between a defined start and end time which is
470 calculated from the notification_interval:
472 start = notification start + (notification_interval * first_notification)
473 end = notification start + (notification_interval * last_notification)
475 In theory first_notification and last_notification can be set to readable
476 numbers. In practice users are manipulating those attributes in combination
477 with notification_interval in order to get a start and end time.
479 In Icinga 2 the notification object can be used as notification escalation
480 if the start and end times are defined within the 'times' attribute using
481 duration literals (e.g. 30m).
483 The Icinga 2 escalation does not replace the current running notification.
484 In Icinga 1.x it's required to copy the contacts from the service notification
485 to the escalation to garantuee the normal notifications once an escalation
487 That's not necessary with Icinga 2 only requiring an additional notification
488 object for the escalation itself.
490 ### <a id="differences-1x-2-notification-options"></a> Notification Options
494 Unlike Icinga 1.x with the 'notification_options' attribute with comma-separated
495 state and type filters, Icinga 2 uses two configuration attributes for that.
496 All state and type filter use long names or'd with a pipe together
498 notification_options w,u,c,r,f,s
500 states = [ Warning, Unknown, Critical ]
501 filters = [ Problem, Recovery, FlappingStart, FlappingEnd, DowntimeStart, DowntimeEnd, DowntimeRemoved ]
503 Icinga 2 adds more fine-grained type filters for acknowledgements, downtime
504 and flapping type (start, end, ...).
506 ## <a id="differences-1x-2-dependencies-parents"></a> Dependencies and Parents
508 In Icinga 1.x it's possible to define host parents to determine network reachability
509 and keep a host's state unreachable rather than down.
510 Furthermore there are host and service dependencies preventing unnecessary checks and
511 notifications. A host must not depend on a service, and vice versa. All dependencies
512 are configured as separate objects and cannot be set directly on the host or service
515 Icinga 2 adds host and service dependencies as attribute directly onto the host or
516 service object or template. A service can now depend on a host, and vice versa. A
517 service has an implicit dependeny (parent) to its host. A host to host dependency acts
518 implicit as host parent relation.
520 The `StatusDataWriter`, `IdoMysqlConnection` and `LivestatusListener` types
521 support the Icinga 1.x schema with dependencies and parent attributes for
522 compatibility reasons.
524 ## <a id="differences-1x-2-flapping"></a> Flapping
526 The Icinga 1.x flapping detection uses the last 21 states of a service. This
527 value is hardcoded and cannot be changed. The algorithm on determining a flapping state
530 flapping value = (number of actual state changes / number of possible state changes)
532 The flapping value is then compared to the low and high flapping thresholds.
534 The algorithm used in Icinga 2 does not store the past states but calculcates the flapping
535 threshold from a single value based on counters and half-life values. Icinga 2 compares
536 the value with a single flapping threshold configuration attribute.
538 ## <a id="differences-1x-2-check-result-freshness"></a> Check Result Freshness
540 Freshness of check results must be explicitely enabled in Icinga 1.x. The attribute
541 `freshness_treshold` defines the threshold in seconds. Once the threshold is triggered, an
542 active freshness check is executed defined by the `check_command` attribute. Both check
543 methods (active and passive) use the same freshness check method.
545 In Icinga 2 active check freshness is determined by the `check_interval` attribute and no
546 incoming check results in that period of time (last check + check interval). Passive check
547 freshness is calculated from the `check_interval` attribute if set. There is no extra
548 `freshness_threshold` attribute in Icinga 2. If the freshness checks are invalid, a new
549 service check is forced.
551 ## <a id="differences-1x-2-state-retention"></a> State Retention
553 Icinga 1.x uses the `retention.dat` file to save its state in order to be able
554 to reload it after a restart. In Icinga 2 this file is called `icinga2.state`.
556 The format objects are stored in is not compatible with Icinga 1.x.
558 ## <a id="differences-1x-2-logging"></a> Logging
560 Icinga 1.x supports syslog facilities and writes its own `icinga.log` log file
561 and archives. These logs are used in Icinga 1.x Classic UI to generate
564 Icinga 2 compat library provides the CompatLogger object which writes the icinga.log and archive
565 in Icinga 1.x format in order to stay compatible with Classic UI and other addons.
566 The native Icinga 2 logging facilities are split into three configuration objects: SyslogLogger,
567 FileLogger, StreamLogger. Each of them got their own severity and target configuration.
570 ## <a id="differences-1x-2-broker-modules-features"></a> Broker Modules and Features
572 Icinga 1.x broker modules are incompatible with Icinga 2.
574 In order to provide compatibility with Icinga 1.x the functionality of several
575 popular broker modules was implemented for Icinga 2:
579 * Cluster (allows for high availability and load balancing)
581 In Icinga 1.x broker modules may only be loaded once which means it is not easily possible
582 to have one Icinga instance write to multiple IDO databases. Due to the way
583 objects work in Icinga 2 it is possible to set up multiple IDO database instances.
586 ## <a id="differences-1x-2-distributed-monitoring"></a> Distributed Monitoring
588 Icinga 1.x uses the native "obsess over host/service" method which requires the NSCA addon
589 passing the slave's checkresults passively onto the master's external command pipe.
590 While this method may be used for check load distribution, it does not provide any configuration
591 distribution out-of-the-box. Furthermore comments, downtimes and other stateful runtime data is
592 not synced between the master and slave nodes. There are addons available solving the check
593 and configuration distribution problems Icinga 1.x distributed monitoring currently suffers from.
595 Icinga 2 implements a new built-in distributed monitoring architecture, including config and check
596 distribution, IPv4/IPv6 support, SSL certificates and domain support for DMZ. High Availability
597 and load balancing are also part of the Icinga 2 [Cluster](#cluster) setup.