Quick Start: Migrating from Search Guard 52 and before
This chapter describes how to quickly migrate legacy Search Guard configuration to the new structure. This is useful for testing - possibly as a preparatory step for updating a production cluster.
Note: If you need to update a production cluster with only minimal outage, refer to the corresponding guide.
In order to perform the migration, you need the following:
- The file
sg_config.ymlfrom the existing OpenSearch/Elasticsearch setup.
sg_config.ymlreferences further files, such as PEM files. You need these as well.
- The file
configdirectory of the existing Dashboards/Kibana setup.
- A system to run the test setup. This can a remote system or your local computer.
- You need to download the
sgctltool. It does not require any special installation, just copy it to a suitable place and execute it.
Migrating the Configuration
Open a shell and perform the following steps:
- Create a work directly
sgctl migrate-config /path/to/legacy/sg_config.yml /path/to/legacy/kibana.yml -o /path/to/your/work/directory. Be sure to specify the correct paths to the files
kibana.yml. If you are using OpenSearch/Elasticsearch 7.11 or newer, additionally specify the option
sgctlwill now create new configuration files and print additional information to the console. Carefully review the printed information and the produced configuration.
- The new Search Guard version requires that users who shall be allowed to log into Dashboards/Kibana have a certain privilege. If your users are mapped to the role
SGS_KIBANA_USER(which was already a recommended practice before), the users will automatically have that privilege. If your users are not mapped to the role, you need to edit your role mapping accordingly.
- Start your OpenSearch/Elasticsearch test instance and upload the new
sg_frontend_config.ymlto it using
- Copy the new
configdirectory of the Dashboards/Kibana test instance and start Dashboards/Kibana.
Testing the Configuration
For testing the configuration, just open the Dashboards/Kibana test instance in your favorite web browser.
If you are experiencing issues, switch on debug mode by editing
sg_config.yml like this:
sg_config: dynamic: debug: true # ...
After having activated the configuration with
sgctl, again open Dashboards/Kibana in your browser and try to log in. If you encounter a login failure, you should see more detailed information about the login process.
More more details refer to the Troubleshooting section.