172 lines
8.6 KiB
Plaintext
172 lines
8.6 KiB
Plaintext
[[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 install 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.
|
||
|
||
|
||
|
||
|
||
|