Enhance advanced topics with (scheduled) downtimes

doc/04-configuring-icinga-2.md

@@ -653,8 +653,10 @@ More details on `Notification` object attributes can be found [here](09-object-t
 The `load` service apply rule defined in [services.conf](04-configuring-icinga-2.md#services-conf) defines
 the `backup_downtime` custom attribute.
 
-The [ScheduledDowntime](09-object-types.md#objecttype-scheduleddowntime) apply rule uses this attribute
+The ScheduledDowntime apply rule uses this attribute to define the default value
-to define the default value for the time ranges required for recurring downtime slots.
+for the time ranges required for recurring downtime slots.
+
+Learn more about downtimes in [this chapter](08-advanced-topics.md#downtimes).
 
     apply ScheduledDowntime "backup-downtime" to Service {
       author = "icingaadmin"

doc/06-distributed-monitoring.md

@@ -1844,7 +1844,7 @@ to all nodes depending on them. Common examples are:
 
 * Templates which are imported into zone specific objects.
 * Command objects referenced by Host, Service, Notification objects.
-* Apply rules for services, notifications, dependencies and scheduled downtimes.
+* Apply rules for services, notifications and dependencies.
 * User objects referenced in notifications.
 * Group objects.
 * TimePeriod objects.
@@ -1892,7 +1892,7 @@ into your global zone.
 Example:
 
     [root@icinga2-master1.localdomain /]# cd /etc/icinga2/conf.d
-    [root@icinga2-master1.localdomain /etc/icinga2/conf.d]# cp {commands,downtimes,groups,notifications,services,templates,timeperiods,users}.conf /etc/icinga2/zones.d/global-templates
+    [root@icinga2-master1.localdomain /etc/icinga2/conf.d]# cp {commands,groups,notifications,services,templates,timeperiods,users}.conf /etc/icinga2/zones.d/global-templates
 
 ### Health Checks <a id="distributed-monitoring-health-checks"></a>
 

doc/08-advanced-topics.md

@@ -8,22 +8,36 @@ can safely skip over things you're not interested in.
 Downtimes can be scheduled for planned server maintenance or
 any other targeted service outage you are aware of in advance.
 
-Downtimes will suppress any notifications, and may trigger other
+Downtimes suppress notifications and can trigger other
 downtimes too. If the downtime was set by accident, or the duration
-exceeds the maintenance, you can manually cancel the downtime.
+exceeds the maintenance windows, you can manually cancel the downtime.
-Planned downtimes will also be taken into account for SLA reporting
+
-tools calculating the SLAs based on the state and downtime history.
+### Scheduling a downtime <a id="scheduling-downtime"></a>
+
+The most convenient way to schedule planned downtimes is to create
+them in Icinga Web 2 inside the host/service detail view. Select
+multiple hosts/services from the listing with the shift key to
+schedule multiple downtimes.
+
+![Downtime in Icinga Web 2](images/advanced-topics/icingaweb2_downtime_handled.png)
+
+In addition to that you can schedule a downtime by using the Icinga 2 API action
+[schedule-downtime](12-icinga2-api.md#icinga2-api-actions-schedule-downtime).
+This is especially useful to schedule a downtime on-demand inside a (remote) backup
+script, or create maintenance downtimes from a cron job for specific dates and intervals.
 
 Multiple downtimes for a single object may overlap. This is useful
 when you want to extend your maintenance window taking longer than expected.
 If there are multiple downtimes triggered for one object, the overall downtime depth
 will be greater than `1`.
 
-
 If the downtime was scheduled after the problem changed to a critical hard
 state triggering a problem notification, and the service recovers during
 the downtime window, the recovery notification won't be suppressed.
 
+Planned downtimes are also taken into account for SLA reporting
+tools calculating the SLAs based on the state and downtime history.
+
 ### Fixed and Flexible Downtimes <a id="fixed-flexible-downtimes"></a>
 
 A `fixed` downtime will be activated at the defined start time, and
@@ -51,13 +65,6 @@ For that reason, you may want to schedule a downtime between 07:30 and
 its trigger time until the duration is over. After that, the downtime
 is removed (may happen before or after the actual end time!).
 
-### Scheduling a downtime <a id="scheduling-downtime"></a>
-
-You can schedule a downtime either by using the Icinga 2 API action
-[schedule-downtime](12-icinga2-api.md#icinga2-api-actions-schedule-downtime) or
-by sending an [external command](14-features.md#external-commands).
-
-
 #### Fixed Downtime <a id="fixed-downtime"></a>
 
 If the host/service changes into a NOT-OK state between the start and
@@ -102,22 +109,37 @@ recurring downtimes for services.
 
 Example:
 
-    apply ScheduledDowntime "backup-downtime" to Service {
+```
-      author = "icingaadmin"
+apply ScheduledDowntime "backup-downtime" to Service {
-      comment = "Scheduled downtime for backup"
+  author = "icingaadmin"
+  comment = "Scheduled downtime for backup"
 
-      ranges = {
+  ranges = {
-        monday = "02:00-03:00"
+    monday = "02:00-03:00"
-        tuesday = "02:00-03:00"
+    tuesday = "02:00-03:00"
-        wednesday = "02:00-03:00"
+    wednesday = "02:00-03:00"
-        thursday = "02:00-03:00"
+    thursday = "02:00-03:00"
-        friday = "02:00-03:00"
+    friday = "02:00-03:00"
-        saturday = "02:00-03:00"
+    saturday = "02:00-03:00"
-        sunday = "02:00-03:00"
+    sunday = "02:00-03:00"
-      }
+  }
 
-      assign where "backup" in service.groups
+  assign where "backup" in service.groups
-    }
+}
+```
+
+Icinga 2 attempts to find the next possible segment from a ScheduledDowntime object's
+`ranges` attribute, and wont create multiple downtimes in the future. In case you need
+all these downtimes planned and visible for the next days, weeks or months, schedule them
+manually via the [REST API](12-icinga2-api.md#icinga2-api-actions-schedule-downtime) using
+a script or cron job.
+
+> **Note**
+>
+> If ScheduledDowntime objects are synced in a distributed high-availability setup,
+> both will create the next possible downtime on their own. These runtime generated
+> downtimes are synced among both zone instances, and you may see sort-of duplicate downtimes
+> in Icinga Web 2.
 
 
 ## Comments <a id="comments-intro"></a>