## 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. ### 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 in 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", }, } ### Notification Commands `NotificationCommand` objects define how notifications are sent to external interfaces (E-Mail, XMPP, IRC, Twitter, etc). > **Note** > > `NotificationCommand` objects require the ITL template `plugin-notification-command` > to support native plugin based checks. 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$`). Please note the notation for better readability using multiple lines enclosed with `{{{ ... }}}`. You can use a single line as argument item as well. 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 = [ "/usr/bin/printf", "\"%b\"", {{{\"***** Icinga ***** Notification Type: $NOTIFICATIONTYPE$ Service: $SERVICEDESC$ Host: $HOSTALIAS$ Address: $HOSTADDRESS$ State: $SERVICESTATE$ Date/Time: $LONGDATETIME$ Additional Info: $SERVICEOUTPUT$ Comment: [$NOTIFICATIONAUTHORNAME$] $NOTIFICATIONCOMMENT$\"}}}, "-s", "\"$NOTIFICATIONTYPE$ - $HOSTDISPLAYNAME$ - $SERVICEDISPLAYNAME$ is $SERVICESTATE$\"", "$USEREMAIL$" ] } ### 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 a an application is locked and requires a restart on 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$'." ] }