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 Prerequisitesedit
To install Shield 2.4.6, you need:
- Java 7 or later
- Elasticsearch 2.4.6
- Elasticsearch License 2.4.6 plugin
You must run the version of Shield that matches the version of Elasticsearch you are running.
Installing Shield on a DEB/RPM Package Installationedit
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 Machinesedit
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.)
bin/plugin installto install the plugins using the zip files. For example:
bin/plugin install file:///path/to/file/license-2.4.6.zip bin/plugin install file:///path/to/file/shield-2.4.6.zip
You must specify an absolute path to the zip file after the
Installing Shield on Tribe Nodesedit
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
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.ymlfile. 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
cluster2each have a single index,
index2. 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_userrole that has read access to
tribe_user: indices: 'index*': search
tribe_userrole to a user on the tribe node and both clusters. For example, run the following command on each node to create
my_tribe_userand assign the
./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_monitorrole that assigns the
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.
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
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
when you upgrade. For more information see Updated Role Definitions.
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.