Secure Elasticsearch with Search Guard: Step‑by‑Step Installation & Configuration Guide

Introduction

Following the earlier article on Elasticsearch security strategies, this guide consolidates essential information about installing and using Search Guard, a security plugin that offers SSL/TLS encryption and a robust user‑role‑permission system.

Key Features of Search Guard

Supports SSL/TLS encryption for both Transport (node‑to‑node) and REST (HTTP/HTTPS) layers, configurable independently.

Provides a complete "user‑role‑permission" model, with free‑edition controls down to index/type and host level.

Advanced features such as Document‑level security (DLS), Field‑level security (FLS), audit logging, and integration with LDAP/Kerberos require the Enterprise license.

Search Guard integrates seamlessly with Logstash and Kibana, especially when using Elasticsearch 2.3.5.

Version Compatibility

Before Elasticsearch 5.x, Search Guard and Search Guard SSL must be installed separately; from 5.x onward, the appropriate SSL component is bundled automatically. Use the version‑matching tables on the official GitHub repository.

GitHub repository: https://github.com/floragunncom/search-guard/wiki

Download and Installation

Because the default plugin installation requires online access, it is recommended to download the necessary packages first and install them locally.

Download Elasticsearch 2.3.5 from https://www.elastic.co/downloads/past-releases/elasticsearch-2-3-5 (choose rpm or zip/tar).

Download Search Guard SSL 2.3.5.19 from https://github.com/floragunncom/search-guard-ssl/tree/v2.3.5.19 .

Download Search Guard 2.3.5.10 from https://github.com/floragunncom/search-guard/tree/v2.3.5.10 .

Install Elasticsearch (installation steps omitted here).

Install Search Guard SSL locally: /path-to-es-install-dir/bin/plugin -install -b file:///your-path/search-guard-ssl-2.3.5.19.zip

Install Search Guard locally: /path-to-es-install-dir/bin/plugin -install -b file:///your-path/search-guard-2-2.3.5.10.zip

Tips

Use the file:// prefix with an absolute path for local installation.

Elasticsearch 5.x changed the plugin installation mechanism; refer to official docs.

The order of installing Search Guard and Search Guard SSL does not matter as long as both are present before startup.

Generate SSL/TLS Certificates

Both transport and REST layers require certificates. You can use the Example PKI Scripts provided by Search Guard SSL, modify them as needed, and generate a shared truststore.jks and node‑specific NODE_NAME‑keystore.jks . Remember the three passwords:

ROOT_CA_PASS

YOUR_KEYSTORE_PASS

YOUR_TRUSTSTORE_PASS

Distribute the generated keystores to each Elasticsearch node’s config directory and ensure the Elasticsearch process user has read access.

Configure Search Guard in Elasticsearch

Add the following parameters to elasticsearch.yml (illustrated in the image below):

Key configuration notes:

Disable OpenSSL if not used: searchguard.ssl.transport.enable_openssl_if_available: false and install NSS.

Enable or disable HTTP SSL with searchguard.ssl.http.enabled: true|false . The client authentication mode can be OPTIONAL , REQUIRE , or NONE (default OPTIONAL ).

Configure admin certificates to allow the sgadmin tool to import security settings into the dedicated searchguard index.

Configure Search Guard Permission System

The permission system uses five YAML configuration files and two helper scripts:

sgconfig/sg_config.yml : defines authentication and authorization methods.

sgconfig/sg_roles.yml : defines roles and associated permissions.

sgconfig/sg_roles_mapping.yml : maps users to roles.

sgconfig/sg_internal_users.yml : stores internal users with hashed passwords.

sgconfig/sg_action_groups.yml : defines reusable permission groups.

tools/hasher.sh : generates password hashes.

tools/sgadmin.sh : imports or updates the security configuration in the cluster.

Refer to the official configuration guide for details: https://github.com/floragunncom/search-guard-docs/blob/master/configuration.md

Deploy Security Configuration with sgadmin

Run sgadmin.sh on any cluster node (or a dedicated management machine) to push the configuration:

/path-to-es-install-dir/plugins/search-guard-2/tools/sgadmin.sh -h NODE -p PORT -cd /path-to-your-sgconfig/ -ks /path-to-your/NODE_NAME-keystore.jks -kspass YOUR_KEYSTORE_PASS -ts /path-to-your/truststore.jks -tspass YOUR_TRUSTSTORE_PASS -nhnv -cn YOUR_CLUSTERNAME

Note that before Elasticsearch 5.x, the searchguard index does not auto‑expand replica shards; use sgadmin to adjust this setting.

Conclusion

After completing these steps, Elasticsearch is secured with Search Guard, protecting both REST API access and transport‑layer client connections. The configuration provides fine‑grained access control while integrating smoothly with the ELK stack.

For further details, consult the official documentation and community resources.