[[security-minimal-setup]]
=== Set up minimal security for {es}
++++
<titleabbrev>Set up minimal security</titleabbrev>
++++

You enable the Elasticsearch security features and then create
passwords for built-in users. You can add more users later, but using the
built-in users simplifies the process of enabling security for your
cluster.

include::../configuring-stack-security.asciidoc[tag=minimal-security-note]

==== Prerequisites

. Install and configure {es} and {kib}. See https://www.elastic.co/guide/en/elastic-stack-get-started/current/get-started-elastic-stack.html[Getting started with the Elastic Stack].

. Verify that you are using a license that includes the specific security
features you want.
+
The basic license includes minimal security settings for the Elastic Stack, so
you can just download the distribution and get to work. You can also enable a
free trial license to access all features of the Elastic Stack. See https://www.elastic.co/subscriptions[subscriptions] and https://www.elastic.co/guide/en/kibana/current/managing-licenses.html[license management].

==== Enable {es} security features

When you use the basic license, the {es} security features are disabled by
default. Enabling the {es} security features enables basic authentication so
that you can run a local cluster with username and password authentication.

. On *every* node in your cluster, stop both {kib} and {es} if they are running.

. On *every* node in your cluster, add the `xpack.security.enabled` setting to
the `$ES_PATH_CONF/elasticsearch.yml` file and set the value to `true`:
+
[source,yaml]
----
xpack.security.enabled: true
----
+
NOTE: The `$ES_PATH_CONF` variable is the path for the {es}
configuration files. If you installed {es} using archive distributions
(`zip` or `tar.gz`), the variable defaults to `$ES_HOME/config`. If you used
package distributions (Debian or RPM), the variable defaults to `/etc/elasticsearch`.

. If your cluster has a single node, add the `discovery.type` setting in the
`$ES_PATH_CONF/elasticsearch.yml` file and set the value to `single-node`. This
setting ensures that your node does not inadvertently connect to other clusters
that might be running on your network.
+
[source,yaml]
----
discovery.type: single-node
----

[[security-create-builtin-users]]
==== Create passwords for built-in users

To communicate with the cluster, you must configure a username for the built-in
users. Unless you enable anonymous access, all requests that don’t include a
user name and password are rejected.

NOTE: You only need to set passwords for the `elastic` and `kibana_system` users
when enabling minimal or basic security.

. On *every* node in your cluster, start {es}. For example, if you installed 
{es} with a `.tar.gz` package, run the following command from the `ES_HOME`
directory:
+
[source,shell]
----
./bin/elasticsearch
----

. In another terminal window, set the passwords for the built-in users by
running the <<setup-passwords,`elasticsearch-setup-passwords`>> utility.
+
IMPORTANT: You can run the `elasticsearch-setup-passwords` utility
against any node in your cluster. However, you should only run this utility *one
time* for the entire cluster.
+
Using the `auto` parameter
outputs randomly-generated passwords to the console that you can change later
if necessary:
+
[source,shell]
----
./bin/elasticsearch-setup-passwords auto
----
+
If you want to use your own passwords, run the command with the
`interactive` parameter instead of the `auto` parameter. Using this mode
steps you through password configuration for all of the built-in users.
+
[source,shell]
----
./bin/elasticsearch-setup-passwords interactive
----

. Save the generated passwords. You'll need them to add the built-in user to
{kib}.

WARNING: After you set a password for the `elastic` user, you cannot run the
`elasticsearch-setup-passwords` command a second time.

*Next*: <<add-built-in-users,Configure {kib} to connect to {es} with a password>>

[[add-built-in-users]]
==== Configure {kib} to connect to {es} with a password

When the {es} security features are enabled, users must log in to {kib} with a
valid username and password.

You'll configure {kib} to use the built-in `kibana_system` user and the password that
you created earlier. {kib} performs some background tasks that require use of the
`kibana_system` user.

This account is not meant for individual users and does not have permission to log in
to {kib} from a browser. Instead, you'll log in to {kib} as the `elastic` superuser. 

. Add the `elasticsearch.username` setting to the `KIB_PATH_CONF/kibana.yml`
file and set the value to the `kibana_system` user:
+
[source,yaml]
----
elasticsearch.username: "kibana_system"
----
+
NOTE: The `KIB_PATH_CONF` variable is the path for the {kib}
configuration files. If you installed {kib} using archive distributions
(`zip` or `tar.gz`), the variable defaults to `KIB_HOME/config`. If you used
package distributions (Debian or RPM), the variable defaults to `/etc/kibana`.

. From the directory where you installed {kib}, run the following commands
to create the {kib} keystore and add the secure settings:

   a. Create the {kib} keystore:
+
[source,shell]
----
./bin/kibana-keystore create
----

   b. Add the password for the `kibana_system` user to the {kib} keystore:
+
[source,shell]
----
./bin/kibana-keystore add elasticsearch.password
----
+
When prompted, enter the password for the `kibana_system` user.

. Restart {kib}. For example, if you installed {kib} with a `.tar.gz` package, run the following command from the {kib} directory:
+
[source,shell]
----
./bin/kibana
----

. Log in to {kib} as the `elastic` user. Use this superuser account to 
{kibana-ref}/tutorial-secure-access-to-kibana.html[manage spaces, create new users, and assign roles]. If you're running {kib} locally, go to `http://localhost:5601` to view the login page.

[[minimal-security-whatsnext]]
==== What's next?

Congratulations! You enabled password protection for your local cluster to
prevent unauthorized access. You can log in to {kib} securely as the `elastic`
user and create additional users and roles. If you're running a <<single-node-discovery,single-node cluster>>, then you can stop here.

If your cluster has multiple nodes, then you must configure Transport Layer
Security (TLS) between nodes. <<dev-vs-prod-mode,Production mode>> clusters
will not start if you do not enable TLS.

<<security-basic-setup,Set up basic security for the Elastic Stack>> to
secure all internal communication between nodes in your cluster.
