icinga2/doc/3.02-commands.md

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.

Environment Varialbes for Commands

Please check Runtime Custom Attributes as Environment Variables.

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
}

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.

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