[DOCS] Create reference for users command (elastic/x-pack-elasticsearch#2480)

Original commit: elastic/x-pack-elasticsearch@d0afe8a20d

docs/en/commands/index.asciidoc

@@ -0,0 +1,16 @@
+[role="xpack"]
+[[xpack-commands]]
+= {xpack} Commands
+
+[partintro]
+--
+
+{xpack} includes commands that help you configure security:
+
+//* <<certgen>>
+//* <<setup-passwords>>
+* <<users-command>>
+
+--
+
+include::users-command.asciidoc[]

docs/en/commands/users-command.asciidoc

@@ -0,0 +1,138 @@
+[role="xpack"]
+[[users-command]]
+== Users Command
+++++
+<titleabbrev>users</titleabbrev>
+++++
+
+If you use file-based user authentication, the `users` command enables you to
+add and remove users, assign user roles, and manage passwords.
+
+[float]
+=== Synopsis
+
+[source,shell]
+--------------------------------------------------
+bin/x-pack/users
+([useradd <username>] [-p <password>] [-r <roles>]) |
+([list] <username>) |
+([passwd <username>] [-p <password>]) |
+([roles <username>] [-a <roles>] [-r <roles>]) |
+([userdel <username>])
+--------------------------------------------------
+
+[float]
+=== 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
+https://en.wikipedia.org/wiki/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 {xpack-ref}/file-realm.html[File-based User Authentication].
+
+[float]
+=== 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.
+
+[float]
+=== Authorization
+
+To ensure that {es} can read the user and role information at startup, run
+`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.
+
+[float]
+=== 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/x-pack/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/x-pack/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/x-pack/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/x-pack/users roles jacknich -r network,monitoring -a user
+------------------------------------------------------------
+
+The following example deletes the `jacknich` user:
+
+[source,shell]
+--------------------------------------------------
+bin/x-pack/users userdel jacknich
+--------------------------------------------------

docs/en/index.asciidoc

@@ -20,5 +20,8 @@ include::{es-repo-dir}/reference/index-shared2.asciidoc[]
 :edit_url!:
 include::rest-api/index.asciidoc[]
 
+:edit_url!:
+include::commands/index.asciidoc[]
+
 :edit_url:
 include::{es-repo-dir}/reference/index-shared3.asciidoc[]