[[alerting-setup]]
== Alerting set up
++++
<titleabbrev>Set up</titleabbrev>
++++

:frontmatter-description: Prerequisites and production considerations for using {kib} {alert-features}.
:frontmatter-tags-products: [alerting]
:frontmatter-tags-content-type: [other]
:frontmatter-tags-user-goals: [configure]

{kib} {alert-features} are automatically enabled, but might require some additional
configuration.

[float]
[[alerting-prerequisites]]
=== Prerequisites
If you are using an *on-premises* {stack} deployment:

* In the `kibana.yml` configuration file, add the
<<general-alert-action-settings,`xpack.encryptedSavedObjects.encryptionKey`>>
setting.
* For emails to have a footer with a link back to {kib}, set the
<<server-publicBaseUrl,`server.publicBaseUrl`>> configuration setting.

If you are using an *on-premises* {stack} deployment with
<<using-kibana-with-security,*security*>>:

* If you are unable to access {kib} {alert-features}, ensure that you have not
{ref}/security-settings.html#api-key-service-settings[explicitly disabled API keys].

The alerting framework uses queries that require the
`search.allow_expensive_queries` setting to be `true`. See the scripts
{ref}/query-dsl-script-query.html#_allow_expensive_queries_4[documentation].

[float]
[[alerting-setup-production]]
=== Production considerations and scaling guidance

When relying on alerting and actions as mission critical services, make sure you
follow the
<<alerting-production-considerations,alerting production considerations>>.

For more information on the scalability of {alert-features}, go to
<<alerting-scaling-guidance>>.

[float]
[[alerting-security]]
=== Security

To use {alert-features} in a {kib} app, you must have the appropriate feature privileges:

[discrete]
==== Give full access to manage alerts, connectors, and rules in *{stack-manage-app}*

**{kib} privileges**

* `All` for the *Management > {stack-rules-feature}* feature.
* `All` for the *Management > Rules Settings* feature.
* `All` for the *Management > {connectors-feature}* feature.

[NOTE]
====
The *{connectors-feature}* feature privilege is required to manage connectors.
To add rule actions and test connectors, you require only `Read` privileges.
By default, `All` privileges include authority to run {endpoint-sec} connectors (such as SentinelOne and CrowdStrike) unless you customize the sub-feature privileges.

Likewise, you can customize the *Rules Settings* sub-feature privileges related to flapping detection settings.

To create a rule that uses the <<cases-action-type,Cases connector>>, you must also have `All` privileges for the *Cases* feature.

The rule type also affects the privileges that are required.
For example, to create or edit {ml} rules, you must have `all` privileges for the *Analytics > {ml-app}* feature.
For {stack-monitor-app} rules, you must have the `monitoring_user` role.
For {observability} rules, you must have `all` privileges for the appropriate {observability} features.
For Security rules, refer to {security-guide}/detections-permissions-section.html[Detections prerequisites and requirements].
====

[discrete]
==== Give view-only access to alerts, connectors, and rules in  *{stack-manage-app}*

**{kib} privileges**

* `Read` for the *Management > {stack-rules-feature}* feature.
* `Read` for the *Management > Rules Settings* feature.
* `Read` for the *Management > {connectors-feature}* feature.

[NOTE]
====
The rule type also affects the privileges that are required.
For example, to view {ml} rules, you must have `read` privileges for the *Analytics > {ml-app}* feature.
For {stack-monitor-app} rules, you must have the `monitoring_user` role.
For {observability} rules, you must have `read` privileges for the appropriate {observability} features.
For Security rules, refer to {security-guide}/detections-permissions-section.html[Detections prerequisites and requirements].
====

[discrete]
==== Give view-only access to alerts in *Discover* or *Dashboards*

**{kib} privileges**

* `Read` index privileges for the `.alerts-*` system indices.

[discrete]
==== Revoke all access to alerts, connectors, and rules in *{stack-manage-app}*, *Discover*, or *Dashboards*

**{kib} privileges**

* `None` for the *Management > {stack-rules-feature}* feature.
* `None` for the *Management > Rules Settings* feature.
* `None` for the *Management > {connectors-feature}* feature.
* No index privileges for the `.alerts-*` system indices.

[discrete]
==== More details

For more information on configuring roles that provide access to features, go to <<kibana-feature-privileges>>.

[float]
[[alerting-authorization]]
==== API keys

Rules are authorized using an API key.
Its credentials are used to run all background tasks associated with the rule, including condition checks like {es} queries and triggered actions.

If you create or edit a rule in {kib}, an API key is created that captures a snapshot of your privileges at the time of the edit.
The following actions regenerate the API key in {kib}:

* Creating a rule
* Updating a rule

When you disable a rule, it retains the associated API key which is reused when the rule is enabled.
If the API key is missing when you enable the rule (for example, in the case of imported rules), it generates a new key that has your security privileges.

You can update an API key manually in **{stack-manage-app} > {rules-ui}** or in the rule details page by selecting **Update API key** in the actions menu.

If you manage your rules by using {kib} APIs, they support support both key- and token-based authentication as described in <<api-authentication>>.
To use key-based authentication, create API keys and use them in the header of your API calls as described in <<api-keys>>.
To use token-based authentication, provide a username and password; an API key that matches the current privileges of the user is created automatically.
In both cases, the API key is subsequently associated with the rule and used when it runs.

[IMPORTANT]
==============================================
If a rule requires certain privileges, such as index privileges, to run and a user without those privileges updates the rule, the rule will no longer function.
Conversely, if a user with greater or administrator privileges modifies the rule, it will begin running with increased privileges.
The same behavior occurs when you change the API key in the header of your API calls.
==============================================

[float]
[[alerting-restricting-actions]]
==== Restrict actions

For security reasons you may wish to limit the extent to which {kib} can connect to external services.
You can use <<action-settings>> to disable certain <<action-types>> and allowlist the hostnames that {kib} can connect with.

[float]
[[alerting-spaces]]
=== Space isolation

Rules and connectors are isolated to the {kib} space in which they were created.
A rule or connector created in one space will not be visible in another.

[float]
[[alerting-ccs-setup]]
=== {ccs-cap}

If you want to use alerting rules with {ccs}, you must configure privileges for
{ccs-init} and {kib}. Refer to {ref}/remote-clusters.html[Remote clusters].