## Configuration Migration
-There are plenty of differences and behavior changes introduced with the new
-Icinga 2 configuration format. In order to ease migration from Icinga 1.x,
+The Icinga 2 configuration format introduces plenty of behavioral changes. In
+order to ease migration from Icinga 1.x,
Icinga 2 ships its own config conversion script.
### Configuration Conversion Script
Due to the complexity of the Icinga 1.x configuration format the conversion
-script might not work for all the use cases out there.
-
-> **Note**
->
-> While automated conversion will quickly create a working Icinga 2 configuration
-> it does not keep the original organisation structure or any special kind of
-> group or template logic. Please keep that mind when using the script.
+script might not currently work for all use cases.
The config conversion script provides support for basic Icinga 1.x
configuration format conversion to native Icinga 2 configuration syntax.
The conversion script tries to preserve your existing template structure and
-adds new templates where appropriate.
-
-The script will also detect the "attach service to hostgroup and put
-hosts as members" trick from 1.x and convert that into Icinga2's template
-system.
-
-Additionally the old "service with contacts and notification commands" logic
-will be converted into Icinga2's logic with new notification objects,
-allowing to define notifications directly on the service definition then.
-
-Commands will be split by type (Check, Event, Notification) and relinked where
-possible. The host's `check_command` is dropped, and a possible host check service
-looked up, if possible. Otherwise a new service object will be added and linked.
-
-Notifications will be built based on the service->contact relations, and
-escalations will also be merged into notifications, having times begin/end as
-additional attributes. Notification options will be converted into the new Icinga2
-logic.
-
-Dependencies and Parents are resolved into host and service dependencies with
-many objects tricks as well.
-
-Timeperiods will be converted as is, because Icinga2's ITL provides the legacy-timeperiod
-template which supports that format for compatibility reasons.
-
-Custom attributes like custom variables, `*_urls`, etc will be collected into the
-custom dictionary, while possible macros are automatically converted into the macro
-dictionary (freely definable macros in Icinga 2).
+adds new templates where appropriate. However, the original file structure is
+not preserved.
The conversion script uses templates from the Icinga Template Library where
possible.
-Regular expressions are not supported, also for the reason that this is optional
-in Icinga 1.x.
-
> **Note**
>
> Please check the provided README file for additional notes and possible
### Manual Config Conversion
-For a long term migration of your configuration you should consider recreating your
-configuration based on the Icinga 2 proposed way of doing configuration right.
+For a long-term migration of your configuration you should consider re-creating
+your configuration based on the Icinga 2 proposed way of doing configuration right.
Please read the next chapter to get an idea about the differences between 1.x and 2.
>
> By convention the `.conf` suffix is used for Icinga 2 configuration files.
-
## Resource File and Global Macros
-Global macros such as for the plugin directory, or hidden passwords/community
-strings can be set in the `resource.cfg` configuration file in Icinga 1.x. By
-convention the `USER1` macro is used to define the directory for the plugins.
+Global macros such as for the plugin directory, usernames and passwords can be
+set in the `resource.cfg` configuration file in Icinga 1.x. By convention the
+`USER1` macro is used to define the directory for the plugins.
Icinga 2 uses a global `IcingaMacros` variable which is set in the
`conf.d/macros.conf` file:
In Icinga 1.x comments are made using a leading hash (`#`) or a semi-colon (`;`)
for inline comments.
+
In Icinga 2 comments can either be encapsulated by `/*` and `*/` (allowing for
multi-line comments) or starting with two slashes (`//`).
to specify user-friendly names which should be shown in UIs (supported by
Icinga 1.x Classic UI and Web).
-Object names are not defined using attributes (e.g. `service_description` for
+Object names are not specified using attributes (e.g. `service_description` for
hosts) like in Icinga 1.x but directly after their type definition.
define service {
object Service "localhost-ping4" { }
-
## Templates
In Icinga 1.x templates are identified using `register 0`. Icinga 2 uses the
> It's also possible to modify attributes in the host's service array inherited
> from the host template. E.g. macros.
-
-
-
## Users
Contacts have been renamed to Users (same for groups). A user does not
only provide attributes and macros used for notifications, but is also
used for authorization checks.
-The revamped notification logic removes the notification commands from
-the contacts (users) too.
-StatusDataWriter, IdoMySqlConnection and LivestatusListener will provide
-the contact and contactgroups attributes for services for compatibility
+In Icinga 2 notification commands are not directly associated with users. Instead
+the notification command is specified in `Notification` objects.
+
+The `StatusDataWriter`, `IdoMySqlConnection` and `LivestatusListener` types will
+provide the contact and contactgroups attributes for services for compatibility
reasons. These values are calculated from all services, their notifications,
and their users.
-
## Macros
### Command Macros
If you have previously used Icinga 1.x you may already be familiar with
-user and argument macros (e.g., USER1 or ARG1). Unlike in Icinga 1.x macros
+user and argument macros (e.g., `USER1` or `ARG1`). Unlike in Icinga 1.x macros
may have arbitrary names and arguments are no longer specified in the
-check_command setting.
+`check_command` setting.
-In Icinga 1.x the 2 argument macros will be passed onto the 'check_command'
-attribute separated by an exclamation mark (!).
+In Icinga 1.x argument macros are specified in the `check_command` attribute and
+are separated from the command name using an exclamation mark (`!`).
define command {
command_name ping4
### Environment Macros
-The global configuration setting 'enable_environment_macros' does not exist in
+The global configuration setting `enable_environment_macros` does not exist in
Icinga 2.
-Macros exported into the environment must be set using the 'export_macros' attribute
+
+Macros exported into the environment must be set using the `export_macros` attribute
in command objects.
### Check Output
-Icinga 2 does not make a difference between output (first line) and long_output
-(remaining lines) like in Icinga 1.x. Performance Data is provided separately.
+Icinga 2 does not make a difference between `output` (first line) and
+`long_output` (remaining lines) like in Icinga 1.x. Performance Data is
+provided separately.
-StatusDataWriter, IdoMysqlConnection, LivestatusListener split the raw output into
-output (first line) and long_output (remaining lines) for compatibility reasons.
+The `StatusDataWriter`, `IdoMysqlConnection` and `LivestatusListener` types
+split the raw output into `output` (first line) and `long_output` (remaining
+lines) for compatibility reasons.
### Initial State
-Icinga 1.x uses max_service_check_spread to define a timerange where the initial
-state checks must have happened. Icinga 2 will use the retry_interval instead
-and check_interval / 5 if not defined.
+Icinga 1.x uses the `max_service_check_spread` setting to specify a timerange
+where the initial state checks must have happened. Icinga 2 will use the
+`retry_interval` setting instead and `check_interval` divided by 5 if
+`retry_interval` is not defined.
### Performance Data
real host checks anymore. Therefore the PerfDataWriter will only write service
performance data files.
-
## Commands
-Unlike in Icinga 1.x there are 3 different command types in Icinga 2: CheckCommand,
-NotificationCommand, EventCommand.
-Previously it was possible to accidently use e.g. a notification command as event
-handler, generating problems with macro resolution and so on.
-In Icinga 2 those types are separated and will generate an error on configuration
-validation if used in the wrong context.
+Unlike in Icinga 1.x there are 3 different command types in Icinga 2:
+`CheckCommand`, `NotificationCommand` and EventCommand`.
+
+For example in Icinga 1.x it is possible to accidently use a notification
+command as an event handler which might cause problems depending on which
+macros are used in the notification command.
+
+In Icinga 2 these command types are separated and will generate an error on
+configuration validation if used in the wrong context.
While Icinga 2 still supports the complete command line in command objects, it's
also possible to encapsulate all arguments into double quotes and passing them as
-array to the 'command_line' attribute i.e. for better readability.
+array to the `command_line` attribute i.e. for better readability.
-It's also possible to define default (argument) macros for the command itsself which
+It's also possible to define default (argument) macros for the command itself which
can be overridden by a service (argument) macro.
objects. Escalations happen between a defined start and end time which is
calculated from the notification_interval:
-start = notification start + (notification_interval * first_notification)
-end = notification start + (notification_interval * last_notification)
+ start = notification start + (notification_interval * first_notification)
+ end = notification start + (notification_interval * last_notification)
In theory first_notification and last_notification can be set to readable
numbers. In practice users are manipulating those attributes in combination
to the escalation to garantuee the normal notifications once an escalation
happens.
That's not necessary with Icinga 2 only requiring an additional notification
-object for the escalation itsself.
+object for the escalation itself.
### Notification Options
notification_state_filter = (StateFilterWarning | StateFilterUnknown | StateFilterCritical),
notification_type_filter = (NotificationProblem | NotificationRecovery | NotificationFlappingStart | NotificationFlappingEnd | NotificationDowntimeStart | NotificationDowntimeEnd | NotificationDowntimeRemoved)
-
> **Note**
>
-> Please note that 'NotificationProblem' as type is required for all problem
+> Please note that `NotificationProblem` as type is required for all problem
> notifications.
-Icinga 2 adds more fine granular type filters for acknowledgements, downtime
+Icinga 2 adds more fine-grained type filters for acknowledgements, downtime
and flapping type (start, end, ...).
> **Note**
## Flapping
-The Icinga 1.x logic on flapping detection uses the last 21 states of a service. This
+The Icinga 1.x flapping detection uses the last 21 states of a service. This
value is hardcoded and cannot be changed. The algorithm on determining a flapping state
is
and enabled on-demand. The Icinga 1.x Livestatus addon is implemented as Icinga 2
LivestatusListener. Icinga 1.x broker modules used for check distributions are replaced
by the Icinga 2 cluster and distributed capabilities using the same protocol and security
-mechanisms as the Icinga 2 instance itsself.
+mechanisms as the Icinga 2 instance itself.
Each feature can be created multiple times, i.e. having 3 IDO Mysql databases, 5 Performance
Data Writers and 2 Livestatus Listeners (one listening on tcp, and one on unix sockets).
Icinga 2 features require a library to be loaded, and object configuration. In order to simplify
the process of enabling/disabling these features Icinga 2 ships with two scripts inspired by
-Apache: i2enfeature and i2disfeature.
+Apache: `i2enfeature` and `i2disfeature`.
projects / icinga2 / commitdiff