Installation
Content
- Community, Enterprise and Compliance Edition
- Prerequisites
- First time installation: Full cluster restart
- General
- Disable shard allocation
- Installing Search Guard
- Adding the TLS configuration
- Optional: Enable the REST management API
- Re-enable shard allocation
- Initializing Search Guard
- Search Guard Health Check
- Fixing curl issues
This chapter describes the steps to install and initialize Search Guard manually. If you just want to try out Search Guard or set up a quick PoC, follow the Quickstart Guide.
Community, Enterprise and Compliance Edition
Search Guard ships with all Enterprise and Compliance features already installed and enabled by default. Just install the Enterprise Edition matching the version of your Elasticsearch installation and you are good to go.
If you just want to use the free Community Edition, install Search Guard Enterprise and then disable all commercial features.
Prerequisites
Ensure that your Java Virtual Machine is supported
- We support the same JVM versions and vendors listed here: Support Matrix
- There is no support for IBM VM and Azul Zing
Generate all required TLS certificates
Make sure you have TLS certificates for all nodes and at least one admin certificate. If you already have a PKI infrastructure in place, you usually obtain the required certificates by issuing certificate signing requests to your PKI.
If this is not the case, you have the following options to generate certificates:
- Use the Search Guard demo installation script (not safe for production)
- Download the Search Guard demo certificates (not safe for production)
- Use the Offline TLS Tool (safe for production)
- Use and customize the example PKI scripts (safe for production)
- Create a CSR and send it to your existing PKI infrastructure, if any (safe for production)
- Using tools like OpenSSL and/or keytool (safe for production)
For a typical installation you will want to generate
- One certificate for each node
- One admin certificate
It’s possible to use the same certificate on each node, however this is less secure since you cannot use the hostname verification and DNS lookup feature of Search Guard to check the validity of the TLS certificates.
First time installation: Full cluster restart
A first time installation of Search Guard on a cluster always requires a full cluster restart. TLS encryption is mandatory on the transport layer of Elasticsearch, and thus all nodes must have Search Guard installed in order to be able to talk to each other. If you already have Search Guard installed and want to upgrade, follow our upgrade instructions.
General
The first time installation procedure on a production cluster is to:
- Disable shard allocation
- Stop all nodes
- Install the Search Guard plugin on all nodes
- Add at least the TLS configuration to
elasticsearch.yml
- Restart Elasticsearch and check that the nodes come up
- Re-enable shard allocation
- Configure authentication/authorization, users, roles and permissions by uploading the Search Guard configuration with sgctl
While for an already configured Search Guard plugin you can also use the Kibana Search Guard configuration GUI, for vanilla systems you need to execute sgctl at least once to initialize the Search Guard index.
Disable shard allocation
This step is optional but recommended especially for large clusters with a huge amount of data. This step makes sure that shards will not be shifted around when restarting the cluster, causing a lot of I/O. See also https://www.elastic.co/guide/en/elasticsearch/reference/current/shards-allocation.html
Using sgctl
./sgctl.sh rest put _cluster/settings --json '{"persistent":{"cluster.routing.allocation.enable": "none"}}'
Using curl
curl -Ss -XPUT 'https://localhost:9200/_cluster/settings?pretty' \
-H 'Content-Type: application/json' -d'
{
"persistent": {
"cluster.routing.allocation.enable": "none"
}
}
'
Installing Search Guard
Search Guard can be installed like any other Elasticsearch plugin by using the elasticsearch-plugin
command.
- Download the Search Guard version matching your Elasticsearch version
- Change to the directory of your Elasticsearch installation and type:
bin/elasticsearch-plugin install -b file:///path/to/search-guard-flx-<version>.zip
Additional permissions dialogue
You will see the following warning message when installating Search Guard. 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.
Adding the TLS configuration
The bare minimum Search Guard configuration consists of the TLS settings on transport layer and at least one admin certificate for initializing the Search Guard index. This is configured in elasticsearch.yml, all paths to certificates must be specified relative to the Elasticsearch config
directory:
searchguard.ssl.transport.pemcert_filepath: <path_to_node_certificate>
searchguard.ssl.transport.pemkey_filepath: <path_to_node_certificate_key>
searchguard.ssl.transport.pemkey_password: <key_password (optional)>
searchguard.ssl.transport.pemtrustedcas_filepath: <path_to_root_ca>
searchguard.ssl.transport.enforce_hostname_verification: <true | false>
searchguard.authcz.admin_dn:
- CN=kirk,OU=client,O=client,L=test, C=de
The searchguard.ssl.transport.pem*
keys define the paths to the node certificate, relative to the Elasticsearch config
directory.
The searchguard.authcz.admin_dn
entry configures the admin certificate that you can use with sgctl or the REST management API. You need to state the full DN of the certificate, and you can configure more than one admin certificate.
If you want to use TLS also on the REST layer (HTTPS), add the following lines to elasticsearch.yml
searchguard.ssl.http.enabled: true
searchguard.ssl.http.pemcert_filepath: <path_to_http_certificate>
searchguard.ssl.http.pemkey_filepath: <path_to_http_certificate_key>
searchguard.ssl.http.pemkey_password: <key_password (optional)>
searchguard.ssl.http.pemtrustedcas_filepath: <path_to_http_root_ca>
You can use the same certificates on the transport and on the REST layer. For production systems, we recommend to use individual certificates.
Optional: Enable the REST management API
In order to use the REST management API, configure the Search Guard roles that should have access to the API. The following entry grants full access to the API for the role SGS_ALL_ACCESS
:
searchguard.restapi.roles_enabled: ["SGS_ALL_ACCESS"]
If you want to further restrict access to certain API endpoints, please refer to the REST management API documentation chapter.
The REST management API is an Enterprise feature.
Re-enable shard allocation
After the cluster is up again, re-enable shard allocation so that the Search Guard configuration index can be created in the next step. Since Search Guard is active now, but not initialized yet, you need to use the admin certificate in combination with sgctl or curl:
./sgctl.sh rest put _cluster/settings --json '{"persistent":{"cluster.routing.allocation.enable": "all"}}'
Initializing Search Guard
All settings regarding users, roles, permissions and authentication methods are stored in an Search Guard index on Elasticsearch. By default, this index is not populated automatically for security reasons. Search Guard propagates a “Security First” mantra, so no default users or passwords are applied by default.
You initialize Search Guard by using the sgctl command line tool with the admin certificate configured by the searchguard.authcz.admin_dn
configuration key. This has to be performed at least once to tell Search Guard which authentication modules to use.
Once initialized, you can also use the Search Guard configuration GUI to edit roles and permissions.
Search Guard Health Check
To check if Search Guard is installed and up and running, access the healthcheck endpoint like:
https://<hostname>:9200/_searchguard/health
It returns a JSON snippet like:
{
message: null,
mode: "strict",
status: "UP"
}
Fixing curl issues
If you experience problems with curl commands see Fixing curl first before reporting any issues.
Additional resources