137 lines
4.4 KiB
Plaintext
137 lines
4.4 KiB
Plaintext
[role="xpack"]
|
|
[testenv="gold+"]
|
|
[[users-command]]
|
|
== elasticsearch-users
|
|
|
|
If you use file-based user authentication, the `elasticsearch-users` command
|
|
enables you to add and remove users, assign user roles, and manage passwords.
|
|
|
|
[discrete]
|
|
=== Synopsis
|
|
|
|
[source,shell]
|
|
--------------------------------------------------
|
|
bin/elasticsearch-users
|
|
([useradd <username>] [-p <password>] [-r <roles>]) |
|
|
([list] <username>) |
|
|
([passwd <username>] [-p <password>]) |
|
|
([roles <username>] [-a <roles>] [-r <roles>]) |
|
|
([userdel <username>])
|
|
--------------------------------------------------
|
|
|
|
[discrete]
|
|
=== Description
|
|
|
|
If you use the built-in `file` internal realm, users are defined in local files
|
|
on each node in the cluster.
|
|
|
|
Usernames and roles must be at least 1 and no more than 1024 characters. They
|
|
can contain alphanumeric characters (`a-z`, `A-Z`, `0-9`), spaces, punctuation,
|
|
and printable symbols in the
|
|
{wikipedia}/Basic_Latin_(Unicode_block)[Basic Latin (ASCII) block].
|
|
Leading or trailing whitespace is not allowed.
|
|
|
|
Passwords must be at least 6 characters long.
|
|
|
|
For more information, see <<file-realm>>.
|
|
|
|
TIP: To ensure that {es} can read the user and role information at startup, run
|
|
`elasticsearch-users useradd` as the same user you use to run {es}. Running the
|
|
command as root or some other user updates the permissions for the `users` and
|
|
`users_roles` files and prevents {es} from accessing them.
|
|
|
|
[discrete]
|
|
=== Parameters
|
|
|
|
`-a <roles>`:: If used with the `roles` parameter, adds a comma-separated list
|
|
of roles to a user.
|
|
|
|
//`-h, --help`:: Returns all of the command parameters.
|
|
|
|
`list`:: List the users that are registered with the `file` realm
|
|
on the local node. If you also specify a user name, the command provides
|
|
information for that user.
|
|
|
|
`-p <password>`:: Specifies the user's password. If you do not specify this
|
|
parameter, the command prompts you for the password.
|
|
+
|
|
--
|
|
TIP: Omit the `-p` option to keep
|
|
plaintext passwords out of the terminal session's command history.
|
|
|
|
--
|
|
|
|
`passwd <username>`:: Resets a user's password. You can specify the new
|
|
password directly with the `-p` parameter.
|
|
|
|
`-r <roles>`::
|
|
* If used with the `useradd` parameter, defines a user's roles. This option
|
|
accepts a comma-separated list of role names to assign to the user.
|
|
* If used with the `roles` parameter, removes a comma-separated list of roles
|
|
from a user.
|
|
|
|
`roles`:: Manages the roles of a particular user. You can combine adding and
|
|
removing roles within the same command to change a user's roles.
|
|
|
|
//`-s, --silent`:: Shows minimal output.
|
|
|
|
`useradd <username>`:: Adds a user to your local node.
|
|
|
|
`userdel <username>`:: Deletes a user from your local node.
|
|
|
|
//`-v, --verbose`:: Shows verbose output.
|
|
|
|
//[discrete]
|
|
//=== Authorization
|
|
|
|
[discrete]
|
|
=== Examples
|
|
|
|
The following example adds a new user named `jacknich` to the `file` realm. The
|
|
password for this user is `theshining`, and this user is associated with the
|
|
`network` and `monitoring` roles.
|
|
|
|
[source,shell]
|
|
-------------------------------------------------------------------
|
|
bin/elasticsearch-users useradd jacknich -p theshining -r network,monitoring
|
|
-------------------------------------------------------------------
|
|
|
|
The following example lists the users that are registered with the `file` realm
|
|
on the local node:
|
|
|
|
[source, shell]
|
|
----------------------------------
|
|
bin/elasticsearch-users list
|
|
rdeniro : admin
|
|
alpacino : power_user
|
|
jacknich : monitoring,network
|
|
----------------------------------
|
|
|
|
Users are in the left-hand column and their corresponding roles are listed in
|
|
the right-hand column.
|
|
|
|
The following example resets the `jacknich` user's password:
|
|
|
|
[source,shell]
|
|
--------------------------------------------------
|
|
bin/elasticsearch-users passwd jachnich
|
|
--------------------------------------------------
|
|
|
|
Since the `-p` parameter was omitted, the command prompts you to enter and
|
|
confirm a password in interactive mode.
|
|
|
|
The following example removes the `network` and `monitoring` roles from the
|
|
`jacknich` user and adds the `user` role:
|
|
|
|
[source,shell]
|
|
------------------------------------------------------------
|
|
bin/elasticsearch-users roles jacknich -r network,monitoring -a user
|
|
------------------------------------------------------------
|
|
|
|
The following example deletes the `jacknich` user:
|
|
|
|
[source,shell]
|
|
--------------------------------------------------
|
|
bin/elasticsearch-users userdel jacknich
|
|
--------------------------------------------------
|