Documentation: Update commands and external commands.

doc/3.02-commands.md

@@ -1,5 +1,167 @@
 ## Commands
 
-Icinga 2 uses command objects to specify how checks should be performed.
+Icinga 2 uses three different command object types to specify how
+checks should be performed, notifications should be sent and
+events should be handled.
+
+> **Tip**
+>
+> Define the `$plugindir$` macro in your global `IcingaMacros` variable
+> (located in `/etc/icinga2/conf.d/macros.conf` by default) and use
+> it in all your command object definitions.
+> Put your plugins and scripts into the directory defined by the `$plugindir$` macro
+> and make sure they are executable by the Icinga 2 user.
+
+### Check Commands
+
+`CheckCommand` objects define the command line how a check is called.
+
+> **Note**
+>
+> `CheckCommand` objects require the ITL template `plugin-check-command`
+> to support native plugin based check methods.
+
+Unless you have done so already, download your check plugin and put it
+into the `$plugindir$` directory. The following example uses the
+`check_disk` plugin shipped with the Nagios Plugins package.
+
+The plugin path and all command arguments are made a list of
+double-quoted string arguments for proper shell escaping.
+
+Call the `check_disk` plugin with the `--help` parameter to see
+all available options. Our example defines warning (`-w`) and
+critical (`-c`) thresholds for the disk usage. Without any
+partition defined (`-p`) it will check all local partitions.
+
+Define the default check command macros `wfree` and `cfree` (freely
+definable naming schema) and their default threshold values. You can
+then use these macros in the command line.
+
+> **Note**
+>
+> The default macros can be overridden by the macros defined in
+> the service using the check command `disk`. The macros can also
+> be inherited from a parent template using additive inheritance (`+=`).
+
+    object CheckCommand "disk" inherits "plugin-check-command" {
+      command = [
+        "$plugindir$/check_disk",
+        "-w", "$wfree$%",
+        "-c", "$cfree$%"
+      ],
+
+      macros += {
+        wfree = 20,
+        cfree = 10,
+      }
+    }
+
+The host `localhost` with the service `disk` checks all disks with modified
+macros (warning thresholds at `10%`, critical thresholds at `5%` free disk
+space).
+
+    object Host "localhost" inherits "generic-host" {
+
+      services["disk"] = {
+        templates = [ "generic-service" ],
+
+        check_command = "disk",
+        macros += {
+          wfree = 10,
+          cfree = 5
+        }
+      },
+
+      macros = {
+        address = "127.0.0.1",
+        address6 = "::1",
+      },
+    }
+    
+
+### Notification Commands
+
+`NotificationCommand` objects define how notifications are sent to external
+interfaces (E-Mail, XMPP, IRC, Twitter, etc).
+
+> **Note**
+>
+> `NotificationCommand` objects require the ITL template `plugin-notification-command`
+> to support native plugin based checks.
+
+Below is an example using runtime macros from Icinga 2 (such as `$SERVICEOUTPUT$` for
+the current check output) sending an email to the user(s) associated with the
+notification itself (`email` macro attribute provided as `$USERMACRO$`).
+
+Please note the notation for better readability using multiple lines enclosed with
+`{{{ ... }}}`. You can use a single line as argument item as well. If you require
+default macro definitions, you can add a macro dictionary as shown for the
+`CheckCommand` object.
+
+    object NotificationCommand "mail-service-notification" inherits "plugin-notification-command" {
+      command = [
+        "/usr/bin/printf",
+        "\"%b\"",
+        {{{\"***** Icinga  *****
+    
+        Notification Type: $NOTIFICATIONTYPE$
+    
+        Service: $SERVICEDESC$
+        Host: $HOSTALIAS$
+        Address: $HOSTADDRESS$
+        State: $SERVICESTATE$
+    
+        Date/Time: $LONGDATETIME$
+    
+        Additional Info: $SERVICEOUTPUT$
+    
+        Comment: [$NOTIFICATIONAUTHORNAME$] $NOTIFICATIONCOMMENT$\"}}},
+        "-s",
+        "\"$NOTIFICATIONTYPE$ - $HOSTDISPLAYNAME$ - $SERVICEDISPLAYNAME$ is $SERVICESTATE$\"",
+        "$USEREMAIL$"
+      ]
+    }
+
+
+
+### Event Commands
+
+Unlike notifications event commands are called on every service state change
+if defined. Therefore the `EventCommand` object should define a command line
+evaluating the current service state and other service runtime attributes
+available through runtime macros. Runtime macros such as `$SERVICESTATETYPE$`
+and `$SERVICESTATE$` will be processed by Icinga 2 helping on fine-granular
+events being triggered.
+
+Common use case scenarios are a failing HTTP check requiring an immediate
+restart via event command, or a an application is locked and requires
+a restart on detection.
+
+> **Note**
+>
+> `EventCommand` objects require the ITL template `plugin-event-command`
+> to support native plugin based checks.
+
+The example below is fictive and not necessarily meant for production use.
+When the event command is triggered on a service state change, it will
+send a check result using the `process_check_result` script forcibly
+changing the service state back to `OK` (`-r 0`) providing some debug
+information in the check output (`-o`).
+
+    object EventCommand "plugin-event-process-check-result" inherits "plugin-event-command" {
+      command = [ 
+        "$plugindir$/process_check_result",
+        "-H",
+        "$HOSTNAME$",
+        "-S",
+        "$SERVICEDESC$",
+        "-c",
+        "/var/run/icinga2/cmd/icinga2.cmd",
+        "-r",
+        "0",
+        "-o",
+        "Event Handler triggered in state '$SERVICESTATE$' with output '$SERVICEOUTPUT$'."
+      ]       
+    }
+    
 
-TODO

doc/3.04-notifications.md

@@ -2,6 +2,11 @@
 
 TODO
 
+Notifications on alerts are an integral part of your Icinga 2 monitoring application.
+You should choose which information you (and your notified users) are interested in
+case of emergency, and also which information does not provide any value to you and
+your environment.
+
 ### Notification Escalations
 
 TODO

doc/3.08-external-commands.md

@@ -1,3 +1,41 @@
 ## External Commands
 
-TODO
+Icinga 2 provides an external command pipe for processing commands
+triggering specific actions (for example rescheduling a service check
+through the web interface).
+
+In order to enable the `ExternalCommandListener` configuration use the
+following command and restart Icinga 2 afterwards:
+
+    # i2enfeature command
+    
+Icinga 2 creates the command pipe file as `/var/run/icinga2/cmd/icinga2.cmd`
+using the default configuration.
+
+Web interfaces and other Icinga addons are able to send commands to
+Icinga 2 through the external command pipe, for example for rescheduling
+a forced service check:
+
+    # /bin/echo "[`date +%s`] SCHEDULE_FORCED_SVC_CHECK;localhost;ping4;`date +%s`" >> /var/run/icinga2/cmd/icinga2.cmd
+    
+    # tail -f /var/log/messages
+    
+    Oct 17 15:01:25 nbmif icinga2: Executing external command: [1382014885] SCHEDULE_FORCED_SVC_CHECK;localhost;ping4;1382014885
+    Oct 17 15:01:25 nbmif icinga2: Rescheduling next check for service 'ping4'
+    
+> **Note**
+>
+> The command pipe file is owned by the group `icingacmd` with read/write
+> permissions. Add your webserver's user to the group `icingacmd` to
+> enable sending commands to Icinga 2 through your web interface.
+
+    # usermod -G -a icingacmd www-data
+
+    
+    
+### External Command List
+
+A list of currently supported external commands can be found on the
+[Icinga Wiki](https://wiki.icinga.org/display/icinga2/External+Commands).
+Detailed information on the commands and their required parameters can be found
+on the [Icinga 1.x documentation](http://docs.icinga.org/latest/en/extcommands2.html).

doc/4.3-object-types.md

@@ -183,7 +183,29 @@ A user.
 
 Example:
 
-    TODO
+    object User "icingaadmin" {
+      display_name = "Icinga 2 Admin",
+      groups = [ "icingaadmins" ],
+
+      enable_notifications = 1,
+      notification_period = "24x7",
+
+      notification_state_filter = (StateFilterWarning |
+                                   StateFilterCritical |
+                                   StateFilterUnknown),
+      notification_type_filter = (NotificationFilterProblem |
+                                  NotificationFilterRecovery),
+      macros = {
+        "name" = "Icinga 2 Admin",
+        "email" = "icinga@localhost",
+        "pager" = "icingaadmin@localhost.localdomain"
+      },
+
+      custom = {
+        notes = "This is the Icinga 2 Admin account.",
+      }
+    }
+
 
 Attributes:
 
@@ -191,6 +213,7 @@ Attributes:
   ----------------|----------------
   display_name    |**Optional.** A short description of the user.
   macros          |**Optional.** A dictionary containing macros that are specific to this user.
+  custom          |**Optional.** A dictionary containing custom attributes that are specific to this user.
   groups          |TODO
   enable_notifications|TODO
   notification_period|TODO
@@ -203,8 +226,8 @@ A user group.
 
 Example:
 
-    object UserGroup "noc-staff" {
+    object UserGroup "icingaadmins" {
-        display_name = "NOC Staff"
+        display_name = "Icinga 2 Admin Group"
     }
 
 Attributes: