[[file-realm]]
=== File-based User Authentication

You can manage and authenticate users with the built-in `file` internal realm.
With the `file` realm users are defined in local files on each node in the cluster.

IMPORTANT:  As the administrator of the cluster, it is your responsibility to
            ensure the same users are defined on every node in the cluster.
            {security} does not deliver any mechanism to guarantee this.

The `file` realm is primarily supported to serve as a fallback/recovery realm. It
is mostly useful in situations where all users locked themselves out of the system
(no one remembers their username/password). In this type of scenarios, the `file`
realm is your only way out - you can define a new `admin` user in the `file` realm
and use it to log in and reset the credentials of all other users.

IMPORTANT: When you configure realms in `elasticsearch.yml`, only the
realms you specify are used for authentication. To use the
`file` realm as a fallback, you must include it in the realm chain.

To define users, {security} provides the {ref}/users-command.html[users]
command-line tool. This tool enables you to add and remove users, assign user
roles and manage user passwords.

==== Configuring a File Realm

The `file` realm is added to the realm chain by default. You don't need to
explicitly configure a `file` realm to manage users with the `users` tool.

Like other realms, you can configure options for a `file` realm in the
`xpack.security.authc.realms` namespace in `elasticsearch.yml`.

To configure an `file` realm:

. Add a realm configuration of type `file` to `elasticsearch.yml` under the
`xpack.security.authc.realms` namespace. At a minimum, you must set the realm `type` to
`file`. If you are configuring multiple realms, you should also explicitly set
the `order` attribute. See <<file-realm-settings>> for all of the options you can set
for a `file` realm.
+
For example, the following snippet shows a `file` realm configuration that sets
the `order` to zero so the realm is checked first:
+
[source, yaml]
------------------------------------------------------------
xpack:
  security:
    authc:
      realms:
        file1:
          type: file
          order: 0
------------------------------------------------------------

. Restart Elasticsearch.

[[file-realm-settings]]
===== File Realm Settings

See {ref}/security-settings.html#ref-users-settings[File Realm Settings].

==== A Look Under the Hood

All the data about the users for the `file` realm is stored in two files, `users`
and `users_roles`. Both files are located in `CONFIG_DIR/x-pack/` and are read
on startup.

By default, {security} checks these files for changes every 5 seconds. You can
change this default behavior by changing the `resource.reload.interval.high` setting in
the `elasticsearch.yml` file (as this is a common setting in Elasticsearch,
changing its value may effect other schedules in the system).

[IMPORTANT]
==============================
These files are managed locally by the node and are **not** managed
globally by the cluster. This means that with a typical multi-node cluster,
the exact same changes need to be applied on each and every node in the
cluster.

A safer approach would be to apply the change on one of the nodes and have the
`users` and `users_roles` files distributed/copied to all other nodes in the
cluster (either manually or using a configuration management system such as
Puppet or Chef).
==============================

While it is possible to modify these files directly using any standard text
editor, we strongly recommend using the {ref}/users-command.html[`bin/elasticsearch-users`]
command-line tool to apply the required changes.

[float]
[[users-file]]
===== The `users` File
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.

[source,bash]
----------------------------------------------------------------------
rdeniro:$2a$10$BBJ/ILiyJ1eBTYoRKxkqbuDEdYECplvxnqQ47uiowE7yGqvCEgj9W
alpacino:$2a$10$cNwHnElYiMYZ/T3K4PvzGeJ1KbpXZp2PfoQD.gfaVdImnHOwIuBKS
jacknich:$2a$10$GYUNWyABV/Ols/.bcwxuBuuaQzV6WIauW6RdboojxcixBq3LtI3ni
----------------------------------------------------------------------

NOTE: {security} uses `bcrypt` to hash the user passwords.

[float]
[[users_defining-roles]]
==== The `users_roles` File

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

[source,shell]
--------------------------------------------------
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.