[[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

If you want to use the {alert-features} in a {kib} app, you must have the
appropriate feature privileges. For example, to create rules in
*{stack-manage-app} > {rules-ui}*, you must have `all` privileges for the
*Management > {stack-rules-feature}* feature. To add rule actions and test
connectors, you must also have `read` privileges for the *{connectors-feature}*
feature. To change rule settings, you must have `all` privileges for the
*Rules Settings* privilege or `all` privileges for the appropriate sub-feature
such as flapping detection. For more information on configuring roles that
provide access to features, go to <<kibana-feature-privileges>>.

For details about the prerequisites for each API, refer to <<alerting-apis>>.

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

For security reasons you may wish to limit the extent to which {kib} can connect 
to external services. <<action-settings>> allows you 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-authorization]]
=== Authorization

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-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].