mirror of https://github.com/Icinga/icinga2.git
Documentation: Update commands and external commands.
This commit is contained in:
Michael Friedrich
parent
25f92b73e6
commit
2164ff22b9
|
|
@ -1,5 +1,167 @@
|
|||
## Commands
|
||||
|
||||
Icinga 2 uses command objects to specify how checks should be performed.
|
||||
Icinga 2 uses three different command object types to specify how
|
||||
checks should be performed, notifications should be sent and
|
||||
events should be handled.
|
||||
|
||||
> **Tip**
|
||||
>
|
||||
> 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.
|
||||
|
||||
### 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$'."
|
||||
]
|
||||
}
|
||||
|
||||
|
||||
TODO
|
||||
|
|
|
|||
|
|
@ -2,6 +2,11 @@
|
|||
|
||||
TODO
|
||||
|
||||
Notifications on alerts are an integral part of your Icinga 2 monitoring application.
|
||||
You should choose which information you (and your notified users) are interested in
|
||||
case of emergency, and also which information does not provide any value to you and
|
||||
your environment.
|
||||
|
||||
### Notification Escalations
|
||||
|
||||
TODO
|
||||
|
|
|
|||
|
|
@ -1,3 +1,41 @@
|
|||
## External Commands
|
||||
|
||||
TODO
|
||||
Icinga 2 provides an external command pipe for processing commands
|
||||
triggering specific actions (for example rescheduling a service check
|
||||
through the web interface).
|
||||
|
||||
In order to enable the `ExternalCommandListener` configuration use the
|
||||
following command and restart Icinga 2 afterwards:
|
||||
|
||||
# i2enfeature command
|
||||
|
||||
Icinga 2 creates the command pipe file as `/var/run/icinga2/cmd/icinga2.cmd`
|
||||
using the default configuration.
|
||||
|
||||
Web interfaces and other Icinga addons are able to send commands to
|
||||
Icinga 2 through the external command pipe, for example for rescheduling
|
||||
a forced service check:
|
||||
|
||||
# /bin/echo "[`date +%s`] SCHEDULE_FORCED_SVC_CHECK;localhost;ping4;`date +%s`" >> /var/run/icinga2/cmd/icinga2.cmd
|
||||
|
||||
# tail -f /var/log/messages
|
||||
|
||||
Oct 17 15:01:25 nbmif icinga2: Executing external command: [1382014885] SCHEDULE_FORCED_SVC_CHECK;localhost;ping4;1382014885
|
||||
Oct 17 15:01:25 nbmif icinga2: Rescheduling next check for service 'ping4'
|
||||
|
||||
> **Note**
|
||||
>
|
||||
> The command pipe file is owned by the group `icingacmd` with read/write
|
||||
> permissions. Add your webserver's user to the group `icingacmd` to
|
||||
> enable sending commands to Icinga 2 through your web interface.
|
||||
|
||||
# usermod -G -a icingacmd www-data
|
||||
|
||||
|
||||
|
||||
### External Command List
|
||||
|
||||
A list of currently supported external commands can be found on the
|
||||
[Icinga Wiki](https://wiki.icinga.org/display/icinga2/External+Commands).
|
||||
Detailed information on the commands and their required parameters can be found
|
||||
on the [Icinga 1.x documentation](http://docs.icinga.org/latest/en/extcommands2.html).
|
||||
|
|
|
|||
|
|
@ -183,7 +183,29 @@ A user.
|
|||
|
||||
Example:
|
||||
|
||||
TODO
|
||||
object User "icingaadmin" {
|
||||
display_name = "Icinga 2 Admin",
|
||||
groups = [ "icingaadmins" ],
|
||||
|
||||
enable_notifications = 1,
|
||||
notification_period = "24x7",
|
||||
|
||||
notification_state_filter = (StateFilterWarning |
|
||||
StateFilterCritical |
|
||||
StateFilterUnknown),
|
||||
notification_type_filter = (NotificationFilterProblem |
|
||||
NotificationFilterRecovery),
|
||||
macros = {
|
||||
"name" = "Icinga 2 Admin",
|
||||
"email" = "icinga@localhost",
|
||||
"pager" = "icingaadmin@localhost.localdomain"
|
||||
},
|
||||
|
||||
custom = {
|
||||
notes = "This is the Icinga 2 Admin account.",
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
Attributes:
|
||||
|
||||
|
|
@ -191,6 +213,7 @@ Attributes:
|
|||
----------------|----------------
|
||||
display_name |**Optional.** A short description of the user.
|
||||
macros |**Optional.** A dictionary containing macros that are specific to this user.
|
||||
custom |**Optional.** A dictionary containing custom attributes that are specific to this user.
|
||||
groups |TODO
|
||||
enable_notifications|TODO
|
||||
notification_period|TODO
|
||||
|
|
@ -203,8 +226,8 @@ A user group.
|
|||
|
||||
Example:
|
||||
|
||||
object UserGroup "noc-staff" {
|
||||
display_name = "NOC Staff"
|
||||
object UserGroup "icingaadmins" {
|
||||
display_name = "Icinga 2 Admin Group"
|
||||
}
|
||||
|
||||
Attributes:
|
||||
|
|
|
|||
Loading…
Reference in New Issue