From: Gunnar Beutner Date: Thu, 10 Oct 2013 07:40:50 +0000 (+0200) Subject: Update documentation. X-Git-Tag: v0.0.3~208 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=5c683dce86e4da966958989c02816784328cf49c;p=icinga2 Update documentation. --- diff --git a/doc/7-migrating-from-icinga-1x.md b/doc/7-migrating-from-icinga-1x.md index 66e98e0ef..2a43f34ea 100644 --- a/doc/7-migrating-from-icinga-1x.md +++ b/doc/7-migrating-from-icinga-1x.md @@ -2,60 +2,25 @@ ## 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 @@ -67,7 +32,7 @@ in Icinga 1.x. ### 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. diff --git a/doc/8-differences-between-icinga-1x-and-2.md b/doc/8-differences-between-icinga-1x-and-2.md index c2d467e64..93cc1b8b0 100644 --- a/doc/8-differences-between-icinga-1x-and-2.md +++ b/doc/8-differences-between-icinga-1x-and-2.md @@ -57,12 +57,11 @@ suffix does not matter as long as it matches the (wildcard) include expression. > > 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: @@ -79,6 +78,7 @@ Icinga 2 uses a global `IcingaMacros` variable which is set in the 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 (`//`). @@ -88,7 +88,7 @@ Object names must not contain a colon (`:`). Use the `display_name` attribute 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 { @@ -98,7 +98,6 @@ hosts) like in Icinga 1.x but directly after their type definition. object Service "localhost-ping4" { } - ## Templates In Icinga 1.x templates are identified using `register 0`. Icinga 2 uses the @@ -209,34 +208,31 @@ be used for host service relation building. > 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 @@ -254,9 +250,10 @@ In Icinga 2 ### 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. @@ -270,17 +267,20 @@ inherit their state from the service that is specified using the `check` attribu ### 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 @@ -288,21 +288,23 @@ There is no host performance data generated in Icinga 2 because there are no 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. @@ -378,8 +380,8 @@ Escalations in Icinga 1.x require a separated object matching on existing objects. Escalations happen between a defined start and end time which is calculated from the notification_interval: -start = notification start + (notification_interval * first_notification) -end = notification start + (notification_interval * last_notification) + 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 @@ -394,7 +396,7 @@ In Icinga 1.x it's required to copy the contacts from the service notification 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 @@ -407,13 +409,12 @@ All state and type filter use long names or'd with a pipe together 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** @@ -442,7 +443,7 @@ schema with dependencies and parent attributes for compatibility reasons. ## 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 @@ -481,7 +482,7 @@ Icinga 1.x IDOUtils was implemented from scratch as Icinga 2 feature which can b 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). @@ -496,4 +497,4 @@ for max age of table entries. 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`. diff --git a/doc/BLACKLIST b/doc/BLACKLIST index ba68a50aa..0fd0f3ebf 100644 --- a/doc/BLACKLIST +++ b/doc/BLACKLIST @@ -1,3 +1,6 @@ seperate logic magic +revamp +and so on +itsself diff --git a/doc/mkdoc.sh b/doc/mkdoc.sh index 94a526f03..e391b93e1 100755 --- a/doc/mkdoc.sh +++ b/doc/mkdoc.sh @@ -1,12 +1,12 @@ #!/bin/sh cd -- `dirname $0` -for badword in $(cat BLACKLIST); do - if grep $badword *.md; then +while read badword; do + if grep -i "$badword" *.md; then echo "Documentation contains banned word." exit 1 fi -done +done < BLACKLIST cat <