Managing Users in an esusers Realm

The esusers command line tool is located in ES_HOME/bin/shield and enables several administrative tasks for managing users:

The esusers useradd command adds a user to your cluster.

esusers useradd <username>

A username must be at least 1 character and no longer than 30 characters. The first character must be a letter (a-z or A-Z) or an underscore (_). Subsequent characters can be letters, underscores (_), digits (0-9), or any of the following symbols @, -, . or $

You can specify the user’s password at the command line with the -p option. When this option is absent, the esusers command prompts you for the password. Omit the -p option to keep plaintext passwords out of the terminal session’s command history.

esusers useradd <username> -p <secret>

Passwords must be at least 6 characters long.

You can define a user’s roles with the -r parameter. This parameter accepts a comma-separated list of role names to associate with the user.

esusers useradd <username> -r <comma-separated list of role names>

The following example adds a new user named jacknich to the esusers realm. The password for this user is theshining, and this user is associated with the logstash and marvel roles.

esusers useradd jacknich -p theshining -r logstash,marvel

For valid role names please see Role Definitions.

The esusers list command lists the users registered in the esusers realm, as in the following example:

esusers list
rdeniro        : admin
alpacino       : power_user
jacknich       : marvel,logstash

Users are in the left-hand column and their corresponding roles are listed in the right-hand column.

The esusers list <username> command lists a specific user. Use this command to verify that a user has been successfully added to the cluster.

esusers list jacknich
jacknich       : marvel,logstash

The esusers passwd command enables you to reset a user’s password. You can specify the new password directly with the -p option. When -p option is omitted, the tool will prompt you to enter and confirm a password in interactive mode.

esusers passwd <username>

esusers passwd <username> -p <password>

The esusers roles command manages the roles associated to a particular user. The -a option adds a comma-separated list of roles to a user. The -r option removes a comma-separated list of roles from a user. You can combine adding and removing roles within the same command to change a user’s roles.

esusers roles <username> -a <commma-separate list of roles> -r <commma-separate list of roles>

The following command removes the logstash and marvel roles from user jacknich, as well as adding the user role:

esusers roles jacknich -r logstash,marvel -a user

Listing the user displays the new role assignment:

esusers list jacknich
jacknich       : user

The esusers userdel command deletes a user.

userdel <username>

The esusers tool manipulates two files, users and users_roles, in CONFIG_DIR/shield/. These two files store all user data for the esusers realm and are read by Shield on startup.

By default, Shield checks these files for changes every 5 seconds. You can change this default behavior by changing the value of the watcher.interval.high setting in the elasticsearch.yml file.

While it is possible to modify these files directly using any standard text editor, we strongly recommend using the esusers command-line tool to apply the required changes.

The users file stores all the users and their passwords. Each line in the users file represents a single user entry consisting of the username and hashed password.

rdeniro:$2a$10$BBJ/ILiyJ1eBTYoRKxkqbuDEdYECplvxnqQ47uiowE7yGqvCEgj9W
alpacino:$2a$10$cNwHnElYiMYZ/T3K4PvzGeJ1KbpXZp2PfoQD.gfaVdImnHOwIuBKS
jacknich:$2a$10$GYUNWyABV/Ols/.bcwxuBuuaQzV6WIauW6RdboojxcixBq3LtI3ni

The users_roles file stores the roles associated with the users, as in the following example:

admin:rdeniro
power_user:alpacino,jacknich
user:jacknich

Each row maps a role to a comma-separated list of all the users that are associated with that role.