Installing Shield

The 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

edit

To 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

edit

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 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

edit

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/release/org/elasticsearch/plugin/license/2.3.5/license-2.3.5.zip (sha1)
- https://download.elastic.co/elasticsearch/release/org/elasticsearch/plugin/shield/2.3.5/shield-2.3.5.zip (sha1)
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

edit

Shield 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 the shield.system_key.file setting in elasticsearch.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

	Results are returned from the preferred cluster if the named index exists in multiple clusters.
	An arbitrary name that represents the connection to the cluster.

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 and cluster2 each have a single index, index1 and index2. To enable a user to submit a request through the tribe node to search both clusters:
1. On the tribe node and both clusters, define a tribe_user role that has read access to index1 and index2:
```
tribe_user:
  indices:
    'index*': search
```
2. 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 create my_tribe_user and assign the tribe_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 the monitor 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

edit

To 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

edit

Uninstalling Shield requires a full cluster restart.

To uninstall Shield:

Shut down Elasticsearch.
Remove the Shield plugin from Elasticsearch:
```
bin/plugin remove shield
```
Restart Elasticsearch.

« Moving On How Shield Works »