From 2148dfe17e22d7cc3350cede4c218f00aa22d7fb Mon Sep 17 00:00:00 2001 From: Peter Schretlen Date: Mon, 10 Feb 2020 10:56:27 -0500 Subject: [PATCH] Add docs for alerting and action settings (#57035) (#57158) --- docs/settings/alert-action-settings.asciidoc | 47 ++++++++++++++++++++ docs/settings/settings-xkb.asciidoc | 1 + docs/setup/settings.asciidoc | 11 +---- 3 files changed, 49 insertions(+), 10 deletions(-) create mode 100644 docs/settings/alert-action-settings.asciidoc diff --git a/docs/settings/alert-action-settings.asciidoc b/docs/settings/alert-action-settings.asciidoc new file mode 100644 index 000000000000..e3b9e61667bd --- /dev/null +++ b/docs/settings/alert-action-settings.asciidoc @@ -0,0 +1,47 @@ +[role="xpack"] +[[alert-action-settings-kb]] +=== Alerting and action settings in Kibana +++++ +Alerting and action settings +++++ + +Alerts and actions are enabled by default in {kib}, but require you configure the following in order to use them: + +. <>. +. <>. +. <>. + +You can configure the following settings in the `kibana.yml` file. + + +[float] +[[general-alert-action-settings]] +==== General settings + +`xpack.encrypted_saved_objects.encryptionKey`:: + +A string of 32 or more characters used to encrypt sensitive properties on alerts and actions before they're stored in {es}. Third party credentials — such as the username and password used to connect to an SMTP service — are an example of encrypted properties. ++ +If not set, {kib} will generate a random key on startup, but all alert and action functions will be blocked. Generated keys are not allowed for alerts and actions because when a new key is generated on restart, existing encrypted data becomes inaccessible. For the same reason, alerts and actions in high-availability deployments of {kib} will behave unexpectedly if the key isn't the same on all instances of {kib}. ++ +Although the key can be specified in clear text in `kibana.yml`, it's recommended to store this key securely in the <>. + +[float] +[[alert-settings]] +==== Action settings + +`xpack.actions.whitelistedHosts`:: +A list of hostnames that {kib} is allowed to connect to when built-in actions are triggered. It defaults to `[*]`, allowing any host, but keep in mind the potential for SSRF attacks when hosts are not explicitly whitelisted. An empty list `[]` can be used to block built-in actions from making any external connections. ++ +Note that hosts associated with built-in actions, such as Slack and PagerDuty, are not automatically whitelisted. If you are not using the default `[*]` setting, you must ensure that the corresponding endpoints are whitelisted as well. + +`xpack.actions.enabledActionTypes`:: +A list of action types that are enabled. It defaults to `[*]`, enabling all types. The names for built-in {kib} action types are prefixed with a `.` and include: `.server-log`, `.slack`, `.email`, `.index`, `.pagerduty`, and `.webhook`. An empty list `[]` will disable all action types. ++ +Disabled action types will not appear as an option when creating new connectors, but existing connectors and actions of that type will remain in {kib} and will not function. + +[float] +[[action-settings]] +==== Alert settings + +You do not need to configure any additional settings to use alerting in {kib}. diff --git a/docs/settings/settings-xkb.asciidoc b/docs/settings/settings-xkb.asciidoc index f509900e0584..f9727db838d5 100644 --- a/docs/settings/settings-xkb.asciidoc +++ b/docs/settings/settings-xkb.asciidoc @@ -10,6 +10,7 @@ include::{asciidoc-dir}/../../shared/settings.asciidoc[] For more {kib} configuration settings, see <>. +include::alert-action-settings.asciidoc[] include::apm-settings.asciidoc[] include::dev-settings.asciidoc[] include::graph-settings.asciidoc[] diff --git a/docs/setup/settings.asciidoc b/docs/setup/settings.asciidoc index db2bc21889be..25d762263ce2 100644 --- a/docs/setup/settings.asciidoc +++ b/docs/setup/settings.asciidoc @@ -463,16 +463,7 @@ Rollup user interface. `i18n.locale`:: *Default: en* Set this value to change the Kibana interface language. Valid locales are: `en`, `zh-CN`, `ja-JP`. -`xpack.actions.enabledActionTypes:`:: *Default: +[ {asterisk} ]+* Set this value -to an array of action types that are enabled. An element of `*` indicates all -action types registered are enabled. The action types provided by Kibana are: -`.server-log`, `.slack`, `.email`, `.index`, `.pagerduty`, `.webhook`. - -`xpack.actions.whitelistedHosts:`:: *Default: +[ {asterisk} ]+* Set this value -to an array of host names which actions such as email, slack, pagerduty, and -webhook can connect to. An element of `*` indicates any host can be connected -to. An empty array indicates no hosts can be connected to. - +include::{docdir}/settings/alert-action-settings.asciidoc[] include::{docdir}/settings/apm-settings.asciidoc[] include::{docdir}/settings/dev-settings.asciidoc[] include::{docdir}/settings/graph-settings.asciidoc[]