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.

### <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.

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

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

`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

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.

`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$'."
      ]       
    }