Installing Shield
editInstalling Shield
editThe 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.
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.
Shield Installation Prerequisites
editTo install Shield 2.3.5, you need:
- Java 7 or later
- Elasticsearch 2.3.5
- Elasticsearch License 2.3.5 plugin
For information about installing the latest Oracle JDK, see Java SE Downloads. For information about installing Elasticsearch, see Installation in the Elasticsearch Reference.
You must run the version of Shield that matches the version of Elasticsearch you are running.
Installing Shield on a DEB/RPM Package Installation
editIf 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 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 install
from the /usr/share/elasticsearch
directory with superuser permissions. For example:
cd /usr/share/elasticsearch sudo bin/plugin install license sudo bin/plugin install shield
Installing Shield on Offline Machines
editElasticsearch’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:
- Transfer the zip files to a temporary directory on the offline machine. (Do NOT put the zip files in the Elasticsearch plugins directory.)
-
Run
bin/plugin install
to install the plugins using the zip files. For example:bin/plugin install file:///path/to/file/license-2.3.5.zip bin/plugin install file:///path/to/file/shield-2.3.5.zip
You must specify an absolute path to the zip file after the
file://
protocol.
Installing Shield on Tribe Nodes
editShield supports tribe nodes that act as a federated client across multiple clusters. When using tribe nodes with Shield, all clusters must run Shield and share the same Shield configuration (users, roles, user-role mappings, SSL/TLS CA). The tribe node itself also must be configured to grant access to actions and indices on all of the connected clusters, as security checking is primarily done on the tribe node.
To use a tribe node with Shield:
- Install Shield on the tribe node and every node in each connected cluster.
-
Enable message authentication globally. Generate a system key on one node and copy it to the tribe node and every other node in each connected cluster.
For message authentication to work properly across multiple clusters, the tribe node and all of the connected clusters must share the same system key. By default, Shield reads the system key from
CONFIG_DIR/shield/system_key
. If you store the key in a different location, you must configure theshield.system_key.file
setting inelasticsearch.yml
. -
Enable encryption globally. To encrypt communications, you must enable SSL/TLS on every node.
To simplify SSL/TLS configuration, use the same certificate authority to generate certificates for all connected clusters.
-
Configure the tribe in the tribe node’s
elasticsearch.yml
file. You must specify each cluster that’s a part of the tribe and configure discovery and encryption settings per cluster. For example, the following configuration adds two clusters to the tribe:tribe: on_conflict: prefer_cluster1 c1: cluster.name: cluster1 discovery.zen.ping.unicast.hosts: [ "cluster1-node1:9300", "cluster1-node2:9300"] shield.ssl.keystore.path: /path-to-keystore/es-tribe-01.jks shield.ssl.keystore.password: secretpassword shield.ssl.keystore.key_password: secretpassword shield.transport.ssl: true shield.http.ssl: true c2: cluster.name: cluster2 discovery.zen.ping.unicast.hosts: [ "cluster2-node1:9300", "cluster2-node2:9300"] shield.ssl.keystore.path: /path-to-keystore/es-tribe-01.jks shield.ssl.keystore.password: secretpassword shield.ssl.keystore.key_password: secretpassword shield.transport.ssl: true shield.http.ssl: true
-
Configure the same index privileges for your users on all nodes, including the tribe node. The nodes in each cluster must grant access to indices in other connected clusters as well as their own.
For example, let’s assume
cluster1
andcluster2
each have a single index,index1
andindex2
. To enable a user to submit a request through the tribe node to search both clusters:-
On the tribe node and both clusters, define a
tribe_user
role that has read access toindex1
andindex2
:tribe_user: indices: 'index*': search
-
Assign the
tribe_user
role to a user on the tribe node and both clusters. For example, run the following command on each node to createmy_tribe_user
and assign thetribe_user
role:./bin/shield/esusers useradd my_tribe_user -p password -r tribe_user
-
-
Grant selected users permission to retrieve merged cluster state information for the tribe from the tribe node. To do that, grant them the monitor privilege on the tribe node. For example, you could create a
tribe_monitor
role that assigns themonitor
privilege:tribe_monitor: cluster: monitor
Each cluster can have it’s own users with admin privileges. In fact, you cannot perform administration tasks such as create index through the tribe node, you must send the request directly to the appropriate cluster.
- Start the tribe node. If you’ve made configuration changes to the nodes in the connected clusters, they also need to to be restarted.
Upgrading Shield
editTo upgrade Shield, uninstall the current Shield plugin and install the new version of Shield. Your configuration will be preserved and you do this with a rolling upgrade of Elasticsearch when upgrading to a new minor version; a full cluster restart is required when upgrading from Elasticsearch 1.x. On each node, after you have stopped it run:
bin/plugin remove shield bin/plugin install shield
Then start the node. Larger sites should follow the steps in the rolling upgrade section 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.
The default role definitions in the roles.yml
file might need to be changed to ensure proper
interoperation with other applications such as Marvel and Kibana. Any role changes are stored in in roles.yml.new
when you upgrade. For more information see Updated Role Definitions.
Uninstalling Shield
editUninstalling Shield requires a full cluster restart.
To uninstall Shield:
- Shut down Elasticsearch.
-
Remove the Shield plugin from Elasticsearch:
bin/plugin remove shield
- Restart Elasticsearch.