[role="xpack"]
[[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. The {stack}
{security-features} do not deliver any mechanism to guarantee this. You should
also be aware that you cannot add or manage users in the `file` realm via the
<<security-user-apis, user APIs>> and you cannot add or manage them in {kib} on the
*Management / Security / Users* page

The `file` realm is very useful as a fallback or recovery realm. For example in cases where
the cluster is unresponsive or the security index is unavailable, or when you forget the
password for your administrative users.
In this type of scenario, the `file` realm is a convenient 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 you must explicitly
include it in the realm chain.

To define users, the {security-features} provide 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.

[[file-realm-configuration]]
==== Configuring a file realm

include::configuring-file-realm.asciidoc[]