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/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 constant and make sure they are executable by the Icinga 2 user.

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.

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" {
  import "plugin-check-command"

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

  macros.wfree = 20
  macros.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" {
  import "generic-host"

  macros.address = "127.0.0.1"
  macros.address6 = "::1"
}

apply Service "disk" {
  import "generic-service"

  check_command = "disk"
  
  macros.wfree = 10
  macros.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 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" {
  import "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.

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