From a0fd423db12a1c072e2a363256e3cd7c0374d144 Mon Sep 17 00:00:00 2001 From: Tim Brooks Date: Thu, 20 Jul 2017 11:23:20 -0500 Subject: [PATCH] Update documentation for bootstrap password work (elastic/x-pack-elasticsearch#2031) This is related to elastic/x-pack-elasticsearch#1217. The commit adds documenation describing how to use the bootstrap password and setup-password tool. Original commit: elastic/x-pack-elasticsearch@1bad8ddb4d5815394a4a15937c4d9b74febc976f --- docs/en/security/authentication.asciidoc | 76 ++++++++++++++++++++--- docs/en/security/getting-started.asciidoc | 44 +++++++------ 2 files changed, 93 insertions(+), 27 deletions(-) diff --git a/docs/en/security/authentication.asciidoc b/docs/en/security/authentication.asciidoc index 73895931a60..ccf74bedad6 100644 --- a/docs/en/security/authentication.asciidoc +++ b/docs/en/security/authentication.asciidoc @@ -16,10 +16,12 @@ see <>. {security} provides built-in user credentials to help you get up and running. These users have a fixed set of privileges and cannot be authenticated until their -passwords have been set. The exception is the `elastic` user which can be authenticated -from a localhost rest request with an empty password. Until a password is set, the elastic -user is only authorized to perform change password requests. -Please read <> below. +passwords have been set. In order to set these passwords, the `elastic` user must +have its password bootstrapped. To bootstrap the password, please read +<> below. + +Once the `elastic` user has its password bootstrapped, +this user can be used to <>. .{security} Built-in Users |======== @@ -46,13 +48,71 @@ be disabled individually, using the {ref}/security-api-users.html[user management API]. [float] -[[reset-built-in-user-passwords]] -==== Reset Built-in User Passwords +[[bootstrap-elastic-passwords]] +==== Bootstrap Elastic Password +The `elastic` user can have its password bootstrapped by placing a password +in the keystore of at least one node. At startup, that node will pull the +password out of the keystore and set the `elastic` password to that value. The +password will only be set if the `elastic` user password has not already been set. + +As the `elastic` user is stored in the native realm, the password will be +synced to all the nodes in a cluster. It is safe to bootstrap the password with +multiple nodes as long as the password is the same. If different passwords are +set with different nodes, it is unpredictable which password will be bootstrapped. + +Specifically, the setting for the bootstrap password is "bootstrap.password". If +the keystore has not been created before, it must be created first. + +[source,shell] +-------------------------------------------------- +bin/elasticsearch-keystore create +bin/elasticsearch-keystore add "bootstrap.password" +-------------------------------------------------- + +After running the "add" command, you will be prompted to enter your password. + +The bootstrap password is only intended to be a transient password used to help you +set all the built-in user passwords. As the password will remain accessible in the +keystore on the machine, the `elastic` user's password should be changed to a different +password when you . + +[float] +[[set-built-in-user-passwords]] +==== Set Built-in User Passwords [IMPORTANT] ============================================================================= You must set the passwords for all built-in users. -You can update passwords from the *Management > Users* UI in Kibana or with the -{ref}/security-api-users.html#security-api-reset-user-password[Reset Password API]: +You can update passwords from the *Management > Users* UI in Kibana, using the +setup-passwords tool, or with the security user api. + +The setup-passwords tool is a command line tool that is provided to assist with +setup. When it is run, it will use the `elastic` user bootstrap password to execute +api requests that will change the passwords of the `elastic`, `kibana`, and +`logstash_system` users. In "auto" mode the passwords will be generated randomly and +printed to the console. + +[source,shell] +-------------------------------------------------- +bin/x-pack/setup-passwords auto +-------------------------------------------------- + +There is also an "interactive" mode that will prompt you to manually enter passwords. + +[source,shell] +-------------------------------------------------- +bin/x-pack/setup-passwords interactive +-------------------------------------------------- + +If the node is not listening at "http://localhost:9200", you will need to pass the url parameter +to tell the tool where to submit the requests. + +[source,shell] +-------------------------------------------------- +bin/x-pack/setup-passwords auto -u "http://localhost:9201" +-------------------------------------------------- + +The {ref}/security-api-users.html#security-api-reset-user-password[Reset Password API] can +also be used to change the passwords manually. [source,js] --------------------------------------------------------------------- diff --git a/docs/en/security/getting-started.asciidoc b/docs/en/security/getting-started.asciidoc index f7d31b0522d..8d3356467ad 100644 --- a/docs/en/security/getting-started.asciidoc +++ b/docs/en/security/getting-started.asciidoc @@ -9,35 +9,41 @@ requests that don't include a user name and password are rejected. {security} provides a built-in `elastic` superuser you can use to start setting things up. This `elastic` user has full access -to the cluster, including all indices and data, so make sure -you change the default password and protect the `elastic` user -credentials accordingly. +to the cluster, including all indices and data, so the `elastic` user +does not have a password set by default. + +In order for the `elastic` user to be usable, its <> +by at least one of the nodes in your cluster. The bootstrap password is intended +to be a temporary password to help you setup your cluster. The `elastic` user password +will be changed during the setup process. To get started with {security}: -. <> and start Elasticsearch and Kibana. +. <>. -. Change the passwords of the built in `kibana`, `logstash_system` and `elastic` users: +. On at least one of the nodes in your cluster, set the "bootstrap.password" secure setting in the keystore. + -- [source,shell] ----------------------------------------------------------- -curl -XPUT -u elastic 'localhost:9200/_xpack/security/user/elastic/_password' -H "Content-Type: application/json" -d '{ - "password" : "elasticpassword" -}' +-------------------------------------------------- +bin/elasticsearch-keystore create +bin/elasticsearch-keystore add "bootstrap.password" +-------------------------------------------------- -curl -XPUT -u elastic 'localhost:9200/_xpack/security/user/kibana/_password' -H "Content-Type: application/json" -d '{ - "password" : "kibanapassword" -}' +-- -curl -XPUT -u elastic 'localhost:9200/_xpack/security/user/logstash_system/_password' -H "Content-Type: application/json" -d '{ - "password" : "logstashpassword" -}' ----------------------------------------------------------- -// NOTCONSOLE +. Start Elasticsearch and Kibana. The Elasticsearch node with the "bootstrap.password" setting will use that +setting to set the `elastic` user password on node startup. -NOTE: By default, the `elastic` user does not have a password set. Until its password is set, the `elastic` user will only be -allowed to submit change password rest requests from localhost. + +. Set the passwords of the built in `elastic`, `kibana`, and `logstash_system` users using the provided setup +passwords tool. In "auto" mode this tool will randomly generate passwords and print them to the console. ++ +-- +[source,shell] +-------------------------------------------------- +bin/x-pack/setup-passwords auto +-------------------------------------------------- --