This is an older version of Search Guard. Switch to Latest version
Upgrading from 5.x to 6.x
Content
Upgrading Search Guard from 5.x to 6.x can be done while you upgrade Elasticsearch from 5.x to 6.x. You can do this by performing a full cluster restart, or by doing a rolling restart:
Search Guard supports running a mixed cluster of 5.6.x and 6.x nodes and is thus compatible with the Elasticsearch upgrade path.
If you have not already done so, make yourself familiar with Elastic’s own upgrade instruction for the Elastic stack:
Prerequisites
In order to to perform a rolling restart and upgrade from 5.x to 6.x, you need to run at least:
- Elasticsearch 5.6.x (Elasticsearch requirement)
- Search Guard 5.6.x-18 (Search Guard requirement)
If you run older versions of Elasticsearch and/or Search Guard, please upgrade first.
Check your configuration settings
If you don’t use any Search Guard enterprise features
Search Guard 6 ships with all enterprise features included. If you used only the free Community Edition of Search Guard 5 before, you need to disable the enterprise features in Search Guard 6 explicitely in elasticsearch.yml
:
searchguard.enterprise_modules_enabled: false
If you use demo certificates
If you used the Search Guard demo installer and the generated certificates for your TLS setup (which of course you should not do on production), you need to explicitely allow the usage of these unsafe demo certificates by adding the following line to elasticsearch.yml
:
searchguard.allow_unsafe_democertificates: true
If you use audit logging
The audit log module has been revised and now comes with a much wider range of configuration options. These are especially useful for staying compliant with HIPAA, GDPR, ISO, PCI or SOX.
The following configuration keys have been removed:
searchguard.audit.enable_request_details: true
searchguard.audit.config.disabled_categories: AUTHENTICATED
If you have used these options in 5.x, you need to remove them from elasticsearch.yml
.
The searchguard.audit.enable_request_details
option has been replaced with separate keys for each feature:
searchguard.audit.log_request_body: <true|false>, defaut: true
searchguard.audit.resolve_indices: <true|false>, default: true
searchguard.audit.resolve_bulk_requests: <true|false>, default: false
You can now disable audit categories separately for the REST and transport layer, so the searchguard.audit.config.disabled_categories
key has been replaced with the following keys:
searchguard.audit.config.disabled_rest_categories
searchguard.audit.config.disabled_transport_categories
The categories AUTHENTICATED
and GRANTED_PRIVILEGES
are disabled by default. You can completely omit any configuratin setting if you excluded the AUTHENTICATED
category in Search Guard 5. In order to log everything, including AUTHENTICATED
and GRANTED_PRIVILEGES
, use:
searchguard.audit.config.disabled_rest_categories: NONE
searchguard.audit.config.disabled_transport_categories: NONE
The default name of the audit log index has been changed, and also the format of the logged messages differs slightly. Please refer to the Audit Logging chapter for more information.
Upgrading Search Guard
After upgrading a node from ES 5.x to 6.x, simply install the correct version of Search Guard on this node.
Search Guard 6 is able to read the Search Guard configuration index created with Search Guard 5.x. You do not need to change any settings during the upgrade process.
After all nodes have been upgraded to 6.x, it is recommended to delete and recreate the Search Guard index.
Back up your current Search Guard configuration
You can retrieve the current configuration of your running cluster by using sgadmin
with the -r
(--retrieve
) switch:
./sgadmin.sh \
-ks kirk.jks -kspass changeit \
-ts truststore.jks -tspass changeit \
-icl -nhnv -r -cd ../myconfigbackup/
This will retrieve and save all Search Guard configuration files to your working directory. You can later use these files to initialize Search Guard 6 after the upgrade.
Deleting the Search Guard index
Use sgadmin.sh to delete the current Search Guard index:
./sgadmin.sh \
-ks kirk.jks -kspass changeit \
-ts truststore.jks -tspass changeit \
-icl -nhnv -r -dci
Re-create the Search Guard index
Re-create the Search Guard index with the backup of your configuration:
./sgadmin.sh \
-ks kirk.jks -kspass changeit \
-ts truststore.jks -tspass changeit \
-icl -nhnv -cd ../myconfigbackup/
Upgrading Kibana
Kibana should be upgraded after the Elasticsearch / Search Guard upgrade is completed. Just install the correct version of the Search Guard plugin to Kibana. There are no configuration changes in kibana.yml
.
If you use Kibana Multi Tenancy
The Elasticsearch Upgrade Assistant will migrate the .kibana index from 5.x to 6.x.
However, this only applies to the original .kibana
index, the tenant specific indices are not recognized. Migrating the tenant indices is a manual process, and you need to follow the instructions from the Elasticsearch documentation for each index.
Please refer to the Kibana Multi Tenancy chapter, section Under the hood: Index rewriting, Snapshot & Restore, to learn how to find these indices on your cluster.
Running in mixed mode: Limitations
Elasticsearch and Search Guard support running your cluster in mixed mode, means with 5.6.x and 6.x nodes. This makes it possible to upgrade via rolling restart.
Running a cluster in mixed mode should only be done while upgrading from 5 to 6. It’s not supposed to be a permanent situation and you should aim to minimize the duration where a mixed cluster exists.
While running in mixed mode, the following limitations apply:
Omit Search Guard configuration changes
Search Guard 6 uses a new layout for the Search Guard configuration index, and is also able to read and configuration indices created with Search Guard 5.
While running in mixed mode, do not perform changes to the Search Guard configuration index.
This applies to sgadmin and the REST management API. Configuration changes are possible again after all nodes have been upgraded.
Monitoring
While running in mixed mode, X-Pack monitoring might return incorrect values or throw Exceptions which you can safely ignore.
Kibana
If you upgrade Kibana before the Elasticsearch / Search Guard upgrade is completed, a license warning may be displayed on the login screen and on the Search Guard configuration GUI screens.