In most cases, roles should be managed through the REST APIs. However, roles defined in the
roles.yml file located in
CONFIG_DIR/shield can be used in conjunction with the
This is a YAML file where each entry defines the unique role name and the cluster and index
privileges associated with it.
roles.yml file is managed locally by the node and is 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
roles.yml distributed/copied to
all other nodes in the cluster (either manually or using a configuration management system such as Puppet or Chef).
The following example configures four roles:
Has full access (all privileges) on the cluster and full access on all indices in the cluster.
Has monitoring-only access on the cluster, enabling the user to request cluster metrics, information, and settings, without the ability to update settings. This user also has full access on all indices in the cluster.
Cannot update or monitor the cluster. Has read-only access to all indices in the cluster.
Has read-only access to all indices with the
# All cluster rights # All operations on all indices admin: cluster: - all indices: - names: '*' privileges: - all # Monitoring cluster privileges # All operations on all indices power_user: cluster: - monitor indices: - names: '*' privileges: - all # Only read operations on indices user: indices: - names: '*' privileges: - read # Only read operations on indices named events_* events_user: indices: - names: 'events_*' privileges: - read
See Privileges for the complete list of cluster and indices privileges you can assign in a role.
Deprecated in 2.3.0.
The role format previously allowed the index expression to be set as a key for a set of privileges as seen below, but this has been deprecated in favor of using the
The privileges can also directly be set on an index expression. This notation is useful if no other security features are configured.
Shorter privileges notation.
# shorter privilege notation using index name as key and privilege as value get_user: indices: 'events_index': read
Index expression key notation.
# this notation uses the index name as the key with privileges as a value within the object get_user: indices: 'events_index': privileges: read
The updated way to define these roles is:
# this notation uses collections equivalent to the above examples get_user: indices: - names: - events_index privileges: - read
An extended example that shows cluster privileges and multiple index privileges in a role:
get_user: cluster: - monitor indices: - names: - events_index privileges: - read - names: - get_user_index privileges: - monitor - index - read