Version: 6.x-23
Community

Demo Installer

To quickly set up a Search Guard secured Elasticsearch cluster:

  1. Install the Search Guard Plugin to Elasticsearch
  2. Execute the Search Guard demo installation script

The demo installation script will setup and configure Search Guard on an existing Elasticsearch cluster. It also installs demo users and roles for Elasticsearch, Kibana and Logstash. It uses self-signed TLS certificates and unsafe configuration options, so do not use in production!

To use the (optional) Search Guard Kibana plugin which adds security and configuration features to Kibana:

  1. Install the Search Guard Kibana plugin to Kibana
  2. Add the minimal Kibana configuration to kibana.yml

Install Search Guard on Elasticsearch

Search Guard can be installed like any other Elasticsearch plugin by using the elasticsearch-plugin command.

Change to the directory of your Elasticsearch installation and type:

bin/elasticsearch-plugin install -b com.floragunn:search-guard-6:<version>

For example:

bin/elasticsearch-plugin install -b com.floragunn:search-guard-6:6.3.2-23.0

Replace the version number in the examples above with the exact version number that matches your Elasticsearch installation. A plugin built for Elasticsearch 6.3.0 will not run on Elasticsearch 6.2.4 and vice versa.

An overview of all available Search Guard versions can be found on the Search Guard Version Matrix page.

For offline installation and more details, see the Search Guard installation chapter

Execute the demo installation script

Search Guard ships with a demo installation script. The script will:

  • Add demo TLS certificates in PEM format to the config directory of Elasticsearch
  • Add the required TLS configuration to the elasticsearch.yml file.
  • Add the auto-initialize option to elasticsearch.yml. This option will initialize the Search Guard configuration index automatically if it does not exist.
  • Generate a sgadmin_demo.sh script that you can use for applying configuration changes on the command line

Note that the script only works with vanilla Elasticsearch installations. If you already made changes to elasticsearch.yml, especially the cluster name and the host entries, you might need to adapt the generated configuration.

To execute the demo installation:

  • cd into <Elasticsearch directory>/plugins/search-guard-6/tools
  • Execute ./install_demo_configuration.sh (chmod the script first if necessary.)

The demo installer will ask if you would like to install the demo certificates, if the Search Guard configuaration should be automatically initialized and if cluster mode should be enabled. Answer as follows:

Search Guard 6 Demo Installer
 ** Warning: Do not use on production or publicly reachable systems **
Install demo certificates? [y/N] y
Initialize Search Guard? [y/N] y
Enable cluster mode? [y/N] n
  • Install demo certificates
    • Whether to install the self-signed demo TLS certificates or not
  • Initialize Search Guard
    • Whether to auto-initialize Search Guard with the demo configuration
    • If answered with y, Search Guard will initialize the configuration index with the files from the <Elasticsearch directory>/plugins/search-guard-6/sgconfig directory if the index does not exist
  • Enable cluster mode

Testing the Elasticsearch installation

  • Open https://localhost:9200/_searchguard/authinfo.
  • Accept the self-signed demo TLS certificate.
  • In the HTTP Basic Authentication dialogue, use admin as username and admin as password.
  • This will print out information about the user admin in JSON format.

Applying configuration changes

The Search Guard configuration, like users, roles and permissions, is stored in a dedicated index in Elasticsearch itself, the so-called Search Guard Index.

Changes to the Search Guard configuration must be applied to this index by either

  • Using the Kibana Configuration GUI (Enterprise feature)
  • Using the sgadmin command line tool with the generated admin certificate

For using the Kibana Configuration GUI you need to install the Search Guard Kibana Plugin, as described below.

If you want to use the sgadmin tool:

  • Apply your changes to the demo configuration files located in <Elasticsearch directory>/plugins/search-guard-6/sgconfig
  • Execute the pre-configured sgadmin call by executing <Elasticsearch directory>/plugins/search-guard-6/tools/sgadmin_demo.sh

This will read the contents of the configuration files in <Elasticsearch directory>/plugins/search-guard-6/sgconfig and upload the contents to the Search Guard index.

The sgadmin tool is very powerful and offers a lot of features to manage any Search Guard installation. For more information about sgadmin, head over to the Using sgadmin chapter.

Install Search Guard on Kibana

The Search Guard Kibana plugin adds authentication, multi tenancy and the Search Guard configuration GUI to Kibana.

  • Copy the URL to the Search Guard Kibana plugin zip matching your exact Kibana version from Maven
  • Stop Kibana
  • cd into your Kibana installaton directory
  • Execute: bin/kibana-plugin install https://url/to/search-guard-kibana-plugin-<version>.zip

Replace the URL in the example above with the URL you have copied.

Add the Search Guard Kibana configuration

If you’ve used the demo configuration to initializing Search Guard as outlined above, add the following lines to your kibana.yml and restart Kibana:

# Use HTTPS instead of HTTP
elasticsearch.url: "https://localhost:9200"

# Configure the Kibana internal server user
elasticsearch.username: "kibanaserver"
elasticsearch.password: "kibanaserver"

# Disable SSL verification because we use self-signed demo certificates
elasticsearch.ssl.verificationMode: none

# Whitelist the Search Guard Multi Tenancy Header
elasticsearch.requestHeadersWhitelist: [ "Authorization", "sgtenant" ]

Start Kibana

After Kibana is started, it will begin optimizing and caching browser bundles. This process may take a few minutes and cannot be skipped. After the plugin is installed and optimized, Kibana will continue to start.

Testing the Kibana installation

  • Open http://localhost:5601/.
  • You should be redirected to the Kibana login page
  • On the login dialogue, use admin as username and admin as password.

If everything is set up correctly, you should see three new navigation entries on the left pane:

Applying configuration changes

The Search Guard configuration GUI allows you to edit

  • Search Guard Roles - define access permissions to indices and types
  • Action Groups - define groups of access permissions
  • Role Mappings - Assign users by username or their backend roles to Search Guard roles
  • Internal User Database - An authentication backend that stores users directly in Elasticsearch

Furthermore you can view your currently active license, upload a new license if it has expired, and display the Search Guard system status.

Where to go next

If you have not already done so, make yourself familiar with the Search Guard Main Concepts.

After that, configure roles and access permissions by either modifying the configuration files and uploading them via sgadmin, or use the Kibana configuration GUI to change them directly.

If you want to use more sophisticated authentication methods like Active Directory, LDAP, Kerberos or JWT, configure your existing authentication and authorisation backends in sg_config.yml.

For fine-grained access control on document- and field level, use the Search Guard Document and field level security module.

If you need to stay compliant with security regulations like GDPR, HIPAA, PCI, ISO or SOX, use the Search Guard Audit Logging to generate and store audit trails.

And if you need to support multiple tenants in Kibana, use Kibana Multitenancy to separate Visualizations and Dashboards by tenant.