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

You can manage and authenticate users with the built-in `file` 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.

For more information, see 
{ref}/configuring-file-realm.html[Configuring a file realm].