[role="xpack"]
[[configuring-file-realm]]
=== Configuring a file realm

You can manage and authenticate users with the built-in `file` internal realm. 
All the data about the users for the `file` realm is stored in two files on each 
node in the cluster: `users` and `users_roles`. Both files are located in 
`ES_PATH_CONF` and are read on startup.

[IMPORTANT]
==============================
The `users` and `users_roles` 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 
files distributed or copied to all other nodes in the cluster (either manually 
or using a configuration management system such as Puppet or Chef).
==============================

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

For more information about file realms, see 
{xpack-ref}/file-realm.html[File-based user authentication].

. (Optional) Add a realm configuration to `elasticsearch.yml` under the
`xpack.security.authc.realms.file` namespace. At a minimum, you must set 
the realm's `order` attribute.
+
--
//See <<ref-users-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:
        file:
          file1:
            order: 0
------------------------------------------------------------
--

. Restart {es}.

. Add user information to the `ES_PATH_CONF/users` file on each node in the 
cluster. 
+
--
The `users` file stores all the users and their passwords. Each line in the file 
represents a single user entry consisting of the username and **hashed** and **salted** password.

[source,bash]
----------------------------------------------------------------------
rdeniro:$2a$10$BBJ/ILiyJ1eBTYoRKxkqbuDEdYECplvxnqQ47uiowE7yGqvCEgj9W
alpacino:$2a$10$cNwHnElYiMYZ/T3K4PvzGeJ1KbpXZp2PfoQD.gfaVdImnHOwIuBKS
jacknich:{PBKDF2}50000$z1CLJt0MEFjkIK5iEfgvfnA6xq7lF25uasspsTKSo5Q=$XxCVLbaKDimOdyWgLCLJiyoiWpA/XDMe/xtVgn1r5Sg=
----------------------------------------------------------------------

NOTE: To limit exposure to credential theft and mitigate credential compromise,
the file realm stores passwords and caches user credentials according to
security best practices. By default, a hashed version of user credentials
is stored in memory, using a salted `sha-256` hash algorithm and a hashed
version of passwords is stored on disk salted and hashed with the `bcrypt`
hash algorithm. To use different hash algorithms, see <<hashing-settings>>.

While it is possible to modify the `users` files directly using any standard text
editor, we strongly recommend using the <<users-command>> tool to apply the 
required changes.

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 {es} {security-features} do not deliver any mechanisms to
            guarantee this.
            
--

. Add role information to the `ES_PATH_CONF/users_roles` file on each node 
in the cluster. 
+
--
The `users_roles` file stores the roles associated with the users. For 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.

You can use the <<users-command>> tool to update this file. You must ensure that 
the same changes are made on every node in the cluster. 
--

. (Optional) Change how often the `users` and `users_roles` files are checked. 
+
--
By default, {es} 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 {es},
changing its value may effect other schedules in the system).
--