granicus.if.org Git - icinga2/blob - doc/3.02-commands.md

   1 ## <a id="commands"></a> Commands
   2
   3 Icinga 2 uses three different command object types to specify how
   4 checks should be performed, notifications should be sent and
   5 events should be handled.
   6
   7 ### <a id="command-environment-variables"></a> Environment Varialbes for Commands
   8
   9 Please check [Runtime Custom Attributes as Environment Variables](#runtime-custom-attribute-env-vars).
  10
  11 ### <a id="check-commands"></a> Check Commands
  12
  13 `CheckCommand` objects define the command line how a check is called.
  14
  15 `CheckCommand` objects require the ITL template `plugin-check-command`
  16 to support native plugin based check methods.
  17
  18 Unless you have done so already, download your check plugin and put it
  19 into the `PluginDir` directory. The following example uses the
  20 `check_disk` plugin shipped with the Nagios Plugins package.
  21
  22 The plugin path and all command arguments are made a list of
  23 double-quoted string arguments for proper shell escaping.
  24
  25 Call the `check_disk` plugin with the `--help` parameter to see
  26 all available options. Our example defines warning (`-w`) and
  27 critical (`-c`) thresholds for the disk usage. Without any
  28 partition defined (`-p`) it will check all local partitions.
  29
  30 Define the default check command custom attribute `wfree` and `cfree` freely
  31 definable naming schema) and their default threshold values. You can
  32 then use these custom attributes as runtime macros on the command line.
  33
  34 The default custom attributes can be overridden by the custom attributes
  35 defined in the service using the check command `disk`. The custom attributes
  36 can also be inherited from a parent template using additive inheritance (`+=`).
  37
  38     object CheckCommand "disk" {
  39       import "plugin-check-command"
  40
  41       command = [
  42         PluginDir + "/check_disk",
  43         "-w", "$wfree$%",
  44         "-c", "$cfree$%"
  45       ],
  46
  47       vars.wfree = 20
  48       vars.cfree = 10
  49     }
  50
  51 The host `localhost` with the service `disk` checks all disks with modified
  52 custom attributes (warning thresholds at `10%`, critical thresholds at `5%`
  53 free disk space).
  54
  55     object Host "localhost" {
  56       import "generic-host"
  57
  58       vars.address = "127.0.0.1"
  59       vars.address6 = "::1"
  60     }
  61
  62     object Service "disk" {
  63       import "generic-service"
  64
  65       host_name = "localhost"
  66       check_command = "disk"
  67
  68       vars.wfree = 10
  69       vars.cfree = 5
  70     }
  71
  72
  73 ### <a id="notification-commands"></a> Notification Commands
  74
  75 `NotificationCommand` objects define how notifications are delivered to external
  76 interfaces (E-Mail, XMPP, IRC, Twitter, etc).
  77
  78 `NotificationCommand` objects require the ITL template `plugin-notification-command`
  79 to support native plugin-based notifications.
  80
  81 Below is an example using runtime macros from Icinga 2 (such as `$SERVICEOUTPUT$` for
  82 the current check output) sending an email to the user(s) associated with the
  83 notification itself (`email` custom attribute provided as `$USERMACRO$`).
  84
  85 If you require default custom attribute definitions, you can add a `vars` dictionary
  86 as shown for the `CheckCommand` object.
  87
  88 TODO
  89
  90     object NotificationCommand "mail-service-notification" {
  91       import "plugin-notification-command"
  92
  93       command = [ SysconfDir + "/icinga2/scripts/mail-notification.sh" ]
  94
  95       env = {
  96         "NOTIFICATIONTYPE" = "$notification.type$"
  97         "SERVICEDESC" = "$service.description$"
  98         "HOSTALIAS" = "$host.displayname$",
  99         "HOSTADDRESS" = "$host.vars.address$",
 100         "SERVICESTATE" = "$service.state$",
 101         "LONGDATETIME" = "$icinga.longdatetime$",
 102         "SERVICEOUTPUT" = "$service.output$",
 103         "NOTIFICATIONAUTHORNAME" = "$notification.author$",
 104         "NOTIFICATIONCOMMENT" = "$notification.comment$",
 105         "HOSTDISPLAYNAME" = "$host.displayname$",
 106         "SERVICEDISPLAYNAME" = "$service.displayname$",
 107         "USEREMAIL" = "$user.vars.email$"
 108       }
 109     }
 110
 111 The command attribute in the `mail-service-notification` command refers to the following
 112 shell script. The macros specified in the `env` array are exported
 113 as environment variables and can be used in the notification script:
 114
 115     #!/usr/bin/env bash
 116     template=$(cat <<TEMPLATE
 117     ***** Icinga  *****
 118
 119     Notification Type: $NOTIFICATIONTYPE
 120
 121     Service: $SERVICEDESC
 122     Host: $HOSTALIAS
 123     Address: $HOSTADDRESS
 124     State: $SERVICESTATE
 125
 126     Date/Time: $LONGDATETIME
 127
 128     Additional Info: $SERVICEOUTPUT
 129
 130     Comment: [$NOTIFICATIONAUTHORNAME] $NOTIFICATIONCOMMENT
 131     TEMPLATE
 132     )
 133
 134     /usr/bin/printf "%b" $template | mail -s "$NOTIFICATIONTYPE - $HOSTDISPLAYNAME - $SERVICEDISPLAYNAME is $SERVICESTATE" $USEREMAIL
 135
 136 While it's possible to specify the entire notification command right
 137 in the NotificationCommand object it is generally advisable to create a
 138 shell script in the `/etc/icinga2/scripts` directory and have the
 139 NotificationCommand object refer to that.
 140
 141 ### <a id="event-commands"></a> Event Commands
 142
 143 Unlike notifications event commands are called on every service state change
 144 if defined. Therefore the `EventCommand` object should define a command line
 145 evaluating the current service state and other service runtime attributes
 146 available through runtime vars. Runtime macros such as `$SERVICESTATETYPE$`
 147 and `$SERVICESTATE$` will be processed by Icinga 2 helping on fine-granular
 148 events being triggered.
 149
 150 Common use case scenarios are a failing HTTP check requiring an immediate
 151 restart via event command, or if an application is locked and requires
 152 a restart upon detection.
 153
 154 `EventCommand` objects require the ITL template `plugin-event-command`
 155 to support native plugin based checks.
 156
 157 The example below is fictive and not necessarily meant for production use.
 158 When the event command is triggered on a service state change, it will
 159 send a check result using the `process_check_result` script forcibly
 160 changing the service state back to `OK` (`-r 0`) providing some debug
 161 information in the check output (`-o`).
 162
 163     object EventCommand "plugin-event-process-check-result" {
 164       import "plugin-event-command"
 165
 166       command = [
 167         PluginDir + "/process_check_result",
 168         "-H", "$host.name$",
 169         "-S", "$service.description$",
 170         "-c", "/var/run/icinga2/cmd/icinga2.cmd",
 171         "-r", "0",
 172         "-o", "Event Handler triggered in state '$SERVICESTATE$' with output '$SERVICEOUTPUT$'."
 173       ]
 174     }