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@1bad8ddb4d

docs/en/security/authentication.asciidoc

@@ -16,10 +16,12 @@ see <<managing-native-users, Managing Native Users>>.
 
 {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
+passwords have been set. In order to set these passwords, the `elastic` user must
-from a localhost rest request with an empty password. Until a password is set, the elastic
+have its password bootstrapped. To bootstrap the password, please read
-user is only authorized to perform change password requests.
+<<bootstrap-elastic-passwords,Bootstrap Elastic Password>> below.
-Please read <<reset-built-in-user-passwords,Reset Built-in User Passwords>> below.
+
+Once the `elastic` user has its password bootstrapped,
+this user can be used to <<set-built-in-user-passwords,set all of the built-in user passwords>>.
 
 .{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]]
+[[bootstrap-elastic-passwords]]
-==== Reset Built-in User 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 <set-built-in-user-passwords,set all the built-in passwords>.
+
+[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
+You can update passwords from the *Management > Users* UI in Kibana, using the
-{ref}/security-api-users.html#security-api-reset-user-password[Reset Password API]:
+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]
 ---------------------------------------------------------------------

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
+to the cluster, including all indices and data, so the `elastic` user
-you change the default password and protect the `elastic` user
+does not have a password set by default.
-credentials accordingly.
+
+In order for the `elastic` user to be usable, its <<bootstrap-elastic-passwords,password must be bootstrapped>>
+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}:
 
-. <<installing-xpack, Install X-Pack>> and start Elasticsearch and Kibana.
+. <<installing-xpack, Install X-Pack>>.
 
-. 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 '{
+bin/elasticsearch-keystore create
-  "password" : "elasticpassword"
+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 '{
+.  Start Elasticsearch and Kibana. The Elasticsearch node with the "bootstrap.password" setting will use that
-  "password" : "logstashpassword"
+setting to set the `elastic` user password on node startup.
-}'
-----------------------------------------------------------
-// NOTCONSOLE
 
-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
+--------------------------------------------------
 
 --