## <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 global `PluginDir` constant (located in
> `/etc/icinga2/constants.conf` by default) and use
> it in all your command object definitions.
> Put your plugins and scripts into the directory defined by the `PluginDir` constant
> and make sure they are executable by the Icinga 2 user.

### <a id="command-environment-variables"></a> Environment Varialbes for Commands

Please check [Runtime Custom Attributes as Environment Variables](#runtime-custom-attribute-env-vars).

### <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 custom attribute `wfree` and `cfree` freely
definable naming schema) and their default threshold values. You can
then use these custom attributes as runtime macros on the command line.

> **Note**
>
> The default custom attributes can be overridden by the custom attributes
> defined in the service using the check command `disk`. The custom attributes
> can also be inherited from a parent template using additive inheritance (`+=`).

    object CheckCommand "disk" {
      import "plugin-check-command"

      command = [
        PluginDir + "/check_disk",
        "-w", "$wfree$%",
        "-c", "$cfree$%"
      ],

      vars.wfree = 20
      vars.cfree = 10
    }

The host `localhost` with the service `disk` checks all disks with modified
custom attributes (warning thresholds at `10%`, critical thresholds at `5%`
free disk space).

    object Host "localhost" {
      import "generic-host"
  
      vars.address = "127.0.0.1"
      vars.address6 = "::1"
    }

    object Service "disk" {
      import "generic-service"
 
      host_name = "localhost"
      check_command = "disk"
      
      vars.wfree = 10
      vars.cfree = 5
    }
    

### <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` custom attribute provided as `$USERMACRO$`).

If you require default custom attribute definitions, you can add a `vars` dictionary
as shown for the `CheckCommand` object.

TODO

    object NotificationCommand "mail-service-notification" {
      import "plugin-notification-command"

      command = [ IcingaSysconfDir + "/icinga2/scripts/mail-notification.sh" ]

      env = {
        "NOTIFICATIONTYPE" = "$notification.type$"
        "SERVICEDESC" = "$service.description$"
        "HOSTALIAS" = "$host.displayname$",
        "HOSTADDRESS" = "$host.vars.address$",
        "SERVICESTATE" = "$service.state$",
        "LONGDATETIME" = "$icinga.longdatetime$",
        "SERVICEOUTPUT" = "$service.output$",
        "NOTIFICATIONAUTHORNAME" = "$notification.author$",
        "NOTIFICATIONCOMMENT" = "$notification.comment$",
    	"HOSTDISPLAYNAME" = "$host.displayname$",
        "SERVICEDISPLAYNAME" = "$service.displayname$",
        "USEREMAIL" = "$user.vars.email$"
      }
    }

The command attribute in the `mail-service-notification` command refers to the following
shell script. The macros specified in the `env` 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 vars. 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" {
      import "plugin-event-command"

      command = [ 
        PluginDir + "/process_check_result",
        "-H", "$host.name$",
        "-S", "$service.description$",
        "-c", "/var/run/icinga2/cmd/icinga2.cmd",
        "-r", "0",
        "-o", "Event Handler triggered in state '$SERVICESTATE$' with output '$SERVICEOUTPUT$'."
      ]       
    }