## 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
projects / icinga2 / blobdiff