Merge branch '7.x-nb' into '7.x'

Signals docs updates

See merge request search-guard/search-guard-docs!80

_content/_docs_signals/accounts.md

@@ -79,6 +79,36 @@ A Slack account looks rather simple:
 
 The value for the `url` property must be obtained by creating a Slack App inside Slack. See the [Slack docs](https://api.slack.com/incoming-webhooks) for details.
 
+### PagerDuty Accounts
+
+PagerDuty accounts represent integration keys for PagerDuty services.
+
+A PagerDuty account in Signals looks like this:
+
+```json
+{
+	"integration_key": "XXXXXXXXXXXXXXXXXXXXXXXX"
+}
+```
+
+The value for `integration_key` needs to be obtained from PagerDuty. 	See the [PagerDuty documentation](https://support.pagerduty.com/docs/services-and-integrations#section-create-a-generic-events-api-integration) for details. You have to create an integration for the Events API v2.
+
+### Jira Accounts
+
+Jira accounts represent auth tokens for Jira instances. Jira auth tokens are always accompanied by the login email address of the respective user.
+
+A Jira account in Signals looks like this:
+
+```json
+{
+    "url": "https://examplejira.atlassian.net/",
+	"user_name": "example.user@example.com",
+	"auth_token": "...."
+}
+```
+
+The attribute `url` references the base URL of your Jira instance. The attribute `user_name` is the login email address of a user. `auth_token` is an API token obtained from Jira for the user. See the [Jira docs](https://confluence.atlassian.com/cloud/api-tokens-938839638.html) for details on obtaining auth tokens.
+
 ## REST API
 
 Accounts may be managed using these REST API endpoints:

_content/_docs_signals/actions.md

@@ -38,15 +38,21 @@ Still, it is possible to configure further action-specific checks. This way, it
 
 ## Action Types
 
-These actions are available at the moment:
+These action types are available at the moment:
 
-**[E-Mail Action](actions_email.md):** Sends e-mails to configurable recipients. Mail content can be defined using templating.
+**[E-Mail Action Type](actions_email.md):** Sends e-mails to configurable recipients. Mail content can be defined using templating.
 
-**[Slack Action](actions_slack.md):** Sends Slack messages to configurable recipients. Message content is templateable as well.
+**[Slack Action Type](actions_slack.md):** Sends Slack messages to configurable recipients. Message content is templateable as well.
 
-**[Webhook Actions](actions_webhook.md):** Sends HTTP requests to external services.
+**[Webhook Action Type](actions_webhook.md):** Sends HTTP requests to external services.
 
-**[Index Action](actions_index.md):** Writes data to an Elasticsearch index.
+**[Index Action Type](actions_index.md):** Writes data to an Elasticsearch index.
+
+These action types are only available in the Enterprise Edition:
+
+**[Pager Duty Action Type](actions_pagerduty.md):** Triggers and resolves incidents in PagerDuty.
+
+**[Jira Action Type](actions_jira.md):** Creates issues in Jira.
 
 ## Action Throttling
 

_content/_docs_signals/actions_jira.md

@@ -11,10 +11,67 @@ description:
 
 <!--- Copyright 2019 floragunn GmbH -->
 
-# JIRA Actions
+# Jira Actions
 {: .no_toc}
 
 {% include toc.md %}
 
 
-## Coming Soon
\ No newline at end of file
+The Jira action type allows creating issues and sub-tasks in the Jira bug tracking software. 
+
+The Jira action type is an enterprise feature; you need to have an enterprise license to use Jira actions.
+
+## Prerequisites
+
+In order to use Jira actions, you need to obtain an API token from Jira and store it as Jira account in Signals. To get an API token from Jira, click on the user icon in the bottom left of the Jira web application. In the appearing pop-up, choose *Account Settings*; afterwards go to *Security* and *Create and manage API tokens*.
+
+The resulting token needs to be registered together with your Jira login email address in the Signals account registry. 
+See the [accounts registry documentation](accounts.md) for more details.
+
+Note that Jira API tokens are always tied to the user who created the token. Thus, issues created using such a token normally show the owner of the token as *Reporter*.
+
+## Basic Functionality
+
+The attributes you can use to configure Jira actions quite resemble to the fields available in the Jira UI for creating issues. 
+
+A basic Jira action might look like this:
+
+
+<!-- {% raw %} -->
+```json
+ {
+	"actions": [
+		{
+			"type": "jira",
+			"name": "my_jira_action",
+			"throttle_period": "1w",
+			"project": "JP",
+			"issue": {
+				"type": "Bug",
+				"summary": "Cheese stock < {{data.cheese_stock}}",
+				"description:" "Please take action",
+			}
+		}
+	]
+}
+```
+<!-- {% endraw %} -->
+
+These attributes are available:
+
+**project:** The *key* of the Jira project in which the issue shall be created. This is usually an abbreviation of the project name and it shows up as prefix of the issue numbers. Mandatory.
+
+**issue.type:** The type of the Jira issue to be created. Note that the available values depend on the configuration of your Jira instance. Typical types include *Bug* and *Task*. Mandatory. You can use Mustache templates for specifying dynamic values. If you specify an issue type which is not configured in your Jira instance, creating the issue will fail.
+
+**issue.summary:** The issue summary which Jira shows in issue lists and as title of the issue. Mandatory. You can use Mustache templates for specifying dynamic values.
+
+**issue.description:** The main text content of the issue. Mandatory. You can use Mustache templates for specifying dynamic values.
+
+**issue.priority:** The priority that shall be assigned to the issue. Note that the available values depend on the configuration of your Jira instance. Typical priorities include *High*, *Medium* and *Low*. Optional. You can use Mustache templates for specifying dynamic values. If you specify a priority which is not configured in your Jira instance, creating the issue will fail.
+
+**issue.component:** A component to be assigned to the issue. Note that the available values depend on the configuration of your Jira instance. Optional. You can use Mustache templates for specifying dynamic values. If you specify a component which is not configured in your Jira instance, creating the issue will fail.
+
+**issue.label:** A label that shall be assigned to the issue. Labels can be created on the fly be specifying them.  Optional. You can use Mustache templates for specifying dynamic values.
+
+**issue.parent:** If you want to create a subtask, you can specify the ID of the parent issue here. Optional. You can use Mustache templates for specifying dynamic values.
+

_content/_docs_signals/actions_pagerduty.md

@@ -11,10 +11,81 @@ description:
 
 <!--- Copyright 2019 floragunn GmbH -->
 
-# Pagerduty Actions
+# PagerDuty Actions
 {: .no_toc}
 
 {% include toc.md %}
 
 
-## Coming Soon
\ No newline at end of file
+The PagerDuty action type allows you to integrate Signals with PagerDuty; it allows to automatically open PagerDuty incidents from Signals watches. Furthermore, PagerDuty actions can also automatically resolve incidents in PagerDuty as soon as the watch has left alert state. PagerDuty actions do this incident resolution automatically by default; this is in contrast to other actions which require an explicit resolve action to be configured. 
+
+If a watch defines severity levels, these are also directly mapped to the severity defined in the event sent to PagerDuty.
+
+The PagerDuty action type is an enterprise feature; you need to have an enterprise license to use PagerDuty actions.
+
+## Prerequisites
+
+In order to use PagerDuty actions, you need to get a Service integration key from PagerDuty. If you already have configured a service in PagerDuty, open that service in the PagerDuty configuration and click on the *Integrations* tab. Click on the *New Integration* button. In the next screen select *Use our API directly* as *Integration Type* and select the *Events API v2* in the dropdown below.
+
+If you don't have any service in PagerDuty yet, go in PagerDuty to *Configuration* > *Services* and click on the *New Service* button. In the next screen, you will also have the configuration elements for the *Integration Settings*. Select 	*Use our API directly* as *Integration Type* and select the *Events API v2* in the dropdown below.
+
+After creating the integration, PagerDuty will show an Integration Key. You will then need to configure a PagerDuty account in Signals using this integration key. See the [accounts registry documentation](accounts.md) for more on that.
+
+## Basic Functionality
+
+PagerDuty actions require very little configuration in Signals. After having created a PagerDuty account with the id `default` in Signals, you can use this action configuration to create incidents in PagerDuty and resolve them.
+
+<!-- {% raw %} -->
+```json
+ {
+	"actions": [
+		{
+			"type": "pagerduty",
+			"name": "my_pagerduty_action",
+			"event": {
+				"dedup_key": "cheese_stock_shortage",
+				"payload": {
+					"summary": "Cheese stock < {{data.cheese_stock}}",
+					"source": "Cheese shop"
+				}
+			}
+		}
+	]
+}
+```
+<!-- {% endraw %} -->
+
+The attribute `event.dedup_key` groups events sent to PagerDuty into incidents. If events are sent to PagerDuty while there is already an open incident with the same `dedup_key`, no new incident will be created.
+
+The attribute `event.payload.summary` is a human readable description of the situation and will become the alert description within PagerDuty. 
+
+The attribute `event.payload.source` shall identify the system having the problem.
+
+Mustache templates can be used for all three attributes.
+
+
+## Adding Information to Events
+
+A number of further configuration attributes can be used to add more information to the events sent to PagerDuty.
+
+**event.payload.component:** Can be used to define the affected component of a system. Optional. Mustache templates can be used for dynamic content.
+
+**event.payload.group:** You can define a group here which the affected system belongs to. Optional. Mustache templates can be used for dynamic content.
+
+**event.payload.class:** You can classify the event here. Optional. Mustache templates can be used for dynamic content.
+
+**event.payload.custom_details:** While the other attributes define textual information, this attribute defines structured information which will be sent as JSON to PagerDuty. You need to use a Painless expression to define the structured data. For example, the value `data`  sends the complete runtime data to PagerDuty. As runtime data might be quite big, it might be a wise choice to send a smaller data set. You can use a Painless map expression for this purpose: `['amount': 'data.aggregations.cheese_amount.total']` 
+
+
+## Advanced Functionality
+
+Furthermore, Signals provides configuration options to completely control the event data sent to PagerDuty. This is however usually not necessary, as Signals initializes these event attributes with suitable defaults.
+
+The structure of the configuration sticks closely to the structure of the PagerDuty event v2 API. Thus, see also the [PagerDuty API docs](https://v2.developer.pagerduty.com/docs/events-api-v2) for details.
+
+**auto_resolve:** By default, PagerDuty actions will automatically send resolve events to PagerDuty, even if no resolve action is configured in Signals. Set this to false to suppress resolve actions.
+
+**event.event_action:** One of `trigger`, `acknowledge` or `resolve`. By default, Signals sends `trigger`or `resolve` depending on whether the Watch is in alert state or it has left alert state.
+
+**event.payload.severity:** One of `info`, `warning`, `error`, `critical`. By default Signals sends the severity defined by the severity mapping of the respective watch.
+

_content/_docs_signals/actions_slack.md

@@ -54,5 +54,3 @@ The basic configuration attributes are:
 **account:** Identifies the Slack application which shall be used for sending the message. See the [accounts registry documentation](accounts.md).
 
 **text:** Defines the content of the message. Mustache templates can be used to render attributes from the watch runtime data. Optional. See the [Slack documentation](https://api.slack.com/messaging/composing/formatting) for details on how to format the message.
-
-*Slack blocks or attachments are not yet supported, but will be coming up soon.*

_content/_docs_signals/administration.md

@@ -61,7 +61,7 @@ These settings can be set using the Signals settings REST API:
 
 The following configuration options can be made in the elasticsearch.yml configuration file. A restart of the respective node is necessary to bring these options into effect.
 
-**signals.enabled:** Can be used to enable or disable Signals on the respective node. Optional, boolean, defaults to true.
+**signals.enabled:** Can be used to enable or disable Signals. Optional, boolean, defaults to true. Take care that the value of this setting is consistent for all nodes in a cluster. It is not supported to enable Signals only on a subset of a cluster using this setting. Use the `node_filter` settings for this purpose instead.
 
 **signals.index_names.log:** Specifies the name of the watch log index. Optional, defaults to `<.signals_log_{now/d}>`.
 

_content/_docs_signals/rest_api.md

@@ -68,3 +68,12 @@ This will give this role complete access to all Signals features and indices.
 
 * [Get Settings](rest_api_settings_get.md)
 * [Put Settings](rest_api_settings_put.md)
+
+## Administration APIs
+
+* [Activate and Deactivate Execution for Tenant](rest_api_tenant_activate.md)
+* [Activate and Deactivate Execution Globally](rest_api_admin_activate.md)
+
+## Other APIs
+
+* [Convert Watch](rest_api_convert_es.md)
\ No newline at end of file

_content/_docs_signals/rest_api_admin_activate.md

+---
+title: Activate and deactivate watch
+html_title: Activating and deactivating a watch with the REST API
+slug: elasticsearch-alerting-rest-api-watch-activate
+category: signals-rest
+order: 500
+layout: docs
+edition: beta
+description: 
+---
+
+<!--- Copyright 2019 floragunn GmbH -->
+
+# Activate/Deactivate Signals API
+{: .no_toc}
+
+{% include toc.md %}
+
+
+## Endpoint
+
+```
+PUT /_signals/admin/_active
+```
+
+```
+DELETE /_signals/admin/_active
+```
+
+These endpoints can be used to globally activate and deactivate the execution of all watches in Signals. 
+
+Using the PUT verb activates the execution, using the DELETE verb deactivates the execution.
+
+This is equivalent to changing the value of the Signals setting `active`. However, this API requires a distinct permission. Thus, it is possible to allow a user activation and deactivation of Signals while the user cannot change other settings.
+
+## Request Body
+
+No request body is required for this endpoint.
+
+## Responses
+
+### 200 OK
+
+The execution was successfully enabled or disabled.
+
+### 403 Forbidden
+
+The user does not have the permission to activate or deactivate the execution globally. 
+
+## Permissions
+
+For being able to access the endpoint, the user needs to have the privilege `cluster:admin:searchguard:signals:admin/start_stop` .
+
+This permission is included in the following [built-in action groups](security_permissions.md):
+
+* SGS\_SIGNALS\_ALL

_content/_docs_signals/rest_api_settings_get.md

@@ -38,7 +38,7 @@ Retries all Signals settings or a single setting item.
 
 ### 200 OK
 
-The setting could be successfully retrieved. The value of the settings is returned in the response body.
+The setting could be successfully retrieved. The value of the settings is returned in the response body. The response format is JSON. This means, that if a setting as a simple textual value, the value will be returned in double quotes. If you specify the header `Accept: text/plain` in the request, you will get a plain text response with unquoted textual values.
 
 ### 403 Forbidden
 
@@ -65,8 +65,31 @@ GET /_signals/settings
 **Response**
 
 ```
-TODO
+{
+  "active": "true",
+  "http": {
+    "allowed_endpoints": [
+      "https://www.example.com/*",
+      "https://intra.example.com/*"
+    ]
+  },
+  "tenant": {
+    "_main": {
+      "active": "true",
+      "node_filter": "node.attr.signals: true"
+    }
+  }
+}
 ```
 
+```
+GET /_signals/settings/watchlog.index
+```
+
+**Response**
+
+```
+"<.signals_log_{now/d}>"
+```
 
 

_content/_docs_signals/rest_api_settings_put.md

@@ -32,7 +32,7 @@ Updates a Signals configuration setting.
 
 ## Request Body
 
-The value of the setting.
+The value of the setting as JSON. This means that if a setting is a simple textual value, you need to specify the value within quotes.
 
 ## Responses
 
@@ -67,7 +67,7 @@ This permission is included in the following [built-in action groups](security_p
 PUT /_signals/tenant._main.node_filter
 ```
 ```
-signals:true
+"signals:true"
 ```
 
 **Response**
@@ -76,5 +76,19 @@ signals:true
 200 OK
 ```
 
+### Active
+
+```
+PUT /_signals/active
+```
+```
+true
+```
+
+**Response**
+
+```
+200 OK
+```
 
 

_content/_docs_signals/rest_api_tenant_activate.md

+---
+title: Activate and deactivate watch
+html_title: Activating and deactivating a watch with the REST API
+slug: elasticsearch-alerting-rest-api-watch-activate
+category: signals-rest
+order: 500
+layout: docs
+edition: beta
+description: 
+---
+
+<!--- Copyright 2019 floragunn GmbH -->
+
+# Activate/Deactivate Signals API
+{: .no_toc}
+
+{% include toc.md %}
+
+
+## Endpoint
+
+```
+PUT /_signals/tenant/{tenant}/_active
+```
+
+```
+DELETE  /_signals/tenant/{tenant}/_active
+```
+
+These endpoints can be used to activate and deactivate the execution of all watches configured for a Signals tenant.
+
+Using the PUT verb activates the execution, using the DELETE verb deactivates the execution.
+
+This is equivalent to changing the value of the Signals setting `tenant.{tenant}.active`. However, this API requires a distinct permission. Thus, it is possible to allow a user activation and deactivation of a tenant while the user cannot change other settings.
+
+## Path Parameters
+
+**{tenant}:** The name of the tenant to be activated or deactivated. `_main` refers to the default tenant. Users of the community edition will can only use `_main` here.
+
+## Request Body
+
+No request body is required for this endpoint.
+
+## Responses
+
+### 200 OK
+
+The execution was successfully enabled or disabled.
+
+### 403 Forbidden
+
+The user does not have the permission to activate or deactivate the execution of a tenant. 
+
+## Permissions
+
+For being able to access the endpoint, the user needs to have the privilege `cluster:admin:searchguard:tenant:signals:tenant/start_stop` .
+
+This permission is included in the following [built-in action groups](security_permissions.md):
+
+* SGS\_SIGNALS\_ALL

_content/_docs_signals/rest_api_watch_activate.md

@@ -20,15 +20,17 @@ description:
 ## Endpoint
 
 ```
-PUT /_signals/watch/{tenant}/{watch_id}/_activate
+PUT /_signals/watch/{tenant}/{watch_id}/_active
 ```
 
 ```
-PUT /_signals/watch/{tenant}/{watch_id}/_deactivate
+DELETE /_signals/watch/{tenant}/{watch_id}/_active
 ```
 
 These endpoints can be used to activate and deactivate watches. Inactive watches are not automatically executed.
 
+Using the PUT verb activates a watch, using the DELETE verb deactivates a watch.
+
 ## Path Parameters
 
 **{tenant}:** The name of the tenant which contains the watch to be activated or deactivated. `_main` refers to the default tenant. Users of the community edition will can only use `_main` here.
@@ -66,10 +68,10 @@ This permission is included in the following [built-in action groups](security_p
 
 ## Examples
 
-### Basic 
+### Deactivate a Watch 
 
 ```
-PUT /_signals/watch/_main/bad_weather/_deactivate
+DELETE /_signals/watch/_main/bad_weather/_active
 ```
 
 **Response**