Documentation: Update Configuring Icinga 2

doc/5-configuring-icinga-2.md

@@ -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
+This chapter prodides an introduction into best practices with your Icinga 2 configuration.
-when installing the Icinga 2 packages.
+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,7 +136,7 @@ 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.
 
@@ -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)
+Includes default templates and dependencies for
-using service discovery and [config generation](9-monitoring-remote-systems.md#icinga2-remote-monitoring-master-discovery-generate-config)
+[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.