This is an older version of Search Guard. Switch to Latest version
Demo Installer
Content
- Install Search Guard on Elasticsearch
- Execute the demo installation script
- Testing the Elasticsearch installation
- Applying configuration changes
- Install Search Guard on Kibana
- Add the Search Guard Kibana configuration
- Start Kibana
- Testing the Kibana installation
- Applying configuration changes
- Where to go next
To quickly set up a Search Guard secured Elasticsearch cluster:
- Install the Search Guard Plugin to Elasticsearch
- 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:
- Install the Search Guard Kibana plugin to Kibana
- 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.
- 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-6-<version>.zip
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
- If answered with
y
, thenetwork.host
parameter will be set to0.0.0.0
to bind to all interfaces - Depending on your system you may need to adjust the
vm.max_map_count
for Elasticsearch to start - see https://www.elastic.co/guide/en/elasticsearch/reference/current/vm-max-map-count.html
- If answered with
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 andadmin
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.
- Download 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 file:///path/to/kibana-plugin.zip
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.hosts: ["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 andadmin
as password.
If everything is set up correctly, you should see three new navigation entries on the left pane:
- Search Guard - the Search Guard configuration GUI
- Tenants - to select a tenant for Kibana Multitenancy
- Logout - to end your current session
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.
- Using and defining action groups
- Defining roles and permissions
- Mapping users to Search Guard roles
- Adding users to the internal user database
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.
Additional resources