## 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
## 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).
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:
----------------|----------------
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
Example:
- object UserGroup "noc-staff" {
- display_name = "NOC Staff"
+ object UserGroup "icingaadmins" {
+ display_name = "Icinga 2 Admin Group"
}
Attributes:
projects / icinga2 / commitdiff