elasticsearch/docs/reference/security/configuring-stack-security.asciidoc

[[configuring-stack-security]]
== Start the {stack} with security enabled automatically

When you start {es} for the first time, the following security configuration
occurs automatically:

* <<stack-security-certificates,Certificates and keys>> for TLS are
generated for the transport and HTTP layers.
* The TLS configuration settings are written to `elasticsearch.yml`.
* A password is generated for the `elastic` user.
* An enrollment token is generated for {kib}.

You can then start {kib} and enter the enrollment token, which is valid for 30
minutes. This token automatically applies the security settings from your {es}
cluster, authenticates to {es} with the built-in `kibana` service account, and
writes the security configuration to `kibana.yml`.

NOTE: There are <<stack-skip-auto-configuration,some cases>> where security
can't be configured automatically because the node startup process detects that
the node is already part of a cluster, or that security is already configured or
explicitly disabled.

[discrete]
=== Prerequisites

* https://www.elastic.co/downloads/elasticsearch[Download] and
unpack the `elasticsearch` package distribution for your
environment.
* https://www.elastic.co/downloads/kibana[Download] and unpack
the `kibana` package distribution for your environment.

[discrete]
[[stack-start-with-security]]
=== Start {es} and enroll {kib} with security enabled

. From the installation directory, start {es}.
+
[source,shell]
----
bin/elasticsearch
----
+
The command prints the `elastic` user password and an enrollment token for {kib}.

. Copy the generated `elastic` password and enrollment token. These credentials
are only shown when you start {es} for the first time.
+
[NOTE]
====
If you need to reset the password for the `elastic` user or other
built-in users, run the <<reset-password,`elasticsearch-reset-password`>> tool.
To generate new enrollment tokens for {kib} or {es} nodes, run the
<<create-enrollment-token,`elasticsearch-create-enrollment-token`>> tool.
These tools are available in the {es} `bin` directory.
====
+
We recommend storing the `elastic` password as an environment variable in your shell. Example:
+
[source,sh]
----
export ELASTIC_PASSWORD="your_password"
----

. (Optional) Open a new terminal and verify that you can connect to your {es}
cluster by making an authenticated call.
+
[source,shell]
----
curl --cacert config/certs/http_ca.crt -u elastic:$ELASTIC_PASSWORD https://localhost:9200
----
// NOTCONSOLE

. From the directory where you installed {kib}, start {kib}.
+
[source,shell]
----
bin/kibana
----

. Enroll {kib} using either interactive or detached mode.

  * *Interactive mode* (browser)

  .. In your terminal, click the generated link to open {kib} in your browser.
  .. In your browser, paste the enrollment token that you copied and click the
  button to connect your {kib} instance with {es}.
+
--
[NOTE]
====
{kib} won't enter interactive mode if it detects existing credentials for {es}
(`elasticsearch.username` and `elasticsearch.password`) or an existing URL for
`elasticsearch.hosts`.
====
--

  * *Detached mode* (non-browser)
+
Run the `kibana-setup` tool and pass the generated enrollment token with the
`--enrollment-token` parameter.
+
["source","sh",subs="attributes"]
----
bin/kibana-setup --enrollment-token <enrollment-token>
----

[discrete]
[[stack-enroll-nodes]]
=== Enroll additional nodes in your cluster

:slash:     /

include::enroll-nodes.asciidoc[]

[discrete]
include::{es-ref-dir}/setup/install/connect-clients.asciidoc[leveloffset=-1]

[discrete]
=== What's next?
Congratulations! You've successfully started the {stack} with security enabled.
{es} and {kib} are secured with TLS on the HTTP layer, and internode
communication is encrypted. If you want to enable HTTPS for web traffic, you
can <<encrypt-kibana-browser,encrypt traffic between your browser and {kib}>>.

[discrete]
[[stack-security-certificates]]
include::{es-ref-dir}/setup/install/security-files-reference.asciidoc[leveloffset=-2]

Additionally, when you use the enrollment token to connect {kib} to a secured {es} cluster, the HTTP layer CA certificate is retrieved from {es} and stored in the
{kib} `/data` directory. This file establishes trust between {kib} and the {es}
Certificate Authority (CA) for the HTTP layer.

[discrete]
[[stack-skip-auto-configuration]]
=== Cases when security auto configuration is skipped
When you start {es} for the first time, the node startup process tries to
automatically configure security for you. The process runs some checks to
determine:

* If this is the first time that the node is starting
* Whether security is already configured
* If the startup process can modify the node configuration

If any of those checks fail, there's a good indication that you
<<manually-configure-security,manually configured security>>, or don't want
security to be configured automatically. In these cases, the node starts
normally using the existing configuration.

IMPORTANT: If you redirect {es} output to a file, security autoconfiguration is skipped.
Autoconfigured credentials can only be viewed on the terminal the first time you start {es}.
If you need to redirect output to a file, start {es} without redirection the first time
and use redirection on all subsequent starts.

[discrete]
[[stack-existing-environment-detected]]
==== Existing environment detected
If certain directories already exist, there's a strong indication that the node
was started previously. Similarly, if certain files _don't_ exist, or we can't
read or write to specific files or directories, then we're likely not running as
the user who installed {es} or an administrator imposed restrictions. If any of
the following environment checks are true, security isn't configured
automatically.

The {es} `/data` directory exists and isn't empty::
The existence of this directory is a strong indicator that the node was started
previously, and might already be part of a cluster.

The `elasticsearch.yml` file doesn't exist (or isn't readable), or the `elasticsearch.keystore` isn't readable::
If either of these files aren't readable, we can't determine whether {es} security
features are already enabled. This state can also indicate that the node startup
process isn't running as a user with sufficient privileges to modify the
node configuration.

The {es} configuration directory isn't writable::
This state likely indicates that an administrator made this directory read-only,
or that the user who is starting {es} is not the user that installed {es}.

[discrete]
[[stack-existing-settings-detected]]
==== Existing settings detected
The following settings are incompatible with security auto configuration. If any
of these settings exist, the node startup process skips configuring security
automatically and the node starts normally.

* {ref}/modules-node.html#node-roles[`node.roles`] is set to a value where the
node can't be elected as `master`, or if the node can't hold data
* {ref}/security-settings.html#general-security-settings[`xpack.security.autoconfiguration.enabled`] is set to `false`
* {ref}/security-settings.html#general-security-settings[`xpack.security.enabled`] has a value set
* Any of the
{ref}/security-settings.html#transport-tls-ssl-settings[`xpack.security.transport.ssl.*`] or
{ref}/security-settings.html#http-tls-ssl-settings[`xpack.security.http.ssl.*`]
settings have a value set in the `elasticsearch.yml` configuration file or in
the `elasticsearch.keystore`
* Any of the `discovery.type`, `discovery.seed_hosts`, or
`cluster.initial_master_nodes`
{ref}/modules-discovery-settings.html[discovery and cluster formation settings]
have a value set
+
--
[NOTE]
====
Exceptions are when `discovery.type` is set to `single-node`, or when
`cluster.initial_master_nodes` exists but contains only the name of the current
node.
====
--