diff --git a/docs/en/commands/index.asciidoc b/docs/en/commands/index.asciidoc index 12792f74ec7..69f279f90ff 100644 --- a/docs/en/commands/index.asciidoc +++ b/docs/en/commands/index.asciidoc @@ -8,10 +8,11 @@ {xpack} includes commands that help you configure security: * <> -//* <> +* <> * <> -- include::certgen.asciidoc[] +include::setup-passwords.asciidoc[] include::users-command.asciidoc[] diff --git a/docs/en/commands/setup-passwords.asciidoc b/docs/en/commands/setup-passwords.asciidoc new file mode 100644 index 00000000000..0b7450e2e06 --- /dev/null +++ b/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 ""] +-------------------------------------------------- + +[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 <>. + +[float] +=== Parameters + +`auto`:: Outputs randomly-generated passwords to the console. + +`interactive`:: Prompts you to manually enter passwords. + +`-u ""`:: 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" +-------------------------------------------------- diff --git a/docs/en/installing-xes.asciidoc b/docs/en/installing-xes.asciidoc index 0107c2896c3..1f837184572 100644 --- a/docs/en/installing-xes.asciidoc +++ b/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 -**Management > Users** UI in {kib}, use the `setup-passwords` tool, or use the -security user API. For example: +.. Set the passwords for all built-in users. The +setup-passwords+ command is +the simplest method to set the built-in users' passwords for the first time. + -- +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 -`-u` parameter to specify the appropriate URL. For more information, -see {xpack-ref}/setting-up-authentication.html[Setting Up User Authentication]. + +For more information about the command options, see <>. + +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}]. diff --git a/docs/en/security/authentication.asciidoc b/docs/en/security/authentication.asciidoc index 3674e3951e7..7acf0acd029 100644 --- a/docs/en/security/authentication.asciidoc +++ b/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 <>. -.{security} Built-in Users -|======== -| Name | Description -| `elastic` | A built-in _superuser_. See <>. -| `kibana` | The user Kibana uses to connect and communicate with Elasticsearch. -| `logstash_system` | The user Logstash uses when storing monitoring information in Elasticsearch. -|======== +`elastic`:: A built-in _superuser_. See <>. +`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 <>, +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 -[IMPORTANT] -============================================================================= +==== Setting Built-in User Passwords + 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 -setup. When it is run, it will use the `elastic` user 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. +The +setup-passwords+ tool is the simplest method to set the built-in users' +passwords for the first time. It uses the `elastic` user's bootstrap password to +run user management API requests. 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 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. +For more information about the command options, see +{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 -also be used to change the passwords manually. +You can then start {es} and {kib} and use the `elastic` user and bootstrap +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] ---------------------------------------------------------------------- -PUT _xpack/security/user/elastic/_password -{ - "password": "elasticpassword" -} ---------------------------------------------------------------------- -// CONSOLE +[float] +[[add-built-in-user-passwords]] +==== Adding Built-in User Passwords To {kib} and Logstash -[source,js] ---------------------------------------------------------------------- -PUT _xpack/security/user/kibana/_password -{ - "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: +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` +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 -be set before the user can be used. - +This setting is deprecated. The elastic user no longer has a default password. +The password must be set before the user can be used. +See <>. ============================================================================= [float] diff --git a/docs/en/security/getting-started.asciidoc b/docs/en/security/getting-started.asciidoc index 1375008b682..75d22d2e90a 100644 --- a/docs/en/security/getting-started.asciidoc +++ b/docs/en/security/getting-started.asciidoc @@ -16,23 +16,12 @@ To get started with {security}: . <>. -. On at least one of the nodes in your cluster, set the "bootstrap.password" secure setting in the keystore. -+ --- -[source,shell] --------------------------------------------------- -bin/elasticsearch-keystore create -bin/elasticsearch-keystore add "bootstrap.password" --------------------------------------------------- +. Start {es} and {kib}. --- - -. 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. - - -. 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. +. 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. +Run that command with the same user that is running your {es} process. +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 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]. --