# <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`.
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
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
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:
* [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
> 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
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
}
-### <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.
}
-### <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:
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.
}
-### <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.
projects / icinga2 / commitdiff