Configuration settings are loaded into the Search Guard index using the sgadmin tool. sgadmin identifies itself against an SG 2 secured Elasticsearch cluster via a client SSL certificate. We'll call this an admin certificate. The DN of this certificate must be configured elasticsearch.yml.
searchguard.authcz.admin_dn:
- cn=admin,ou=Test,ou=ou,dc=company,dc=com
If you use the example PKI scripts to generate the certificates, it's for example the kirk or spock client certificate:
searchguard.authcz.admin_dn:
- CN=kirk,OU=client,O=client,L=test, C=DE
You can find the sgadmin tool in the following directory:
<ES installation directory>/plugins/search-guard-2/tools
Change the permissions on that script and give it execution rights:
chmod +x plugins/search-guard-2/tools/sgadmin.sh
Before executing sgadmin.bat check that you have set JAVA_HOME environment variable and if you don't have, you can set it like:
set JAVA_HOME=C:\Program Files\Java\jdk1.8.0_65
Replace jdk1.8.0_65 with your installed JDK or JRE version
After that you can execute the script against any node in your cluster. The configuration settings are pushed to that node, and depending on your shard settings, replicated to the other nodes.
You can find sample configuration files that you can start with in this directory:
<ES installation directory>/plugins/search-guard-2/sgconfig
For basic usage, you need to specify the key- and truststore, the respective passwords for them, and the directory where to configuation files can be found. In addition, you either specify the cluster name (-cn option), or as in this example, tell sgadmin to ignore the cluster name altogether (-icl option).
./sgadmin.sh -ts <path/to/truststore> -tspass <truststore password>
-ks <path/to/keystore> -kspass <keystore password> -cd ../sgconfig -icl -nhnv
The path to the keystore and truststore are resolved relative to the directory where you execute sgadmin from. You can of course also use absolute paths. This also applies for the configuration directory.
If you use the certificates generated by the example PKI scripts., copy the truststore.jks and the kirk-keystore.jks to the tools directory and execute:
./sgadmin.sh -ts truststore.jks -tspass changeit
-ks kirk-keystore.jks -kspass changeit -cd ../sgconfig -icl - nhnv
This will push all configuration files in the sgconfig directory to your cluster.
After one or more files are updated, Search Guard will automatically reconfigure. and the changes will take effect almost immediately. There is no need to restart ES nodes.
Note that you can execute sgadmin from any machine that has access to your cluster on transport level (default port 9300).
sgadmin comes with a bunch of command line options. You can always execute ./sgadmin.sh without any options to display them:
If you run a default Elasticsearch installation which listens on transport port 9300 and uses elasticsearch as cluster name, you can omit the following settings altogether. Otherwise, specify your Elasticsearch settings by using the following switches:
| Name | Description |
|---|---|
| -h | elasticsearch hostname, default: localhost |
| -p | elasticsearch port, default: 9300 (NOT the http port!) |
| -cn | clustername, default: elasticsearch |
| -icl | Ignore clustername |
| -sniff | Sniff cluster nodes |
Ignore cluster name means that the name of your cluster will not be validated. Sniffing can be used to detected available nodes by using the ES cluster state API. You can read more about this feature in the Elasticsearch documentation
In order to identify against Search Guard as admin, sgadmin needs a client certificate, contained in the keystore, and the root CA and any intermediate certificates, contained in the truststore. This is basically the same as configuring the keystroe and truststore for a node. The ony difference is that the DN of the client certificate is configured in elasticsearch.yml as admin certificate.
Use the following options to control the key- and truststore settings:
| Name | Description |
|---|---|
| -ks | The keystore containing the admin certificate, as an absolute or relative path. Relative paths are resolved based on the execution directory of sgadmin. |
| -kspass | The password for the keystore |
| -kst | The key store type, either JKS or PKCS12. If not specified, Search Guard tries to deduct the type from the file extension |
| -ksalias | The keystore alias, if any |
| -ts | truststore which contains the root certificate, as an absolute or relative path. Relative paths are resolved based on the execution directory of sgadmin. |
| -tspass | The password for the trutstore |
| -tst | The trust store type, either JKS or PKCS12. If not specified, Search Guard tries to deduct the type from the file extension |
| -tsalias | The truststore alias, if any |
| -nhnv | disable-host-name-verification, do not validate hostname |
| -nrhn | disable-resolve-hostname, do not resolve hostname (only relevant if -nhnv is not set) |
The following switches define which configuration file(s) you want to push to Search Guard. You can either push a single file, or specify a directory containing one or more configuration files.
| Name | Description |
|---|---|
| -cd | configuration directory containing a bunch of .yml files |
| -f | single config file (cannot be used together with -cd) |
| -t | file type |
| -rl | Reload the current configuration and flush the internal cache |
If you push a single configuration file, the filetype must be one of:
- config
- roles
- rolesmapping
- internalusers
- actiongroups
The following switched control the Search Guard index settings.
| Name | Description |
|---|---|
| -i | Search Guard index name, defaults to searchguard |
| -us | update the replica settings |
| -era | enable replica auto-expand |
| -dra | disable replica auto-expand |
See chapter index management for more details on how the Search Guard index is structured and how to manage it.
Usually you do not need to fiddle around with the cipher settings. If you do, use the following switches:
| Name | Description |
|---|---|
| -ec | enabled-ciphers, comma separated list of TLS ciphers |
| -ep | enabled-protocols, comma separated list of TLS protocols |
plugins/search-guard-2/tools/sgadmin.sh \
-cd plugins/search-guard-2/sgconfig/ \
-ks plugins/search-guard-2/sgconfig/keystore.jks \
-kspass changeit
-ts plugins/search-guard-2/sgconfig/truststore.jks \
-tspass changeit
-nhnv
plugins/search-guard-2/tools/sgadmin.sh \
-f /path/to/file/updated_internal_users.yml \
-t internalusers \
-ks plugins/search-guard-2/sgconfig/keystore.jks \
-kspass changeit
-ts plugins/search-guard-2/sgconfig/truststore.jks \
-tspass changeit
-cn myclustername \
-nhnv
plugins/search-guard-2/tools/sgadmin.sh \
-h esnode1.mycompany.com \
-p 9301 \
-f /path/to/file/updated_internal_users.yml \
-t internalusers \
-ks plugins/search-guard-2/sgconfig/keystore.jks \
-kspass changeit
-ts plugins/search-guard-2/sgconfig/truststore.jks \
-tspass changeit
-icl
plugins/search-guard-2/tools/sgadmin.sh \
-ks plugins/search-guard-2/sgconfig/keystore.jks \
-kspass changeit
-ts plugins/search-guard-2/sgconfig/truststore.jks \
-tspass changeit
-us 5
plugins/search-guard-2/tools/sgadmin.sh \
-ks plugins/search-guard-2/sgconfig/keystore.jks \
-kspass changeit
-ts plugins/search-guard-2/sgconfig/truststore.jks \
-tspass changeit
-era