Update bootstrap security details (elastic/x-pack-elasticsearch#2430)

* [DOCS] Update bootstrap security details

* [DOCS] Addressed feedback about bootstrap

* [DOCS] Update bootstrap password details

* [DOCS] Addressed feedback about setup-passwords

* [DOCS] Update security in x-pack install info

* [DOCS] Remove bootstrap.password details

* [DOCS] Update setup-passwords info

* [DOCS] Re-add bootstrap.password details

Original commit: elastic/x-pack-elasticsearch@04d3ee8509

docs/en/commands/index.asciidoc

@@ -8,10 +8,11 @@
 {xpack} includes commands that help you configure security:
 
 * <<certgen>>
-//* <<setup-passwords>>
+* <<setup-passwords>>
 * <<users-command>>
 
 --
 
 include::certgen.asciidoc[]
+include::setup-passwords.asciidoc[]
 include::users-command.asciidoc[]

docs/en/commands/setup-passwords.asciidoc

@@ -0,0 +1,47 @@
+[role="xpack"]
+[[setup-passwords]]
+== setup-passwords
+
+The `setup-passwords` command sets the passwords for the built-in `elastic`,
+`kibana`, and `logstash_system` users.
+
+[float]
+=== Synopsis
+
+[source,shell]
+--------------------------------------------------
+bin/x-pack/setup-passwords auto|interactive [-u "<URL>"]
+--------------------------------------------------
+
+[float]
+=== Description
+
+This command is intended for use only during the initial configuration of
+{xpack}. It uses the
+{xpack-ref}/setting-up-authentication.html#bootstrap-elastic-passwords[`elastic` bootstrap password]
+to run user management API requests. After you set a password for the `elastic`
+user, the bootstrap password is no longer active and you cannot use this command.
+Instead, you can change passwords by using the *Management > Users* UI in {kib}
+or the <<security-api-change-password,Change Password API>>.
+
+[float]
+=== Parameters
+
+`auto`::  Outputs randomly-generated passwords to the console.
+
+`interactive`:: Prompts you to manually enter passwords.
+
+`-u "<URL>"`:: Specifies the URL that the tool uses to submit the user management API
+requests. The default value is determined from the settings in your
+`elasticsearch.yml` file.
+
+[float]
+=== Examples
+
+The following example uses the `-u` parameter to tell the tool where to submit
+its user management API requests:
+
+[source,shell]
+--------------------------------------------------
+bin/x-pack/setup-passwords auto -u "http://localhost:9201"
+--------------------------------------------------

docs/en/installing-xes.asciidoc

@@ -197,19 +197,27 @@ bin/elasticsearch
 ----------------------------------------------------------
 --
 
-.. Set the passwords for all built-in users. You can update passwords from the
+.. Set the passwords for all built-in users. The +setup-passwords+ command is
-**Management > Users** UI in {kib}, use the `setup-passwords` tool, or use the
+the simplest method to set the built-in users' passwords for the first time.
-security user API. For example:
 +
 --
+For example, you can run the command in an "interactive" mode, which prompts you
+to enter new passwords for the `elastic`, `kibana`, and `logstash_system` users:
+
 [source,shell]
 --------------------------------------------------
 bin/x-pack/setup-passwords interactive
 --------------------------------------------------
-If you prefer to have randomly generated passwords, specify `auto` instead of
+
-`interactive`. If the node is not listening on "http://localhost:9200", use the
+For more information about the command options, see <<setup-passwords>>.
-`-u` parameter to specify the appropriate URL. For more information,
+
-see {xpack-ref}/setting-up-authentication.html[Setting Up User Authentication].
+IMPORTANT: The `setup-passwords` command uses a transient bootstrap password
+that is no longer valid after the command runs successfully. You cannot run the
+`setup-passwords` command a second time. Instead, you can update passwords from
+the **Management > Users** UI in {kib} or use the security user API.
+
+For more information, see
+{ref}/setting-up-authentication.html#set-built-in-user-passwords[Setting Built-in User Passwords].
 --
 
 . {kibana-ref}/installing-xpack-kb.html[Install {xpack} on {kib}].

docs/en/security/authentication.asciidoc

@@ -19,13 +19,10 @@ These users have a fixed set of privileges and cannot be authenticated until the
 passwords have been set. The `elastic` user can be used to
 <<set-built-in-user-passwords,set all of the built-in user passwords>>.
 
-.{security} Built-in Users
+`elastic`:: A built-in _superuser_. See <<built-in-roles>>.
-|========
+`kibana`:: The user Kibana uses to connect and communicate with Elasticsearch.
-| Name               | Description
+`logstash_system`:: The user Logstash uses when storing monitoring information in Elasticsearch.
-| `elastic`          | A built-in _superuser_. See <<built-in-roles>>.
+
-| `kibana`           | The user Kibana uses to connect and communicate with Elasticsearch.
-| `logstash_system`  | The user Logstash uses when storing monitoring information in Elasticsearch.
-|========
 
 [float]
 [[built-in-user-explanation]]
@@ -43,74 +40,84 @@ realm will not have any effect on the built-in users. The built-in users can
 be disabled individually, using the
 {ref}/security-api-users.html[user management API].
 
+[float]
+[[bootstrap-elastic-passwords]]
+==== The Elastic Bootstrap Password
+
+When you install {xpack}, if the `elastic` user does not already have a password,
+it uses a default bootstrap password. The bootstrap password is a transient
+password that enables you to run the tools that set all the built-in user passwords.
+
+By default, the bootstrap password is derived from a randomized `keystore.seed`
+setting, which is added to the keystore when you install {xpack}. You do not need
+to know or change this bootstrap password. If you have defined a
+`bootstrap.password` setting in the keystore, however, that value is used instead.
+For more information about interacting with the keystore, see
+{ref}/secure-settings.html[Secure Settings].
+////
+//TBD: Is the following still true?
+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.
+////
+
+NOTE: After you <<set-built-in-user-passwords,set passwords for the built-in users>>,
+in particular for the `elastic` user, there is no further use for the bootstrap
+password.
+
 [float]
 [[set-built-in-user-passwords]]
-==== Set Built-in User Passwords
+==== Setting 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, 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
+The +setup-passwords+ tool is the simplest method to set the built-in users'
-setup. When it is run, it will use the `elastic` user to execute API requests
+passwords for the first time. It uses the `elastic` user's bootstrap password to
-that will change the passwords of the `elastic`, `kibana`, and
+run user management API requests. For example, you can run the command in
-`logstash_system` users. In "auto" mode the passwords will be generated randomly and
+an "interactive" mode, which prompts you to enter new passwords for the
-printed to the console.
+`elastic`, `kibana`, and `logstash_system` users:
-
-[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
+For more information about the command options, see
-to tell the tool where to submit the requests.
+{ref}/setup-passwords.html[setup-passwords].
+
+IMPORTANT: After you set a password for the `elastic` user, the bootstrap
+password is no longer valid; you cannot run the `setup-passwords` command a
+second time.
+
+Alternatively, you can set the initial passwords for the built-in users by using
+the *Management > Users* page in {kib} or the
+{ref}/security-api-change-password.html[Change Password API]. These methods are
+more complex. You must supply the `elastic` user and its bootstrap password to
+log into {kib} or run the API. This requirement means that you cannot use the
+default bootstrap password that is derived from the `keystore.seed` setting.
+Instead, you must explicitly set a `bootstrap.password` setting in the keystore
+before you start {es}. For example, the following command prompts you to enter a
+new bootstrap password:
 
 [source,shell]
---------------------------------------------------
+----------------------------------------------------
-bin/x-pack/setup-passwords auto -u "http://localhost:9201"
+bin/elasticsearch-keystore add "bootstrap.password"
---------------------------------------------------
+----------------------------------------------------
 
-The {ref}/security-api-users.html#security-api-reset-user-password[Reset Password API] can
+You can then start {es} and {kib} and use the `elastic` user and bootstrap
-also be used to change the passwords manually.
+password to log into {kib} and change the passwords. Alternatively, you can
+submit Change Password API requests for each built-in user. These methods are
+better suited for changing your passwords after the initial setup is complete,
+since at that point the bootstrap password is no longer required.
 
-[source,js]
+[float]
----------------------------------------------------------------------
+[[add-built-in-user-passwords]]
-PUT _xpack/security/user/elastic/_password
+==== Adding Built-in User Passwords To {kib} and Logstash
-{
-  "password": "elasticpassword"
-}
----------------------------------------------------------------------
-// CONSOLE
 
-[source,js]
+After the `kibana` user password is set, you need to update the {kib} server
----------------------------------------------------------------------
+with the new password by setting `elasticsearch.password` in the `kibana.yml`
-PUT _xpack/security/user/kibana/_password
+configuration file:
-{
-  "password": "kibanapassword"
-}
----------------------------------------------------------------------
-// CONSOLE
-
-[source,js]
----------------------------------------------------------------------
-PUT _xpack/security/user/logstash_system/_password
-{
-  "password": "logstashpassword"
-}
----------------------------------------------------------------------
-// CONSOLE
-
-Once the `kibana` user password is reset, you need to update the Kibana server
-with the new password by setting `elasticsearch.password` in the
-`kibana.yml` configuration file:
 
 [source,yaml]
 -----------------------------------------------
@@ -138,16 +145,15 @@ Once the password has been changed, you can enable the user via the following AP
 PUT _xpack/security/user/logstash_system/_enable
 ---------------------------------------------------------------------
 // CONSOLE
-=============================================================================
 
 [float]
 [[disabling-default-password]]
-==== Disable Default Password Functionality
+==== Disabling Default Password Functionality
 [IMPORTANT]
 =============================================================================
-This setting is deprecated. The elastic user no longer has a default password. The password must
+This setting is deprecated. The elastic user no longer has a default password.
-be set before the user can be used.
+The password must be set before the user can be used.
-
+See <<bootstrap-elastic-passwords>>.
 =============================================================================
 
 [float]

docs/en/security/getting-started.asciidoc

@@ -16,23 +16,12 @@ To get started with {security}:
 
 . <<installing-xpack, Install X-Pack>>.
 
-. On at least one of the nodes in your cluster, set the "bootstrap.password" secure setting in the keystore.
+.  Start {es} and {kib}.
-+
---
-[source,shell]
---------------------------------------------------
-bin/elasticsearch-keystore create
-bin/elasticsearch-keystore add "bootstrap.password"
---------------------------------------------------
 
---
+. Set the passwords of the built in `elastic`, `kibana`, and `logstash_system` users.
-
+In most cases, you can simply run the `bin/x-pack/setup-passwords` tool on one of the nodes in your cluster.
-.  Start Elasticsearch and Kibana. The Elasticsearch node with the "bootstrap.password" setting will use that
+Run that command with the same user that is running your {es} process.
-setting to set the `elastic` user password on node startup.
+In "auto" mode this tool will randomly generate passwords and print them to the console.
-
-
-. 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]
@@ -40,9 +29,10 @@ passwords tool. In "auto" mode this tool will randomly generate passwords and pr
 bin/x-pack/setup-passwords auto
 --------------------------------------------------
 
+For more information, see <<set-built-in-user-passwords>>.
 --
 
-. Set up roles and users to control access to Elasticsearch and Kibana.
+. Set up roles and users to control access to {es} and {kib}.
 For example, to grant _John Doe_ full access to all indices that match
 the pattern `events*` and enable him to create visualizations and dashboards
 for those indices in Kibana, you could create an `events_admin` role and
@@ -76,7 +66,7 @@ curl -XPOST -u elastic 'localhost:9200/_xpack/security/user/johndoe' -H "Content
 
 [[enable-auditing]]
 . Enable Auditing to keep track of attempted and successful interactions with
-  your Elasticsearch cluster:
+  your {es} cluster:
 +
 --
 .. Add the following setting to `elasticsearch.yml` on all nodes in your cluster:
@@ -85,10 +75,10 @@ curl -XPOST -u elastic 'localhost:9200/_xpack/security/user/johndoe' -H "Content
 ----------------------------
 xpack.security.audit.enabled: true
 ----------------------------
-.. Restart Elasticsearch.
+.. Restart {es}.
 
 By default, events are logged to a dedicated `elasticsearch-access.log` file in
-`ES_HOME/logs`. You can also store the events in an Elasticsearch index for
+`ES_HOME/logs`. You can also store the events in an {es} index for
 easier analysis and control what events are logged. For more information, see
 {xpack-ref}/auditing.html[Configuring Auditing].
 --