tyler.durden
/
icinga2
mirror of https://github.com/Icinga/icinga2.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Documentation: Update Configuring Icinga 2

This commit is contained in:
Michael Friedrich 2015-02-11 17:16:44 +01:00
parent 06e6da081a
commit 42031b5faa
1 changed files with 76 additions and 17 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

93
doc/5-configuring-icinga-2.md
View File

@ -1,13 +1,70 @@
# <a id="configuring-icinga2-first-steps"></a> Configuring Icinga 2: First Steps
This chapter prodides an introduction to the configuration files which are automatically created
when installing the Icinga 2 packages.
This chapter prodides an introduction into best practices with your Icinga 2 configuration.
The configuration files which are automatically created when installing the Icinga 2 packages
are a good way to start with Icinga 2.
If you're interested in a detailed explanation of each language feature used in those
configuration files you can find more information in the [Language Reference](16-language-reference.md#language-reference)
chapter.
## <a id="icinga2-conf"></a> icinga2.conf
## <a id="configuration-best-practice"></a> Configuration Best Practice
If you are ready to configure additional hosts, services, notifications,
dependencies, etc, you should think about the requirements first and then
decide for a possible strategy.
There are many ways of creating Icinga 2 configuration objects:
* Manually with your preferred editor, for example vi(m), nano, notepad, etc.
* Generated by a [configuration management too](10-addons-plugins.md#configuration-tools) such as Puppet, Chef, Ansible, etc.
* A configuration addon for Icinga 2
* A custom exporter script from your CMDB or inventory tool
* your own.
In order to find the best strategy for your own configuration, ask yourself the following questions:
* Do your hosts share a common group of services (for example linux hosts with disk, load, etc checks)?
* Only a small set of users receives notifications and escalations for all hosts/services?
If you can at least answer one of these questions with yes, look for the
[apply rules](3-monitoring-basics.md#using-apply) logic instead of defining objects on a per
host and service basis.
* You are required to define specific configuration for each host/service?
* Does your configuration generation tool already know about the host-service-relationship?
Then you should look for the object specific configuration setting `host_name` etc accordingly.
Finding the best files and directory tree for your configuration is up to you. Make sure that
the [icinga2.conf](5-configuring-icinga-2.md#icinga2-conf) configuration file includes them,
and then think about:
* tree-based on locations, hostgroups, specific host attributes with sub levels of directories.
* flat `hosts.conf`, `services.conf`, etc files for rule based configuration.
* generated configuration with one file per host and a global configuration for groups, users, etc.
* one big file generated from an external application (probably a bad idea for maintaining changes).
* your own.
In either way of choosing the right strategy you should additionally check the following:
* Are there any specific attributes describing the host/service you could set as `vars` custom attributes?
You can later use them for applying assign/ignore rules, or export them into external interfaces.
* Put hosts into hostgroups, services into servicegroups and use these attributes for your apply rules.
* Use templates to store generic attributes for your objects and apply rules making your configuration more readable.
Details can be found in the [using templates](3-monitoring-basics.md#object-inheritance-using-templates) chapter.
* Apply rules may overlap. Keep a central place (for example, [services.conf](5-configuring-icinga-2.md#services-conf) or [notifications.conf](5-configuring-icinga-2.md#notifications-conf)) storing
the configuration instead of defining apply rules deep in your configuration tree.
* Every plugin used as check, notification or event command requires a `Command` definition.
Further details can be looked up in the [check commands](3-monitoring-basics.md#check-commands) chapter.
If you happen to have further questions, do not hesitate to join the
[community support channels](https://support.icinga.org)
and ask community members for their experience and best practices.
## <a id="configuring-icinga2-overview"></a> Configuration Overview
### <a id="icinga2-conf"></a> icinga2.conf
An example configuration file is installed for you in `/etc/icinga2/icinga2.conf`.
@ -79,14 +136,14 @@ and their generated configuration described in
You can put your own configuration files in the [conf.d](5-configuring-icinga-2.md#conf-d) directory. This
directive makes sure that all of your own configuration files are included.
## <a id="constants-conf"></a> constants.conf
### <a id="constants-conf"></a> constants.conf
The `constants.conf` configuration file can be used to define global constants.
By default, you need to make sure to set these constants:
* The `PluginDir` constant must be set to the path where the [Monitoring Project plugins](2-getting-started.md#setting-up-check-plugins) are installed.
This constant is used by a number of
This constant is used by a number of
[built-in check command definitions](7-icinga-template-library.md#plugin-check-commands).
* The `NodeName` constant defines your local node name. Should be set to FQDN which is the default
if not set. This constant is required for local host configuration, monitoring remote clients and
@ -117,7 +174,7 @@ Example:
The `ZoneName` and `TicketSalt` constants are required for remote client
and distributed setups only.
## <a id="conf-d"></a> The conf.d Directory
### <a id="conf-d"></a> The conf.d Directory
This directory contains example configuration which should help you get started
with monitoring the local host and its services. It is included in the
@ -131,7 +188,7 @@ You are certainly not bound to it. Remove it, if you prefer your own
way of deploying Icinga 2 configuration.
Further details on configuration best practice and how to build your
own strategy is described in [this chapter](#configuration-best-practice).
own strategy is described in [this chapter](5-configuring-icinga-2.md#configuration-best-practice).
Available configuration files which are installed by default:
@ -146,7 +203,7 @@ Available configuration files which are installed by default:
* [timeperiods.conf](5-configuring-icinga-2.md#timeperiods-conf)
* [satellite.conf](5-configuring-icinga-2.md#satellite-conf)
### <a id="hosts-conf"></a> hosts.conf
#### <a id="hosts-conf"></a> hosts.conf
The `hosts.conf` file contains an example host based on your
`NodeName` setting in [constants.conf](5-configuring-icinga-2.md#constants-conf). You
@ -240,7 +297,7 @@ host and your additional hosts are getting [services](5-configuring-icinga-2.md#
> don't worry - the [monitoring basics](3-monitoring-basics.md#monitoring-basics) chapter will explain
> that in detail.
### <a id="services-conf"></a> services.conf
#### <a id="services-conf"></a> services.conf
These service [apply rules](16-language-reference.md#apply) will show you how to monitor
the local host, but also allow you to re-use or modify them for
@ -382,7 +439,7 @@ the hosts and services and their check commands.
Further details on the monitoring configuration can be found in the
[monitoring basics](3-monitoring-basics.md#monitoring-basics) chapter.
### <a id="users-conf"></a> users.conf
#### <a id="users-conf"></a> users.conf
Defines the `icingaadmin` User and the `icingaadmins` UserGroup. The latter is used in
[hosts.conf](5-configuring-icinga-2.md#hosts-conf) for defining a custom host attribute later used in
@ -402,7 +459,7 @@ Defines the `icingaadmin` User and the `icingaadmins` UserGroup. The latter is u
}
### <a id="notifications-conf"></a> notifications.conf
#### <a id="notifications-conf"></a> notifications.conf
Notifications for check alerts are an integral part or your
Icinga 2 monitoring stack.
@ -492,7 +549,7 @@ and the attribute string to match with.
}
### <a id="templates-conf"></a> templates.conf
#### <a id="templates-conf"></a> templates.conf
Most of the example configuration objects use generic global templates by
default:
@ -540,7 +597,7 @@ The `hostalive` check command is part of the
More details on `Notification` object attributes can be found [here](6-object-types.md#objecttype-notification).
### <a id="downtimes-conf"></a> downtimes.conf
#### <a id="downtimes-conf"></a> downtimes.conf
The `load` service apply rule defined in [services.conf](5-configuring-icinga-2.md#services-conf) defines
the `backup_downtime` custom attribute.
@ -566,17 +623,19 @@ to define the default value for the time ranges required for recurring downtime
}
### <a id="timeperiods-conf"></a> timeperiods.conf
#### <a id="timeperiods-conf"></a> timeperiods.conf
This file contains the default timeperiod definitions for `24x7`, `9to5`
and `never`. Timeperiod objects are referenced by `*period`
objects such as hosts, services or notifications.
### <a id="satellite-conf"></a> satellite.conf
#### <a id="satellite-conf"></a> satellite.conf
Includes default templates and dependencies for [monitoring remote clients](9-monitoring-remote-systems.md#icinga2-remote-client-monitoring)
using service discovery and [config generation](9-monitoring-remote-systems.md#icinga2-remote-monitoring-master-discovery-generate-config)
Includes default templates and dependencies for
[monitoring remote clients](9-monitoring-remote-systems.md#icinga2-remote-client-monitoring)
using service discovery and
[config generation](9-monitoring-remote-systems.md#icinga2-remote-monitoring-master-discovery-generate-config)
on the master. Can be ignored/removed on setups not using this features.