164 lines
8.3 KiB
Plaintext
164 lines
8.3 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 {version}, you need:
|
||
|
||
* Java 7 or later
|
||
* Elasticsearch {version}
|
||
* Elasticsearch License plugin {version}
|
||
|
||
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 use the DEB/RPM packages to install Elasticsearch, by default Elasticsearch is installed in
|
||
`/usr/share/elasticsearch` and the configuration files are stored in `/etc/elasticsearch`. (For the
|
||
complete list of default paths, see {ref}/setup-dir-layout.html#_deb_and_rpm[Directory Layout] in
|
||
the Elasticsearch Reference.)
|
||
|
||
To install the Shield and License plugins on a DEB/RPM package installation, you need to run
|
||
`bin/plugin -i` from the `/usr/share/elasticsearch` directory with superuser permissions. For example:
|
||
|
||
[source,shell]
|
||
----------------------------------------------------------
|
||
cd /usr/share/elasticsearch
|
||
sudo bin/plugin -i license
|
||
sudo bin/plugin -i shield
|
||
----------------------------------------------------------
|
||
|
||
[float]
|
||
[[offline-install]]
|
||
=== Installing Shield on Offline Machines
|
||
|
||
Elasticsearch’s `bin/plugin` script requires direct Internet access to download and install the
|
||
License and Shield plugins. If your server doesn’t have Internet access, you can manually
|
||
download and install the plugins.
|
||
|
||
To install Shield on a machine that doesn't have Internet access:
|
||
|
||
. Manually download the appropriate License and Shield binaries:
|
||
** https://download.elastic.co/elasticsearch/license/license-latest.zip[
|
||
`https://download.elastic.co/elasticsearch/license/license-latest.zip`]
|
||
** https://download.elastic.co/elasticsearch/shield/shield-latest.zip[
|
||
`https://download.elastic.co/elasticsearch/shield/shield-latest.zip`]
|
||
|
||
. Transfer the zip files to the offline machine.
|
||
|
||
. Run `bin/plugin` with the `-u` option to install the plugins using the zip files. For example:
|
||
+
|
||
[source,shell]
|
||
----------------------------------------------------------
|
||
bin/plugin install file:///path/to/file/license-2.1.0.zip <1>
|
||
bin/plugin install file:///path/to/file/shield-2.1.0.zip
|
||
----------------------------------------------------------
|
||
<1> Note that you must specify an absolute path to the zip file after the `file://` protocol.
|
||
|
||
[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 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.
|
||
|
||
|
||
|
||
|
||
|