diff options
Diffstat (limited to 'modules/monitoring/doc')
| -rw-r--r-- | modules/monitoring/doc/01-About.md | 10 | ||||
| -rw-r--r-- | modules/monitoring/doc/02-Installation.md | 15 | ||||
| -rw-r--r-- | modules/monitoring/doc/03-Configuration.md | 69 | ||||
| -rw-r--r-- | modules/monitoring/doc/04-Backends.md | 30 | ||||
| -rw-r--r-- | modules/monitoring/doc/05-Command-Transports.md | 185 | ||||
| -rw-r--r-- | modules/monitoring/doc/06-Security.md | 66 | ||||
| -rw-r--r-- | modules/monitoring/doc/10-Restrict-Custom-Variables.md | 77 | ||||
| -rw-r--r-- | modules/monitoring/doc/11-Add-Columns-List-Views.md | 32 | ||||
| -rw-r--r-- | modules/monitoring/doc/20-Hooks.md | 161 | ||||
| -rw-r--r-- | modules/monitoring/doc/img/hooks-detailviewextension-01.png | bin | 0 -> 10714 bytes | |||
| -rw-r--r-- | modules/monitoring/doc/img/list_hosts_add_columns.png | bin | 0 -> 187915 bytes | |||
| -rw-r--r-- | modules/monitoring/doc/img/list_services_add_columns.png | bin | 0 -> 209925 bytes |
12 files changed, 645 insertions, 0 deletions
diff --git a/modules/monitoring/doc/01-About.md b/modules/monitoring/doc/01-About.md new file mode 100644 index 0000000..deb47bf --- /dev/null +++ b/modules/monitoring/doc/01-About.md @@ -0,0 +1,10 @@ +# About the Monitoring Module <a id="monitoring-module-about"></a> + +Please read the following chapters for more insights on this module: + +* [Installation](02-Installation.md#monitoring-module-installation) +* [Configuration](03-Configuration.md#monitoring-module-configuration) +* [Security](06-Security.md#monitoring-module-security) +* [Restrict Custom Variables](10-Restrict-Custom-Variables.md#monitoring-module-restrict-access-custom-variables) +* [Hooks](20-Hooks.md#monitoring-module-hooks) +* [Add Columns to List Views](11-Add-Columns-List-Views.md#monitoring-module-add-columns-list-views) diff --git a/modules/monitoring/doc/02-Installation.md b/modules/monitoring/doc/02-Installation.md new file mode 100644 index 0000000..43a7cd0 --- /dev/null +++ b/modules/monitoring/doc/02-Installation.md @@ -0,0 +1,15 @@ +# Monitoring Module Installation <a id="monitoring-module-installation"></a> + +This module is provided with the Icinga Web 2 package and does +not need any extra installation step. + +## Enable the Module <a id="monitoring-module-enable"></a> + +Navigate to `Configuration` -> `Modules` -> `monitoring` and enable +the module. + +You can also enable the module during the setup wizard, or on the CLI: + +``` +icingacli module enable monitoring +``` diff --git a/modules/monitoring/doc/03-Configuration.md b/modules/monitoring/doc/03-Configuration.md new file mode 100644 index 0000000..9adacc1 --- /dev/null +++ b/modules/monitoring/doc/03-Configuration.md @@ -0,0 +1,69 @@ +# Monitoring Module Configuration <a id="monitoring-module-configuration"></a> + +## Overview <a id="monitoring-module-configuration-overview"></a> + +The module specific configuration is stored in `/etc/icingaweb2/modules/monitoring`. + +File/Directory | Description +----------------------------------------------------------------------|--------------------------------- +config.ini | Security settings (e.g. protected custom vars) for the `monitoring` module | +[backends.ini](04-Backends.md#monitoring-module-backends) | Data backend (e.g. the IDO database [resource](../../../doc/04-Resources.md#resources-configuration-database) name). +[commandtransports.ini](05-Command-Transports.md) | Command transports for specific Icinga instances + + +## General Configuration <a id="monitoring-module-configuration-general"></a> + +Navigate into `Configuration` -> `Modules` -> `Monitoring`. This allows +you to see the provided [permissions and restrictions](06-Security.md#monitoring-security) +by this module. + +### Default Settings <a id="monitoring-module-configuration-settings"></a> + +Option | Description +----------------------------------|----------------------------------------------- +acknowledge_expire | **Optional.** Check "Use Expire Time" in Acknowledgement dialog by default. Defaults to **0 (false)**. +acknowledge_expire_time | **Optional.** Set default value for "Expire Time" in Acknowledgement dialog, its calculated as now + this setting. Format is a [PHP Dateinterval](http://www.php.net/manual/en/dateinterval.construct.php). Defaults to **1 hour (PT1H)**. +acknowledge_notify | **Optional.** Check "Send Notification" in Acknowledgement dialog by default. Defaults to **1 (true)**. +acknowledge_persistent | **Optional.** Check "Persistent Comment" in Acknowledgement dialog by default. Defaults to **0 (false)**. +acknowledge_sticky | **Optional.** Check "Sticky Acknowledgement" in Acknowledgement dialog by default. Defaults to **0 (false)**. +comment_expire | **Optional.** Check "Use Expire Time" in Comment dialog by default. Defaults to **0 (false)**. +hostdowntime_comment_text | **Optional.** Set default text for "Comment" in Host Downtime dialog by default. +servicedowntime_comment_text | **Optional.** Set default text for "Comment" in Service Downtime dialog by default. +comment_expire_time | **Optional.** Set default value for "Expire Time" in Comment dialog, its calculated as now + this setting. Format is a [PHP Dateinterval](http://www.php.net/manual/en/dateinterval.construct.php). Defaults to **1 hour (PT1H)**. +custom_notification_forced | **Optional.** Check "Forced" in Custom Notification dialog by default. Defaults to **0 (false)**. +hostcheck_all_services | **Optional.** Check "All Services" in Schedule Host Check dialog by default. Defaults to **0 (false)**. +hostdowntime_all_services | **Optional.** Check "All Services" in Schedule Host Downtime dialog by default. Defaults to **0 (false)**. +hostdowntime_end_fixed | **Optional.** Set default value for "End Time" in Schedule Host Downtime dialog for **Fixed** downtime, its calculated as now + this setting. Format is a [PHP Dateinterval](http://www.php.net/manual/en/dateinterval.construct.php). Defaults to **1 hour (PT1H)**. +hostdowntime_end_flexible | **Optional.** Set default value for "End Time" in Schedule Host Downtime dialog for **Flexible** downtime, its calculated as now + this setting. Format is a [PHP Dateinterval](http://www.php.net/manual/en/dateinterval.construct.php). Defaults to **1 hour (PT1H)**. +hostdowntime_flexible_duration | **Optional.** Set default value for "Flexible Duration" in Schedule Host Downtime dialog for **Flexible** downtime. Format is a [PHP Dateinterval](http://www.php.net/manual/en/dateinterval.construct.php). Defaults to **2 hour (PT2H)**. +servicedowntime_end_fixed | **Optional.** Set default value for "End Time" in Schedule Service Downtime dialog for **Fixed** downtime, its calculated as now + this setting. Format is a [PHP Dateinterval](http://www.php.net/manual/en/dateinterval.construct.php). Defaults to **1 hour (PT1H)**. +servicedowntime_end_flexible | **Optional.** Set default value for "End Time" in Schedule Service Downtime dialog for **Flexible** downtime, its calculated as now + this setting. Format is a [PHP Dateinterval](http://www.php.net/manual/en/dateinterval.construct.php). Defaults to **1 hour (PT1H)**. +servicedowntime_flexible_duration | **Optional.** Set default value for "Flexible Duration" in Schedule Service Downtime dialog for **Flexible** downtime. Format is a [PHP Dateinterval](http://www.php.net/manual/en/dateinterval.construct.php). Defaults to **2 hour (PT2H)**. + +Example for having acknowledgements with 2 hours expire time by default. + +``` +# vim /etc/icingaweb2/modules/monitoring/config.ini + +[settings] +acknowledge_expire = 1 +acknowledge_expire_time = PT2H + +``` + +### Security Configuration <a id="monitoring-module-configuration-security"></a> + +Option | Description +-------------------------|----------------------------------------------- +protected\_customvars | **Optional.** Comma separated list of string patterns for custom variables which should be excluded from user's view. + + +Example for custom variable names which match `*pw*` or `*pass*` or `community`. + +``` +# vim /etc/icingaweb2/modules/monitoring/config.ini + +[security] +protected_customvars = "*pw*,*pass*,community" +``` + diff --git a/modules/monitoring/doc/04-Backends.md b/modules/monitoring/doc/04-Backends.md new file mode 100644 index 0000000..2681109 --- /dev/null +++ b/modules/monitoring/doc/04-Backends.md @@ -0,0 +1,30 @@ +# Backends <a id="monitoring-module-backends"></a> + +The configuration file `backends.ini` contains information about data sources which are +used to fetch monitoring objects presented to the user. + +The required [resources](../../../doc/04-Resources.md#resources-configuration-database) must be globally defined beforehand. + +## Configuration <a id="monitoring-module-backends-configuration"></a> + +Navigate into `Configuration` -> `Modules` -> `Monitoring` -> `Backends`. +You can select a specified global resource here, and also update its details. + +Each section in `backends.ini` references a resource. By default you should only have one backend enabled. + +### IDO Backend <a id="monitoring-module-backends-ido"></a> + +Option | Description +-------------------------|----------------------------------------------- +type | **Required.** Specify the backend type. Must be set to `ido`. +resource | **Required.** Specify a defined [resource](../../../doc/04-Resources.md#resources-configuration-database) name which provides details about the IDO database resource. + + +Example for using the database resource `icinga2_ido_mysql`: + +``` +[icinga2_ido_mysql] +type = "ido" +resource = "icinga2_ido_mysql" +``` + diff --git a/modules/monitoring/doc/05-Command-Transports.md b/modules/monitoring/doc/05-Command-Transports.md new file mode 100644 index 0000000..bdf9f56 --- /dev/null +++ b/modules/monitoring/doc/05-Command-Transports.md @@ -0,0 +1,185 @@ +# External Command Transport Configuration <a id="monitoring-module-commandtransports"></a> + +## Configuration <a id="monitoring-module-commandtransports-configuration"></a> + +Navigate into `Configuration` -> `Modules` -> `Monitoring` -> `Backends`. +You can create/edit command transports here. + +The `commandtransports.ini` configuration file defines how Icinga Web 2 +transports commands to your Icinga instance in order to submit +external commands. By default, this file is located at `/etc/icingaweb2/modules/monitoring/commandtransports.ini`. + +You can define multiple command transports in the `commandtransports.ini` file. Every transport starts with a section header +containing its name, followed by the config directives for this transport in the standard INI-format. + +Icinga Web 2 will try one transport after another to send a command until the command is successfully sent. +If [configured](05-Command-Transports.md#commandtransports-multiple-instances), Icinga Web 2 will take different instances into account. +The order in which Icinga Web 2 processes the configured transports is defined by the order of sections in +`commandtransports.ini`. + +## Use the Icinga 2 API <a id="commandtransports-icinga2-api"></a> + +If you're running Icinga 2 it's best to use the [Icinga 2 API](https://icinga.com/docs/icinga2/latest/doc/12-icinga2-api/) +for transmitting external commands. + +### Icinga 2 Preparations <a id="commandtransports-icinga2-api-preparations"></a> + +You have to run the `api` setup on the Icinga 2 host where you want to send the commands to: + +``` +icinga2 api setup +``` + +Next, you have to create an ApiUser object for authenticating against the Icinga 2 API. This configuration also applies +to the host where you want to send the commands to. We recommend to create/edit the file +`/etc/icinga2/conf.d/api-users.conf`: + +``` +object ApiUser "icingaweb2" { + password = "bea11beb7b810ea9ce6ea" // Change this! + permissions = [ "status/query", "actions/*", "objects/modify/*", "objects/query/*" ] +} +``` + +The permissions are mandatory in order to submit all external commands from within Icinga Web 2. + +**Restart Icinga 2** for the changes to take effect. + +``` +systemctl restart icinga2 +``` + +### Configuration in Icinga Web 2 <a id="commandtransports-icinga2-api-configuration"></a> + +> **Note** +> +> Please make sure that your server running Icinga Web 2 has the `PHP cURL` extension installed and enabled. + +The Icinga 2 API requires the following settings: + +Option | Description +-------------------------|----------------------------------------------- +transport | **Required.** The transport type. Must be set to `api`. +host | **Required.** The host address where the Icinga 2 API is listening on. +port | **Required.** The port where the Icinga 2 API is listening on. Defaults to `5665`. +username | **Required.** Basic auth username. +password | **Required.** Basic auth password. + +Example: + +``` +# vim /etc/icingaweb2/modules/monitoring/commandtransports.ini + +[icinga2] +transport = "api" +host = "127.0.0.1" ; Icinga 2 host +port = "5665" +username = "icingaweb2" +password = "bea11beb7b810ea9ce6ea" ; Change this! +``` + +## Use a Local Command Pipe <a id="commandtransports-local-command-pipe"></a> + +A local Icinga instance requires the following settings: + +Option | Description +-------------------------|----------------------------------------------- +transport | **Required.** The transport type. Must be set to `local`. +path | **Required.** The absolute path to the local command pipe. + +Example: + +``` +# vim /etc/icingaweb2/modules/monitoring/commandtransports.ini + +[icinga2] +transport = local +path = /var/run/icinga2/cmd/icinga2.cmd +``` + +When commands are being sent to the Icinga instance, Icinga Web 2 opens the file found +on the local filesystem underneath `path` and writes the external command to it. + +Please note that errors are not returned using this method. The Icinga 2 API sends +error feedback. + +## Use SSH For a Remote Command Pipe <a id="commandtransports-ssh-remote-command-pipe"></a> + +A command pipe on a remote host's filesystem can be accessed by configuring a +SSH based command transport and requires the following settings: + +Option | Description +-------------------------|----------------------------------------------- +transport | **Required.** The transport type. Must be set to `remote`. +path | **Required.** The path on the remote server to its local command pipe. +host | **Required.** The SSH host. +port | **Optional.** The SSH port. Defaults to `22`. +user | **Required.** The SSH auth user. +resource | **Optional.** The SSH [resource](../../../doc/04-Resources.md#resources-configuration-ssh) +instance | **Optional.** The Icinga instance name. Only required for multiple instances. + +Example: + +``` +# vim /etc/icingaweb2/modules/monitoring/commandtransports.ini + +[icinga2] +transport = remote +path = /var/run/icinga2/cmd/icinga2.cmd +host = example.tld +user = icinga +;port = 22 ; Optional. The default is 22 +``` + +To make this example work, you'll need to permit your web-server's user +public-key based access to the defined remote host so that Icinga Web 2 can +connect to it and login as the defined user. + +You can also make use of a dedicated SSH resource to permit access for a +different user than the web-server's one. This way, you can provide a private +key file on the local filesystem that is used to access the remote host. + +To accomplish this, a new resource is required that is defined in your +transport's configuration instead of a user: + +``` +# vim /etc/icingaweb2/modules/monitoring/commandtransports.ini + +[icinga2] +transport = remote +path = /var/run/icinga2/cmd/icinga2.cmd +host = example.tld +resource = example.tld-icinga2 +;port = 22 ; Optional. The default is 22 +``` + +The resource's configuration needs to be put into the resources.ini file: + +``` +# vim /etc/icingaweb2/resources.ini + +[example.tld-icinga2] +type = ssh +user = icinga +private_key = /etc/icingaweb2/ssh/icinga +``` + +## Configure Transports for Different Icinga Instances <a id="commandtransports-multiple-instances"></a> + +If there are multiple but different Icinga instances writing to your IDO database, +you can define which transport belongs to which Icinga instance by providing the +`instance` setting. This setting must specify the name of the Icinga +instance you want to assign to the transport: + +``` +[icinga1] +... +instance = icinga1 + +[icinga2] +... +instance = icinga2 +``` + +Associating a transport to a specific Icinga instance causes this transport to be used to send commands to the linked +instance only. Transports without a linked Icinga instance are used to send commands to all instances. diff --git a/modules/monitoring/doc/06-Security.md b/modules/monitoring/doc/06-Security.md new file mode 100644 index 0000000..750eaef --- /dev/null +++ b/modules/monitoring/doc/06-Security.md @@ -0,0 +1,66 @@ +# Security <a id="monitoring-module-security"></a> + +The monitoring module provides an additional set of restrictions and permissions +that can be used for access control. The following sections will list those +restrictions and permissions in detail: + + +## Permissions <a id="monitoring-module-security-permissions"></a> + +The monitoring module allows to send commands to an Icinga 2 instance. +A user needs specific permissions to be able to send those commands +when using the monitoring module. + + +Name | Permits +-------------------------------------------------|----------------------------------------------- +monitoring/command/* | Allow all commands. +monitoring/command/schedule-check | Allow scheduling host and service checks. +monitoring/command/schedule-check/active-only | Allow scheduling host and service checks. (Only on objects with active checks enabled) +monitoring/command/acknowledge-problem | Allow acknowledging host and service problems. +monitoring/command/remove-acknowledgement | Allow removing problem acknowledgements. +monitoring/command/comment/* | Allow adding and deleting host and service comments. +monitoring/command/comment/add | Allow commenting on hosts and services. +monitoring/command/comment/delete | Allow deleting host and service comments. +monitoring/command/downtime/* | Allow scheduling and deleting host and service downtimes. +monitoring/command/downtime/schedule | Allow scheduling host and service downtimes. +monitoring/command/downtime/delete | Allow deleting host and service downtimes. +monitoring/command/process-check-result | Allow processing host and service check results. +monitoring/command/feature/instance | Allow processing commands for toggling features on an instance-wide basis. +monitoring/command/feature/object/* | Allow processing commands for toggling features on host and service objects. +monitoring/command/feature/object/active-checks | Allow processing commands for toggling active checks on host and service objects. +monitoring/command/feature/object/passive-checks | Allow processing commands for toggling passive checks on host and service objects. +monitoring/command/feature/object/notifications | Allow processing commands for toggling notifications on host and service objects. +monitoring/command/feature/object/event-handler | Allow processing commands for toggling event handlers on host and service objects. +monitoring/command/feature/object/flap-detection | Allow processing commands for toggling flap detection on host and service objects. +monitoring/command/send-custom-notification | Allow sending custom notifications for hosts and services. + + +## Restrictions <a id="monitoring-module-security-restrictions"></a> + +The monitoring module allows filtering objects: + + +Keys | Restricts +--------------------------------------------|----------------------------------------------- +monitoring/filter/objects | Applies a filter to all hosts and services. + + +This filter will affect all hosts and services. Furthermore, it will also +affect all related objects, like notifications, downtimes and events. If a +service is hidden, all notifications, downtimes on that service will be hidden too. + + +### Filter Column Names <a id="monitoring-module-security-restrictions-filter-column-names"></a> + +The following filter column names are available in filter expressions: + + +Column | Description +-----------------------------------------------------------|----------------------------------------------- +instance\_name | Filter on an Icinga 2 instance. +host\_name | Filter on host object names. +hostgroup\_name | Filter on hostgroup object names. +service\_description | Filter on service object names. +servicegroup\_name | Filter on servicegroup object names. +all custom variables prefixed with `_host_` or `_service_` | Filter on specified custom variables. diff --git a/modules/monitoring/doc/10-Restrict-Custom-Variables.md b/modules/monitoring/doc/10-Restrict-Custom-Variables.md new file mode 100644 index 0000000..8d3a3b1 --- /dev/null +++ b/modules/monitoring/doc/10-Restrict-Custom-Variables.md @@ -0,0 +1,77 @@ +# Restrict Access to Custom Variables <a id="monitoring-module-restrict-access-custom-variables"></a> + +* Restriction name: monitoring/blacklist/properties +* Restriction value: Comma separated list of GLOB like filters + +Imagine the following host custom variable structure. + +``` +host.vars. +|-- cmdb_name +|-- cmdb_id +|-- cmdb_location +|-- wiki_id +|-- passwords. +| |-- mysql_password +| |-- ldap_password +| `-- mongodb_password +|-- legacy. +| |-- cmdb_name +| |-- mysql_password +| `-- wiki_id +`-- backup. + `-- passwords. + |-- mysql_password + `-- ldap_password +``` + +`host.vars.cmdb_name` + +Blacklists `cmdb_name` in the first level of the custom variable structure only. +`host.vars.legacy.cmdb_name` is not blacklisted. + + +`host.vars.cmdb_*` + +All custom variables in the first level of the structure which begin with `cmdb_` become blacklisted. +Deeper custom variables are ignored. `host.vars.legacy.cmdb_name` is not blacklisted. + +`host.vars.*id` + +All custom variables in the first level of the structure which end with `id` become blacklisted. +Deeper custom variables are ignored. `host.vars.legacy.wiki_id` is not blacklisted. + +`host.vars.*.mysql_password` + +Matches all custom variables on the second level which are equal to `mysql_password`. + +`host.vars.*.*password` + +Matches all custom variables on the second level which end with `password`. + +`host.vars.*.mysql_password,host.vars.*.ldap_password` + +Matches all custorm variables on the second level which equal `mysql_password` or `ldap_password`. + +`host.vars.**.*password` + +Matches all custom variables on all levels which end with `password`. + +Please note the two asterisks, `**`, here for crossing level boundaries. This syntax is used for matching the complete +custom variable structure. + +If you want to restrict all custom variables that end with password for both hosts and services, you have to define +the following restriction. + +`host.vars.**.*password,service.vars.**.*password` + +## Escape Meta Characters <a id="restrict-access-custom-variables-escape-meta-chars"></a> + +Use backslash to escape the meta characters + +* * +* , + +`host.vars.\*fall` + +Matches all custom variables in the first level which equal `*fall`. diff --git a/modules/monitoring/doc/11-Add-Columns-List-Views.md b/modules/monitoring/doc/11-Add-Columns-List-Views.md new file mode 100644 index 0000000..2567ead --- /dev/null +++ b/modules/monitoring/doc/11-Add-Columns-List-Views.md @@ -0,0 +1,32 @@ +# Add Columns to List Views <a id="monitoring-module-add-columns-list-views"></a> + +The monitoring module provides list views for hosts and services. +These lists only provide the most common columns to reduce the backend +query load. + +If you want to add more columns to the list view e.g. in order to use the URL in +your dashboards or as external iframe integration, you need the `addColumns` URL +parameter. + + + +Example for adding the host `address` attribute in a host list: + +``` +http://localhost/icingaweb2/monitoring/list/hosts?addColumns=host_address +``` + + + + + + +Example for multiple columns as comma separated parameter string. This +includes a reference to the Icinga 2 host object custom attribute `os` using +`_host_` as custom variable identifier. + +``` +http://localhost/icingaweb2/monitoring/list/services?addColumns=host_address,_host_os +``` + + diff --git a/modules/monitoring/doc/20-Hooks.md b/modules/monitoring/doc/20-Hooks.md new file mode 100644 index 0000000..5d38843 --- /dev/null +++ b/modules/monitoring/doc/20-Hooks.md @@ -0,0 +1,161 @@ +# Monitoring Module Hooks <a id="monitoring-module-hooks"></a> + +## Detail View Extension Hook <a id="monitoring-module-hooks-detailviewextension"></a> + +This hook can be used to easily extend the detail view of monitored objects (hosts and services). + +### How it works <a id="monitoring-module-hooks-detailviewextension-how-it-works"></a> + +#### Directory structure <a id="monitoring-module-hooks-detailviewextension-directory-structure"></a> + +* `icingaweb2/modules/example` + * `library/Example/ProvidedHook/Monitoring/DetailviewExtension/Simple.php` + * `run.php` + +#### Files <a id="monitoring-module-hooks-detailviewextension-files"></a> + +##### run.php <a id="monitoring-module-hooks-detailviewextension-files-run-php"></a> + +```php +<?php +/** @var \Icinga\Application\Modules\Module $this */ + +$this->provideHook( + 'monitoring/DetailviewExtension', + 'Icinga\Module\Example\ProvidedHook\Monitoring\DetailviewExtension\Simple' +); +``` + +##### Simple.php <a id="monitoring-module-hooks-detailviewextension-files-simple-php"></a> + +```php +<?php +namespace Icinga\Module\Example\ProvidedHook\Monitoring\DetailviewExtension; + +use Icinga\Module\Monitoring\Hook\DetailviewExtensionHook; +use Icinga\Module\Monitoring\Object\MonitoredObject; + +class Simple extends DetailviewExtensionHook +{ + public function getHtmlForObject(MonitoredObject $object) + { + $stats = array(); + foreach (str_split($object->name) as $c) { + if (isset($stats[$c])) { + ++$stats[$c]; + } else { + $stats[$c] = 1; + } + } + + ksort($stats); + + $view = $this->getView(); + + $thead = ''; + $tbody = ''; + foreach ($stats as $c => $amount) { + $thead .= '<th>' . $view->escape($c) . '</th>'; + $tbody .= '<td>' . $amount . '</td>'; + } + + return '<h2>' + . $view->escape(sprintf($view->translate('A %s named "%s"'), $object->getType(), $object->name)) + . '</h2>' + . '<h3>Character stats</h3>' + . '<table>' + . '<thead>' . $thead . '</thead>' + . '<tbody>' . $tbody . '</tbody>' + . '</table>'; + } +} +``` + +### How it looks <a id="monitoring-module-hooks-detailviewextension-how-it-looks"></a> + + + +## Plugin Output Hook <a id="monitoring-module-hooks-pluginoutput"></a> + +The Plugin Output Hook allows you to rewrite the plugin output based on check commands. You have to implement the +following methods: + +* `getCommands()` +* and `render()` + +With `getCommands()` you specify for which commands the provided hook is responsible for. You may return a single +command as string or a list of commands as array. If you want your hook to be responsible for every command, you have to +specify the `*`. + +In `render()` you rewrite the plugin output based on check commands. The parameter `$command` specifies the check +command of the host or service and `$output` specifies the plugin output. The parameter `$detail` tells you +whether the output is requested from the detail area of the host or service. + +Do not use complex logic for rewriting plugin output in list views because of the performance impact! + +You have to return the rewritten plugin output as string. It is also possible to return a HTML string here. +Please refer to `\Icinga\Module\Monitoring\Web\Helper\PluginOutputPurifier` for a list of allowed tags. + +Please also have a look at the following examples. + +**Example hook which is responsible for disk checks:** + +```php +<?php + +namespace Icinga\Module\Example\ProvidedHook\Monitoring; + +use Icinga\Module\Monitoring\Hook\PluginOutputHook; + +class PluginOutput extends PluginOutputHook +{ + public function getCommands() + { + return ['disk']; + } + + public function render($command, $output, $detail) + { + if (! $detail) { + // Don't rewrite plugin output in list views + return $output; + } + return implode('<br>', explode(';', $output)); + } +} +``` + +**Example hook which is responsible for disk and procs checks:** + +```php +<?php + +namespace Icinga\Module\Example\ProvidedHook\Monitoring; + +use Icinga\Module\Monitoring\Hook\PluginOutputHook; + +class PluginOutput extends PluginOutputHook +{ + public function getCommands() + { + return ['disk', 'procs']; + } + + public function render($command, $output, $detail) + { + switch ($command) { + case 'disk': + if ($detail) { + // Only rewrite plugin output in the detail area + $output = implode('<br>', explode(';', $output)); + } + break; + case 'procs': + $output = preg_replace('/(\d)+/', '<b>$1</b>', $output); + break; + } + + return $output; + } +} +``` diff --git a/modules/monitoring/doc/img/hooks-detailviewextension-01.png b/modules/monitoring/doc/img/hooks-detailviewextension-01.png Binary files differnew file mode 100644 index 0000000..a5ddaf1 --- /dev/null +++ b/modules/monitoring/doc/img/hooks-detailviewextension-01.png diff --git a/modules/monitoring/doc/img/list_hosts_add_columns.png b/modules/monitoring/doc/img/list_hosts_add_columns.png Binary files differnew file mode 100644 index 0000000..874a8f1 --- /dev/null +++ b/modules/monitoring/doc/img/list_hosts_add_columns.png diff --git a/modules/monitoring/doc/img/list_services_add_columns.png b/modules/monitoring/doc/img/list_services_add_columns.png Binary files differnew file mode 100644 index 0000000..dd0db82 --- /dev/null +++ b/modules/monitoring/doc/img/list_services_add_columns.png |
