honeymoose
/
OpenSearch
mirror of https://github.com/honeymoose/OpenSearch.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Docs: Reorganized Shield TOC, renamed files, cleaned up hierarchy. 

Original commit: elastic/x-pack-elasticsearch@15caf307c4
This commit is contained in:
debadair 2015-07-15 10:02:11 -07:00
parent 15e2798638
commit dce7c48f67
46 changed files with 1044 additions and 1208 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

25
shield/docs/public/00-index.asciidoc
View File

@ -1,25 +0,0 @@
[[shield]]
= Shield - Elasticsearch Security Plugin
:ref: http://www.elastic.co/guide/en/elasticsearch/reference/current
include::01-introduction.asciidoc[]
include::02-architecture.asciidoc[]
include::03-quick-getting-started.asciidoc[]
include::04-getting-started.asciidoc[]
include::05-authorization.asciidoc[]
include::06-authentication.asciidoc[]
include::07-securing-nodes.asciidoc[]
include::08-auditing.asciidoc[]
include::09-clients.asciidoc[]
include::10-appendices.asciidoc[]

75
shield/docs/public/03-quick-getting-started.asciidoc
View File

@ -1,75 +0,0 @@
[[quick-getting-started]]
== Getting Started (Short Version)
The following tutorial will get you up and running with Shield in 2 minutes.
[float]
=== Assumptions
* You have Java(TM) 7 or above installed.
* You have downloaded elasticsearch 1.5.0+ and extracted it (from now on, we'll refer to the elasticsearch directory as `ES_HOME`).
If you haven't done so, you can download it https://download.elastic.co/elasticsearch/elasticsearch/elasticsearch-1.5.1.tar.gz[here].
* You are *not* using a package installation (RPM/DEB) or a custom configuration directory. If you are, please see the full <<getting-started,getting started>> guide.
[float]
=== Installation
1. `cd` to `ES_HOME`
2. Install the license plugin
+
[source,shell]
----------------------------------------------------------
bin/plugin -i elasticsearch/license/latest
----------------------------------------------------------
3. Next, install the shield plugin
+
[source,shell]
----------------------------------------------------------
bin/plugin -i elasticsearch/shield/latest
----------------------------------------------------------
4. Start Elasticsearch
+
[source,shell]
----------------------------------------------------------
bin/elasticsearch
----------------------------------------------------------
5. Add a `es_admin` user with administrative permissions
+
[source,shell]
----------------------------------------------------------
bin/shield/esusers useradd es_admin -r admin
----------------------------------------------------------
6. Try it out - without username/password, the request should be rejected:
+
[source,shell]
----------------------------------------------------------
curl -XGET 'http://localhost:9200/'
----------------------------------------------------------
7. Now try with username and password
+
[source,shell]
----------------------------------------------------------
curl -u es_admin -XGET 'http://localhost:9200/'
----------------------------------------------------------
8. Optionally, verify the Shield version
+
[source,shell]
----------------------------------------------------------
curl -u es_admin -XGET 'http://localhost:9200/_shield'
----------------------------------------------------------
[float]
=== Next Steps
* For a more in-depth look into the meaning of each step above, please proceed to the full <<getting-started,getting started>> guide.
* For better understanding of the authentication mechanisms we just used, please refer to <<esusers, esusers - internal file based authentication>>
* To learn about how to create roles and customize the permissions for users, please refer to the <<authorization, authorization>> section.
* To enable secure SSL/TLS encryption of cluster and client communication, please refer to the <<securing-nodes, securing nodes>> section.
* If you are new to Shield, we suggest following the guide's natural path and reading each section in order. To continue, <<getting-started, proceed to the next section>>

322
shield/docs/public/04-getting-started.asciidoc
View File

@ -1,322 +0,0 @@
[[getting-started]]
== Getting Started (Long Version)
Security is installed as an Elasticsearch plugin. The plugin must be installed on every node in the cluster, and every
node must be restarted after installation. Plan for a complete cluster restart before beginning the installation
process.
IMPORTANT: Shield 2.0.x is compatible with Elasticsearch 1.5.0 and above.
[float]
=== Configuring your environment
If you install Elasticsearch as a package or you specify a custom configuration directory, the command line
tools require you to specify the configuration directory. On Linux systems, add the following line to your
`.profile` file:
[source,shell]
----------------------------------------------------------
export ES_JAVA_OPTS="-Des.path.conf=/etc/elasticsearch"
----------------------------------------------------------
NOTE: When using `sudo` to run commands as a different user, the `ES_JAVA_OPTS` setting from your profile will not be
available in the other user's environment. You can manually pass the environment variables to the command or you can
make the environment variable available by adding the following line to the `/etc/sudoers` file:
[source,shell]
----------------------------------------------------------
Defaults env_keep += "ES_JAVA_OPTS"
----------------------------------------------------------
On Windows systems, the `setx` command can be used to specify a custom configuration directory:
[source,shell]
----------------------------------------------------------
setx ES_JAVA_OPTS "-Des.path.conf=C:\config"
----------------------------------------------------------
[float]
=== Shield And Licensing
Shield requires a license to operate and the licensing is managed by a separate plugin. For this reason,
the License plugin must be installed (without the license plugin Shield will prevent the node from starting up).
For instructions on how to install the License plugin, please refer to <<license-management, License Management>>.
Once you have the licensing plugin installed, you may begin working with Shield immediately. When elasticsearch starts for the
first time with Shield and the licensing plugin installed, a 30-day trial license for Shield will automatically be generated.
If you have a license for Shield that you would like to install, please refer to <<installing-license, installing a license>>.
IMPORTANT: With a valid license, Shield will be fully operational. Upon license expiry, Shield will operate in a
degraded mode, where cluster health, cluster stats, and index stats APIs will be blocked. All other operations will
continue operating normally. Additional information can be found at the <<license-expiration, Shield license expiration>>
section.
[float]
=== Installing the Shield plugin
Follow these steps on every node in the cluster:
. From the Elasticsearch home directory, run:
+
[source,sh]
------------------------------------------
bin/plugin -i elasticsearch/shield/latest
------------------------------------------
. Restart your Elasticsearch node.
+
Before restarting your cluster, consider temporarily {ref}/modules-cluster.html[disabling shard allocation].
If your server doesn't have direct Internet access, see <<manual_download,manual download>> for an alternative way to
get the Security binaries.
[[manual_download]]
[float]
==== Manual Download
Elasticsearch’s `bin/plugin` script requires direct Internet access for downloading and installing the security plugin.
If your server doesn’t have Internet access, you can download the required binaries from the following link:
[source,sh]
----------------------------------------------------
https://download.elastic.co/elasticsearch/shield/shield-2.0.0.zip
----------------------------------------------------
Transfer the compressed file to your server, then install the plugin with the `bin/plugin` script:
[source,shell]
----------------------------------------------------
bin/plugin -i shield -u file://PATH_TO_ZIP_FILE <1>
----------------------------------------------------
<1> Absolute path to Shield plugin zip distribution file (e.g. `file:///path/to/file/shield-2.0.0.zip`,
note the three slashes at the beginning)
[[install-layout]]
[float]
=== Shield Installation Layout
Shield comes with its own set of configuration files and executable tools. These include:
[horizontal]
[[shield-bin]] *Executables*::
Shield's bin directory is located at `$ES_HOME/bin/shield`. Consider adding this directory to
your `PATH` environment variable.
[[shield-config]] *Configuration*::
Shield's config directory is located at `<elasticsearch_config>/shield` (where
`<elasticsearch_config>` refers to the standard config directory of
Elasticsearch - typically at `$ES_HOME/config`).
Unless otherwise stated, Shield's settings are placed in the main
`elasticsearch.yml` configuration file.
[[message-authentication]]
[float]
=== Message Authentication
Message authentication verifies that a message has not been tampered with or corrupted in transit. To enable message
authentication, run the `syskeygen` tool without any options:
[source, shell]
----------------
bin/shield/syskeygen
----------------
This creates the system key file in Shield's <<shield-config,config>> directory, e.g. `config/shield/system_key`. You
can customize this file's location by changing the value of the `shield.system_key.file` setting in the
`elasticsearch.yml` file.
IMPORTANT: Because the system key is a symmetric key, the same key must be on every node in the cluster. Copy the key to
every node in the cluster after generating it.
[float]
=== Enabling Role-based Access Control
Now that we have Shield installed, we'll move to configuring the users (and their roles) with which we'll be able to execute
various of APIs on Elasticsearch.
[float]
==== Defining Roles
A _role_ encompasses a set of permissions over the cluster and/or the indices in it. Roles are defined in the
`$ES_HOME/config/shield/roles.yml` file.
.Example role definition
[source,yaml]
--------------------------------------------------
# All cluster rights
# All operations on all indices
admin: <1>
cluster: all
indices:
'*': all
# monitoring cluster privileges
# All operations on all indices
power_user: <2>
cluster: monitor
indices:
'*': all
# Read-only operations on indices
user: <3>
indices:
'*': read
--------------------------------------------------
<1> The `admin` role enables full access to the cluster and all its indices.
<2> The `power_user` role enables monitoring only access on the cluster and full access on all its indices.
<3> The `user` role has no cluster wide permissions and only has data read access on all its indices.
For this quick getting started guide, we won't need to change anything in the `roles.yml` file that comes out-of-the-box
with Shield, as it already defines the roles listed in the snippet above. To learn more on roles and how one can configure
them, please see <<roles, Roles>>.
[float]
==== Defining Users
Shield supports different authentication realms that authenticate users from different sources. In this example, we'll
use the internal <<esusers,`esusers`>> realm that comes with Shield. The `esusers` realm supports user management using
the `esusers` command line tool from Shield's `bin` directory.
NOTE: The `esusers` realm is enabled by default when no realms are explicitly configured in `elasticsearch.yml`. For more
information on realms configuration please see <<realms, Realms>>.
[source,shell]
--------------------------------------------------
bin/shield/esusers useradd rdeniro -p taxidriver -r admin
--------------------------------------------------
[source,shell]
--------------------------------------------------
bin/shield/esusers useradd alpacino -p godfather -r user
--------------------------------------------------
The example above adds two users:
* The `rdeniro` user with password `taxidriver`, with the `admin` role in the cluster
* The `alpacino` user with password `godfather`, with the `user` role in the cluster
NOTE: To ensure that Elasticsearch can read the user and role information at startup, run `esusers useradd` as the
same user you use to run Elasticsearch. Running the command as root or some other user will update the permissions
for the `users` and `users_roles` files and prevent Elasticsearch from accessing them.
Now that we've defined the roles and the users of the cluster, you can start the Elasticsearch node and we'll verify that
Shield plugin has been loaded.
[float]
==== Verifying Shield Installation
Once your Elasticsearch node is running, you can issue a `curl` command to verify that Shield has been loaded and is the
expected version.
[source,shell]
-------------------------------------------------------------------------------
curl --user rdeniro:taxidriver 'localhost:9200/_shield'
-------------------------------------------------------------------------------
[source,json]
-------------------------------------------------------------------------------
{
"status" : "enabled",
"name" : "Mimic",
"cluster_name" : "elasticsearch",
"version" : {
"number" : "2.0.0",
"build_hash" : "",
"build_timestamp" : "NA",
"build_snapshot" : true
},
"tagline" : "You know, for security"
}
-------------------------------------------------------------------------------
You can also check the startup logs to verify that the Shield plugin has loaded and the network transports are using Shield.
A successful installation will show lines similar to the following:
[source,shell]
----------------
[2014-10-09 13:47:38,841][INFO ][transport ] [Ezekiel Stane] Using [org.elasticsearch.shield.transport.ShieldServerTransportService] as transport service, overridden by [shield]
[2014-10-09 13:47:38,841][INFO ][transport ] [Ezekiel Stane] Using [org.elasticsearch.shield.transport.netty.ShieldNettyTransport] as transport, overridden by [shield]
[2014-10-09 13:47:38,842][INFO ][http ] [Ezekiel Stane] Using [org.elasticsearch.shield.transport.netty.ShieldNettyHttpServerTransport] as http transport, overridden by [shield]
----------------
In the next section, we'll use a simple HTTP client to interact with Elasticsearch protected by Shield.
[[clientauth]]
[float]
=== Configuring HTTP REST Clients
Elasticsearch works with standard HTTP http://en.wikipedia.org/wiki/Basic_access_authentication[basic authentication]
headers to identify the requester. Since Elasticsearch is stateless, this header must be sent with every request:
[source,shell]
--------------------------------------------------
Authorization: Basic <TOKEN> <1>
--------------------------------------------------
<1> The `<TOKEN>` is computed as `base64(USERNAME:PASSWORD)`
[float]
==== Client examples
Using `curl` without basic authentication to create an index has the following result:
[source,shell]
-------------------------------------------------------------------------------
curl -XPUT 'localhost:9200/idx'
-------------------------------------------------------------------------------
[source,json]
-------------------------------------------------------------------------------
{
"error": "AuthenticationException[Missing authentication token]",
"status": 401
}
-------------------------------------------------------------------------------
Since no user is associated with the request above, the request returns an authentication error. Next, use `curl`
with basic auth to create an index as the `rdeniro` user:
[source,shell]
---------------------------------------------------------
curl --user rdeniro:taxidriver -XPUT 'localhost:9200/idx'
---------------------------------------------------------
[source,json]
---------------------------------------------------------
{
"acknowledged": true
}
---------------------------------------------------------
Since the request is executed on behalf of administrative user `rdeniro`, the create index request authenticates and
authorizes successfully, resulting in normal execution of the request. Creating another index as the `alpacino` user
results in the following error:
[source,shell]
------------------------------------------------------------------------------------------------------------------
curl --user alpacino:godfather -XPUT 'localhost:9200/idx2'
------------------------------------------------------------------------------------------------------------------
[source,json]
------------------------------------------------------------------------------------------------------------------
{
"error": "AuthorizationException[Action [indices:admin/create] is unauthorized for user [alpacino]]",
"status": 403
}
------------------------------------------------------------------------------------------------------------------
As user `alpacino` does not have any index administration rights, the request is rejected with an authorization error.
[float]
=== Next Steps
Now you have a working cluster with authentication and access control enabled.
In the <<authorization, _Authorization_>> section, we explain how to manage users and their roles. The
<<authentication, _Authentication_>> section explains how to use Shield's authentication realms and LDAP integration. The
<<securing-nodes, _Securing Nodes_>> section discusses enabling SSL/TLS encryption for nodes and clients.

17
shield/docs/public/09-clients.asciidoc
View File

@ -1,17 +0,0 @@
[[clients]]
== Integrating Shield with clients
You will need to update the configuration for several clients to work with the Shield security plugin. The jump list in
the right side bar lists the configuration information for the clients that support Shield.
include::clients/java.asciidoc[]
include::clients/http.asciidoc[]
include::clients/logstash.asciidoc[]
include::clients/marvel.asciidoc[]
include::clients/kibana.asciidoc[]
include::clients/hadoop.asciidoc[]

17
shield/docs/public/10-appendices.asciidoc
View File

@ -1,17 +0,0 @@
include::appendices/01-certificate-authority.asciidoc[]
include::appendices/02-license-management.asciidoc[]
include::appendices/03-limitations.asciidoc[]
include::appendices/04-securing-aliases.asciidoc[]
include::appendices/05-tribe-node.asciidoc[]
include::appendices/06-example.asciidoc[]
include::appendices/07-trouble-shooting.asciidoc[]
include::appendices/08-reference.asciidoc[]
include::appendices/09-release-notes.asciidoc[]

110
shield/docs/public/appendices/05-tribe-node.asciidoc
View File

@ -1,110 +0,0 @@
[[tribe-node]]
== Appendix 5. Tribe Node
Shield supports the {ref}/modules-tribe.html[Tribe Node], which acts as a federated client across multiple clusters.
When using Tribe Node with Shield, you must have the same Shield configurations (users, roles, user-role mappings, SSL/TLS CA)
on each cluster, and on the Tribe Node itself, where security checking is primarily done. This, of course, also means
that all clusters must be running Shield. The following are the current limitations to keep in mind when using the
Tribe Node in combination with Shield.
[float]
=== Same privileges on all connected clusters
The Tribe Node has its own configuration and privileges, which need to grant access to actions and indices on all of the
connected clusters. Also, each cluster needs to grant access to indices belonging to other connected clusters as well.
Let's look at an example: assuming we have two clusters, `cluster1` and `cluster2`, each one holding an index, `index1`
and `index2`. A search request that targets multiple clusters, as follows
[source,shell]
-----------------------------------------------------------
curl -XGET tribe_node:9200/index1,index2/_search -u tribe_user:tribe_user
-----------------------------------------------------------
requires `search` privileges for both `index1` and `index2` on the Tribe Node:
[source,yaml]
-----------------------------------------------------------
tribe_user:
indices:
'index*': search
-----------------------------------------------------------
Also, the same privileges need to be granted on the connected clusters, meaning that `cluster1` has to grant access to
`index2` even though `index2` only exists on `cluster2`; the same requirement applies for `index1` on `cluster2`. This
applies to any indices action. As for cluster state read operations (e.g. cluster state api, get mapping api etc.),
they always get executed locally on the Tribe Node, to make sure that the merged cluster state gets returned; their
privileges are then required on the Tribe Node only.
[float]
=== Same system key on all clusters
In order for <<message-authentication,message authentication>> to properly work across multiple clusters, the Tribe Node
and all of the connected clusters need to share the same system key.
[float]
=== Encrypted communication
Encrypted communication via SSL can only be enabled globally, meaning that either all of the connected clusters and the
Tribe Node have SSL enabled, or none of them have.
[float]
=== Same certification authority on all clusters
When using encrypted communication, for simplicity, we recommend all of the connected clusters and the Tribe Node use
the same certification authority to generate their certificates.
[float]
=== Example
Let's see a complete example on how to use the Tribe Node with shield and the configuration required. First of all the
Shield and License plugins need to be installed and enabled on all clusters and on the Tribe Node.
The system key needs to be generated on one node, as described in the <<message-authentication, Getting Started section>>,
and then copied over to all of the other nodes in each cluster and the Tribe Node itself.
Each cluster can have its own users with `admin` privileges that don't need to be present in the Tribe Node too. In fact,
administration tasks (e.g. create index) cannot be performed through the Tribe Node but need to be sent directly to the
corresponding cluster. The users that need to be created on Tribe Node are those that allow to get back data merged from
the different clusters through the Tribe Node itself. Let's for instance create as follows a `tribe_user` user, with
role `user`, that has `read` privileges on any index.
[source,shell]
-----------------------------------------------------------
./bin/shield/esusers useradd tribe_user -p tribe_user -r user
-----------------------------------------------------------
The above command needs to be executed on each cluster, since the same user needs to be present on the Tribe Node as well
as on every connected cluster.
The following is the configuration required on the Tribe Node, that needs to be added to `elasticsearch.yml`.
Elasticsearch allows to list specific settings per cluster. We disable multicast discovery as described in the
<<disable-multicast, Disable Multicast section>> and configure the proper unicast discovery hosts for each cluster,
as well as their cluster names:
[source,yaml]
-----------------------------------------------------------
tribe:
t1:
cluster.name: tribe1
discovery.zen.ping.multicast.enabled: false
discovery.zen.ping.unicast.hosts: ["tribe1:9300"]
t2:
cluster.name: tribe2
discovery.zen.ping.multicast.enabled: false
discovery.zen.ping.unicast.hosts: ["tribe2:9300"]
-----------------------------------------------------------
The Tribe Node can then be started and once initialized it will be ready to accept requests like the following search,
which will return documents coming from the different connected clusters:
[source,shell]
-----------------------------------------------------------
curl -XGET localhost:9200/_search -u tribe_user:tribe_user
-----------------------------------------------------------
As for encrypted communication, the required settings are the same as described in <<securing-nodes, Securing Nodes>>,
but need to be specified per tribe as we did for discovery settings above.

20
shield/docs/public/08-auditing.asciidoc → shield/docs/public/configuring-auditing.asciidoc
View File

@ -1,6 +1,5 @@
[[auditing]]
== Auditing
[[configuring-auditing]]
== Configuring Auditing
[IMPORTANT]
====
@ -13,12 +12,12 @@ shield.audit.enabled: true
----------------------------
====
The audit functionality was added to keep track of important events occurring in elasticsearch, primarily around security
The audit functionality was added to keep track of important events occurring in Elasticsearch, primarily around security
concerns. Keeping track and persisting these events is essential for any secured environment and potentially provides
evidence for suspicious/malicious activity on the elasticsearch cluster.
evidence for suspicious/malicious activity on the Elasticsearch cluster.
Shield provides two ways to output these events: in a dedicated `access.log` file stored on the host's file system, or
in an elasticsearch index on the same or separate cluster. These options are not mutually exclusive. For example, both
in an Elasticsearch index on the same or separate cluster. These options are not mutually exclusive. For example, both
options can be enabled through an entry in the `elasticsearch.yml` file:
[source,yaml]
@ -66,7 +65,7 @@ possible log levels:
| `WARN` | `authentication_failed`, `access_denied`, `tampered_request`, `connection_denied`, `anonymous_access_denied`
| `INFO` | `authentication_failed`, `access_denied`, `tampered_request`, `connection_denied`, `anonymous_access_denied`, `access_granted`
| `DEBUG` | (doesn't output additional entry types beyond `INFO`, but extends the information emitted for each entry (see <<audit-log-entry-format, Log Entry Format>> below)
| `TRACE` | `authentication_failed`, `access_denied`, `tampered_request`, `connection_denied`, `anonymous_access_denied`, `access_granted`, `connection_granted`, `authentication_failed [<realm>]`. In addition, internal system requests (self-management requests triggered by elasticsearch itself) will also be logged for `access_granted` entry type.
| `TRACE` | `authentication_failed`, `access_denied`, `tampered_request`, `connection_denied`, `anonymous_access_denied`, `access_granted`, `connection_granted`, `authentication_failed [<realm>]`. In addition, internal system requests (self-management requests triggered by Elasticsearch itself) will also be logged for `access_granted` entry type.
|======
@ -208,8 +207,7 @@ The following tables describe the possible attributes each entry type can carry
[float]
=== Audit Logs Settings
As mentioned above, the audit logs are configured in the `logging.yml` file located in Shield's <<shield-config, config>>
directory. The following snippet shows the default logging configuration:
As mentioned above, the audit logs are configured in the `logging.yml` file located in `ES_HOME/config/shield`. The following snippet shows the default logging configuration:
[[logging-file]]
@ -234,13 +232,13 @@ appender:
----
As can be seen above, by default audit information is appended to the `access.log` file located in the
standard elasticsearch `logs` directory (typically located at `$ES_HOME/logs`).
standard Elasticsearch `logs` directory (typically located at `$ES_HOME/logs`).
[float]
[[audit-index]]
=== Storing Audit Logs in an Elasticsearch Index
It is possible to store audit logs in an elasticsearch index. This index can be either on the same cluster, or on
It is possible to store audit logs in an Elasticsearch index. This index can be either on the same cluster, or on
a different cluster (see below). Several settings in `elasticsearch.yml` control this behavior.
.`audit log indexing configuration`

17
shield/docs/public/configuring-clients-integrations.asciidoc Normal file
View File

@ -0,0 +1,17 @@
[[configuring-clients-integrations]]
== Configuring Clients and Integrations
You will need to update the configuration for several clients to work with the Shield security plugin. The jump list in
the right side bar lists the configuration information for the clients that support Shield.
include::configuring-clients-integrations/java.asciidoc[]
include::configuring-clients-integrations/http.asciidoc[]
include::configuring-clients-integrations/hadoop.asciidoc[]
include::configuring-clients-integrations/logstash.asciidoc[]
include::configuring-clients-integrations/marvel.asciidoc[]
include::configuring-clients-integrations/kibana.asciidoc[]

2
shield/docs/public/clients/hadoop.asciidoc → shield/docs/public/configuring-clients-integrations/hadoop.asciidoc
View File

@ -1,5 +1,5 @@
[[hadoop]]
=== Shield with Elasticsearch for Apache Hadoop
=== Using Elasticsearch for Apache Hadoop with Shield
Elasticsearch for Apache Hadoop ("ES-Hadoop") is capable of using HTTP basic and PKI authentication and/or TLS/SSL when accessing an Elasticsearch cluster. For full details please refer to the ES-Hadoop documentation, in particular the `Security` section.

5
shield/docs/public/clients/http.asciidoc → shield/docs/public/configuring-clients-integrations/http.asciidoc
View File

@ -1,4 +1,4 @@
=== HTTP/REST Clients
=== Using Elasticsearch HTTP/REST Clients with Shield
Elasticsearch works with standard HTTP http://en.wikipedia.org/wiki/Basic_access_authentication[basic authentication]
headers to identify the requester. Since Elasticsearch is stateless, this header must be sent with every request:
@ -9,6 +9,7 @@ Authorization: Basic <TOKEN> <1>
--------------------------------------------------
<1> The `<TOKEN>` is computed as `base64(USERNAME:PASSWORD)`
[float]
==== Client examples
This example uses `curl` without basic auth to create an index:
@ -41,7 +42,7 @@ curl --user rdeniro:taxidriver -XPUT 'localhost:9200/idx'
}
---------------------------------------------------------
[float]
==== Client Libraries over HTTP
For more information about how to use Shield with the language specific clients please refer to

39
shield/docs/public/clients/java.asciidoc → shield/docs/public/configuring-clients-integrations/java.asciidoc
View File

@ -1,4 +1,4 @@
=== Java clients
=== Using Elasticsearch Java Clients with Shield
Elasticsearch supports two types of Java clients: _Node Client_ and _Transport Client_.
@ -14,6 +14,7 @@ http://www.elastic.co/guide/en/elasticsearch/client/java-api/current/transport-c
Shield supports both clients. This section provides configuration instructions for these clients.
[float]
==== Node Client
WARNING: While _Node Clients_ may work with Shield, since these are actual nodes in the cluster, they require access
@ -30,13 +31,15 @@ There are several steps for setting up this client:
. Configure the authentication token
. (Optional) If SSL/TLS is enabled, set up the keystore, then create and import the appropriate certificates.
[float]
===== Java project dependencies
If you plan on using the Node Client, you first need to make sure the Shield jar files (`elasticsearch-shield-2.0.0.jar`,
`automaton-1.11-8.jar`, `unboundid-ldapsdk-2.3.8.jar`) and the License jar file (`elasticsearch-license-2.0.0.jar`) are
If you plan on using the Node Client, you first need to make sure the Shield jar files (`elasticsearch-shield-1.3.0.jar`,
`automaton-1.11-8.jar`, `unboundid-ldapsdk-2.3.8.jar`) and the License jar file (`elasticsearch-license-1.0.0.jar`) are
in the classpath. You can either download the distributions, extract the jar files manually and include them in your
classpath, or you can pull them out of the Elasticsearch Maven repository.
[float]
===== Maven Example
The following snippet shows the configuration you will need to include in your project's `pom.xml` file:
@ -66,13 +69,13 @@ The following snippet shows the configuration you will need to include in your p
<dependency>
<groupId>org.elasticsearch</groupId>
<artifactId>elasticsearch-shield</artifactId>
<version>2.0.0</version>
<version>1.3.0</version>
</dependency>
<!-- add the License jar as a dependency -->
<dependency>
<groupId>org.elasticsearch</groupId>
<artifactId>elasticsearch-license-plugin</artifactId>
<version>2.0.0</version>
<version>1.0.0</version>
<scope>runtime</scope>
</dependency>
...
@ -82,6 +85,7 @@ The following snippet shows the configuration you will need to include in your p
</project>
--------------------------------------------------------------
[float]
===== Gradle Example
If you are using Gradle, then you will need to add the dependencies to your `build.gradle` file:
@ -100,19 +104,20 @@ repositories {
dependencies {
// Provide the Shield jar on the classpath for compilation and at runtime
// Note: Many projects can use the Shield jar as a runtime dependency
compile "org.elasticsearch:elasticsearch-shield:2.0.0"
compile "org.elasticsearch:elasticsearch-shield:1.3.0"
/* ... */
// Provide the License jar on the classpath at runtime (not needed for compilation)
runtime "org.elasticsearch:elasticsearch-license-plugin:2.0.0"
runtime "org.elasticsearch:elasticsearch-license-plugin:1.0.0"
}
--------------------------------------------------------------
It is also possible to manually download the http://maven.elasticsearch.org/releases/org/elasticsearch/elasticsearch-shield/2.0.0/elasticsearch-shield-2.0.0.jar[Shield jar]
and the http://maven.elasticsearch.org/releases/org/elasticsearch/elasticsearch-license-plugin/1.0.0/elasticsearch-license-plugin-2.0.0.jar[License jar]
It is also possible to manually download the http://maven.elasticsearch.org/releases/org/elasticsearch/elasticsearch-shield/1.3.0/elasticsearch-shield-1.3.0.jar[Shield jar]
and the http://maven.elasticsearch.org/releases/org/elasticsearch/elasticsearch-license-plugin/1.0.0/elasticsearch-license-plugin-1.0.0.jar[License jar]
files from our Maven repository.
[float]
===== Duplicate Shield Configuration Files
The _Node Client_ will authenticate requests before sending the requests to the cluster. To do this, copy the `users`,
@ -145,6 +150,7 @@ Node node = nodeBuilder().client(true).settings(ImmutableSettings.builder()
Additionally, if you are using LDAP or Active Directory authentication then you will need to specify that configuration
in the settings when configuring the node or provide a `elasticsearch.yml` in the classpath with the appropriate settings.
[float]
===== Configuring Authentication Token
The authentication token can be configured in two ways - globally or per-request. When setting it up globally, the
@ -188,6 +194,7 @@ client.prepareSearch().putHeader("Authorization", token).get();
The example above executes a search request and manually adds the authentication token as a header on it.
[float]
===== Setting up SSL
Authenticating to the cluster requires proof that a node client is trusted as part of the cluster. This is done through
@ -222,16 +229,18 @@ Node node = nodeBuilder().client(true).settings(ImmutableSettings.builder()
.node();
------------------------------------------------------------------------------------------------------
[float]
[[transport-client]]
==== Transport Client
If you plan on using the Transport Client over SSL/TLS you first need to make sure the Shield jar file
(`elasticsearch-shield-2.0.0.jar`) is in the classpath. You can either download the Shield distribution, extract the jar
(`elasticsearch-shield-2.0.jar`) is in the classpath. You can either download the Shield distribution, extract the jar
files manually and include them in your classpath, or you can pull them out of the Elasticsearch Maven repository.
NOTE: Unlike the _Node Client_, the _Transport Client_ is not acting as a node in the cluster, and therefore
**does not** require the License plugin to be installed.
[float]
===== Maven Example
The following snippet shows the configuration you will need to include in your project's `pom.xml` file:
@ -261,7 +270,7 @@ The following snippet shows the configuration you will need to include in your p
<dependency>
<groupId>org.elasticsearch</groupId>
<artifactId>elasticsearch-shield</artifactId>
<version>2.0.0</version>
<version>1.3.0</version>
</dependency>
...
</dependencies>
@ -270,6 +279,7 @@ The following snippet shows the configuration you will need to include in your p
</project>
--------------------------------------------------------------
[float]
===== Gradle Example
If you are using Gradle, then you will need to add the dependencies to your `build.gradle` file:
@ -288,13 +298,13 @@ repositories {
dependencies {
// Provide the Shield jar on the classpath for compilation and at runtime
// Note: Many projects can use the Shield jar as a runtime dependency
compile "org.elasticsearch:elasticsearch-shield:2.0.0"
compile "org.elasticsearch:elasticsearch-shield:1.3.0"
/* ... */
}
--------------------------------------------------------------
It is also possible to manually download the http://maven.elasticsearch.org/releases/org/elasticsearch/elasticsearch-shield/2.0.0/elasticsearch-shield-2.0.0.jar[Shield jar]
It is also possible to manually download the http://maven.elasticsearch.org/releases/org/elasticsearch/elasticsearch-shield/1.3.0/elasticsearch-shield-1.3.0.jar[Shield jar]
file from our Maven repository.
TIP: Even if you are not planning on using the client over SSL/TLS, it is still worth having the Shield jar file in
@ -398,6 +408,7 @@ TransportClient client = new TransportClient(ImmutableSettings.builder()
client.prepareSearch().putHeader("Authorization", token).get();
------------------------------------------------------------------------------------------------------
[float]
===== Anonymous Access
added[1.1.0]
@ -408,8 +419,8 @@ set, as shown above). For this to work, please make sure the anonymous user is c
the same privileges as described <<java-transport-client-role,above>>.
[float]
[[shield-client]]
==== Shield Client
Shield exposes its own API to the user which is accessible by the `ShieldClient` class. The purpose of this API

78
shield/docs/public/clients/kibana.asciidoc → shield/docs/public/configuring-clients-integrations/kibana.asciidoc
View File

@ -1,32 +1,36 @@
[[kibana]]
=== Kibana
=== Using Kibana with Shield
Shield supports both Kibana 3 and Kibana 4.0+ releases. The configuration required differs
between Kibana 3 and 4. Please follow the instructions below for the version of Kibana you are working with.
=== Shield with Kibana 3
[float]
==== Using Kibana 3 with Shield
Shield and Kibana 3 have been tested together for recent versions of Chrome, Safari, and IE. This section describes
configuration changes and general information to ensure that the two products work together successfully for you.
Kibana 3 uses the `kibana-int` index to store saved dashboards. All users store dashboards in this index. Enable all
users to save and load dashboards from this index. When the Shield plugin is installed, users may be able to load
Kibana 3 uses the `kibana-int` index to store saved dashboards. All users store dashboards in this index. Enable all
users to save and load dashboards from this index. When the Shield plugin is installed, users may be able to load
dashboards that access data in indices that they are not authorized to view. A user that loads such a dashboard
will receive a Kibana error stating that the disallowed index does not exist.
At the moment, there is no way to control which users can load which dashboards. We expect to address this
At the moment, there is no way to control which users can load which dashboards. We expect to address this
limitation with future versions of Shield and Kibana.
==== Kibana configuration
Kibana will need to be informed that you wish use credentials. In Kibana's `config.js` set the elasticsearch property:
[float]
===== Configuring Kibana 3
Kibana will need to be informed that you wish use credentials. In Kibana's `config.js` set the `elasticsearch` property:
[source,yaml]
------------------------------------
elasticsearch: {server: "http://YOUR_ELASTICSEARCH_SERVER:9200", withCredentials: true}
------------------------------------
[float]
[[cors]]
==== Elasticsearch configuration
===== Enabling CORS in Elasticsearch
HTTP authentication interacts with cross-origin resource sharing (CORS). Clusters that use CORS must send authentication
headers to the browser.
@ -46,9 +50,10 @@ protocol, hostname and port that would normally be entered into your browser.
Restart the nodes after modifying the configuration file. This change enables Elasticsearch to send the required
`Access-Control-Allow-Credentials` header.
NOTE: To learn more about enabling CORS, see http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/modules-http.html[elasticsearch documentation].
NOTE: To learn more about enabling CORS, see http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/modules-http.html[Elasticsearch Reference].
==== Shield configuration
[float]
===== Configuring Shield for Kibana 3
Shield includes a default <<roles,role>> for use with Kibana 3:
@ -58,14 +63,14 @@ kibana3:
cluster: cluster:monitor/nodes/info
indices:
'*': indices:data/read/search, indices:data/read/get, indices:admin/get <1>
'kibana-int': indices:data/read/get, indices:data/read/search, indices:data/write/delete, indices:data/write/index,
create_index
'kibana-int': indices:data/read/get, indices:data/read/search, indices:data/write/delete, indices:data/write/index,
create_index
------------------------------------------------------------------------------------------------------------------------
<1> This line gives the Kibana 3 user read access to indices in order to search and display the data in them. To
constrain this role's access to specific indices, alter the wildcard.
Kibana 3 uses the `kibana-int` index to save and load dashboards. This role definition allows the user to manage and
Kibana 3 uses the `kibana-int` index to save and load dashboards. This role definition allows the user to manage and
use the dashboards in the `kibana-int` index.
Kibana 3 uses the cluster permission to access the `/_nodes` endpoint in order to check the node version.
@ -76,7 +81,15 @@ indices specified by your organization's goals and policies.
==== SSL/TLS and browsers
===== Trusting certificates
As discussed in <<securing-nodes, Securing Nodes>>, Shield supports adding SSL to the Elasticsearch HTTP interface.
As discussed in <<securing-communications, Securing Communications>>, Shield supports adding SSL to the Elasticsearch HTTP interface.
When using Kibana, your browser verifies that the certificate received from the Elasticsearch node is trusted
before sending a request to the node. Establishing this trust requires that either your browser or operating
system trust the Certificate Authority (CA) that signed the node's certificate. To use SSL with Shield and
Kibana 3, ensure that the browser or operating system has been configured to trust this CA.
[float]
===== Configuring Your Browser to Use SSL
As discussed in <<securing-communications, Securing Communications with Encryption and IP Filtering>>, Shield supports adding SSL to the Elasticsearch HTTP interface.
When using Kibana, your browser verifies that the certificate received from the Elasticsearch node is trusted
before sending a request to the node. Establishing this trust requires that either your browser or operating
system trust the Certificate Authority (CA) that signed the node's certificate. To use SSL with Shield and
@ -84,38 +97,41 @@ Kibana 3, ensure that the browser or operating system has been configured to tru
The process to ensure this trust varies per organization. Some organizations will have pre-installed these CA
certificates into the operating system or the browser's local certificate store. If this is the case, you will
not need to take any further action.
not need to take any further action.
Other organizations will not have pre-installed the CA certificate. Or you may have created your own CA as discussed
in <<certificate-authority, Appendix 1>>. In these cases, we recommend that you consult your local IT professional to
in <<certificate-authority, Setting Up a Certificate Authority>>. In these cases, we recommend that you consult your local IT professional to
determine the recommended procedure for adding trusted CAs in your organization.
[float]
===== Working with source builds of Kibana 3
Some developers use Kibana 3 by pulling the software from our GitHub repository, and not using a built package
Some developers use Kibana 3 by pulling the software from our GitHub repository, and not using a built package
from our download site. If you do this, be sure to clear your browser's cache after deploying Shield and
configuring the `http.cors.allow-credentials` parameter to avoid authentication errors with most browsers.
=== Shield with Kibana 4
[float]
==== Using Kibana 4 with Shield
Kibana 4 adds a server-side component that changes the integration with Shield and the steps required to configure Shield, Elasticsearch, and Kibana to work together. With Kibana 4, the browser makes requests to the Kibana 4 server, and not to Elasticsearch directly. The Kibana 4 server then makes requests to Elasticsearch on behalf of the browser. We recommend using separate roles for your users who log into Kibana and for the Kibana 4 server itself.
Kibana 4 adds a server-side component that changes the integration with Shield and the steps required to configure Shield, Elasticsearch, and Kibana to work together. With Kibana 4, the browser makes requests to the Kibana 4 server, and not to Elasticsearch directly. The Kibana 4 server then makes requests to Elasticsearch on behalf of the browser. We recommend using separate roles for your users who log into Kibana and for the Kibana 4 server itself.
[float]
[[kibana4-roles]]
==== Configuring Roles for Kibana 4 Users
===== Configuring Roles for Kibana 4 Users
Kibana users need access to the indices that they will be working with and the `.kibana` index where their
saved searches, visualizations, and dashboards are stored. Shield includes a default `kibana4` role that grants
read access to all indices and full access to the `.kibana` index.
saved searches, visualizations, and dashboards are stored. Shield includes a default `kibana4` role that grants
read access to all indices and full access to the `.kibana` index.
IMPORTANT: The default Kibana 4 user role grants read access to all indices. We strongly recommend deriving
IMPORTANT: The default Kibana 4 user role grants read access to all indices. We strongly recommend deriving
custom roles for your Kibana users that limit access to specific indices according to your organization's goals and policies.
[source,yaml]
------------------------------------------------------------------------------------------------------------------------
kibana4:
cluster:
cluster:
- cluster:monitor/nodes/info
- cluster:monitor/health
- cluster:monitor/health
indices:
'*':
- indices:admin/mappings/fields/get
@ -146,15 +162,16 @@ To constrain Kibana's access to specific indices, explicitly specify the index n
* `indices:data/read/msearch`
* `indices:admin/get`
[float]
[[kibana4-server-role]]
==== Configuring a Role for the Kibana 4 Server
===== Configuring a Role for the Kibana 4 Server
The Kibana 4 server needs access to the cluster monitoring APIs and the `.kibana` index. However, the server
does not need access to user indexes. The following `kibana4_server` role shows the privileges required
does not need access to user indexes. The following `kibana4_server` role shows the privileges required
by the Kibana 4 server.
NOTE: This role is included in roles.yml by default as of Shield 1.1. If you are running an older version of Shield,
you need to add it yourself.
you need to add it yourself.
[source,yaml]
------------------------------------------------------------------------------------------------------------------------
@ -180,6 +197,7 @@ kibana4_server:
To configure the Kibana 4 server, you must assign this role to a user and add the user credentials to `kibana.yml`.
For more information, see http://www.elastic.co/guide/en/kibana/current/production.html#configuring-kibana-shield[Configuring Kibana to Work with Shield] in the Kibana 4 User Guide.
==== Configuring Kibana 4 to Use SSL
[float]
===== Configuring Kibana 4 to Use SSL
You should also configure Kibana 4 to use SSL encryption for both client requests and the requests the Kibana server sends to Elasticsearch. For more information, see http://www.elastic.co/guide/en/kibana/current/production.html#enabling-ssl[Enabling SSL] in the Kibana 4 User Guide.
You should also configure Kibana 4 to use SSL encryption for both client requests and the requests the Kibana server sends to Elasticsearch. For more information, see http://www.elastic.co/guide/en/kibana/current/production.html#enabling-ssl[Enabling SSL] in the Kibana 4 User Guide.

24
shield/docs/public/clients/logstash.asciidoc → shield/docs/public/configuring-clients-integrations/logstash.asciidoc
View File

@ -1,20 +1,16 @@
[[logstash]]
=== Shield with Logstash
=== Using Logstash with Shield
IMPORTANT: Shield 2.0.x is compatible with Logstash 1.5 and above.
IMPORTANT: Shield 1.0+ is compatible with Logstash 1.5 and above.
Logstash provides Elasticsearch https://www.elastic.co/guide/en/logstash/current/plugins-outputs-elasticsearch.html[output], https://www.elastic.co/guide/en/logstash/current/plugins-inputs-elasticsearch.html[input] and https://www.elastic.co/guide/en/logstash/current/plugins-filters-elasticsearch.html[filter] plugins
used to index and retrieve documents through HTTP, transport or client node protocols.
All plugins support authentication and encryption over HTTP, while the output plugin additionally supports these
features over the transport protocol.
Note: When using the elasticsearch output, only the `transport` and `http` protocol are supported (i.e. `node` protocol is unsupported)
For information on setting up authentication and authorization on the Elasticsearch side, check the corresponding
documentation sections: <<authorization,_Authorization_>> and <<authentication,_Authentication_>>.
To configure the certificates and other SSL related options, see <<securing-nodes,_Securing Nodes_>>.
NOTE: When using the `elasticsearch` output, only the `transport` and `http` protocol are supported (i.e. `node` protocol is unsupported)
[float]
[[ls-user]]
==== Creating a user
@ -30,7 +26,7 @@ logstash:
'logstash-*': indices:data/write/bulk, indices:data/write/delete, indices:data/write/update, indices:data/read/search, indices:data/read/scroll, create_index
--------------------------------------------------------------------------------------------
See the <<roles-file,_Role Definition File_>> section for information on modifying roles.
See the <<defining-roles,_Role Definition File_>> section for information on modifying roles.
Create a user associated with the `logstash` role on the Elasticsearch cluster, using the <<esusers,`esusers` tool>>:
@ -43,12 +39,14 @@ NOTE: When using the transport protocol, the logstash user requires the predefin
Once you've created the user, you are ready to configure Logstash.
[float]
[[ls-http]]
==== Connecting with HTTP/HTTPS
All three input, filter and output plugins support HTTP Basic Authentication as well as SSL/TLS.
The sections below demonstrate the output plugin's configuration parameters, but input and filter are the same.
[float]
[[ls-http-auth]]
===== Basic Authentication
@ -68,6 +66,7 @@ output {
}
--------------------------------------------------
[float]
[[ls-http-ssl]]
===== SSL/TLS Configuration for HTTPS
@ -87,6 +86,7 @@ output {
--------------------------------------------------
<1> The path to the `.pem` file in your filesystem that contains the Certificate Authority's certificate.
[float]
[[ls-transport]]
==== Connecting with Transport protocol
@ -100,11 +100,13 @@ In order to unlock this option, it's necessary to install an additional plugin i
bin/plugin install logstash-output-elasticsearch-shield
--------------------------------------------------
[float]
[[ls-transport-auth]]
===== Authentication for Transport protocol
Transport protocol supports both basic auth and client-certificate authentication through the use of Public Key Infrastructure (PKI).
[float]
[[ls-transport-auth-basic]]
===== Basic Authentication
@ -123,6 +125,7 @@ output {
}
--------------------------------------------------
[float]
[[ls-transport-auth-pki]]
===== PKI Authentication
@ -142,7 +145,7 @@ output {
}
--------------------------------------------------
[float]
[[ls-transport-conf]]
===== SSL Configuration for Transport or Node protocols
@ -168,6 +171,7 @@ output {
For more information on encryption and certificates, see the <<ssl-tls,Securing Nodes>> section:
[float]
[[ls-failure]]
==== Failures

6
shield/docs/public/clients/marvel.asciidoc → shield/docs/public/configuring-clients-integrations/marvel.asciidoc
View File

@ -1,5 +1,5 @@
[[marvel]]
=== Shield with Marvel
=== Using Marvel with Shield
Marvel consists of a user interface over a data exporter known as the _agent_. The agent runs on each node and accesses
that node's monitoring API. The agent can store this collected data locally, on the cluster, or send the data to an
@ -21,6 +21,7 @@ You will configure at least two users to work with Marvel. These users have to
The default `roles.yml` file includes definitions for these two roles. The steps below show you how to create these
users on the monitoring cluster.
[float]
[[monitoring-cluster]]
==== Monitoring Cluster Settings
@ -64,7 +65,7 @@ Then create one or more users for the Marvel UI:
bin/shield/esusers useradd USER -p strongerpassword -r marvel_user
--------------------------------------------------
[float]
==== Production Cluster Settings
The Marvel agent is installed on every node in the production cluster. The agent collects monitoring data from the
@ -103,6 +104,7 @@ other SSL related settings.
NOTE: The 1.3.0 release of Marvel adds HTTPS support.
[float]
==== Marvel user interface & Sense
The Marvel UI supports SSL without the need for any additional configuration. You can change URL access scheme for Marvel to

24
shield/docs/public/05-authorization.asciidoc → shield/docs/public/configuring-rbac.asciidoc
View File

@ -1,5 +1,5 @@
[[authorization]]
== Authorization
[[configuring-rbac]]
== Configuring Role-based Access Control
Shield introduces the concept of _action authorization_ to Elasticsearch. Action authorization restricts the actions
users can execute on the cluster. Shield implements authorization as Role Based Access Control (RBAC), where all
@ -23,11 +23,9 @@ administrator is allowed to take all actions on indices named `logs-*`.
As an administrator, you will need to define the roles that you want to use, then assign users to the roles.
[[roles-file]]
[float]
==== The Role Definition File `roles.yml`
Roles are defined in the role definition file `roles.yml` located under Shield's <<shield-config,config>> directory.
[[defining-roles]]
=== Defining Roles
Roles are defined in the role definition file `roles.yml` located in `ES_HOME/config/shield`.
This is a YAML file where each entry defines the unique role name and the cluster and indices permissions associated
with it.
@ -88,8 +86,8 @@ The above example defines these roles:
See the complete list of available <<privileges-list, cluster and indices privileges>>.
[float]
==== Action Level Access Control
=== Granting Privileges for Specific Actions
The Shield security plugin enables access to specific actions in Elasticsearch. Access control using specific actions
provides a finer level of granularity than roles based on named privileges.
@ -127,6 +125,10 @@ TIP: When specifying index names, you can use indices and aliases with their ful
"/foo": all # syntax error - missing final /
------------------------------------------------------------------------------------
TIP: Once the roles are defined, users can then be associated with any number of these roles. In the
<<authentication,next section>> we'll learn more about authentication and see how users can be associated with the
TIP: Once the roles are defined, users can then be associated with any number of these roles. In
<<setting-up-authentication,Setting Up Authentication>> we'll learn more about authentication and see how users can be associated with the
configured roles.
include::granting-alias-privileges.asciidoc[]
include::mapping-roles.asciidoc[]

6
shield/docs/public/example-deployments.asciidoc Normal file
View File

@ -0,0 +1,6 @@
[[example-deployments]]
== Example Shield Deployments
The examples in this section demonstrate how you might deploy Shield to secure an Elasticsearch cluster.
include::example-deployments/e-commerce.asciidoc[]

12
shield/docs/public/appendices/06-example.asciidoc → shield/docs/public/example-deployments/e-commerce.asciidoc
View File

@ -1,8 +1,6 @@
[[example]]
== Appendix 6. Full `esusers` Example
[float]
=== Putting it all together: Ecommerce Store Example
[[example]]
=== E-commerce Example Using esusers
The e-commerce store site in this example store has the following components:
@ -12,7 +10,7 @@ The e-commerce store site in this example store has the following components:
* A sales representative that needs to read sales-specific indices
[float]
=== Defining the roles
==== Defining the roles
[source,yaml]
--------------------------------------------------
@ -57,7 +55,7 @@ the `products` index are the `write` and `delete` privileges, as well as index o
index.
[float]
=== Creating Users and Their Roles
==== Creating Users and Their Roles
After creating the `roles.yml` file, you can use the `esusers` tool to create the needed users and the respective
user-to-role mapping.
@ -88,7 +86,7 @@ bin/shield/esusers useradd second_best_sales_guy_of_the_world -r sales_rep
----------------------------------------------------------------------------
[float]
=== Modifying Your Application
==== Modifying Your Application
With the users and roles defined, you now need to modify your application. Each part of the application must
authenticate to Elasticsearch using the username and password you gave it in the previous steps.

54
shield/docs/public/getting-started.asciidoc Normal file
View File

@ -0,0 +1,54 @@
[[getting-started]]
== Getting Started with Shield
This getting started guide walks you through installing Shield, setting up basic authentication, and getting started with role-based
access control. You can install Shield on nodes running Elasticsearch 1.5 or later.
IMPORTANT: The Shield plugin must be installed on every node in the cluster and every
node must be restarted after installation. Plan for a complete cluster restart before beginning the installation process.
To install and run Shield:
. Run `bin/plugin` -i from `ES_HOME` to install the license plugin.
+
[source,shell]
----------------------------------------------------------
bin/plugin -i elasticsearch/license/latest
----------------------------------------------------------
. Run `bin/plugin -i` to install the Shield plugin.
+
[source,shell]
----------------------------------------------------------
bin/plugin -i elasticsearch/shield/latest
----------------------------------------------------------
+
NOTE: If you are using a <<deb-rpm-install, DEB/RPM distribution>> of Elasticsearch, you need to specify the configuration directory and run the installation with superuser permissions. To perform an offline installation, <<offline-install,download the Shield binaries>>.
. Start Elasticsearch.
+
[source,shell]
----------------------------------------------------------
bin/elasticsearch
----------------------------------------------------------
. To verify that Shield is up and running, check the startup log entries. When Shield is operating normally, the log indicates that the network transports are using Shield:
+
[source,shell]
----------------
[2014-10-09 13:47:38,841][INFO ][transport ] [Ezekiel Stane] Using [org.elasticsearch.shield.transport.ShieldServerTransportService] as transport service, overridden by [shield]
[2014-10-09 13:47:38,841][INFO ][transport ] [Ezekiel Stane] Using [org.elasticsearch.shield.transport.netty.ShieldNettyTransport] as transport, overridden by [shield]
[2014-10-09 13:47:38,842][INFO ][http ] [Ezekiel Stane] Using [org.elasticsearch.shield.transport.netty.ShieldNettyHttpServerTransport] as http transport, overridden by [shield]
----------------
Now you're ready to secure your cluster! Here are a few things
you might want to do to start with:
* <<enable-basic-auth, Control Access with Basic Authentication>>
* <<enable-message-authentication, Enable Message Authentication>>
* <<enable-auditing, Enable Auditing>>
include::getting-started/enable-basic-auth.asciidoc[]
include::getting-started/enable-message-authentication.asciidoc[]
include::getting-started/enable-auditing.asciidoc[]
include::getting-started/moving-on.asciidoc[]

17
shield/docs/public/getting-started/enable-auditing.asciidoc Normal file
View File

@ -0,0 +1,17 @@
[[enable-auditing]]
=== Enable Auditing
When you enable auditing, Shield stores a record of attempted and successful interactions with
your Elasticsearch cluster. You can use this information to keep track of who is doing what to
your cluster and identify potential security issues.
To enable auditing, add the following setting to `elasticsearch.yml`:
[source,yaml]
----------------------------
shield.audit.enabled: true
----------------------------
By default, events are logged to a dedicated `elasticsearch-access.log` file in `ES_HOME/logs`. You can also store the events in an Elasticsearch index for easier analysis and control what events
are logged. For more information, see <<configuring-auditing, Configuring Auditing>>.

53
shield/docs/public/getting-started/enable-basic-auth.asciidoc Normal file
View File

@ -0,0 +1,53 @@
[[enable-basic-auth]]
=== Control Access with Basic Authentication
Shield makes it simple to password-protect your Elasticsearch cluster. Once Shield is installed, a username and password is required to communicate with the cluster.
If you submit a request without a username and password, the request is rejected:
[source,shell]
----------------------------------------------------------
curl -XGET 'http://localhost:9200/'
----------------------------------------------------------
All you need to do to use basic authentication is set up users and assign them to one of the basic predefined roles:
`admin` :: Can perform any cluster or index action.
`power_user` :: Can monitor the cluster and perform any index action.
`user` :: Can perform read actions on any index.
To create a user and try out basic authentication:
. Add a user called `es_admin` and assign the `admin` role.
+
[source,shell]
----------------------------------------------------------
bin/shield/esusers useradd es_admin -r admin
----------------------------------------------------------
. When prompted, enter a password for the new user. Passwords must be at least 6 characters long.
. Submit a request using the newly-created user.
+
[source,shell]
----------------------------------------------------------
curl -u es_admin -XGET 'http://localhost:9200/'
----------------------------------------------------------
That's it! That's all it takes to set up the first layer of
security for your Elasticsearch cluster. However, Shield
offers much more that simple password protection. For example,
you can:
* <<enable-message-authentication, Enable Message Authentication>> to verify that messages have not not been tampered with or corrupted in transit.
* <<enable-auditing, Enable Auditing>> to keep track of attempted and successful interactions with
your Elasticsearch cluster.
And that's just the start. You can also:
* <<defining-roles, Define and Use Custom Roles>> for fine-grained access control.
* Integrate with <<ldap, LDAP>> or <<active-directory, Active Directory>>, or <<pki, require certificates>> for authentication.
* Use <<ssl-tls, SSL/TLS encryption>> to secure communications to and from nodes.
* Use <<ip-filtering, IP Filtering>> to allow or deny requests from particular IP addresses or address ranges.

23
shield/docs/public/getting-started/enable-message-authentication.asciidoc Normal file
View File

@ -0,0 +1,23 @@
[[enable-message-authentication]]
=== Enable Message Authentication
Message authentication verifies that a message has not been tampered with or corrupted in transit.
To enable message authentication:
. Run the `syskeygen` tool from `ES_HOME` without any options:
+
[source, shell]
----------------
bin/shield/syskeygen
----------------
+
This creates a system key file in `ES_HOME/config/shield/system_key`. You
can customize this file's location by changing the value of the `shield.system_key.file` setting in
`elasticsearch.yml`.
. Copy the genererated system key to the rest of the nodes in the cluster.
IMPORTANT: The system key is a symmetric key, so the same key must be on every node in the cluster.
Now that you've enabled message authentication, you might also want to <<enable-auditing, Enable Auditing>> to keep track of attempted and successful interactions with your Elasticsearch cluster.

9
shield/docs/public/getting-started/moving-on.asciidoc Normal file
View File

@ -0,0 +1,9 @@
[[moving-on]]
=== Moving On
Now that you have Shield up and running, you might want to:
* <<defining-roles, Define and Use Custom Roles>> for fine-grained access control.
* Integrate with <<ldap, LDAP>> or <<active-directory, Active Directory>>, or <<pki, require certificates>> for authentication.
* Use <<ssl-tls, SSL/TLS encryption>> to secure communications to and from nodes.
* Use <<ip-filtering, IP Filtering>> to allow or deny requests from particular IP addresses or address ranges.

6
shield/docs/public/appendices/04-securing-aliases.asciidoc → shield/docs/public/granting-alias-privileges.asciidoc
View File

@ -1,5 +1,5 @@
[[securing-aliases]]
== Appendix 4. Securing Indices & Aliases
=== Granting Privileges for Indices & Aliases
Elasticsearch allows to execute operations against {ref}/indices-aliases.html[index aliases],
which are effectively virtual indices. An alias points to one or more indices, holds metadata and potentially a filter.
@ -35,7 +35,7 @@ current_year_read:
--------------------------------------------------
[float]
=== Managing aliases
==== Managing aliases
Unlike creating indices, which requires `create_index` privilege, adding/removing/retrieving aliases requires
`manage_aliases` permission. Aliases can be added to an index directly as part of the index creation:
@ -94,7 +94,7 @@ curl -XPOST 'http://localhost:9200/_aliases' -d '
-------------------------------------------------------------------------------
[float]
=== Filtered aliases
==== Filtered aliases
Aliases can hold a filter, which allows to select a subset of documents that can be accessed out of all the documents that
the physical index contains. Filtered aliases allow to mimic document level security, but have limitations. Please read

10
shield/docs/public/02-architecture.asciidoc → shield/docs/public/how-shield-works.asciidoc
View File

@ -1,5 +1,5 @@
[[architecture]]
== Architecture Overview
[[how-shield-works]]
== How Shield Works
Shield installs as a plugin into Elasticsearch. Once installed, the plugin intercepts inbound API calls in order to
enforce authentication and authorization. The plugin can also provide encryption using Secure Sockets Layer/Transport
@ -24,7 +24,7 @@ also enables mapping LDAP groups to roles in Shield (more on roles below).
Your application can be a user in a Shield realm. Elasticsearch Clients authenticate to the cluster by providing a
username and password pair (a.k.a _Authentication Token_) with each request. To learn more on how different clients
can authenticate, see <<clients, Clients>>.
can authenticate, see <<configuring-clients-integrations, Configuring Clients and Integrations>>.
[float]
@ -66,7 +66,7 @@ Users are responsible for generating and installing their own certificates.
You can choose a variety of ciphers for encryption. See the <<ciphers,_Adding Ciphers to Java for Stronger Encryption_>>
section for details.
For more information on how to secure nodes see <<securing-nodes, Securing Nodes>>.
For more information on how to secure nodes see <<securing-communications, Securing Communications with Encryption and IP Filtering>>.
[float]
@ -80,5 +80,5 @@ whitelisting and blacklisting of subnets, specific IP addresses, and DNS domains
[float]
=== Auditing
The <<auditing,audit functionality>> in a secure Elasticsearch cluster logs particular events and activity on that
The <<configuring-auditing,audit functionality>> in a secure Elasticsearch cluster logs particular events and activity on that
cluster. The events logged include authentication attempts, including granted and denied access.

41
shield/docs/public/index.asciidoc Normal file
View File

@ -0,0 +1,41 @@
[[shield]]
= Shield Reference
:ref: http://www.elastic.co/guide/en/elasticsearch/reference/current
include::introduction.asciidoc[]
include::getting-started.asciidoc[]
include::how-shield-works.asciidoc[]
include::installing-shield.asciidoc[]
include::setting-up-authentication.asciidoc[]
include::managing-users.asciidoc[]
include::configuring-rbac.asciidoc[]
include::configuring-auditing.asciidoc[]
include::securing-communications.asciidoc[]
include::configuring-clients-integrations.asciidoc[]
include::managing-shield-licenses.asciidoc[]
include::example-deployments.asciidoc[]
include::reference.asciidoc[]
include::limitations.asciidoc[]
include::troubleshooting.asciidoc[]
include::setting-up-certificate-authority.asciidoc[]
include::release-notes.asciidoc[]

171
shield/docs/public/installing-shield.asciidoc Normal file
View File

@ -0,0 +1,171 @@
[[installing-shield]]
== Installing Shield
The <<getting-started, Getting Started Guide>> steps through a basic Shield installation. This section provides some additional information about the installation prerequisites, deployment options, and the installation process for RPM/DEB package installations.
IMPORTANT: The Shield plugin must be installed on every node in the cluster and every
node must be restarted after installation. Plan for a complete cluster restart before beginning the installation process.
[float]
=== Shield Installation Prerequisites
To install Shield 2.x, you need:
* Java 7 or later
* Elasticsearch 2.x
* Elasticsearch License plugin 2.x
For information about installing the latest Oracle JDK, see http://www.oracle.com/technetwork/java/javase/downloads/index-jsp-138363.html[Java SE Downloads]. For information about installing Elasticsearch, see http://www.elastic.co/guide/en/elasticsearch/reference/current/_installation.html[Installation] in the Elasticsearch Reference.
[float]
[[deb-rpm-install]]
=== Installing Shield on a DEB/RPM Package Installation
If you install Elasticsearch as a package or you specify a custom configuration directory, the command line
tools require you to specify the configuration directory. On Linux systems, add the following line to your
`.profile` file:
[source,shell]
----------------------------------------------------------
export ES_JAVA_OPTS="-Des.path.conf=/etc/elasticsearch"
----------------------------------------------------------
NOTE: When using `sudo` to run commands as a different user, the `ES_JAVA_OPTS` setting from your profile will not be
available in the other user's environment. You can manually pass the environment variables to the command or you can
make the environment variable available by adding the following line to the `/etc/sudoers` file:
[source,shell]
----------------------------------------------------------
Defaults env_keep += "ES_JAVA_OPTS"
----------------------------------------------------------
On Windows systems, the `setx` command can be used to specify a custom configuration directory:
[source,shell]
----------------------------------------------------------
setx ES_JAVA_OPTS "-Des.path.conf=C:\config"
----------------------------------------------------------
If your server doesn't have direct Internet access, see <<offline-install,Installing Shield on Offline Machines>> for information about downloading the Shield binaries.
[float]
[[offline-install]]
=== Installing Shield on Offline Machines
Elasticsearch’s `bin/plugin` script requires direct Internet access for downloading and installing the security plugin.
If your server doesn’t have Internet access, you can download the required binaries from the following link:
[source,sh]
----------------------------------------------------
https://download.elastic.co/elasticsearch/shield/shield-1.3.0.zip
----------------------------------------------------
Transfer the compressed file to your server, then install the plugin with the `bin/plugin` script:
[source,shell]
----------------------------------------------------
bin/plugin -i shield -u file://PATH_TO_ZIP_FILE <1>
----------------------------------------------------
<1> Absolute path to Shield plugin zip distribution file (e.g. `file:///path/to/file/shield-1.3.0.zip`,
note the three slashes at the beginning)
[float]
[[tribe-node]]
=== Installing Shield on Tribe Nodes
Shield supports the {ref}/modules-tribe.html[Tribe Node], which acts as a federated client across multiple clusters. When using Tribe Nodes with Shield, you must have the same Shield configuration (users, roles, user-role mappings, SSL/TLS CA) on each cluster, and on the Tribe Node itself, where security checking is primarily done. This, of course, also means
that all clusters must be running Shield.
To use a Tribe Node with Shield:
. Configure the same privileges on all connected clusters. The Tribe Node has its own configuration and privileges, which need to grant access to actions and indices on all of the
connected clusters. Also, each cluster needs to grant access to indices belonging to other connected clusters as well.
+
Let's look at an example: assuming we have two clusters, `cluster1` and `cluster2`, each one holding an index, `index1`
and `index2`. A search request that targets multiple clusters, as follows
+
[source,shell]
-----------------------------------------------------------
curl -XGET tribe_node:9200/index1,index2/_search -u tribe_user:tribe_user
-----------------------------------------------------------
+
requires `search` privileges for both `index1` and `index2` on the Tribe Node:
+
[source,yaml]
-----------------------------------------------------------
tribe_user:
indices:
'index*': search
-----------------------------------------------------------
+
Also, the same privileges need to be granted on the connected clusters, meaning that `cluster1` has to grant access to
`index2` even though `index2` only exists on `cluster2`; the same requirement applies for `index1` on `cluster2`. This
applies to any indices action. As for cluster state read operations (e.g. cluster state api, get mapping api etc.),
they always get executed locally on the Tribe Node, to make sure that the merged cluster state gets returned; their
privileges are then required on the Tribe Node only.
. Use the same system key on all clusters. For <<enable-message-authentication,message authentication>> to properly work across multiple clusters, the Tribe Node
and all of the connected clusters need to share the same system key.
. Enable encryption globally. Encrypted communication via SSL/TLS can only be enabled globally, meaning that either all of the connected clusters and the Tribe Node have SSL enabled, or none of them have.
. Use the same certification authority on all clusters. When using encrypted communication, for simplicity, we recommend all of the connected clusters and the Tribe Node use
the same certification authority to generate their certificates.
[float]
==== Tribe Node Example
Let's see a complete example on how to use the Tribe Node with shield and the configuration required. First of all the
Shield and License plugins need to be installed and enabled on all clusters and on the Tribe Node.
The system key needs to be generated on one node, as described in <<enable-message-authentication, Enabling Message Authentication>>,
and then copied over to all of the other nodes in each cluster and the Tribe Node itself.
Each cluster can have its own users with `admin` privileges that don't need to be present in the Tribe Node too. In fact,
administration tasks (e.g. create index) cannot be performed through the Tribe Node but need to be sent directly to the
corresponding cluster. The users that need to be created on Tribe Node are those that allow to get back data merged from
the different clusters through the Tribe Node itself. Let's for instance create as follows a `tribe_user` user, with
role `user`, that has `read` privileges on any index.
[source,shell]
-----------------------------------------------------------
./bin/shield/esusers useradd tribe_user -p tribe_user -r user
-----------------------------------------------------------
The above command needs to be executed on each cluster, since the same user needs to be present on the Tribe Node as well
as on every connected cluster.
The following is the configuration required on the Tribe Node, that needs to be added to `elasticsearch.yml`.
Elasticsearch allows to list specific settings per cluster. We disable multicast discovery as described in the
<<disable-multicast, Disable Multicast section>> and configure the proper unicast discovery hosts for each cluster,
as well as their cluster names:
[source,yaml]
-----------------------------------------------------------
tribe:
t1:
cluster.name: tribe1
discovery.zen.ping.multicast.enabled: false
discovery.zen.ping.unicast.hosts: ["tribe1:9300"]
t2:
cluster.name: tribe2
discovery.zen.ping.multicast.enabled: false
discovery.zen.ping.unicast.hosts: ["tribe2:9300"]
-----------------------------------------------------------
The Tribe Node can then be started and once initialized it will be ready to accept requests like the following search,
which will return documents coming from the different connected clusters:
[source,shell]
-----------------------------------------------------------
curl -XGET localhost:9200/_search -u tribe_user:tribe_user
-----------------------------------------------------------
As for encrypted communication, the required settings are the same as described in <<securing-communications, Securing Communications with Encryption and IP Filtering>>,
but need to be specified per tribe as we did for discovery settings above.

4
shield/docs/public/01-introduction.asciidoc → shield/docs/public/introduction.asciidoc
View File

@ -11,7 +11,7 @@ An Elasticsearch cluster benefits from properly implemented security in the foll
* <<roles,Role-based>> access control at the index level and <<ldap,LDAP>> authentication integration to _prevent
unauthorized access_
* <<ssl-tls,Encryption>> to _preserve the integrity of your data_, keeping confidential data confidential.
* An _<<auditing,Audit>> trail_ to analyze access patterns.
* An _<<configuring-auditing,Audit>> trail_ to analyze access patterns.
[float]
==== Prevent Unauthorized Access
@ -53,7 +53,7 @@ your cluster.
The information in this document covers the following broad categories:
* To learn about the architecture of the Elasticsearch security plugin and how the various elements of security
interact, see the <<architecture, Architecture Overview>> section.
interact, see <<how-shield-works, How Shield Works>>.
* To get started with Elasticsearch security, from installation to initial configuration, see the
<<getting-started,Getting Started>> section.
* To answer specific questions about configuration elements and privileges in Elasticsearch security, see the

8
shield/docs/public/appendices/03-limitations.asciidoc → shield/docs/public/limitations.asciidoc
View File

@ -1,5 +1,5 @@
[[limitations]]
== Appendix 3. Limitations
== Limitations
[float]
=== Plugins
@ -39,7 +39,7 @@ that users with privileges on that index alias can access.
WARNING: Filtering secured index aliases does not provide security for documents retrieved through the
{ref}/docs-get.html[get api]. Read
https://github.com/elasticsearch/elasticsearch/issues/3861[elasticsearch issue #3861] to learn more about this limitation.
https://github.com/elasticsearch/elasticsearch/issues/3861[Elasticsearch issue #3861] to learn more about this limitation.
Users can obtain secure near-real-time get under this restriction with searches by document ID, using the
{ref}/search-search.html[search api] instead. Restrict get operations when you use this approach by granting the `search`
privilege and disallowing `get`.
@ -47,7 +47,7 @@ privilege and disallowing `get`.
WARNING: In Elasticsearch, issuing a delete operation on an alias also deletes all of the indices that the alias
points to, regardless of the filter that the alias might hold. Keep this behavior in mind when granting users
administrative privileges to filtered index aliases. Read
https://github.com/elasticsearch/elasticsearch/issues/2318[elasticsearch issue #2318] to learn more about this limitation.
https://github.com/elasticsearch/elasticsearch/issues/2318[Elasticsearch issue #2318] to learn more about this limitation.
[float]
=== Queries and Filters
@ -90,5 +90,5 @@ does not work with Shield. The document deletions will fail and the documents co
=== LDAP Realm
The <<ldap, LDAP Realm>> does not currently support the discovery of nested LDAP Groups. For example, if a user is a member
of GroupA and GroupA is a member of GroupB, only GroupA will be discovered. However, the <<active_directory, Active Directory Realm>> _does_
of GroupA and GroupA is a member of GroupB, only GroupA will be discovered. However, the <<active-directory, Active Directory Realm>> _does_
support transitive group membership.

44
shield/docs/public/appendices/02-license-management.asciidoc → shield/docs/public/managing-shield-licenses.asciidoc
View File

@ -1,38 +1,15 @@
[[license-management]]
== Appendix 2. License Management
[float]
==== Installing The License Plugin
To install the license plugin, you'll need to run the following command:
[source,shell]
----------------------------------------------------------
bin/plugin -i elasticsearch/license/latest
----------------------------------------------------------
If your server doesn’t have direct Internet access, it is also possible to download the plugin separately and install
it manually by following these steps:
1. Download the plugin package in https://download.elastic.co/elasticsearch/license/license-latest.zip
2. Transfer the compressed file to your server, then install the plugin using the `bin/plugin` script:
[source,shell]
----------------------------------------------------
bin/plugin -i license -u file://PATH_TO_ZIP_FILE <1>
----------------------------------------------------
<1> URI to license plugin zip distribution file (e.g. `file:///path/to/file/license-latest.zip`,
note the three slashes at the beginning)
[[installing-license]]
[float]
==== Installing A License
== Managing Shield Licenses
When installing Shield for the first time, having the license plugin installed is the minimum required for Shield to work.
You can just start up the node and everything will just work as expected. The first time you start up the node, a 30 days
trial license will automatically be created which will enable Shield to be fully operational. Within these 30 days, you
will be able to replace the trial license with another one that will be provided to you up on purchase. Updating the
will be able to replace the trial license with another one that will be provided to you up on purchase.
[float]
[[installing-license]]
=== Updating Your Shield License
Updating the
license can be done at runtime (no need to shutdown the nodes) using a dedicated API.
IMPORTANT: With a valid license, Shield will be fully operational. Upon license expiry, Shield will operate in a
@ -50,7 +27,7 @@ curl -XPUT -u admin 'http://<host>:<port>/_licenses' -d @license.json
Where:
* `<host>` is the hostname of the elasticsearch node (`localhost` if executing locally)
* `<host>` is the hostname of the Elasticsearch node (`localhost` if executing locally)
* `<port>` is the http port (defaults to `9200`)
* `license.json` is the license json file
@ -58,7 +35,8 @@ NOTE: The put license API is protected under the cluster admin privilege, theref
by a user with the appropriate permissions.
[float]
=== Listing Currently Installed Licenses
[[listing-licenses]]
=== Listing Installed Licenses
You can list all currently installed licenses by executing the following REST API:
@ -97,8 +75,8 @@ entry will be shown:
NOTE: The get license API is protected under the cluster admin privilege, therefore it has to be executed
by a user with the appropriate permissions.
[[license-expiration]]
[float]
[[license-expiration]]
=== License Expiration
License expiration should never be a surprise. Beginning 30 days from license expiration, Shield will begin logging daily messages

89
shield/docs/public/realms/01-esusers.asciidoc → shield/docs/public/managing-users.asciidoc
View File

@ -1,48 +1,6 @@
[[esusers]]
=== esusers - Internal File Based Authentication
== Managing Users in an esusers Realm
The _esusers_ realm is the default Shield realm. The _esusers_ realm enables the registration of users, passwords for
those users, and associates those users with roles. The `esusers` command-line tool assists with the registration and
administration of users.
==== `esusers` Realm Settings
Like all other realms, the `esusers` realm is configured under the `shield.authc.realms` settings namespace in the
`elasticsearch.yml` file. The following snippet shows an example of such configuration:
.Example `esusers` Realm Configuration
[source, yaml]
------------------------------------------------------------
shield:
authc:
realms:
default:
type: esusers
order: 0
------------------------------------------------------------
[[esusers-settings]]
.`esusers` Realm Settings
|=======================
| Setting | Required | Description
| `type` | yes | Indicates the realm type and must be set to `esusers`.
| `order` | no | Indicates the priority of this realm within the realm chain. Realms with lower order will be consulted first. Although not required, it is highly recommended to explicitly set this value when multiple realms are configured. Defaults to `Integer.MAX_VALUE`.
| `enabled` | no | Indicates whether this realm is enabled/disabled. Provides an easy way to disable realms in the chain without removing their configuration. Defaults to `true`.
| `files.users` | no | Points to the location of the `users` file where the users and their passwords are stored. Defaults to `users` file under shield's <<shield-config, config directory>>.
| `files.users_roles` | no | Points to the location of the `users_roles` file where the users and their roles are stored. Defaults to `users_roles` file under shield's <<shield-config, config directory>>.
| `cache.ttl` | no | Specified the time-to-live for cached user entries (a user and its credentials will be cached for this configured period of time). Defaults to `20m` (use the standard elasticsearch {ref}/common-options.html#time-units[time units]).
| `cache.max_users` | no | Specified the maximum number of user entries that can live in the cache at a given time. Defaults to 100,000.
| `cache.hash_algo` | no | (Expert Setting) Specifies the hashing algorithm that will be used for the in-memory cached user credentials (see <<esusers-cache-hash-algo,here>> for possible values).
|=======================
NOTE: When no realms are explicitly configured in `elasticsearch.yml`, a default realm chain will be created that holds
a single `esusers` realm. If you wish to only work with `esusers` realm and you're satisfied with the default
files paths, there is no real need to add the above configuration.
==== The `esusers` Command Line Tool
The `esusers` command line tool is located under Shield's <<shield-bin, bin>> directory and enables several
The `esusers` command line tool is located in `ES_HOME/bin/shield` and enables several
administrative tasks for managing users:
* <<esusers-add,Adding users>>
@ -51,8 +9,9 @@ administrative tasks for managing users:
* <<esusers-roles,Managing users' roles>>
* <<esusers-del,Removing users>>
[float]
[[esusers-add]]
===== Adding Users
=== Adding Users
The `esusers useradd` command adds a user to your cluster.
@ -98,9 +57,9 @@ esusers useradd jacknich -p theshining -r logstash,marvel
For valid role names please see <<valid-role-name, Role Definitions>>.
[float]
[[esusers-list]]
===== Listing Users
=== Listing Users
The `esusers list` command lists the users registered in the _esusers_ realm, as in the following example:
[source, shell]
@ -113,8 +72,6 @@ jacknich : marvel,logstash
Users are in the left-hand column and their corresponding roles are listed in the right-hand column.
===== Listing Specific Users
The `esusers list <username>` command lists a specific user. Use this command to verify that a user has been
successfully added to the cluster.
@ -124,8 +81,9 @@ esusers list jacknich
jacknich : marvel,logstash
-----------------------------------
[float]
[[esusers-pass]]
===== Changing Users' Passwords
=== Managing User Passwords
The `esusers passwd` command enables you to reset a user's password. You can specify the new password directly with the
`-p` option. When `-p` option is omitted, the tool will prompt you to enter and confirm a password in interactive mode.
@ -140,8 +98,9 @@ esusers passwd <username>
esusers passwd <username> -p <password>
--------------------------------------------------
[float]
[[esusers-roles]]
===== Changing Users' Roles
=== Assigning Users to Roles
The `esusers roles` command manages the roles associated to a particular user. The `-a` option adds a comma-separated
list of roles to a user. The `-r` option removes a comma-separated list of roles from a user. You can combine adding and
@ -167,8 +126,9 @@ esusers list jacknich
jacknich : user
---------------------------------
[float]
[[esusers-del]]
===== Deleting Users
=== Deleting Users
The `esusers userdel` command deletes a user.
@ -177,14 +137,14 @@ The `esusers userdel` command deletes a user.
userdel <username>
--------------------------------------------------
==== How `esusers` Works
[float]
=== About `esusers`
The `esusers` tool manipulates two files, `users` and `users_roles`, in Shield's
<<shield-config,config>> directory. These two files store all user data for the _esusers_ realm and are read by Shield
The `esusers` tool manipulates two files, `users` and `users_roles`, in `ES_HOME/config/shield/`. These two files store all user data for the _esusers_ realm and are read by Shield
on startup.
By default, Shield checks these files for changes every 5 seconds. You can change this default behavior by changing the
value of the `resource.reload.interval.high` setting in the `elasticsearch.yml` file.
value of the `watcher.interval.high` setting in the `elasticsearch.yml` file.
[IMPORTANT]
==============================
@ -205,9 +165,9 @@ While it is possible to modify these files directly using any standard text
editor, we strongly recommend using the `esusers` command-line tool to apply
the required changes.
[float]
[[users-file]]
===== The `users` File
==== The `users` File
The `users` file stores all the users and their passwords. Each line in the `users` file represents a single user entry
consisting of the username and **hashed** password.
@ -220,8 +180,9 @@ jacknich:$2a$10$GYUNWyABV/Ols/.bcwxuBuuaQzV6WIauW6RdboojxcixBq3LtI3ni
NOTE: The `esusers` command-line tool uses `bcrypt` to hash the password by default.
[[users_roles-file]]
===== The `users_roles` File
[float]
[[users_defining-roles]]
==== The `users_roles` File
The `users_roles` file stores the roles associated with the users, as in the following example:
@ -234,8 +195,9 @@ user:jacknich
Each row maps a role to a comma-separated list of all the users that are associated with that role.
[float]
[[user-cache]]
==== User Cache
The user credentials are not stored on disk in clear text. The esusers creates a `bcrypt` hashes of the passwords and
stores those. `bcrypt` is considered to be highly secured hash and by default it uses 10 rounds to generate the salts
it hashes with. While highly secured, it is also relatively slow. For this reason, Shield also introduce an in-memory
@ -265,8 +227,9 @@ describes the different hash algorithm that can be set:
level (e.g. memory dumps and `ptrace`).
|=======================
===== Cache Eviction API
[float]
[[cache-eviction-api]]
==== Cache Eviction API
Shield exposes an API to force cached user eviction. The following example, evicts all users from the `ldap1`
realm:

77
shield/docs/public/mapping-roles.asciidoc Normal file
View File

@ -0,0 +1,77 @@
[[mapping-roles]]
=== Mapping Users and Groups to Roles
If you authenticate users with an `esusers` realm, you can assign roles when you <<esusers-add,add a user>> and use the <<esusers-roles,`roles`>> command to add or remove roles.
For other types of realms, you configure role mappings for users and groups in a YAML file. By default, role mappings are stored in `config/shield/role_mapping.yml`. You can specify
the name and location of the mapping file by configuring the appropriate `role_mapping` setting in `elasticsearch.yml`:
`shield.authc.ldap.files.role_mapping` :: The location of the role mapping file for LDAP realms.
`shield.authc.active-directory.files.role_mapping` :: The location of the role mapping file for Active Directory realms.
`shield.authc.pki.files.role_mapping` :: The location of the role mapping file for PKI realms.
Within the role mapping file, Elasticsearch roles are keys and groups
and users are values. The mapping can have a many-to-many relationship.
When you map roles to groups, the roles of a user in that group are the combination of the
roles assigned to that group and the roles assigned to that user.
To map users and groups to a role, you create a mapping file and copy it to each node in the cluster. Tools like Puppet or Chef can help with this.
[[ldap-role-mapping]]
.Example LDAP Role Mapping File
[source, yaml]
------------------------------------------------------------
# Example LDAP group mapping configuration:
# roleA: <1>
# - groupA-DN <2>
# - groupB-DN
# - user1-DN <3>
monitoring:
- "cn=admins,dc=example,dc=com"
user:
- "cn=users,dc=example,dc=com"
- "cn=admins,dc=example,dc=com"
- "cn=John Doe,cn=contractors,dc=example,dc=com"
------------------------------------------------------------
<1> The name of the Elasticsearch role found in the <<defining-roles, roles file>>
<2> Example specifying the distinguished name of a LDAP group
<3> Example specifying the distinguished name of a LDAP user added[1.1.0]
[[ad-role-mapping]]
.Example Active Directory Role Mapping File
[source, yaml]
------------------------------------------------------------
# Example Active Directory group mapping configuration:
# roleA: <1>
# - groupA-DN <2>
# - groupB-DN
# - user1-DN <3>
monitoring:
- "cn=admins,dc=example,dc=com"
user:
- "cn=users,dc=example,dc=com"
- "cn=admins,dc=example,dc=com"
- "cn=John Doe,cn=contractors,dc=example,dc=com"
------------------------------------------------------------
<1> The name of a Shield role defined in the <<defining-roles, roles file>>
<2> Example specifying the distinguished name of a Active Directory group
<3> Example specifying the distinguished name of a Active Directory user
[[pki-role-mapping]]
.Example PKI Role Mapping File
[source, yaml]
------------------------------------------------------------
# Example user mapping configuration:
# roleA: <1>
# - user1-DN <2>
monitoring:
- "cn=Admin,ou=example,o=com"
user:
- "cn=John Doe,ou=example,o=com"
------------------------------------------------------------
<1> The name of a Shield role defined in the <<defining-roles, roles file>>
<2> Example specifying the distinguished name of a PKI user
NOTE: For PKI realms, only the DN of a user can be mapped as there is no concept of a group in PKI

36
shield/docs/public/appendices/08-reference.asciidoc → shield/docs/public/reference.asciidoc
View File

@ -1,5 +1,5 @@
[[reference]]
== Appendix 8. Reference
== Reference
[[privileges-list]]
@ -163,7 +163,7 @@ The parameters listed in this section are configured in the `config/elasticsearc
[options="header"]
|======
| Name | Default | Description
| `shield.system_key.file` | `system_key` under Shield's <<shield-config,config>> | Sets the location of the `system_key` file (read more <<message-authentication,here>>)
| `shield.system_key.file` |`ES_HOME/config/shield/system_key` | Sets the location of the `system_key` file. For more information, see <<enable-message-authentication,Enabling Message Authentication>>.
|======
[[ref-anonymous-access]]
@ -200,7 +200,7 @@ shield.authc.realms:
...
realm3:
type: active_directory
type: active-directory
order: 2
...
...
@ -210,7 +210,7 @@ shield.authc.realms:
[options="header"]
|======
| Name | Required | Default | Description
| `type` | yes | - | The type of the reamlm (currently `esusers`, `ldap` or `active_directory`)
| `type` | yes | - | The type of the reamlm (currently `esusers`, `ldap` or `active-directory`)
| `order` | no | Integer.MAX_VALUE | The priority of the realm within the realm chain
| `enabled` | no | true | Enable/disable the realm
|======
@ -221,9 +221,9 @@ shield.authc.realms:
[options="header"]
|======
| Name | Required | Default | Description
| `files.users` | no | `users` under Shield's <<shield-config,config>> | The location of <<users-file, _users_>> file
| `files.users_roles` | no | `users_roles` under Shield's <<shield-config,config>> | The location of <<users_roles-file, _users_roles_>> file
| `cache.ttl` | no | `20m` | Specified the time-to-live for cached user entries (a user and its credentials will be cached for this configured period of time). Defaults to `20m` (use the standard elasticsearch {ref}/common-options.html#time-units[time units]).
| `files.users` | no | `ES_HOME/config/shield/users`
| `files.users_roles` | no | `ES_HOME/config/shield/users_roles`| The location of <<users_defining-roles, _users_roles_>> file
| `cache.ttl` | no | `20m` | Specified the time-to-live for cached user entries (a user and its credentials will be cached for this configured period of time). Defaults to `20m` (use the standard Elasticsearch {ref}/common-options.html#time-units[time units]).
| `cache.max_users` | no | 100000 | Specified the maximum number of user entries that can live in the cache at a given time. Defaults to 100,000.
| `cache.hash_algo` | no | `ssha256` | (Expert Setting) Specifies the hashing algorithm that will be used for the in-memory cached user credentials (see <<ref-cache-hash-algo,Cache hash algorithms>> table for all possible values).
|======
@ -251,12 +251,12 @@ shield.authc.realms:
| `group_search.filter` | no | See description | When not set, the realm will search for `group`, `groupOfNames`, or `groupOfUniqueNames`, with the attributes `member` or `memberOf`. Any instance of `{0}` in the filter will be replaced by the user attribute defined in `group_search.user_attribute`
| `group_search.user_attribute` | no | Empty | Specifies the user attribute that will be fetched and provided as a parameter to the filter. If not set, the user DN is passed into the filter.
| `unmapped_groups_as_roles` | no | false | Takes a boolean variable. When this element is set to `true`, the names of any unmapped LDAP groups are used as role names and assigned to the user. THe default value is `false`.
| `files.role_mapping` | no | `role_mapping.yml` under Shield's <<shield-config,config>> | The path and file name for the <<ldap-role-mapping, YAML role mapping configuration file>>. The default file name is `role_mapping.yml` in the <<shield-config,Shield config directory>>.
| `files.role_mapping` | no | `ES_HOME/config/shield/users/role_mapping.yml` | The path and file name for the <<ldap-role-mapping, YAML role mapping configuration file>>.
| `follow_referrals` | no | `true` | Boolean value that specifies whether Shield should follow referrals returned by the LDAP server. Referrals are URLs returned by the server that are to be used to continue the LDAP operation (e.g. search).
| `connect_timeout` | no | "5s" - for 5 seconds | The timeout period for establishing an LDAP connection. An `s` at the end indicates seconds, or `ms` indicates milliseconds.
| `read_timeout` | no | "5s" - for 5 seconds | The timeout period for an LDAP operation. An `s` at the end indicates seconds, or `ms` indicates milliseconds.
| `hostname_verification` | no | true | Performs hostname verification when using `ldaps` to protect against man in the middle attacks.
| `cache.ttl` | no | `20m` | Specified the time-to-live for cached user entries (a user and its credentials will be cached for this configured period of time). (use the standard elasticsearch {ref}/common-options.html#time-units[time units]).
| `cache.ttl` | no | `20m` | Specified the time-to-live for cached user entries (a user and its credentials will be cached for this configured period of time). (use the standard Elasticsearch {ref}/common-options.html#time-units[time units]).
| `cache.max_users` | no | 100000 | Specified the maximum number of user entries that can live in the cache at a given time.
| `cache.hash_algo` | no | `ssha256` |(Expert Setting) Specifies the hashing algorithm that will be used for the in-memory cached user credentials (see <<ref-cache-hash-algo,Cache hash algorithms>> table for all possible values).
|======
@ -271,7 +271,7 @@ NOTE: `user_dn_templates` is required to operate in user template mode and `user
| `url` | no | `ldap://<domain_name>:389` | A URL in the format `ldap[s]://<server>:<port>` If not specified the URL will be derived from the domain_name, assuming clear-text `ldap` and port `389` (e.g. `ldap://<domain_name>:389`).
| `domain_name` | yes | - | The domain name of Active Directory. The cluster can derive the URL and `user_search_dn` fields from values in this element if those fields are not otherwise specified.
| `unmapped_groups_as_roles` | no | false | Takes a boolean variable. When this element is set to `true`, the names of any unmapped groups and the user's relative distinguished name are used as role names and assigned to the user. THe default value is `false`.
| `files.role_mapping` | no | `role_mapping.yml` under Shield's <<shield-config,config>> | The path and file name for the <<ad-role-mapping, YAML role mapping configuration file>>. The default file name is `role_mapping.yml` in the <<shield-config,Shield config directory>>.
| `files.role_mapping` | no | `ES_HOME/config/shield/users/role_mapping.yml` | The path and file name for the <<ad-role-mapping, YAML role mapping configuration file>>.
| `user_search.base_dn` | no | Root of Active Directory | The context to search for a user. The default value for this element is the root of the Active Directory domain.
| `user_search.scope` | no | `sub_tree` | Specifies whether the user search should be `sub_tree`, `one_level` or `base`. `one_level` only searches users directly contained within the `base_dn`. `sub_tree` searches all objects contained under `base_dn`. `base` specifies that the `base_dn` is a user object, and that it is the only user considered.
| `user_search.filter` | no | See description | Specifies a filter to use to lookup a user given a username. The default filter looks up `user` objects with either `sAMAccountName` or `userPrincipalName`
@ -281,7 +281,7 @@ NOTE: `user_dn_templates` is required to operate in user template mode and `user
| `timeout.tcp_read` | no | `5s` - for 5 seconds | The TCP read timeout period after establishing an LDAP connection. An `s` at the end indicates seconds, or `ms` indicates milliseconds.
| `timeout.ldap_search` | no | `5s` - for 5 seconds | The LDAP Server enforced timeout period for an LDAP search. An `s` at the end indicates seconds, or `ms` indicates milliseconds.
| `hostname_verification` | no | true | Performs hostname verification when using `ldaps` to protect against man in the middle attacks.
| `cache.ttl` | no | `20m` | Specified the time-to-live for cached user entries (a user and its credentials will be cached for this configured period of time). (use the standard elasticsearch {ref}/common-options.html#time-units[time units]).
| `cache.ttl` | no | `20m` | Specified the time-to-live for cached user entries (a user and its credentials will be cached for this configured period of time). (use the standard Elasticsearch {ref}/common-options.html#time-units[time units]).
| `cache.max_users` | no | 100000 | Specified the maximum number of user entries that can live in the cache at a given time.
| `cache.hash_algo` | no | `ssha256` |(Expert Setting) Specifies the hashing algorithm that will be used for the in-memory cached user credentials (see <<ref-cache-hash-algo,Cache hash algorithms>> table for all possible values).
|======
@ -296,7 +296,7 @@ NOTE: `user_dn_templates` is required to operate in user template mode and `user
| `truststore.path` | no | `shield.ssl.keystore` | The path of a truststore to use. The default truststore is the one defined by <<ref-ssl-tls-settings,SSL/TLS settings>>
| `truststore.password` | no | - | The password to the truststore. Must be provided if `truststore.path` is set.
| `truststore.algorithm` | no | SunX509 | Algorithm for the trustsore. Default is `SunX509`
| `files.role_mapping` | no | `role_mapping.yml` under Shield's <<shield-config,config>> | Specifies the path and file name for the <<pki-role-mapping, YAML role mapping configuration file>>. The default file name
| `files.role_mapping` | no | `ES_HOME/config/shield/users/role_mapping.yml` | Specifies the path and file name for the <<pki-role-mapping, YAML role mapping configuration file>>.
|======
[[ref-cache-hash-algo]]
@ -324,7 +324,7 @@ NOTE: `user_dn_templates` is required to operate in user template mode and `user
[options="header"]
|======
| Name | Default | Description
| `shield.authz.store.file.roles` | `roles.yml` under Shield's <<shield-config,config>> | The location of the roles definition file
| `shield.authz.store.file.roles` | `ES_HOME/config/shield/users/roles.yml` | The location of the roles definition file.
|======
[[ref-ssl-tls-settings]]
@ -349,7 +349,7 @@ NOTE: `user_dn_templates` is required to operate in user template mode and `user
| `shield.ssl.hostname_verification` | `true` | Performs hostname verification on transport connections. This is enabled by default to protect against man in the middle attacks.
| `shield.ssl.hostname_verification.resolve_name` | `true` | A reverse DNS lookup is necessary to find the hostname when connecting to a node via an IP Address. If this is disabled and IP addresses are used to connect to a node, the IP address must be specified as a `SubjectAlternativeName` when <<private-key,creating the certificate>> or hostname verification will fail. IP addresses will be used to connect to a node if they are used in following settings: `network.host`, `network.publish_host`, `transport.publish_host`, `transport.profiles.$PROFILE.publish_host`, `discovery.zen.ping.unicast.hosts`
| `shield.ssl.session.cache_size` | `1000` | Number of SSL Sessions to cache in order to support session resumption. Setting the value to `0` means there is no size limit.
| `shield.ssl.session.cache_timeout` | `24h` | The time after the creation of a SSL session before it times out. (uses the standard elasticsearch {ref}/common-options.html#time-units[time units]).
| `shield.ssl.session.cache_timeout` | `24h` | The time after the creation of a SSL session before it times out. (uses the standard Elasticsearch {ref}/common-options.html#time-units[time units]).
| `shield.transport.ssl` | `false` | Set this parameter to `true` to enable SSL/TLS
| `shield.transport.ssl.client.auth` | `required` | Require client side certificates for transport protocol. Valid values are `required`, `optional`, and `no`. `required` forces a client to present a certificate, while `optional` requests a client certificate but the client is not required to present one.
| `shield.transport.filter.allow` | None | List of IP addresses to allow
@ -375,7 +375,7 @@ NOTE: `user_dn_templates` is required to operate in user template mode and `user
| `transport.profiles.$PROFILE.shield.keystore.key_password` | Same value as `transport.profiles.$PROFILE.shield.keystore.password` | Password for the private key in the keystore
| `transport.profiles.$PROFILE.shield.keystore.algorithm` | SunX509 | Format for the keystore
| `transport.profiles.$PROFILE.shield.session.cache_size` | `1000` | Number of SSL Sessions to cache in order to support session resumption. Setting the value to `0` means there is no size limit.
| `transport.profiles.$PROFILE.shield.session.cache_timeout` | `24h` | The time after the creation of a SSL session before it times out. (uses the standard elasticsearch {ref}/common-options.html#time-units[time units]).
| `transport.profiles.$PROFILE.shield.session.cache_timeout` | `24h` | The time after the creation of a SSL session before it times out. (uses the standard Elasticsearch {ref}/common-options.html#time-units[time units]).
| `transport.profiles.$PROFILE.shield.filter.allow` | None | List of IP addresses to allow for this profile
| `transport.profiles.$PROFILE.shield.filter.deny` | None | List of IP addresses to deny for this profile
| `transport.profiles.$PROFILE.shield.ssl.client.auth` | `required` | Require client side certificates. Valid values are `required`, `optional`, and `no`. `required` forces a client to present a certificate, while `optional` requests a client certificate but the client is not required to present one.
@ -392,13 +392,13 @@ NOTE: `user_dn_templates` is required to operate in user template mode and `user
The Shield security plugin uses the following files:
* `config/shield/roles.yml` defines the roles in use on the cluster (read more <<roles-file,here>>).
* `config/shield/roles.yml` defines the roles in use on the cluster (read more <<defining-roles,here>>).
* `config/shield/users` defines the hashed passwords for users on the cluster (read more <<users-file,here>>).
* `config/shield/users_roles` defines the role assignments for users on the cluster (read more <<users_roles-file,here>>).
* `config/shield/users_roles` defines the role assignments for users on the cluster (read more <<users_defining-roles,here>>).
* `config/shield/role_mapping.yml` defines the role assignments for a Distinguished Name (DN) to a role. This allows for
LDAP and Active Directory groups and users and PKI users to be mapped to roles (read more <<ldap-role-mapping,here>>).
* `config/shield/logging.yml` contains audit information (read more <<logging-file,here>>).
* `config/shield/system_key` holds a cluster secret key used for message authentication (read more <<message-authentication,here>>).
* `config/shield/system_key` holds a cluster secret key used for message authentication. For more information, see <<enable-message-authentication,Enabling Message Authentication>>.
Several of these files are in the YAML format. When you edit these files, be aware that YAML is indentation-level
sensitive and indentation errors can lead to configuration errors. Avoid the tab character to set indentation levels,

17
shield/docs/public/appendices/09-release-notes.asciidoc → shield/docs/public/release-notes.asciidoc
View File

@ -1,14 +1,15 @@
[[release-notes]]
== Appendix 9. Release Notes
== Release Notes
[[version-compatibility]]
[float]
[[version-compatibility]]
=== Version Compatibility
Shield 2.x is compatible with:
* elasticsearch: 1.5.0+
* license: 1.0
* Elasticsearch: 2.x
* License plugin: 2.x
[float]
[[upgrade-instructions]]
=== Upgrading Shield
@ -20,7 +21,7 @@ will be preserved and you do this with a rolling upgrade of Elasticsearch. On ea
bin/plugin -r shield
bin/plugin -i elasticsearch/shield/latest <1>
---------------------------------------------------
<1> `latest` will install the latest version of Shield compatible with your version of elasticsearch. A specific version,
<1> `latest` will install the latest version of Shield compatible with your version of Elasticsearch. A specific version,
such as `1.1.0` can also be specified.
Then start the node. Larger sites should follow the steps in the {ref}/setup-upgrade.html#_1_0_and_later[rolling upgrade section]
@ -29,6 +30,7 @@ in order to ensure recovery is as quick as possible.
On upgrade, your current configuration files will remain untouched. The configuration files provided by the new version
of Shield will be added with a `.new` extension.
[float]
==== updated role definitions
The default role definitions in the `roles.yml` file may need to be changed to ensure proper functionality with other
applications such as Marvel and Kibana. Any role changes will be found in `roles.yml.new` after upgrading to the new
@ -37,6 +39,7 @@ version of Shield. We recommend copying the changes listed below to your `roles.
* added[1.1.0] `kibana4_server` role added that defines the minimum set of permissions necessary for the Kibana 4 server.
* added[1.0.1] `kibana4` role updated to work with new features in Kibana 4 RC1
[float]
[[changelist]]
=== Change List
@ -46,7 +49,7 @@ version of Shield. We recommend copying the changes listed below to your `roles.
.new features
* <<pki,PKI Realm>>: Adds Public Key Infrastructure (PKI) authentication through the use of X.509 certificates in place of
username and password credentials.
* <<auditing, Index Output for Audit Events>>: An index based output has been added for storing audit events in an Elasticsearch index.
* <<configuring-auditing, Index Output for Audit Events>>: An index based output has been added for storing audit events in an Elasticsearch index.
.breaking changes
* The `sha2` and `apr1` hashing algorithms have been removed as options for the <<ref-cache-hash-algo,`cache.hash_algo` setting>>.
@ -89,7 +92,7 @@ works properly with Shield
[float]
==== 1.2.0
* Adds support for elasticsearch 1.5
* Adds support for Elasticsearch 1.5
[float]
==== 1.1.1

19
shield/docs/public/securing-communications.asciidoc Normal file
View File

@ -0,0 +1,19 @@
[[securing-communications]]
== Securing Communications with Encryption and IP Filtering
Elasticsearch nodes store data that may be confidential. Attacks on the data may come from the network. These attacks
could include sniffing of the data, manipulation of the data, and attempts to gain access to the server and thus the
files storing the data. Securing your nodes with the procedures below helps to reduce risk from network-based attacks.
This section shows how to:
* Encrypt traffic to and from Elasticsearch nodes using SSL/TLS,
* Require that nodes authenticate new nodes that join the cluster using SSL certificates, and
* Make it more difficult for remote attackers to issue any commands to Elasticsearch.
The authentication of new nodes helps prevent a rogue node from joining the cluster and receiving data through replication.
include::securing-communications/setting-up-ssl.asciidoc[]
include::securing-communications/enabling-cipher-suites.asciidoc[]
include::securing-communications/separating-node-client-traffic.asciidoc[]
include::securing-communications/using-ip-filtering.asciidoc[]

19
shield/docs/public/securing-communications/enabling-cipher-suites.asciidoc Normal file
View File

@ -0,0 +1,19 @@
[[ciphers]]
=== Enabling Cipher Suites for Stronger Encryption
The SSL/TLS protocols use a cipher suite that determines the strength of encryption used to protect the data. You may
want to increase the strength of encryption used when using a Oracle JVM; the IcedTea OpenJDK ships without these
restrictions in place. This step is not required to successfully use Shield.
The Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files enable additional cipher suites for
Java in a separate JAR file that you need to add to your Java installation. You can download this JAR file from
Oracle's http://www.oracle.com/technetwork/java/javase/downloads/index.html[download page]. The JCE Unlimited Strength
Jurisdiction Policy Files are required for encryption with key lengths greater than 128 bits, such as 256-bit AES
encryption.
After installation, all cipher suites in the JCE are available for use. To enable the use of stronger cipher suites with
Shield, configure the `ciphers` parameter. See the <<ref-ssl-tls-settings, Configuration Parameters for TLS/SSL>> section
of this document for specific parameter information.
NOTE: The JCE Unlimited Strength Jurisdiction Policy Files must be installed on all nodes to establish an improved level
of encryption strength.

65
shield/docs/public/securing-communications/separating-node-client-traffic.asciidoc Normal file
View File

@ -0,0 +1,65 @@
[[separating-node-client-traffic]]
=== Separating node to node and client traffic
Elasticsearch has the feature of so called {ref}/modules-transport.html#_tcp_transport_profiles[tcp transport profiles].
This allows Elasticsearch to bind to several ports and addresses. Shield extends on this functionality to enhance the
security of the cluster by enabling the separation of node to node transport traffic from client transport traffic. This
is important if the client transport traffic is not trusted and could potentially be malicious. To separate the node to
node traffic from the client traffic, add the following to `elasticsearch.yml`:
[source, yaml]
--------------------------------------------------
transport.profiles.client<1>:
port: 9500-9600 <2>
shield:
type: client <3>
--------------------------------------------------
<1> `client` is the name of this example profile
<2> The port range that will be used by transport clients to communicate with this cluster
<3> A type of `client` enables additional filters for added security by denying internal cluster operations (e.g shard
level actions and ping requests)
If supported by your environment, an internal network can be used for node to node traffic and public network can be
used for client traffic by adding the following to `elasticsearch.yml`:
[source, yaml]
--------------------------------------------------
transport.profiles.default.bind_host: 10.0.0.1 <1>
transport.profiles.client.bind_host: 1.1.1.1 <2>
--------------------------------------------------
<1> The bind address for the network that will be used for node to node communication
<2> The bind address for the network used for client communication
If separate networks are not available, then <<ip-filtering, IP Filtering>> can be enabled to limit access to the profiles.
The tcp transport profiles also allow for enabling SSL on a per profile basis. This is useful if you have a secured network
for the node to node communication, but the client is on an unsecured network. To enable SSL on a client profile when SSL is
disabled for node to node communication, add the following to `elasticsearch.yml`:
[source, yaml]
--------------------------------------------------
transport.profiles.client.ssl: true <1>
--------------------------------------------------
<1> This enables SSL on the client profile. The default value for this setting is the value of `shield.transport.ssl`.
When using SSL for transport, a different set of certificates can also be used for the client traffic by adding the
following to `elasticsearch.yml`:
[source, yaml]
--------------------------------------------------
transport.profiles.client.shield.truststore:
path: /path/to/another/truststore
password: changeme
transport.profiles.client.shield.keystore:
path: /path/to/another/keystore
password: changeme
--------------------------------------------------
To change the default behavior that requires certificates for transport clients, set the following value in the `elasticsearch.yml`
file:
[source, yaml]
--------------------------------------------------
transport.profiles.client.shield.ssl.client.auth: no
--------------------------------------------------
This setting keeps certificate authentication active for node-to-node traffic, but removes the requirement to distribute
a signed certificate to transport clients. Please see the <<transport-client, Transport Client>> section.

273
shield/docs/public/07-securing-nodes.asciidoc → shield/docs/public/securing-communications/setting-up-ssl.asciidoc
View File

@ -1,21 +1,5 @@
[[securing-nodes]]
== Securing Nodes
Elasticsearch nodes store data that may be confidential. Attacks on the data may come from the network. These attacks
could include sniffing of the data, manipulation of the data, and attempts to gain access to the server and thus the
files storing the data. Securing your nodes with the procedures below helps to reduce risk from network-based attacks.
This section shows how to:
* encrypt traffic to and from Elasticsearch nodes using SSL/TLS,
* require that nodes authenticate new nodes that join the cluster using SSL certificates, and
* make it more difficult for remote attackers to issue any commands to Elasticsearch.
The authentication of new nodes will help prevent a rogue node from joining the cluster and receiving data through
replication.
[[ssl-tls]]
=== Encryption and Certificates
=== Setting Up SSL/TLS on a Cluster
Shield allows for the installation of X.509 certificates that establish trust between nodes. When a client connects to a
node using SSL or TLS, the node will present its certificate to the client, and then as part of the handshake process the
@ -32,12 +16,12 @@ installed to trust the other nodes in the cluster.
The best practice with Shield is to use certificates signed by a CA. Self-signed certificates introduce a lot of
overhead as they require each client to trust every self-signed certificate. Self-signed certificates also limit
the elasticity of elasticsearch as adding a new node to the cluster requires a restart of every node after
the elasticity of Elasticsearch as adding a new node to the cluster requires a restart of every node after
installing the new node's certificate. This overhead is not present when using a CA as a new node only needs a
certificate signed by the CA to establish trust with the other nodes in the cluster.
Many organizations have a CA to sign certificates for each nodes. If not, see
<<certificate-authority, Appendix - Certificate Authority>> for instructions on setting up a CA.
<<certificate-authority, Setting Up a Certificate Authority>> for instructions on setting up a CA.
The following steps will need to be repeated on each node to setup SSL/TLS:
@ -51,7 +35,8 @@ The steps in this procedure use the <<keytool,`keytool`>> command-line utility.
WARNING: Nodes that do not have SSL/TLS encryption enabled send passwords in plain text.
=== Set up a keystore
[float]
==== Set up a keystore
These instructions show how to place a CA certificate and a certificate for the node in a single keystore.
You can optionally store the CA certificate in a separate truststore. The configuration for this is
@ -77,8 +62,9 @@ will need to remember this password as it will be needed for all further interac
The keystore needs an update when the CA expires.
[float]
[[private-key]]
=== Generate a node private key and certificate
==== Generate a node private key and certificate
This step creates a private key and certificate that the node will use to identify itself. This step must
be done for every node.
@ -163,8 +149,9 @@ Enter key password for <mydomain>
Now you have a certificate and private key stored in `node01.jks`.
[float]
[[generate-csr]]
=== Create a certificate signing request
==== Create a certificate signing request
The next step is to get the node certificate signed by your CA. To do this you must generate a _Certificate Signing
Request_ (CSR) with the `keytool -certreq` command:
@ -187,7 +174,8 @@ be specified in this list.
The resulting file -- `node01.csr` -- is your _Certificate Signing Request_, or _CSR file_.
==== Send the signing request
[float]
===== Send the signing request
Send the CSR file to the Certificate Authority for signing. The Certificate Authority will sign the certificate and
return a signed version of the certificate. See <<sign-csr>> if you are running your own Certificate Authority.
@ -195,7 +183,8 @@ return a signed version of the certificate. See <<sign-csr>> if you are running
NOTE: When running multiple nodes on the same host, the same signed certificate can be used on each node or a unique
certificate can be requested per node if your CA supports multiple certificates with the same common name.
=== Install the newly signed certificate
[float]
==== Install the newly signed certificate
Replace the existing unsigned certificate by importing the new signed certificate from your CA into the node keystore:
@ -218,17 +207,19 @@ can be deleted from the certificate. The following openssl command will remove t
openssl x509 -in node01-signed.crt -out node01-signed-noheaders.crt
--------------------------------------------------
=== Configure the keystores and enable SSL
[float]
==== Configure the keystores and enable SSL
NOTE: All ssl related node settings that are considered to be highly sensitive and therefore are not exposed via the
{ref}/cluster-nodes-info.html#cluster-nodes-info[nodes info API].
The next step is to configure the node to enable SSL, to identify itself using
its signed certificate, and to verify the identify of incoming connections.
You need to configure the node to enable SSL, identify itself using
its signed certificate, and verify the identify of incoming connections.
The settings below should be added to the main `elasticsearch.yml` config file.
==== Node identity
[float]
===== Node identity
The `node01.jks` contains the certificate that `node01` will use to identify
itself to other nodes in the cluster, to transport clients, and to HTTPS
@ -251,8 +242,9 @@ shield.ssl.keystore.key_password: myKeyPass <1>
--------------------------------------------------
<1> The password entered at the end of the `keytool -genkey` command
[float]
[[create-truststore]]
==== Optional truststore configuration
===== Optional truststore configuration
The truststore holds the trusted CA certificates. Shield will use the keystore as the truststore
by default. You can optionally provide a separate path for the truststore. In this case, Shield
will use the keystore for the node's private key and the configured truststore for trusted certificates.
@ -282,7 +274,7 @@ shield.ssl.truststore.password: myPass <2>
<1> The full path to the truststore file.
<2> The password used to decrypt the `truststore.jks` keystore.
[float]
[[ssl-transport]]
==== Enable SSL on the transport layer
@ -296,6 +288,7 @@ shield.transport.ssl: true
Regardless of this setting, transport clients can only connect to the cluster with a valid username and password.
[float]
[[disable-multicast]]
==== Disable multicast
@ -311,6 +304,7 @@ discovery.zen.ping.unicast.hosts: ["node01:9300", "node02:9301"]
You can learn more about unicast configuration in the {ref}/modules-discovery.html[Zen Discovery] documentation.
[float]
[[ssl-http]]
==== Enable SSL on the HTTP layer
@ -328,222 +322,3 @@ Congratulations! At this point, you have a node with encryption enabled for both
Your node will correctly present its certificate to other nodes or clients when connecting. There are optional,
more advanced features you may use to further configure or protect your node. They are described in the following
paragraphs.
[[ciphers]]
=== Enabling Cipher Suites for Stronger Encryption
The SSL/TLS protocols use a cipher suite that determines the strength of encryption used to protect the data. You may
want to increase the strength of encryption used when using a Oracle JVM; the IcedTea OpenJDK ships without these
restrictions in place. This step is not required to successfully use Shield.
The Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files enable additional cipher suites for
Java in a separate JAR file that you need to add to your Java installation. You can download this JAR file from
Oracle's http://www.oracle.com/technetwork/java/javase/downloads/index.html[download page]. The JCE Unlimited Strength
Jurisdiction Policy Files are required for encryption with key lengths greater than 128 bits, such as 256-bit AES
encryption.
After installation, all cipher suites in the JCE are available for use. To enable the use of stronger cipher suites with
Shield, configure the `ciphers` parameter. See the <<ref-ssl-tls-settings, Configuration Parameters for TLS/SSL>> section
of this document for specific parameter information.
NOTE: The JCE Unlimited Strength Jurisdiction Policy Files must be installed on all nodes to establish an improved level
of encryption strength.
[[separating-node-client-traffic]]
=== Separating node to node and client traffic
Elasticsearch has the feature of so called {ref}/modules-transport.html#_tcp_transport_profiles[tcp transport profiles].
This allows elasticsearch to bind to several ports and addresses. Shield extends on this functionality to enhance the
security of the cluster by enabling the separation of node to node transport traffic from client transport traffic. This
is important if the client transport traffic is not trusted and could potentially be malicious. To separate the node to
node traffic from the client traffic, add the following to `elasticsearch.yml`:
[source, yaml]
--------------------------------------------------
transport.profiles.client<1>:
port: 9500-9600 <2>
shield:
type: client <3>
--------------------------------------------------
<1> `client` is the name of this example profile
<2> The port range that will be used by transport clients to communicate with this cluster
<3> A type of `client` enables additional filters for added security by denying internal cluster operations (e.g shard
level actions and ping requests)
If supported by your environment, an internal network can be used for node to node traffic and public network can be
used for client traffic by adding the following to `elasticsearch.yml`:
[source, yaml]
--------------------------------------------------
transport.profiles.default.bind_host: 10.0.0.1 <1>
transport.profiles.client.bind_host: 1.1.1.1 <2>
--------------------------------------------------
<1> The bind address for the network that will be used for node to node communication
<2> The bind address for the network used for client communication
If separate networks are not available, then <<ip-filtering, IP Filtering>> can be enabled to limit access to the profiles.
The tcp transport profiles also allow for enabling SSL on a per profile basis. This is useful if you have a secured network
for the node to node communication, but the client is on an unsecured network. To enable SSL on a client profile when SSL is
disabled for node to node communication, add the following to `elasticsearch.yml`:
[source, yaml]
--------------------------------------------------
transport.profiles.client.ssl: true <1>
--------------------------------------------------
<1> This enables SSL on the client profile. The default value for this setting is the value of `shield.transport.ssl`.
When using SSL for transport, a different set of certificates can also be used for the client traffic by adding the
following to `elasticsearch.yml`:
[source, yaml]
--------------------------------------------------
transport.profiles.client.shield.truststore:
path: /path/to/another/truststore
password: changeme
transport.profiles.client.shield.keystore:
path: /path/to/another/keystore
password: changeme
--------------------------------------------------
To change the default behavior that requires certificates for transport clients, set the following value in the `elasticsearch.yml`
file:
[source, yaml]
--------------------------------------------------
transport.profiles.client.shield.ssl.client.auth: no
--------------------------------------------------
This setting keeps certificate authentication active for node-to-node traffic, but removes the requirement to distribute
a signed certificate to transport clients. Please see the <<transport-client, Transport Client>> section.
[[ip-filtering]]
=== IP filtering
You can apply IP filtering to application clients, node clients, or transport clients, in addition to other nodes that
are attempting to join the cluster.
If a node's IP address is on the blacklist, Shield will still allow the connection to Elasticsearch. The connection will
be dropped immediately, and no requests will be processed.
NOTE: Elasticsearch installations are not designed to be publicly accessible over the Internet. IP Filtering and the
other security capabilities of Shield do not change this condition.
==== Node filtering
Shield features an access control feature that allows or rejects hosts, domains, or subnets.
===== Configuration setting
IP filtering configuration is part of the `elasticsearch.yml` file
===== Configuration Syntax
The configuration file for IP filtering consists of a list of one `allow` and `deny` statement each, possibly containing an array. Also, the `allow` rule is prioritized over the `deny` rule.
.Example 1. Allow/Deny Statement Priority
[source,yaml]
--------------------------------------------------
shield.transport.filter.allow: "192.168.0.1"
shield.transport.filter.deny: "192.168.0.0/24"
--------------------------------------------------
The `_all` keyword denies all connections that are not explicitly allowed earlier in the file.
.Example 2. `_all` Keyword Usage
[source,yaml]
--------------------------------------------------
shield.transport.filter.allow: [ "192.168.0.1", "192.168.0.2", "192.168.0.3", "192.168.0.4" ]
shield.transport.filter.deny: _all
--------------------------------------------------
IP Filtering configuration files support IPv6 addresses.
.Example 3. IPv6 Filtering
[source,yaml]
--------------------------------------------------
shield.transport.filter.allow: "2001:0db8:1234::/48"
shield.transport.filter.deny: "1234:0db8:85a3:0000:0000:8a2e:0370:7334"
--------------------------------------------------
Shield supports hostname filtering when DNS lookups are available.
.Example 4. Hostname Filtering
[source,yaml]
--------------------------------------------------
shield.transport.filter.allow: localhost
shield.transport.filter.deny: '*.google.com'
--------------------------------------------------
==== Disabling IP Filtering
Disabling IP filtering can slightly improve performance under some conditions. To disable IP filtering entirely, set the
value of the `shield.transport.filter.enabled` attribute in the `elasticsearch.yml` configuration file to `false`.
.Example 5. Disabled IP Filtering
[source,yaml]
--------------------------------------------------
shield.transport.filter.enabled: false
--------------------------------------------------
You can also disable IP filtering for the transport protocol but enable it for HTTP only like this
.Example 6. Enable HTTP based IP Filtering
[source,yaml]
--------------------------------------------------
shield.transport.filter.enabled: false
shield.http.filter.enabled: true
--------------------------------------------------
==== Support for TCP transport profiles
In order to support bindings on multiple host, you can specify the profile name as a prefix in order to allow/deny based on profiles
.Example 7. Profile based filtering
[source,yaml]
--------------------------------------------------
shield.transport.filter.allow: 172.16.0.0/24
shield.transport.filter.deny: _all
transport.profiles.client.shield.filter.allow: 192.168.0.0/24
transport.profiles.client.shield.filter.deny: _all
--------------------------------------------------
Note: When you do not specify a profile, `default` is used automatically.
==== Support for HTTP
You may want to have different filtering between the transport and HTTP protocol
.Example 8. HTTP only filtering
[source,yaml]
--------------------------------------------------
shield.transport.filter.allow: localhost
shield.transport.filter.deny: '*.google.com'
shield.http.filter.allow: 172.16.0.0/16
shield.http.filter.deny: _all
--------------------------------------------------
[[dynamic-ip-filtering]]
==== Dynamically updating ip filter settings added[1.1.0]
In case of running in an environment with highly dynamic IP addresses like cloud based hosting it is very hard to know the IP addresses upfront when provisioning a machine. Instead of changing the configuration file and restarting the node, you can use the Cluster Update Settings API like this
[source,json]
--------------------------------------------------
curl -XPUT localhost:9200/_cluster/settings -d '{
"persistent" : {
"shield.transport.filter.allow" : "172.16.0.0/24"
}
}'
--------------------------------------------------
You can also disable filtering completely setting `shield.transport.filter.enabled` like this
[source,json]
--------------------------------------------------
curl -XPUT localhost:9200/_cluster/settings -d '{
"persistent" : {
"shield.transport.filter.enabled" : false
}
}'
--------------------------------------------------
Note: In order to not lock yourself out, the default bound transport address will never be denied. This means you can always SSH into a system and use curl to apply changes.

131
shield/docs/public/securing-communications/using-ip-filtering.asciidoc Normal file
View File

@ -0,0 +1,131 @@
[[ip-filtering]]
=== Using IP Filtering
You can apply IP filtering to application clients, node clients, or transport clients, in addition to other nodes that
are attempting to join the cluster.
If a node's IP address is on the blacklist, Shield will still allow the connection to Elasticsearch. The connection will
be dropped immediately, and no requests will be processed.
NOTE: Elasticsearch installations are not designed to be publicly accessible over the Internet. IP Filtering and the
other security capabilities of Shield do not change this condition.
[float]
==== Enabling IP filtering
Shield features an access control feature that allows or rejects hosts, domains, or subnets.
You configure IP filtering by specifying the `shield.transport.filter.allow` and `shield.transport.filter.deny` settings in in `elasticsearch.yml`. Allow rules take prececence over the deny rules.
.Example 1. Allow/Deny Statement Priority
[source,yaml]
--------------------------------------------------
shield.transport.filter.allow: "192.168.0.1"
shield.transport.filter.deny: "192.168.0.0/24"
--------------------------------------------------
The `_all` keyword denies all connections that are not explicitly allowed earlier in the file.
.Example 2. `_all` Keyword Usage
[source,yaml]
--------------------------------------------------
shield.transport.filter.allow: [ "192.168.0.1", "192.168.0.2", "192.168.0.3", "192.168.0.4" ]
shield.transport.filter.deny: _all
--------------------------------------------------
IP Filtering configuration files support IPv6 addresses.
.Example 3. IPv6 Filtering
[source,yaml]
--------------------------------------------------
shield.transport.filter.allow: "2001:0db8:1234::/48"
shield.transport.filter.deny: "1234:0db8:85a3:0000:0000:8a2e:0370:7334"
--------------------------------------------------
Shield supports hostname filtering when DNS lookups are available.
.Example 4. Hostname Filtering
[source,yaml]
--------------------------------------------------
shield.transport.filter.allow: localhost
shield.transport.filter.deny: '*.google.com'
--------------------------------------------------
[float]
==== Disabling IP Filtering
Disabling IP filtering can slightly improve performance under some conditions. To disable IP filtering entirely, set the
value of the `shield.transport.filter.enabled` attribute in the `elasticsearch.yml` configuration file to `false`.
.Example 5. Disabled IP Filtering
[source,yaml]
--------------------------------------------------
shield.transport.filter.enabled: false
--------------------------------------------------
You can also disable IP filtering for the transport protocol but enable it for HTTP only like this
.Example 6. Enable HTTP based IP Filtering
[source,yaml]
--------------------------------------------------
shield.transport.filter.enabled: false
shield.http.filter.enabled: true
--------------------------------------------------
[float]
==== Specifying TCP transport profiles
In order to support bindings on multiple host, you can specify the profile name as a prefix in order to allow/deny based on profiles
.Example 7. Profile based filtering
[source,yaml]
--------------------------------------------------
shield.transport.filter.allow: 172.16.0.0/24
shield.transport.filter.deny: _all
transport.profiles.client.shield.filter.allow: 192.168.0.0/24
transport.profiles.client.shield.filter.deny: _all
--------------------------------------------------
Note: When you do not specify a profile, `default` is used automatically.
[float]
==== HTTP Filtering
You may want to have different filtering between the transport and HTTP protocol
.Example 8. HTTP only filtering
[source,yaml]
--------------------------------------------------
shield.transport.filter.allow: localhost
shield.transport.filter.deny: '*.google.com'
shield.http.filter.allow: 172.16.0.0/16
shield.http.filter.deny: _all
--------------------------------------------------
[float]
[[dynamic-ip-filtering]]
==== Dynamically updating ip filter settings added[1.1.0]
In case of running in an environment with highly dynamic IP addresses like cloud based hosting it is very hard to know the IP addresses upfront when provisioning a machine. Instead of changing the configuration file and restarting the node, you can use the Cluster Update Settings API like this
[source,json]
--------------------------------------------------
curl -XPUT localhost:9200/_cluster/settings -d '{
"persistent" : {
"shield.transport.filter.allow" : "172.16.0.0/24"
}
}'
--------------------------------------------------
You can also disable filtering completely setting `shield.transport.filter.enabled` like this
[source,json]
--------------------------------------------------
curl -XPUT localhost:9200/_cluster/settings -d '{
"persistent" : {
"shield.transport.filter.enabled" : false
}
}'
--------------------------------------------------
NOTE: In order to not lock yourself out, the default bound transport address will never be denied. This means you can always SSH into a system and use curl to apply changes.

63
shield/docs/public/06-authentication.asciidoc → shield/docs/public/setting-up-authentication.asciidoc
View File

@ -1,20 +1,16 @@
[[authentication]]
== Authentication
[[setting-up-authentication]]
== Setting Up User Authentication
Authentication identifies an individual. To gain access to restricted resources, a user must prove their identity, via
passwords, credentials, or some other means (typically referred to as authentication tokens).
[[realms]]
[float]
=== Realms
A _realm_ is an authentication mechanism, which Shield uses to resolve and authenticate users and their roles. Shield
currently provides four realm types:
[horizontal]
_esusers_:: A native authentication system built into Shield and available by default. See <<esusers>>.
_LDAP_:: Authentication via an external Lightweight Directory Protocol. See <<ldap>>.
_Active Directory_:: Authentication via an external Active Directory service. See <<active_directory>>.
_Active Directory_:: Authentication via an external Active Directory service. See <<active-directory>>.
_PKI_:: Authentication through the use of trusted X.509 certificates. See <<pki>>.
@ -70,7 +66,7 @@ shield.authc:
...
ad1:
type: active_directory
type: active-directory
order: 3
url: 'url_to_ad'
----------------------------------------
@ -78,7 +74,7 @@ shield.authc:
As can be seen above, each realm has a unique name that identifies it. There are three settings that are common to all
realms:
* `type` (required) - Identifies the type of the ream (currently can be `esusers`, `ldap` or `active_directory`). The realm
* `type` (required) - Identifies the type of the ream (currently can be `esusers`, `ldap` or `active-directory`). The realm
type determines what other settings the realms should be configured with.
* `order` (optional) - Defines the priority/index of the realm within the realm chain. This will determine when the realm
will be consulted during authentication.
@ -88,55 +84,22 @@ realms:
The realm types can roughly be categorized to two categories:
* `internal` - Internal realm types are realms that are internal to elasticsearch and don't require any communication with
* `internal` - Internal realm types are realms that are internal to Elasticsearch and don't require any communication with
external parties - they are fully managed by shield. There can only be a maximum of one configured realm
per internal realm type. (Currently, only one internal realm type exists - `esusers`).
* `external` - External realm types are realms that require interaction with parties/components external to elasticsearch,
* `external` - External realm types are realms that require interaction with parties/components external to Elasticsearch,
typically, with enterprise level identity management systems. Unlike the `internal` realms, there can be
as many `external` realms as one would like - each with a unique name and different settings. (Currently
the only `external` realm types that exist are `ldap` and `active_directory`).
the only `external` realm types that exist are `ldap` and `active-directory`).
[[anonymous-access]]
[float]
=== Anonymous Access added[1.1.0]
The authentication process can be split into two phases - token extraction and user authentication. During the first
phase (token extraction phase), the configured realms are requested to try and extract/resolve an authentication token
from the incoming request. The first realm that finds an authentication token in the request "wins", meaning, the found
authentication token will be used for authentication (moving to the second phase - user authentication - where each realm
that support this authentication token type will try to authenticate the user).
include::setting-up-authentication/enabling-anonymous-access.asciidoc[]
In the event where no authentication token was resolved by any of the active realms, the incoming request is considered
to be anonymous.
include::setting-up-authentication/configuring-esusers-realm.asciidoc[]
By default, anonymous requests are rejected and an authentication error is returned (status code `401`). It is possible
to change this behaviour and instruct Shield to associate an default/anonymous user with the anonymous request. This can
be done by configuring the following settings in the `elasticsearch.yml` file:
include::setting-up-authentication/configuring-ldap-realm.asciidoc[]
[source,yaml]
----------------------------------------
shield.authc:
anonymous:
username: anonymous_user <1>
roles: role1, role2 <2>
authz_exception: true <3>
----------------------------------------
<1> The username/principal of the anonymous user. This setting is optional and will be set to `_es_anonymous_user` by default
when not configured.
<2> The roles that will be associated with the anonymous user. This setting is mandatory - without it, anonymous access
will be disabled (i.e. anonymous requests will be rejected and return an authentication error)
<3> When `true`, a HTTP 403 response will be returned when the anonymous user does not have the appropriate permissions
for the requested action. The web browser will not be prompt the user to provide credentials to access the requested
resource. When set to `false`, a HTTP 401 will be returned allowing for credentials to be provided for a user with
the appropriate permissions. If you are using anonymous access in combination with HTTP, setting this to `false` may
be necessary if your client does not support preemptive basic authentication. This setting is optional and will be
set to `true` by default.
include::setting-up-authentication/configuring-active-directory-realm.asciidoc[]
include::realms/01-esusers.asciidoc[]
include::realms/02-ldap.asciidoc[]
include::realms/03-active-directory.asciidoc[]
include::realms/04-pki.asciidoc[]
include::setting-up-authentication/configuring-pki-realm.asciidoc[]

50
shield/docs/public/realms/03-active-directory.asciidoc → shield/docs/public/setting-up-authentication/configuring-active-directory-realm.asciidoc
View File

@ -1,5 +1,5 @@
[[active_directory]]
=== Active Directory Authentication
[[active-directory]]
=== Configuring an Active Directory Realm
A secure Elasticsearch cluster can authenticate users from a Active Directory using the LDAP protocol.
With the Active Directory Realm Authentication, you can assign roles to Active Directory groups. When a user
@ -31,7 +31,7 @@ server. These certificates should be put into each node's keystore/truststore.
==== Active Directory Realm Configuration
Like all realms, the `active_directory` realm is configured under the `shield.authc.realms` settings namespace in the
Like all realms, the `active-directory` realm is configured under the `shield.authc.realms` settings namespace in the
`elasticsearch.yml` file. The following snippet shows an example of such configuration:
.Example Active Directory Configuration
@ -40,8 +40,8 @@ Like all realms, the `active_directory` realm is configured under the `shield.au
shield:
authc:
realms:
active_directory:
type: active_directory
active-directory:
type: active-directory
order: 0
domain_name: example.com
unmapped_groups_as_roles: true
@ -53,7 +53,7 @@ shield:
.Active Directory Realm Settings
|=======================
| Setting | Required | Description
| `type` | yes | Indicates the realm type and must be set to `active_directory`
| `type` | yes | Indicates the realm type and must be set to `active-directory`
| `order` | no | Indicates the priority of this realm within the realm chain. Realms with lower order will be consulted first. Although not required, it is highly recommended to explicitly set this value when multiple realms are configured. Defaults to `Integer.MAX_VALUE`.
| `enabled` | no | Indicates whether this realm is enabled/disabled. Provides an easy way to disable realms in the chain without removing their configuration. Defaults to `true`.
| `domain_name` | yes | Specifies the domain name of the Active Directory. The cluster can derive the LDAP URL and `user_search_dn` fields from values in this element if those fields are not otherwise specified.
@ -64,10 +64,10 @@ shield:
| `group_search.base_dn` | no | Specifies the context to search for groups in which the user has membership. The default value for this element is the root of the Active Directory domain.
| `group_search.scope` | no | Specifies whether the group search should be `sub_tree` (default), `one_level` or `base`. `one_level` searches for groups directly contained within the `base_dn`. `sub_tree` searches all objects contained under `base_dn`. `base` specifies that the `base_dn` is a group object, and that it is the only group considered.
| `unmapped_groups_as_roles` | no | When set to `true`, the names of any unmapped LDAP groups are used as role names and assigned to the user. The default value is `false`.
| `files.role_mapping` | no | Specifies the path and file name for the <<ad-role-mapping, YAML role mapping configuration file>>. The default file name is `role_mapping.yml` in the <<shield-config,Shield config directory>>.
| `files.role_mapping` | no | Specifies the path and file name for the <<ad-role-mapping, YAML role mapping configuration file>>. By default it is `ES_HOME/config/shield/users/role_mapping.yml`.
| `follow_referrals` | no | Boolean value that specifies whether Shield should follow referrals returned by the LDAP server. Referrals are URLs returned by the server that are to be used to continue the LDAP operation (e.g. search). Default is `true`.
| `hostname_verification` | no | When set to `true`, hostname verification will be performed when connecting to a LDAP server. The hostname or IP address used in the `url` must match one of the names in the certificate or the connection will not be allowed. Defaults to `true`.
| `cache.ttl` | no | Specified the time-to-live for cached user entries (a user and its credentials will be cached for this configured period of time). Defaults to `20m` (use the standard elasticsearch {ref}/common-options.html#time-units[time units])
| `cache.ttl` | no | Specified the time-to-live for cached user entries (a user and its credentials will be cached for this configured period of time). Defaults to `20m` (use the standard Elasticsearch {ref}/common-options.html#time-units[time units])
| `cache.max_users` | no | Specified the maximum number of user entries that can live in the cache at a given time. Defaults to 100,000.
| `cache.hash_algo` | no | (Expert Setting) Specifies the hashing algorithm that will be used for the in-memory cached user credentials (see <<ad-cache-hash-algo,here>> for possible values).
|=======================
@ -83,38 +83,6 @@ NOTE: Binding to Active Directory fails when the domain name is not mapped in DN
by a Windows DNS server, add a mapping for the domain in the local `/etc/hosts` file.
[[ad-role-mapping]]
==== Mapping Users and Groups to Roles
By default, the file that maps users and groups to roles is `config/shield/role_mapping.yml`. You can configure
the path and name of the mapping file by setting the appropriate value for the `shield.authc.active_directory.files.role_mapping`
configuration parameter. When you map roles to groups, the roles of a user in that group are the combination of the
roles assigned to that group and the roles assigned to that user.
The `role_mapping.yml` file uses the YAML format. Within a mapping file, Elasticsearch roles are keys and Active
Directory groups and users are values. The mapping can have a many-to-many relationship.
.Example Group and Role Mapping File
[source, yaml]
------------------------------------------------------------
# Example LDAP group mapping configuration:
# roleA: <1>
# - groupA-DN <2>
# - groupB-DN
# - user1-DN <3>
monitoring:
- "cn=admins,dc=example,dc=com"
user:
- "cn=users,dc=example,dc=com"
- "cn=admins,dc=example,dc=com"
- "cn=John Doe,cn=contractors,dc=example,dc=com"
------------------------------------------------------------
<1> The name of the elasticsearch role found in the <<roles-file, roles file>>
<2> Example specifying the distinguished name of a Active Directory group
<3> Example specifying the distinguished name of a Active Directory user
After setting up role mappings, copy this file to each node. Tools like Puppet or Chef can help with this.
==== Adding a Server Certificate
To use SSL/TLS to access your Active Directory server over an URL with the `ldaps` protocol, make sure the client
@ -139,7 +107,7 @@ following command, providing the password for the keystore when prompted.
keytool -import -keystore node01.jks -file ldap.crt
----------------------------------------------------------------------------------------------------
If not already configured, add the path of the keystore/truststore to `elasticsearch.yml` as described in <<securing-nodes>>.
If not already configured, add the path of the keystore/truststore to `elasticsearch.yml` as described in <<securing-communications, Securing Communications with Encryption and IP Filtering>>.
By default, Shield will attempt to verify the hostname or IP address used in the `url` with the values in the
certificate. If the values in the certificate do not match, Shield will not allow a connection to the Active Directory server.
This behavior can be disabled by setting the `hostname_verification` property.

41
shield/docs/public/setting-up-authentication/configuring-esusers-realm.asciidoc Normal file
View File

@ -0,0 +1,41 @@
[[esusers]]
=== Configuring an esusers Realm
The _esusers_ realm is the default Shield realm. The _esusers_ realm enables the registration of users, passwords for
those users, and associates those users with roles. The `esusers` command-line tool assists with the registration and
administration of users.
==== `esusers` Realm Settings
Like all other realms, the `esusers` realm is configured under the `shield.authc.realms` settings namespace in the
`elasticsearch.yml` file. The following snippet shows an example of such configuration:
.Example `esusers` Realm Configuration
[source, yaml]
------------------------------------------------------------
shield:
authc:
realms:
default:
type: esusers
order: 0
------------------------------------------------------------
[[esusers-settings]]
.`esusers` Realm Settings
|=======================
| Setting | Required | Description
| `type` | yes | Indicates the realm type and must be set to `esusers`.
| `order` | no | Indicates the priority of this realm within the realm chain. Realms with lower order will be consulted first. Although not required, it is highly recommended to explicitly set this value when multiple realms are configured. Defaults to `Integer.MAX_VALUE`.
| `enabled` | no | Indicates whether this realm is enabled/disabled. Provides an easy way to disable realms in the chain without removing their configuration. Defaults to `true`.
| `files.users` | no | Points to the location of the `users` file where the users and their passwords are stored. By default, it is `ES_HOME/config/shield/users`.
| `files.users_roles` | no | Points to the location of the `users_roles` file where the users and their roles are stored. By default, it is `ES_HOME/config/shield/users_roles`.
| `cache.ttl` | no | Specified the time-to-live for cached user entries (a user and its credentials will be cached for this configured period of time). Defaults to `20m` (use the standard Elasticsearch {ref}/common-options.html#time-units[time units]).
| `cache.max_users` | no | Specified the maximum number of user entries that can live in the cache at a given time. Defaults to 100,000.
| `cache.hash_algo` | no | (Expert Setting) Specifies the hashing algorithm that will be used for the in-memory cached user credentials (see <<esusers-cache-hash-algo,here>> for possible values).
|=======================
NOTE: When no realms are explicitly configured in `elasticsearch.yml`, a default realm chain will be created that holds
a single `esusers` realm. If you wish to only work with `esusers` realm and you're satisfied with the default
files paths, there is no real need to add the above configuration.

41
shield/docs/public/realms/02-ldap.asciidoc → shield/docs/public/setting-up-authentication/configuring-ldap-realm.asciidoc
View File

@ -1,5 +1,5 @@
[[ldap]]
=== LDAP Authentication
=== Configuring an LDAP Realm
A secure Elasticsearch cluster can authenticate users from a Lightweight Directory Access Protocol (LDAP) directory.
With LDAP Authentication, you can assign roles to LDAP groups. When a user authenticates with LDAP, the privileges for
@ -101,10 +101,10 @@ shield:
| `unmapped_groups_as_roles` | no | When set to `true`, the names of any unmapped LDAP groups are used as role names and assigned to the user. The default value is `false`.
| `connect_timeout` | no | The timeout period for establishing an LDAP connection. An `s` at the end indicates seconds, or `ms` indicates milliseconds. Defaults to "5s" - for 5 seconds
| `read_timeout` | no | The timeout period for an LDAP operation. An `s` at the end indicates seconds, or `ms` indicates milliseconds. Defaults to "5s" - for 5 seconds
| `files.role_mapping` | no | Specifies the path and file name for the <<ldap-role-mapping, YAML role mapping configuration file>>. The default file name is `role_mapping.yml` in the <<shield-config,Shield config directory>>.
| `files.role_mapping` | no | Specifies the path and file name for the <<ldap-role-mapping, YAML role mapping configuration file>>. By default, it is `ES_HOME/config/shield/role_mapping.yml`.
| `follow_referrals` | no | Boolean value that specifies whether Shield should follow referrals returned by the LDAP server. Referrals are URLs returned by the server that are to be used to continue the LDAP operation (e.g. search). Default is `true`.
| `hostname_verification` | no | When set to `true`, hostname verification will be performed when connecting to a LDAP server. The hostname or IP address used in the `url` must match one of the names in the certificate or the connection will not be allowed. Defaults to `true`.
| `cache.ttl` | no | Specified the time-to-live for cached user entries (a user and its credentials will be cached for this configured period of time). Defaults to `20m` (use the standard elasticsearch {ref}/common-options.html#time-units[time units]).
| `cache.ttl` | no | Specified the time-to-live for cached user entries (a user and its credentials will be cached for this configured period of time). Defaults to `20m` (use the standard Elasticsearch {ref}/common-options.html#time-units[time units]).
| `cache.max_users` | no | Specified the maximum number of user entries that can live in the cache at a given time. Defaults to 100,000.
| `cache.hash_algo` | no | (Expert Setting) Specifies the hashing algorithm that will be used for the in-memory cached user credentials (see <<ldap-cache-hash-algo,here>> for possible values).
|=======================
@ -135,39 +135,6 @@ NOTE: If any settings starting with `user_search` are specified the `user_dn_t
NOTE: `bind_dn`, `bind_password` and `hostname_verification` are considered to be senstivie settings and therefore are not exposed via
{ref}/cluster-nodes-info.html#cluster-nodes-info[nodes info API].
[[ldap-role-mapping]]
==== Mapping Users and Groups to Roles
By default, the file that maps users and groups to roles is `config/shield/role_mapping.yml`. You can configure
the path and name of the mapping file by setting the appropriate value for the `shield.authc.ldap.files.role_mapping`
configuration parameter. When you map roles to groups, the roles of a user in that group are the combination of the
roles assigned to that group and the roles assigned to that user.
The `role_mapping.yml` file uses the YAML format. Within a mapping file, Elasticsearch roles are keys and LDAP groups
and users are values. The mapping can have a many-to-many relationship.
.Example Role Mapping File
[source, yaml]
------------------------------------------------------------
# Example LDAP group mapping configuration:
# roleA: <1>
# - groupA-DN <2>
# - groupB-DN
# - user1-DN <3>
monitoring:
- "cn=admins,dc=example,dc=com"
user:
- "cn=users,dc=example,dc=com"
- "cn=admins,dc=example,dc=com"
- "cn=John Doe,cn=contractors,dc=example,dc=com"
------------------------------------------------------------
<1> The name of the elasticsearch role found in the <<roles-file, roles file>>
<2> Example specifying the distinguished name of a LDAP group
<3> Example specifying the distinguished name of a LDAP user added[1.1.0]
After setting up role mappings, copy this file to each node. Tools like Puppet or Chef can help with this.
==== Adding an LDAP server certificate
To use SSL/TLS to access your LDAP server over an URL with the `ldaps` protocol, make sure the LDAP client used by
@ -194,7 +161,7 @@ following command, providing the password for the keystore when prompted.
keytool -import -keystore node01.jks -file ldap.crt
----------------------------------------------------------------------------------------------------
If not already configured, add the path of the keystore/truststore to `elasticsearch.yml` as described in <<securing-nodes>>.
If not already configured, add the path of the keystore/truststore to `elasticsearch.yml` as described in <<securing-communications, Securing Communications with Encryption and IP Filtering>>.
By default, Shield will attempt to verify the hostname or IP address used in the `url` with the values in the
certificate. If the values in the certificate do not match, Shield will not allow a connection to the LDAP server. This
behavior can be disabled by setting the `hostname_verification` property.

31
shield/docs/public/realms/04-pki.asciidoc → shield/docs/public/setting-up-authentication/configuring-pki-realm.asciidoc
View File

@ -1,5 +1,5 @@
[[pki]]
=== PKI Authentication
=== Configuring a PKI Realm
added[1.3.0] Shield allows for authentication through the use of Public Key Infrastructure (PKI). This works by requiring
clients to present X.509 certificates that are used for authentication and authorization will be performed by mapping the
@ -73,33 +73,6 @@ shield:
| `truststore.path` | no | The path of a truststore to use. The default truststore is the one defined by <<ref-ssl-tls-settings,SSL/TLS settings>>
| `truststore.password` | no | The password to the truststore. Must be provided if `truststore.path` is set.
| `truststore.algorithm` | no | Algorithm for the trustsore. Default is `SunX509`
| `files.role_mapping` | no | Specifies the path and file name for the <<pki-role-mapping, YAML role mapping configuration file>>. The default file name is `role_mapping.yml` in the <<shield-config,Shield config directory>>.
| `files.role_mapping` | no | Specifies the path and file name for the <<pki-role-mapping, YAML role mapping configuration file>>. By default, it is `ES_HOME/config/shield/role_mapping.yml`.
|=======================
[[pki-role-mapping]]
==== Mapping Users and Groups to Roles
By default, the file that maps users to roles is `config/shield/role_mapping.yml`. You can configure
the path and name of the mapping file by setting the appropriate value for the `.files.role_mapping` configuration
parameter for a specific realm.
The `role_mapping.yml` file uses the YAML format. Within a mapping file, Elasticsearch roles are keys and distinguished
names (DNs) are values. The mapping can have a many-to-many relationship.
.Example Role Mapping File
[source, yaml]
------------------------------------------------------------
# Example group mapping configuration:
# roleA: <1>
# - user1-DN <2>
monitoring:
- "cn=Admin,ou=example,o=com"
user:
- "cn=John Doe,ou=example,o=com"
------------------------------------------------------------
<1> The name of the elasticsearch role found in the <<roles-file, roles file>>
<2> Example specifying the distinguished name of a PKI user
NOTE: For the PKI realm, only the DN of a user can be mapped as there is no concept of a group in PKI
After setting up role mappings, copy this file to each node. Tools like Puppet or Chef can help with this.

34
shield/docs/public/setting-up-authentication/enabling-anonymous-access.asciidoc Normal file
View File

@ -0,0 +1,34 @@
[[anonymous-access]]
=== Enabling Anonymous Access added[1.1.0]
The authentication process can be split into two phases - token extraction and user authentication. During the first
phase (token extraction phase), the configured realms are requested to try and extract/resolve an authentication token
from the incoming request. The first realm that finds an authentication token in the request "wins", meaning, the found
authentication token will be used for authentication (moving to the second phase - user authentication - where each realm
that support this authentication token type will try to authenticate the user).
In the event where no authentication token was resolved by any of the active realms, the incoming request is considered
to be anonymous.
By default, anonymous requests are rejected and an authentication error is returned (status code `401`). It is possible
to change this behaviour and instruct Shield to associate an default/anonymous user with the anonymous request. This can
be done by configuring the following settings in the `elasticsearch.yml` file:
[source,yaml]
----------------------------------------
shield.authc:
anonymous:
username: anonymous_user <1>
roles: role1, role2 <2>
authz_exception: true <3>
----------------------------------------
<1> The username/principal of the anonymous user. This setting is optional and will be set to `_es_anonymous_user` by default
when not configured.
<2> The roles that will be associated with the anonymous user. This setting is mandatory - without it, anonymous access
will be disabled (i.e. anonymous requests will be rejected and return an authentication error)
<3> When `true`, a HTTP 403 response will be returned when the anonymous user does not have the appropriate permissions
for the requested action. The web browser will not be prompt the user to provide credentials to access the requested
resource. When set to `false`, a HTTP 401 will be returned allowing for credentials to be provided for a user with
the appropriate permissions. If you are using anonymous access in combination with HTTP, setting this to `false` may
be necessary if your client does not support preemptive basic authentication. This setting is optional and will be
set to `true` by default.

13
shield/docs/public/appendices/01-certificate-authority.asciidoc → shield/docs/public/setting-up-certificate-authority.asciidoc
View File

@ -1,5 +1,5 @@
[[certificate-authority]]
== Appendix 1. Running a Certificate Authority
== Setting Up a Certificate Authority
A Certificate Authority (CA) can greatly simplify managing trust. Instead of trusting hundreds of certificates
individually, a client only needs to trust the certificate from the CA. When the CA signs other node certificates,
@ -16,13 +16,12 @@ signed certificate that you install on the node.
IMPORTANT: Because a Certificate Authority is a central point for trust, the private keys to the CA must be protected
from compromise.
=== Setting up a CA
To set up a CA, generate a private and public key pair and build a certificate from the public key. This procedure
uses OpenSSL to create the CA certificate and sign CSRs. First, set up a file structure and configuration template for
the CA.
==== Creating the Certificate Authority
[float]
=== Creating a Certificate Authority
Create the `ca` directory along with the `private`, `certs`, and `conf` subdirectories, then populate the required
`serial` and `index.txt` files.
@ -115,7 +114,8 @@ certificates signed by a CA must expire before the CA certificate expires.
<4> Certificate Defaults: The `OrganizationName`, `localityName`, `stateOrProvinceName`, `countryName`, and
`emailAddress` fields are informational. The settings in the above example are the defaults for these values.
=== Create a CA Certificate
[float]
=== Creating a CA Certificate
In the `ca` directory, create the CA certificate and export the certificate. The following command creates and signs
the CA certificate, resulting in a _self-signed_ certificate that establishes the CA as an authority.
@ -170,8 +170,9 @@ Common Name (hostname, IP, or your name) []:Elasticsearch Test CA
You now have a CA private key and a CA certificate (which includes the public key). You can now distribute the CA
certificate and sign CSRs.
[float]
[[sign-csr]]
==== Signing a CSR
=== Signing CSRs
Signing a certificate with the CA means that the CA vouches for the owner of the certificate. The private key that is
linked to the certificate proves certificate ownership. The CSR includes the certificate. Signing a CSR results in a

14
shield/docs/public/appendices/07-trouble-shooting.asciidoc → shield/docs/public/troubleshooting.asciidoc
View File

@ -1,5 +1,5 @@
[[trouble-shooting]]
== Appendix 7. Trouble Shooting
[[troubleshooting]]
== Troubleshooting
[float]
=== `settings`
@ -99,7 +99,7 @@ misconfigured. See <<ref-shield-files, Shield Files>> for more.
|======================
To help track down these possibilities, add `shield.authc: DEBUG` to the `logging.yml` <<shield-config, config file>>. A successful
To help track down these possibilities, add `shield.authc: DEBUG` to the `logging.yml` configuration file in `ES_HOME/config/shield/`. A successful
authentication should produce debug statements that list groups and role mappings.
--
@ -177,7 +177,7 @@ to make an unencrypted call to the REST interface. Please ensure that all applic
REST interface with SSL enabled.
--
`org.jboss.netty.handler.ssl.NotSslRecordException: not an SSL/TLS record:`::
`org.elasticsearch.common.netty.handler.ssl.NotSslRecordException: not an SSL/TLS record:`::
+
--
Indicates that there was incoming plaintext traffic on an SSL connection. This typically occurs when a node is not
@ -208,7 +208,7 @@ shield.http.ssl: true
ERROR: unsupported ciphers [...] were requested but cannot be used in this JVM::
+
--
This error occurs when a SSL/TLS cipher suite is specified that cannot supported by the JVM that elasticsearch is running
This error occurs when a SSL/TLS cipher suite is specified that cannot supported by the JVM that Elasticsearch is running
in. Shield will try to use the specified cipher suites that are supported by this JVM. This error can occur when using
the Shield defaults as some distributions of OpenJDK do not enable the PKCS11 provider by default. In this case, we
recommend consulting your JVM documentation for details on how to enable the PKCS11 provider.
@ -227,10 +227,10 @@ This warning occurs in the logs every 30 seconds when the Shield license is expi
internal request to gather disk usage information from the nodes and indices, to enable {ref}/index-modules-allocation.html#disk[disk-based shard allocation].
Disk-based shard allocation is not required, though it is enabled by default.
If you are using elasticsearch 1.4.3 or higher with disk-based shard allocation enabled, it will be automatically disabled when the Shield
If you are using Elasticsearch 1.4.3 or higher with disk-based shard allocation enabled, it will be automatically disabled when the Shield
license is expired or invalid, and will be automatically re-enabled when a valid Shield license is installed.
If you are using elasticsearch 1.4.2 with disk-based shard allocation enabled, we recommend manually disabling disk-based shard
If you are using Elasticsearch 1.4.2 with disk-based shard allocation enabled, we recommend manually disabling disk-based shard
allocation while your Shield license is expired, and re-enabling it after installing a valid Shield license. Instructions for
disabling disk-based shard allocation are {ref}/index-modules-allocation.html#disk[here].
--