Skip to content

Commit 6af6cc8

Browse files
lcawllcawl
committed
[DOCS] Revert removal of configuration file
1 parent 1583e87 commit 6af6cc8

File tree

2 files changed

+104
-107
lines changed

2 files changed

+104
-107
lines changed

‎x-pack/docs/en/security/authentication/configuring-file-realm.asciidoc

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
All the data about the users for the `file` realm is stored in two files on each
2+
node in the cluster: `users` and `users_roles`. Both files are located in
3+
`ES_PATH_CONF` and are read on startup.
4+
5+
[IMPORTANT]
6+
==============================
7+
The `users` and `users_roles` files are managed locally by the node and are
8+
**not** managed globally by the cluster. This means that with a typical
9+
multi-node cluster, the exact same changes need to be applied on each and every
10+
node in the cluster.
11+
12+
A safer approach would be to apply the change on one of the nodes and have the
13+
files distributed or copied to all other nodes in the cluster (either manually
14+
or using a configuration management system such as Puppet or Chef).
15+
==============================
16+
17+
The `file` realm is added to the realm chain by default. You don't need to
18+
explicitly configure a `file` realm.
19+
20+
. (Optional) Add a realm configuration to `elasticsearch.yml` under the
21+
`xpack.security.authc.realms.file` namespace. At a minimum, you must set
22+
the realm's `order` attribute.
23+
+
24+
--
25+
//See <<ref-users-settings>> for all of the options you can set for a `file` realm.
26+
27+
For example, the following snippet shows a `file` realm configuration that sets
28+
the `order` to zero so the realm is checked first:
29+
30+
[source, yaml]
31+
------------------------------------------------------------
32+
xpack:
33+
security:
34+
authc:
35+
realms:
36+
file:
37+
file1:
38+
order: 0
39+
------------------------------------------------------------
40+
--
41+
42+
. Restart {es}.
43+
44+
. Add user information to the `ES_PATH_CONF/users` file on each node in the
45+
cluster.
46+
+
47+
--
48+
The `users` file stores all the users and their passwords. Each line in the file
49+
represents a single user entry consisting of the username and **hashed** and **salted** password.
50+
51+
[source,bash]
52+
----------------------------------------------------------------------
53+
rdeniro:$2a$10$BBJ/ILiyJ1eBTYoRKxkqbuDEdYECplvxnqQ47uiowE7yGqvCEgj9W
54+
alpacino:$2a$10$cNwHnElYiMYZ/T3K4PvzGeJ1KbpXZp2PfoQD.gfaVdImnHOwIuBKS
55+
jacknich:{PBKDF2}50000$z1CLJt0MEFjkIK5iEfgvfnA6xq7lF25uasspsTKSo5Q=$XxCVLbaKDimOdyWgLCLJiyoiWpA/XDMe/xtVgn1r5Sg=
56+
----------------------------------------------------------------------
57+
58+
NOTE: To limit exposure to credential theft and mitigate credential compromise,
59+
the file realm stores passwords and caches user credentials according to
60+
security best practices. By default, a hashed version of user credentials
61+
is stored in memory, using a salted `sha-256` hash algorithm and a hashed
62+
version of passwords is stored on disk salted and hashed with the `bcrypt`
63+
hash algorithm. To use different hash algorithms, see <<hashing-settings>>.
64+
65+
While it is possible to modify the `users` files directly using any standard text
66+
editor, we strongly recommend using the <<users-command>> tool to apply the
67+
required changes.
68+
69+
IMPORTANT: As the administrator of the cluster, it is your responsibility to
70+
ensure the same users are defined on every node in the cluster.
71+
The {es} {security-features} do not deliver any mechanisms to
72+
guarantee this.
73+
74+
--
75+
76+
. Add role information to the `ES_PATH_CONF/users_roles` file on each node
77+
in the cluster.
78+
+
79+
--
80+
The `users_roles` file stores the roles associated with the users. For example:
81+
82+
[source,shell]
83+
--------------------------------------------------
84+
admin:rdeniro
85+
power_user:alpacino,jacknich
86+
user:jacknich
87+
--------------------------------------------------
88+
89+
Each row maps a role to a comma-separated list of all the users that are
90+
associated with that role.
91+
92+
You can use the <<users-command>> tool to update this file. You must ensure that
93+
the same changes are made on every node in the cluster.
94+
--
95+
96+
. (Optional) Change how often the `users` and `users_roles` files are checked.
97+
+
98+
--
99+
By default, {es} checks these files for changes every 5 seconds. You can
100+
change this default behavior by changing the `resource.reload.interval.high`
101+
setting in the `elasticsearch.yml` file (as this is a common setting in {es},
102+
changing its value may effect other schedules in the system).
103+
--

‎x-pack/docs/en/security/authentication/file-realm.asciidoc

Lines changed: 1 addition & 107 deletions
Original file line numberDiff line numberDiff line change
@@ -23,113 +23,7 @@ To define users, the {security-features} provide the
2323
<<users-command,users>> command-line tool. This tool enables you to add
2424
and remove users, assign user roles, and manage user passwords.
2525

26-
[discrete]
2726
[[file-realm-configuration]]
2827
==== Configuring a file realm
2928

30-
You can manage and authenticate users with the built-in `file` internal realm.
31-
All the data about the users for the `file` realm is stored in two files on each
32-
node in the cluster: `users` and `users_roles`. Both files are located in
33-
`ES_PATH_CONF` and are read on startup.
34-
35-
[IMPORTANT]
36-
==============================
37-
The `users` and `users_roles` files are managed locally by the node and are
38-
**not** managed globally by the cluster. This means that with a typical
39-
multi-node cluster, the exact same changes need to be applied on each and every
40-
node in the cluster.
41-
42-
A safer approach would be to apply the change on one of the nodes and have the
43-
files distributed or copied to all other nodes in the cluster (either manually
44-
or using a configuration management system such as Puppet or Chef).
45-
==============================
46-
47-
The `file` realm is added to the realm chain by default. You don't need to
48-
explicitly configure a `file` realm.
49-
50-
For more information about file realms, see <<file-realm>>.
51-
52-
. (Optional) Add a realm configuration to `elasticsearch.yml` under the
53-
`xpack.security.authc.realms.file` namespace. At a minimum, you must set
54-
the realm's `order` attribute.
55-
+
56-
--
57-
//See <<ref-users-settings>> for all of the options you can set for a `file` realm.
58-
59-
For example, the following snippet shows a `file` realm configuration that sets
60-
the `order` to zero so the realm is checked first:
61-
62-
[source, yaml]
63-
------------------------------------------------------------
64-
xpack:
65-
security:
66-
authc:
67-
realms:
68-
file:
69-
file1:
70-
order: 0
71-
------------------------------------------------------------
72-
--
73-
74-
. Restart {es}.
75-
76-
. Add user information to the `ES_PATH_CONF/users` file on each node in the
77-
cluster.
78-
+
79-
--
80-
The `users` file stores all the users and their passwords. Each line in the file
81-
represents a single user entry consisting of the username and **hashed** and **salted** password.
82-
83-
[source,bash]
84-
----------------------------------------------------------------------
85-
rdeniro:$2a$10$BBJ/ILiyJ1eBTYoRKxkqbuDEdYECplvxnqQ47uiowE7yGqvCEgj9W
86-
alpacino:$2a$10$cNwHnElYiMYZ/T3K4PvzGeJ1KbpXZp2PfoQD.gfaVdImnHOwIuBKS
87-
jacknich:{PBKDF2}50000$z1CLJt0MEFjkIK5iEfgvfnA6xq7lF25uasspsTKSo5Q=$XxCVLbaKDimOdyWgLCLJiyoiWpA/XDMe/xtVgn1r5Sg=
88-
----------------------------------------------------------------------
89-
90-
NOTE: To limit exposure to credential theft and mitigate credential compromise,
91-
the file realm stores passwords and caches user credentials according to
92-
security best practices. By default, a hashed version of user credentials
93-
is stored in memory, using a salted `sha-256` hash algorithm and a hashed
94-
version of passwords is stored on disk salted and hashed with the `bcrypt`
95-
hash algorithm. To use different hash algorithms, see <<hashing-settings>>.
96-
97-
While it is possible to modify the `users` files directly using any standard text
98-
editor, we strongly recommend using the <<users-command>> tool to apply the
99-
required changes.
100-
101-
IMPORTANT: As the administrator of the cluster, it is your responsibility to
102-
ensure the same users are defined on every node in the cluster.
103-
The {es} {security-features} do not deliver any mechanisms to
104-
guarantee this.
105-
106-
--
107-
108-
. Add role information to the `ES_PATH_CONF/users_roles` file on each node
109-
in the cluster.
110-
+
111-
--
112-
The `users_roles` file stores the roles associated with the users. For example:
113-
114-
[source,shell]
115-
--------------------------------------------------
116-
admin:rdeniro
117-
power_user:alpacino,jacknich
118-
user:jacknich
119-
--------------------------------------------------
120-
121-
Each row maps a role to a comma-separated list of all the users that are
122-
associated with that role.
123-
124-
You can use the <<users-command>> tool to update this file. You must ensure that
125-
the same changes are made on every node in the cluster.
126-
--
127-
128-
. (Optional) Change how often the `users` and `users_roles` files are checked.
129-
+
130-
--
131-
By default, {es} checks these files for changes every 5 seconds. You can
132-
change this default behavior by changing the `resource.reload.interval.high`
133-
setting in the `elasticsearch.yml` file (as this is a common setting in {es},
134-
changing its value may effect other schedules in the system).
135-
--
29+
include::configuring-file-realm.asciidoc[]

0 commit comments

Comments
 (0)