The basic installation procedure is to:
You need to install the Search Guard version that matches your Elasticsearch Version. For example, a plugin built for ES 5.4.1 will not run on ES 5.4.2 and vice versa.
In order to find the correct Search Guard and Search Guard SSL version for your Elasticsearch installation, please refer to our version matrix in the github repository. This matrix will be kept up-to-date with each release.
If you use the enterprise features, please make sure that also the versions of these modules match.
Search Guard can be installed like any other Elasticsearch plugin. Replace the version number in the following examples with the version suitable for your Elasticsearch installation.
Make sure to install the plugins with the same user you run Elasticsearch. For example, if you installed Elasticsearch using the official Debian packages, it is executed with user
Search Guard 5
For Search Guard 5, you only need to install one plugin, namely Search Guard. The SSL layer is bundled with the main plugin.
Change to the directory of your Elasticsearch installation and type:
bin/elasticsearch-plugin install -b com.floragunn:search-guard-5:5.4.2-13
After the installation you should see a folder called “search-guard-5” in the plugin directory of your Elasticsearch installation.
Search Guard 2
For Search Guard 2, you need to install Search Guard SSL first and after that Search Guard itself. Change to the directory of your Elasticsearch installation and type:
bin/plugin install -b com.floragunn/search-guard-ssl/184.108.40.206 bin/plugin install -b com.floragunn/search-guard-2/220.127.116.11
After the installation you should see a folder called “search-guard-2” in the plugin directory of your Elasticsearch installation.
If you are behind a firewall and need to perform an offline installation, follow these steps:
Search Guard 5
bin/elasticsearch-plugin install -b file:///path/to/search-guard-5-<version>.zip
Search Guard 2
bin/plugin install -b file:///location/of/search-guard-ssl-<version>.zip bin/plugin install -b file:///location/of/search-guard-2-<version>.zip
Since ES 2.2, you will see the following warning message when installating Search Guard and/or Search Guard SSL. For some ES versions, you need to actively confirm it by pressing ‘y’:
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @ WARNING: plugin requires additional permissions @ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ * java.lang.RuntimePermission accessClassInPackage.sun.misc * java.lang.RuntimePermission getClassLoader * java.lang.RuntimePermission loadLibrary.* * java.lang.reflect.ReflectPermission suppressAccessChecks * java.security.SecurityPermission getProperty.ssl.KeyManagerFactory.algorithm See http://docs.oracle.com/javase/8/docs/technotes/guides/security/permissions.html for descriptions of what these permissions allow and the associated risks.
If you want to use any of the enterprise modules, download the respective jar file and place it in the folder
<ES installation directory>/plugins/search-guard-5
<ES installation directory>/plugins/search-guard-2
Each module lives in its own github repository. You can either download the repository and build the jar files yourself via a simple
mvn install command. Or you can choose to download the jar file(s) (choose jar file(s) with dependencies) directly from Maven.
Most of these modules require additional configuration settings. Please see the respective sections of this document for further information.
WARNING: Only use the following instructions if you know what you are doing. If you set wrong values this could be a security risk or make Search Guard stop working! In most cases, you do not need to change the default settings.
Search Guard stores all configuration information in a specially secured index. By default, this index is named
searchguard. You can change this index name with the following configuration key:
All certificates used by the nodes on transport level need to have the
oid field set to a specific value. By default, this is
This oid value is checked by Search Guard to identify if an incoming request comes from a trusted node in the cluster or not. In the former case, all actions are allowed, in the latter case, privilege checks apply. Plus, the oid is also checked whenever a node wants to join the cluster. This prohibits a malicious attacker from joinng the cluster by using a client certificate.
You can change the oid value with this confguration key:
For other ways to identify nodes, please check the chapter on TLS node certificates.
If you have other plugins like kopf installed, please check the compatibility with Search Guard.
As a rule of thumb, if a plugin is compatible with Shield, it is also compatible with Search Guard. Specifically:
If the plugin talks to Elasticsearch using REST and you have REST TLS enabled, the plugin must also support TLS.
If the plugin talks to Elasticsearch on the transport layer, you need to be able to add the Search Guard SSL plugin and its configuration settings to the transport client. You can read more about using transport clients with a Search Guard secured cluster in this blog post.
The following plugins and tools have been tested for compatibility with Search Guard: