elasticsearch/x-pack/docs/en/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}. A password is generated for the
`elastic` user and output to the terminal, plus an enrollment token for
enrolling {kib}.
+
[source,shell]
----
bin/elasticsearch
----
+
TIP: You might need to scroll back a bit in the terminal to view the password
and enrollment token.

. Copy the generated password and enrollment token and save them in a secure
location. These values are shown only 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.
====

. (Optional) Open a new terminal and verify that you can connect to your {es}
cluster by making an authenticated call. Enter the password for the `elastic`
user when prompted:
+
[source,shell]
----
curl --cacert config/certs/http_ca.crt -u elastic 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. 

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