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
This commit is contained in:
Lisa Cawley
GitHub
parent
b3ae022985
commit
64e2f4c93c
|
|
@ -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[]
|
||||
|
|
|
|||
|
|
@ -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"
|
||||
--------------------------------------------------
|
||||
|
|
@ -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 <<setup-passwords>>.
|
||||
|
||||
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}].
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|========
|
||||
| Name | Description
|
||||
| `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.
|
||||
|========
|
||||
`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
|
||||
[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 <<bootstrap-elastic-passwords>>.
|
||||
=============================================================================
|
||||
|
||||
[float]
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
+
|
||||
--
|
||||
[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-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].
|
||||
--
|
||||
|
|
|
|||
Loading…
Reference in New Issue