[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]
[[users-command-parameters]]
=== 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
--------------------------------------------------