mirror of https://github.com/Icinga/icinga2.git
207 lines
6.4 KiB
Markdown
207 lines
6.4 KiB
Markdown
## 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 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" inherits "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 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$'."
|
|
]
|
|
}
|
|
|
|
|