icinga2/doc/3.02-commands.md

## <a id="commands"></a> Commands

Icinga 2 uses three different command object types to specify how
checks should be performed, notifications should be sent and
events should be handled.

> **Note**
>
> 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.

### <a id="environment-macros"></a> Environment Macros

If your plugins require environment macros instead of command arguments you have
to define all macros in the `export_macros` attribute as list.

    export_macros = [
      "HOSTNAME",
      "SERVICEDESC",
      "SERVICESTATE"
    ]
    
> **Note**
>
> Use templates to define global `export_macros` attributes for the three
> command types and let each command object inherit the attribute.

### <a id="check-commands"></a> 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 on 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",
      },
    }
    

### <a id="notification-commands"></a> Notification Commands

`NotificationCommand` objects define how notifications are delivered to external
interfaces (E-Mail, XMPP, IRC, Twitter, etc).

> **Note**
>
> `NotificationCommand` objects require the ITL template `plugin-notification-command`
> to support native plugin-based notifications.

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$`).

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 = [ (IcingaSysconfDir + "/icinga2/scripts/mail-notification.sh") ],

      export_macros = [
        "NOTIFICATIONTYPE",
        "SERVICEDESC",
        "HOSTALIAS",
        "HOSTADDRESS",
        "SERVICESTATE",
        "LONGDATETIME",
        "SERVICEOUTPUT",
        "NOTIFICATIONAUTHORNAME",
        "NOTIFICATIONCOMMENT",
        "HOSTDISPLAYNAME",
        "SERVICEDISPLAYNAME",
        "USEREMAIL"
      ]
    }

The command attribute in the `mail-service-notification` command refers to the following
shell script. The macros specified in the `export_macros` array are exported
as environment variables and can be used in the notification script:

    #!/usr/bin/env bash
    template=$(cat <<TEMPLATE
    ***** Icinga  *****

    Notification Type: $NOTIFICATIONTYPE

    Service: $SERVICEDESC
    Host: $HOSTALIAS
    Address: $HOSTADDRESS
    State: $SERVICESTATE

    Date/Time: $LONGDATETIME

    Additional Info: $SERVICEOUTPUT

    Comment: [$NOTIFICATIONAUTHORNAME] $NOTIFICATIONCOMMENT
    TEMPLATE
    )

    /usr/bin/printf "%b" $template | mail -s "$NOTIFICATIONTYPE - $HOSTDISPLAYNAME - $SERVICEDISPLAYNAME is $SERVICESTATE" $USEREMAIL

> **Best Practice**
>
> While it's possible to specify the entire notification command right
> in the NotificationCommand object it is generally advisable to create a
> shell script in the `/etc/icinga2/scripts` directory and have the
> NotificationCommand object refer to that.

### <a id="event-commands"></a> 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 if an application is locked and requires
a restart upon 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$'."
      ]       
    }