mirror of https://github.com/Icinga/icinga2.git
Update documentation.
This commit is contained in:
Gunnar Beutner
parent
29a9365a48
commit
6559c4b2ff
|
|
@ -2,37 +2,37 @@
|
|||
|
||||
## Configuration Migration
|
||||
|
||||
There are plenty of differences and behavior changes introduced with the new Icinga 2.x
|
||||
configuration format. In order to quickly surpass the issue, Icinga 2.x ships its own
|
||||
config conversion script.
|
||||
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,
|
||||
Icinga 2 ships its own config conversion script.
|
||||
|
||||
### Configuration Conversion Script
|
||||
|
||||
Since Icinga 1.x configuration provides multiple ways of creating a valid configuration
|
||||
it may not work for all the use cases out there.
|
||||
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.x configuration
|
||||
> 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.
|
||||
|
||||
The config conversion script provides support for basic Icinga 1.x
|
||||
configuration format conversion to native Icinga 2.x configuration syntax.
|
||||
configuration format conversion to native Icinga 2 configuration syntax.
|
||||
|
||||
It won't just compile all objects and drop them at once, but keep your
|
||||
existing 1.x template structure, only adding a new host->service link relation.
|
||||
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.
|
||||
|
||||
Furthermore the old "service with contacts and notification commands" logic
|
||||
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
|
||||
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
|
||||
|
|
@ -46,17 +46,20 @@ 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 automagically converted into the macro
|
||||
dictionary (freely definable macros in Icinga 2.x).
|
||||
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).
|
||||
|
||||
All required templates will be inherited from Icinga2's Template Library (ITL).
|
||||
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
|
||||
Regular expressions are not supported, also for the reason that this is optional
|
||||
in Icinga 1.x.
|
||||
|
||||
> **Note**
|
||||
>
|
||||
> Please check the provided README for additional NOTES and possible caveats.
|
||||
> Please check the provided README file for additional notes and possible
|
||||
> scaveats.
|
||||
|
||||
# cd tools/configconvert
|
||||
# ./icinga2_convert_v1_v2.pl -c /etc/icinga/icinga.cfg -o conf/
|
||||
|
|
@ -65,513 +68,6 @@ Regular expressions are not supported, also for the reason that this is optional
|
|||
### Manual Config Conversion
|
||||
|
||||
For a long term migration of your configuration you should consider recreating your
|
||||
configuration based on the Icinga 2.x proposed way of doing configuration right.
|
||||
|
||||
> **Note**
|
||||
>
|
||||
> Configuration addons in the Icinga ecosystem should be able to adopt the new
|
||||
> Icinga 2.x configuration format soon but please ask them kindly while waiting :)
|
||||
|
||||
Please read the next chapter to get an idea about the differences between 1.x and 2.x
|
||||
|
||||
|
||||
|
||||
|
||||
# Differences between Icinga 1.x and 2.x
|
||||
|
||||
## Configuration Format
|
||||
|
||||
Icinga 1.x supports two configuration formats: key-value-based in icinga.cfg and
|
||||
object based in included files (cfg_dir, cfg_file). The icinga.cfg must be passed
|
||||
onto the Icinga daemon at startup.
|
||||
|
||||
enable_notifications=1
|
||||
|
||||
define service {
|
||||
notifications_enabled=0
|
||||
}
|
||||
|
||||
Icinga 2.x supports objects and (global) variables, but does not make a difference if it's
|
||||
the "main" configuration file, or any included file.
|
||||
|
||||
set IcingaEnableNotifications = 1,
|
||||
|
||||
object Service "test" {
|
||||
enable_notifications = 0,
|
||||
}
|
||||
|
||||
|
||||
### Sample Configuration and ITL
|
||||
|
||||
While Icinga 1.x ships sample configuration and templates spread in various object files
|
||||
Icinga 2.x moves all templates into the Icinga Template Library (ITL) and includes that
|
||||
in the sample configuration.
|
||||
|
||||
The ITL will be updated on every releases and must not be edited by the user.
|
||||
|
||||
> **Note**
|
||||
>
|
||||
> Sample configuration is located in conf.d/ which is included in icinga2.conf by default.
|
||||
|
||||
### Include Files and Directories
|
||||
|
||||
In Icinga 1.x icinga.cfg contains cfg_file and cfg_dir keys. cfg_dir recursively includes all
|
||||
files with a .cfg suffix in the given directory. All paths must be configured absolute,
|
||||
relative paths are not possible. cfg_file and cfg_dir can include the same file twice which
|
||||
leads into configuration errors in Icinga 1.x.
|
||||
|
||||
cfg_file=/etc/icinga/objects/commands.cfg
|
||||
cfg_dir=/etc/icinga/objects
|
||||
|
||||
Icinga 2.x supports wildcard includes and relative paths for e.g. including conf.d/*.conf
|
||||
in the same directory. A global search path for includes is available for advanced features
|
||||
like the Icinga Template Library (ITL). The file suffix does not matter as long as it matches
|
||||
the (wildcard) include expression.
|
||||
|
||||
include "conf.d/*.conf"
|
||||
include <itl/itl.conf>
|
||||
|
||||
|
||||
## Resource File and Global Macros
|
||||
|
||||
Adding global macros such as plugin directory, or hidden passwords/community strings
|
||||
happens with user macros in resource.cfg in Icinga 1.x. By default the USER1 macro
|
||||
is used to define the directory for the plugins.
|
||||
|
||||
Icinga 2.x uses a global IcingaMacros dictionary and ships that by default in
|
||||
conf.d/macros.conf
|
||||
|
||||
/**
|
||||
* Global macros
|
||||
*/
|
||||
set IcingaMacros = {
|
||||
plugindir = "/usr/lib/nagios/plugins"
|
||||
}
|
||||
|
||||
|
||||
## Comments
|
||||
|
||||
In Icinga 1.x comments are made using a leading hash (#) or a semi-colon (;)
|
||||
for inline comments.
|
||||
In Icinga 2.x comments can either be encapsulated by /* ... */ (multiple lines
|
||||
possible) or starting with two slashes (//). If you're familiar with C/C++
|
||||
you'll get the idea.
|
||||
|
||||
## Object names
|
||||
|
||||
Object names must not contain a colon (:). Use the 'display_name' attribute
|
||||
for detailed identifiers and gui representation (supported by Icinga 1.x Classic
|
||||
UI and Web).
|
||||
|
||||
Object names are not defined as attribute like in Icinga 1.x but directly after
|
||||
their type definition.
|
||||
|
||||
define service {
|
||||
host_name localhost
|
||||
service_description ping4
|
||||
}
|
||||
|
||||
object Service "localhost-ping4" { }
|
||||
|
||||
|
||||
## Templates
|
||||
|
||||
In Icinga 1.x templates are identified by 'register 0' not registering the
|
||||
final object. Icinga 2.x uses the "template" identifier.
|
||||
|
||||
template Service "ping4-template" { }
|
||||
|
||||
Icinga 1.x objects literally "use" template objects in a comma seperated list.
|
||||
Icinga 2.x uses the keyword "inherits" after the object name and requires a
|
||||
comma seperated list with template names in double quotes.
|
||||
|
||||
define service {
|
||||
service_description testservice
|
||||
use tmpl1,tmpl2,tmpl3
|
||||
}
|
||||
|
||||
object Service "testservice" inherits "tmpl1", "tmpl2", "tmpl3" {
|
||||
}
|
||||
|
||||
## Object attributes
|
||||
|
||||
### Attribute values
|
||||
|
||||
Icinga 1.x seperates attribute and value with whitespaces/tabs. Icinga 2.x
|
||||
requires an equal sign (=) between them.
|
||||
|
||||
define service {
|
||||
check_interval 5
|
||||
}
|
||||
|
||||
object Service "test" {
|
||||
check_interval = 5m,
|
||||
}
|
||||
|
||||
> **Note**
|
||||
>
|
||||
> Please note that the default time value is seconds, if no duration literal
|
||||
> is given. check_interval = 5 behaves the same as check_interval = 5s.
|
||||
|
||||
### Attribute strings
|
||||
|
||||
All strings require double quotes in Icinga 2.x. Therefore a double-quote
|
||||
must be escaped with a backslash (e.g. in command line).
|
||||
If an attribute identifier starts with a number, it must be encapsulated
|
||||
with double quotes as well.
|
||||
|
||||
### Attribute lines
|
||||
|
||||
Unlike in Icinga 1.x all attributes within the current object must be
|
||||
terminated with a comma (,).
|
||||
|
||||
|
||||
## Host Service Relation
|
||||
|
||||
In Icinga 1.x a service object is linked to a host by defining the 'host_name'
|
||||
attribute in the service definition. Alternate object tricks refer to
|
||||
'hostgroup_name' or behavior changing regular expression. It's not possible
|
||||
to define a service definition within a host definition, or even link from
|
||||
a host definition to services.
|
||||
|
||||
The preferred way of linking hosts with services in Icinga 2.x are services
|
||||
defined inline to the host object (or template) definition. Icinga 2.x will
|
||||
implicitely create a new service object on configuration activation. These
|
||||
inline service definitions can reference service templates.
|
||||
Linking a service to a host is still possible with the 'host' attribute in
|
||||
a service object in Icinga 2.x
|
||||
|
||||
### Service Hostgroup to Hosts Trick
|
||||
|
||||
A common pattern in Icinga 1.x is to add services to hostgroups. When a host
|
||||
is added as hostgroup member, it will automatically collect all services linked
|
||||
to that hostgroup. Inheriting services from a parent hostgroup to a member
|
||||
hostgroup does not work.
|
||||
|
||||
define hostgroup {
|
||||
hostgroup_name testhg
|
||||
}
|
||||
define service {
|
||||
service_description testservice
|
||||
hostgroup_name testhg
|
||||
}
|
||||
define host {
|
||||
host_name testhost
|
||||
hostgroups testhg
|
||||
}
|
||||
|
||||
Since it's possible to define services inline in a host template object and
|
||||
inherit them to actual host objects in Icinga 2.x the preferred method works
|
||||
like: Create a host template (acting as "hostgroup" relation) and define all
|
||||
services (either inline, or reference a service template). Then let all hosts
|
||||
inherit from that host template, collecting all service relations.
|
||||
|
||||
template Host "testhg" {
|
||||
services["testservice"] = {
|
||||
...
|
||||
}
|
||||
}
|
||||
|
||||
object Host "testhost" inherits "testhg" {
|
||||
...
|
||||
}
|
||||
|
||||
Hostgroups in Icinga 2.x are only used for grouping the views but must not
|
||||
be used for host service relation building.
|
||||
|
||||
> **Note**
|
||||
>
|
||||
> 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
|
||||
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
|
||||
may have arbitrary names and arguments are no longer specified in the
|
||||
check_command setting.
|
||||
|
||||
In Icinga 1.x the 2 argument macros will be passed onto the 'check_command'
|
||||
attribute seperated by an exclamation mark (!).
|
||||
|
||||
define command {
|
||||
command_name ping4
|
||||
command_line $USER1$/check_ping -H $HOSTADDRESS$ -w $ARG1$ -c $ARG2$ -p 5
|
||||
}
|
||||
|
||||
define service{
|
||||
use local-service
|
||||
host_name localhost
|
||||
service_description PING
|
||||
check_command check_ping!100.0,20%!500.0,60%
|
||||
}
|
||||
|
||||
In Icinga 2.x
|
||||
|
||||
### Environment Macros
|
||||
|
||||
The global configuration setting 'enable_environment_macros' does not exist in
|
||||
Icinga 2.x.
|
||||
Macros exported into the environment must be set using the 'export_macros' attribute
|
||||
in command objects.
|
||||
|
||||
|
||||
|
||||
## Checks
|
||||
|
||||
### Host Check
|
||||
|
||||
Unlike in Icinga 1.x hosts are not checkable objects in Icinga 2. Instead hosts
|
||||
inherit their state from the service that is specified using the `check` attribute.
|
||||
|
||||
### Check Output
|
||||
|
||||
Icinga 2.x does not make a difference between output (first line) and long_output
|
||||
(remaining lines) like in Icinga 1.x. Performance Data is provided seperately.
|
||||
|
||||
StatusDataWriter, IdoMysqlConnection, LivestatusListener 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.x will use the retry_interval instead
|
||||
and check_interval / 5 if not defined.
|
||||
|
||||
### Performance Data
|
||||
|
||||
There is no host performance data generated in Icinga 2.x 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.x those types are seperated and will generate an error on configuration
|
||||
validation if used in the wrong context.
|
||||
|
||||
While Icinga 2.x 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.
|
||||
|
||||
It's also possible to define default (argument) macros for the command itsself which
|
||||
can be overridden by a service (argument) macro.
|
||||
|
||||
|
||||
## Groups
|
||||
|
||||
### Group Membership
|
||||
|
||||
Assigning members to hostgroups, servicegroups, usergroups is done only at the
|
||||
host/service/user object using the 'groups' attribute. The old method defining
|
||||
that directly as group attribute is not supported. Better use templates inheriting
|
||||
the 'groups' attribute to all your objects.
|
||||
|
||||
### Hostgroup with Services
|
||||
|
||||
Hostgroups are used for grouping only, and cannot be used for object tricks like in
|
||||
Icinga 1.x.
|
||||
|
||||
|
||||
## Notifications
|
||||
|
||||
Notifications are a new object type in Icinga 2.x. Imagine the following
|
||||
notification configuration problem in Icinga 1.x:
|
||||
|
||||
Service A should notify contact X via SMS
|
||||
Service B should notify contact X via Mail
|
||||
Service C should notify contact Y via Mail and SMS
|
||||
Contact X and Y should also be used for authorization (e.g. in Classic UI)
|
||||
|
||||
The only way achieving a semi-clean solution is to
|
||||
|
||||
Create contact X-sms, set service_notification_command for sms, assign
|
||||
contact to service A
|
||||
Create contact X-mail, set service_notification_command for mail, assign
|
||||
contact to service B
|
||||
Create contact Y, set service_notification_command for sms and mail, assign
|
||||
contact to service C
|
||||
Create contact X without notification commands, assign to service A and B
|
||||
|
||||
Basically you are required to create duplicated contacts for either each
|
||||
notification method or used for authorization only.
|
||||
|
||||
Icinga 2.x attempts to solve that problem in this way
|
||||
|
||||
Create user X, set SMS and Mail attributes, used for authorization
|
||||
Create user Y, set SMS and Mail attributes, used for authorization
|
||||
Create notification A-SMS, set notification_command for sms, add user X, assign
|
||||
notification A-SMS to service A
|
||||
Create notification B-Mail, set notification_command for mail, add user X, assign
|
||||
notification Mail to service B
|
||||
Create notification C-SMS, set notification_command for sms, add user Y, assign
|
||||
notification C-SMS to service C
|
||||
Create notification C-Mail, set notification_command for mail, add user Y, assign
|
||||
notification C-Mail to service C
|
||||
|
||||
> **Note**
|
||||
>
|
||||
> Notification objects are not required to be service agnostic. They may use
|
||||
> global notification templates and can be added to a service wherever needed.
|
||||
|
||||
Previously in Icinga 1.x it looked like
|
||||
|
||||
service -> (contact, contactgroup) -> notification command
|
||||
|
||||
In Icinga 2.x it will look like
|
||||
|
||||
Service -> Notification -> NotificationCommand
|
||||
-> User, UserGroup
|
||||
|
||||
|
||||
### Escalations
|
||||
|
||||
Escalations in Icinga 1.x require a seperated 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)
|
||||
|
||||
In theory first_notification and last_notification can be set to readable
|
||||
numbers. In practice users are manipulating those attributes in combination
|
||||
with notification_interval in order to get a start and end time.
|
||||
|
||||
In Icinga 2.x the notification object can be used as notification escalation
|
||||
if the start and end times are defined within the 'times' attribute using
|
||||
duration literals (e.g. 30m).
|
||||
|
||||
The Icinga 2.x escalation does not replace the current running notification.
|
||||
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.x only requiring an additional notification
|
||||
object for the escalation itsself.
|
||||
|
||||
### Notification Options
|
||||
|
||||
Unlike Icinga 1.x with the 'notification_options' attribute with comma seperated
|
||||
state and type filters, Icinga 2.x uses two configuration attributes for that.
|
||||
All state and type filter use long names or'd with a pipe together
|
||||
|
||||
notification_options w,u,c,r,f,s
|
||||
|
||||
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
|
||||
> notifications.
|
||||
|
||||
Icinga 2.x adds more fine granular type filters for acknowledgements, downtime
|
||||
and flapping type (start, end, ...).
|
||||
|
||||
> **Note**
|
||||
>
|
||||
> Notification state and type filters are only valid configuration attributes for
|
||||
> Notification and User objects.
|
||||
|
||||
|
||||
## Dependencies and Parents
|
||||
|
||||
In Icinga 1.x it's possible to define host parents to determine network reachability
|
||||
and keep a host's state unreachable rather than down.
|
||||
Furthermore there are host and service dependencies preventing unnecessary checks and
|
||||
notifications. A host must not depend on a service, and vice versa. All dependencies
|
||||
are configured as seperate objects and cannot be set directly on the host or service
|
||||
object.
|
||||
|
||||
Icinga 2.x adds host and service dependencies as attribute directly onto the host or
|
||||
service object or template. A service can now depend on a host, and vice versa. A
|
||||
service has an implicit dependeny (parent) to its host. A host to host dependency acts
|
||||
implicit as host parent relation.
|
||||
|
||||
StatusDataWriter, IdoMysqlConnection and LivestatusListener support the Icinga 1.x
|
||||
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
|
||||
value is hardcoded and cannot be changed. The algorithm on determining a flapping state
|
||||
is
|
||||
|
||||
flap threshold = (number of actual state changes / number of possible state changes) * 100%
|
||||
|
||||
comparing that to low and high flapping thresholds.
|
||||
|
||||
The algorithm uses in Icinga 2.x does not store the past states but calculcates the flapping
|
||||
threshold from a single value based on counters and half-life values. Icinga 2.x compares
|
||||
the value with a single flapping threshold configuration attribute.
|
||||
|
||||
|
||||
## State Retention
|
||||
|
||||
Icinga 1.x uses retention.dat to save historical and modified-at-runtime data over restarts.
|
||||
Icinga 2.x uses its own icinga2.state file with a json-like serialized format.
|
||||
|
||||
|
||||
## Logging
|
||||
|
||||
Icinga 1.x supports syslog facilities and writes to its own icinga.log and archives. These logs
|
||||
are used in Icinga 1.x Classic UI to generate historical reports.
|
||||
|
||||
Icinga 2.x compat library provides the CompatLogger object which writes the icinga.log and archive
|
||||
in Icinga 1.x format in order to stay compatible with Classic UI and other addons.
|
||||
The native Icinga 2.x logging facilities are split into three configuration objects: SyslogLogger,
|
||||
FileLogger, StreamLogger. Each of them got their own severity and target configuration.
|
||||
|
||||
|
||||
## Broker Modules and Features
|
||||
|
||||
Icinga 1.x broker modules are binary incompatible with the Icinga 2.x component loader.
|
||||
Therefore the module configuration cannot be copied 1:1
|
||||
|
||||
Icinga 1.x IDOUtils was implemented from scratch as Icinga 2.x feature which can be loaded
|
||||
and enabled on-demand. The Icinga 1.x Livestatus addon is implemented as Icinga 2.x
|
||||
LivestatusListener. Icinga 1.x broker modules used for check distributions are replaced
|
||||
by the Icinga 2.x cluster and distributed capabilities using the same protocol and security
|
||||
mechanisms as the Icinga 2.x instance itsself.
|
||||
|
||||
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).
|
||||
|
||||
### IDOUtils Database Backend
|
||||
|
||||
Icinga 2.x uses Ido<DBType>Connection configuration objects re-using some options known from
|
||||
Icinga 1.x IDOUtils such as the database credentials, instance_name or the cleanup attributes
|
||||
for max age of table entries.
|
||||
|
||||
### Enable Features
|
||||
|
||||
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.x ships with two scripts inspired by
|
||||
Apache: i2enfeature and i2disfeature.
|
||||
|
||||
|
||||
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.
|
||||
|
|
|
|||
|
|
@ -0,0 +1,499 @@
|
|||
# Differences between Icinga 1.x and 2
|
||||
|
||||
## Configuration Format
|
||||
|
||||
Icinga 1.x supports two configuration formats: key-value-based settings in
|
||||
`icinga.cfg` and object-based in included files (`cfg_dir`, `cfg_file`). The
|
||||
path to the `icinga.cfg` configuration file must be passed to the Icinga daemon
|
||||
at startup.
|
||||
|
||||
enable_notifications=1
|
||||
|
||||
define service {
|
||||
notifications_enabled=0
|
||||
}
|
||||
|
||||
Icinga 2 supports objects and (global) variables, but does not make a difference if it's
|
||||
the main configuration file, or any included file.
|
||||
|
||||
set IcingaEnableNotifications = 1,
|
||||
|
||||
object Service "test" {
|
||||
enable_notifications = 0,
|
||||
}
|
||||
|
||||
### Sample Configuration and ITL
|
||||
|
||||
While Icinga 1.x ships sample configuration and templates spread in various object files
|
||||
Icinga 2 moves all templates into the Icinga Template Library (ITL) and includes that
|
||||
in the sample configuration.
|
||||
|
||||
The ITL will be updated on every releases and should not be edited by the user.
|
||||
|
||||
> **Note**
|
||||
>
|
||||
> Sample configuration is located in `conf.d/` which is included in `icinga2.conf` by default.
|
||||
|
||||
### Include Files and Directories
|
||||
|
||||
In Icinga 1.x the `icinga.cfg` file contains `cfg_file` and `cfg_dir`
|
||||
directives. The `cfg_dir` directive recursively includes all files with a `.cfg`
|
||||
suffix in the given directory. All paths must be configured absolute, relative
|
||||
paths are not possible. The `cfg_file` and `cfg_dir` directives can include the
|
||||
same file twice which leads into configuration errors in Icinga 1.x.
|
||||
|
||||
cfg_file=/etc/icinga/objects/commands.cfg
|
||||
cfg_dir=/etc/icinga/objects
|
||||
|
||||
Icinga 2 supports wildcard includes and relative paths, e.g. for including
|
||||
`conf.d/*.conf` in the same directory. A global search path for includes is
|
||||
available for advanced features like the Icinga Template Library (ITL). The file
|
||||
suffix does not matter as long as it matches the (wildcard) include expression.
|
||||
|
||||
include "conf.d/*.conf"
|
||||
include <itl/itl.conf>
|
||||
|
||||
> **Best Practice**
|
||||
>
|
||||
> 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.
|
||||
|
||||
Icinga 2 uses a global `IcingaMacros` variable which is set in the
|
||||
`conf.d/macros.conf` file:
|
||||
|
||||
/**
|
||||
* Global macros
|
||||
*/
|
||||
set IcingaMacros = {
|
||||
plugindir = "/usr/lib/nagios/plugins"
|
||||
}
|
||||
|
||||
|
||||
## Comments
|
||||
|
||||
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 (`//`).
|
||||
|
||||
## Object names
|
||||
|
||||
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
|
||||
hosts) like in Icinga 1.x but directly after their type definition.
|
||||
|
||||
define service {
|
||||
host_name localhost
|
||||
service_description ping4
|
||||
}
|
||||
|
||||
object Service "localhost-ping4" { }
|
||||
|
||||
|
||||
## Templates
|
||||
|
||||
In Icinga 1.x templates are identified using `register 0`. Icinga 2 uses the
|
||||
"template" identifier.
|
||||
|
||||
template Service "ping4-template" { }
|
||||
|
||||
Icinga 1.x objects inherit from templates using the `use` attribute.
|
||||
Icinga 2 uses the keyword `inherits` after the object name and requires a
|
||||
comma-separated list with template names in double quotes.
|
||||
|
||||
define service {
|
||||
service_description testservice
|
||||
use tmpl1,tmpl2,tmpl3
|
||||
}
|
||||
|
||||
object Service "testservice" inherits "tmpl1", "tmpl2", "tmpl3" {
|
||||
}
|
||||
|
||||
## Object attributes
|
||||
|
||||
### Attribute values
|
||||
|
||||
Icinga 1.x separates attribute and value with whitespaces/tabs. Icinga 2
|
||||
requires an equal sign (=) between them.
|
||||
|
||||
define service {
|
||||
check_interval 5
|
||||
}
|
||||
|
||||
object Service "test" {
|
||||
check_interval = 5m,
|
||||
}
|
||||
|
||||
> **Note**
|
||||
>
|
||||
> Please note that the default time value is seconds, if no duration literal
|
||||
> is given. check_interval = 5 behaves the same as check_interval = 5s.
|
||||
|
||||
### Attribute strings
|
||||
|
||||
All strings require double quotes in Icinga 2. Therefore a double-quote
|
||||
must be escaped with a backslash (e.g. in command line).
|
||||
If an attribute identifier starts with a number, it must be encapsulated
|
||||
with double quotes as well.
|
||||
|
||||
### Attribute lines
|
||||
|
||||
Unlike in Icinga 1.x all attributes within the current object must be
|
||||
terminated with a comma (,).
|
||||
|
||||
|
||||
## Host Service Relation
|
||||
|
||||
In Icinga 1.x a service object is linked to a host by defining the 'host_name'
|
||||
attribute in the service definition. Alternate object tricks refer to
|
||||
'hostgroup_name' or behavior changing regular expression. It's not possible
|
||||
to define a service definition within a host definition, or even link from
|
||||
a host definition to services.
|
||||
|
||||
The preferred way of linking hosts with services in Icinga 2 are services
|
||||
defined inline to the host object (or template) definition. Icinga 2 will
|
||||
implicitely create a new service object on configuration activation. These
|
||||
inline service definitions can reference service templates.
|
||||
Linking a service to a host is still possible with the 'host' attribute in
|
||||
a service object in Icinga 2.
|
||||
|
||||
### Service Hostgroup to Hosts Trick
|
||||
|
||||
A common pattern in Icinga 1.x is to add services to hostgroups. When a host
|
||||
is added as hostgroup member, it will automatically collect all services linked
|
||||
to that hostgroup. Inheriting services from a parent hostgroup to a member
|
||||
hostgroup does not work.
|
||||
|
||||
define hostgroup {
|
||||
hostgroup_name testhg
|
||||
}
|
||||
define service {
|
||||
service_description testservice
|
||||
hostgroup_name testhg
|
||||
}
|
||||
define host {
|
||||
host_name testhost
|
||||
hostgroups testhg
|
||||
}
|
||||
|
||||
Since it's possible to define services inline in a host template object and
|
||||
inherit them to actual host objects in Icinga 2 the preferred method works
|
||||
like: Create a host template (acting as "hostgroup" relation) and define all
|
||||
services (either inline, or reference a service template). Then let all hosts
|
||||
inherit from that host template, collecting all service relations.
|
||||
|
||||
template Host "testhg" {
|
||||
services["testservice"] = {
|
||||
...
|
||||
}
|
||||
}
|
||||
|
||||
object Host "testhost" inherits "testhg" {
|
||||
...
|
||||
}
|
||||
|
||||
Hostgroups in Icinga 2 are only used for grouping the views but must not
|
||||
be used for host service relation building.
|
||||
|
||||
> **Note**
|
||||
>
|
||||
> 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
|
||||
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
|
||||
may have arbitrary names and arguments are no longer specified in the
|
||||
check_command setting.
|
||||
|
||||
In Icinga 1.x the 2 argument macros will be passed onto the 'check_command'
|
||||
attribute separated by an exclamation mark (!).
|
||||
|
||||
define command {
|
||||
command_name ping4
|
||||
command_line $USER1$/check_ping -H $HOSTADDRESS$ -w $ARG1$ -c $ARG2$ -p 5
|
||||
}
|
||||
|
||||
define service{
|
||||
use local-service
|
||||
host_name localhost
|
||||
service_description PING
|
||||
check_command check_ping!100.0,20%!500.0,60%
|
||||
}
|
||||
|
||||
In Icinga 2
|
||||
|
||||
### Environment Macros
|
||||
|
||||
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
|
||||
in command objects.
|
||||
|
||||
|
||||
|
||||
## Checks
|
||||
|
||||
### Host Check
|
||||
|
||||
Unlike in Icinga 1.x hosts are not checkable objects in Icinga 2. Instead hosts
|
||||
inherit their state from the service that is specified using the `check` attribute.
|
||||
|
||||
### 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.
|
||||
|
||||
StatusDataWriter, IdoMysqlConnection, LivestatusListener 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.
|
||||
|
||||
### Performance Data
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
It's also possible to define default (argument) macros for the command itsself which
|
||||
can be overridden by a service (argument) macro.
|
||||
|
||||
|
||||
## Groups
|
||||
|
||||
### Group Membership
|
||||
|
||||
Assigning members to hostgroups, servicegroups, usergroups is done only at the
|
||||
host/service/user object using the 'groups' attribute. The old method defining
|
||||
that directly as group attribute is not supported. Better use templates inheriting
|
||||
the 'groups' attribute to all your objects.
|
||||
|
||||
### Hostgroup with Services
|
||||
|
||||
Hostgroups are used for grouping only, and cannot be used for object tricks like in
|
||||
Icinga 1.x.
|
||||
|
||||
|
||||
## Notifications
|
||||
|
||||
Notifications are a new object type in Icinga 2. Imagine the following
|
||||
notification configuration problem in Icinga 1.x:
|
||||
|
||||
Service A should notify contact X via SMS
|
||||
Service B should notify contact X via Mail
|
||||
Service C should notify contact Y via Mail and SMS
|
||||
Contact X and Y should also be used for authorization (e.g. in Classic UI)
|
||||
|
||||
The only way achieving a semi-clean solution is to
|
||||
|
||||
Create contact X-sms, set service_notification_command for sms, assign
|
||||
contact to service A
|
||||
Create contact X-mail, set service_notification_command for mail, assign
|
||||
contact to service B
|
||||
Create contact Y, set service_notification_command for sms and mail, assign
|
||||
contact to service C
|
||||
Create contact X without notification commands, assign to service A and B
|
||||
|
||||
Basically you are required to create duplicated contacts for either each
|
||||
notification method or used for authorization only.
|
||||
|
||||
Icinga 2 attempts to solve that problem in this way
|
||||
|
||||
Create user X, set SMS and Mail attributes, used for authorization
|
||||
Create user Y, set SMS and Mail attributes, used for authorization
|
||||
Create notification A-SMS, set notification_command for sms, add user X, assign
|
||||
notification A-SMS to service A
|
||||
Create notification B-Mail, set notification_command for mail, add user X, assign
|
||||
notification Mail to service B
|
||||
Create notification C-SMS, set notification_command for sms, add user Y, assign
|
||||
notification C-SMS to service C
|
||||
Create notification C-Mail, set notification_command for mail, add user Y, assign
|
||||
notification C-Mail to service C
|
||||
|
||||
> **Note**
|
||||
>
|
||||
> Notification objects are not required to be service agnostic. They may use
|
||||
> global notification templates and can be added to a service wherever needed.
|
||||
|
||||
Previously in Icinga 1.x it looked like
|
||||
|
||||
service -> (contact, contactgroup) -> notification command
|
||||
|
||||
In Icinga 2 it will look like
|
||||
|
||||
Service -> Notification -> NotificationCommand
|
||||
-> User, UserGroup
|
||||
|
||||
|
||||
### Escalations
|
||||
|
||||
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)
|
||||
|
||||
In theory first_notification and last_notification can be set to readable
|
||||
numbers. In practice users are manipulating those attributes in combination
|
||||
with notification_interval in order to get a start and end time.
|
||||
|
||||
In Icinga 2 the notification object can be used as notification escalation
|
||||
if the start and end times are defined within the 'times' attribute using
|
||||
duration literals (e.g. 30m).
|
||||
|
||||
The Icinga 2 escalation does not replace the current running notification.
|
||||
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.
|
||||
|
||||
### Notification Options
|
||||
|
||||
Unlike Icinga 1.x with the 'notification_options' attribute with comma-separated
|
||||
state and type filters, Icinga 2 uses two configuration attributes for that.
|
||||
All state and type filter use long names or'd with a pipe together
|
||||
|
||||
notification_options w,u,c,r,f,s
|
||||
|
||||
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
|
||||
> notifications.
|
||||
|
||||
Icinga 2 adds more fine granular type filters for acknowledgements, downtime
|
||||
and flapping type (start, end, ...).
|
||||
|
||||
> **Note**
|
||||
>
|
||||
> Notification state and type filters are only valid configuration attributes for
|
||||
> Notification and User objects.
|
||||
|
||||
|
||||
## Dependencies and Parents
|
||||
|
||||
In Icinga 1.x it's possible to define host parents to determine network reachability
|
||||
and keep a host's state unreachable rather than down.
|
||||
Furthermore there are host and service dependencies preventing unnecessary checks and
|
||||
notifications. A host must not depend on a service, and vice versa. All dependencies
|
||||
are configured as separate objects and cannot be set directly on the host or service
|
||||
object.
|
||||
|
||||
Icinga 2 adds host and service dependencies as attribute directly onto the host or
|
||||
service object or template. A service can now depend on a host, and vice versa. A
|
||||
service has an implicit dependeny (parent) to its host. A host to host dependency acts
|
||||
implicit as host parent relation.
|
||||
|
||||
StatusDataWriter, IdoMysqlConnection and LivestatusListener support the Icinga 1.x
|
||||
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
|
||||
value is hardcoded and cannot be changed. The algorithm on determining a flapping state
|
||||
is
|
||||
|
||||
flap threshold = (number of actual state changes / number of possible state changes) * 100%
|
||||
|
||||
comparing that to low and high flapping thresholds.
|
||||
|
||||
The algorithm uses in Icinga 2 does not store the past states but calculcates the flapping
|
||||
threshold from a single value based on counters and half-life values. Icinga 2 compares
|
||||
the value with a single flapping threshold configuration attribute.
|
||||
|
||||
|
||||
## State Retention
|
||||
|
||||
Icinga 1.x uses retention.dat to save historical and modified-at-runtime data over restarts.
|
||||
Icinga 2 uses its own icinga2.state file with a json-like serialized format.
|
||||
|
||||
|
||||
## Logging
|
||||
|
||||
Icinga 1.x supports syslog facilities and writes to its own icinga.log and archives. These logs
|
||||
are used in Icinga 1.x Classic UI to generate historical reports.
|
||||
|
||||
Icinga 2 compat library provides the CompatLogger object which writes the icinga.log and archive
|
||||
in Icinga 1.x format in order to stay compatible with Classic UI and other addons.
|
||||
The native Icinga 2 logging facilities are split into three configuration objects: SyslogLogger,
|
||||
FileLogger, StreamLogger. Each of them got their own severity and target configuration.
|
||||
|
||||
|
||||
## Broker Modules and Features
|
||||
|
||||
Icinga 1.x broker modules are binary incompatible with the Icinga 2 component loader.
|
||||
Therefore the module configuration cannot be copied 1:1
|
||||
|
||||
Icinga 1.x IDOUtils was implemented from scratch as Icinga 2 feature which can be loaded
|
||||
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.
|
||||
|
||||
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).
|
||||
|
||||
### IDOUtils Database Backend
|
||||
|
||||
Icinga 2 uses Ido<DBType>Connection configuration objects re-using some options known from
|
||||
Icinga 1.x IDOUtils such as the database credentials, instance_name or the cleanup attributes
|
||||
for max age of table entries.
|
||||
|
||||
### Enable Features
|
||||
|
||||
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.
|
||||
|
|
@ -23,6 +23,7 @@ EXTRA_DIST = \
|
|||
5-icinga-template-library.md \
|
||||
6-advanced-topics.md \
|
||||
7-migrating-from-icinga-1x.md \
|
||||
8-differences-between-icinga-1x-and-2.md \
|
||||
icinga2.8
|
||||
|
||||
icinga2docdir = ${docdir}
|
||||
|
|
|
|||
Loading…
Reference in New Issue