Version: Search Guard 5 / This is an older version of Search Guard. Switch to Latest version

Using sgadmin to configure Search Guard

The Search Guard configuration, including users, roles and permissions, is stored in an index on the Elasticsearch cluster. This allows for hot configuration reloading, and eliminates the need to place configuration files on each node.

Configuration settings are loaded into this Search Guard configuration index using the sgadmin tool. sgadmin identifies itself against a Search Guard secured Elasticsearch cluster via an admin TLS certificate, either in .jks or .pem format. An admin certificate grants full access to the cluster, including making changes to the Search Guard configuration index.

Configuring the admin certificate

You can configure all certificates that should have admin privileges in elasticsearch.yml by stating their respective DNs. If you use the example PKI scripts to generate the certificates, you can use the kirk or spock client certificate:

searchguard.authcz.admin_dn:
  - CN=kirk,OU=client,O=client,L=test, C=DE
  - CN=spock,OU=client,O=client,L=test, C=DE

Do not use node certificates as admin certifcates. The intended use is to keep node and admin certificates separate. Using node certificates as admin certificates can lead to unexpected results. Also, do not use any whitespaces between the parts of the DN.

Basic Usage

The sgadmin CLI tool can be run from any machine that has access to the transport port of your Elasticsearch cluster (default: 9300). This means that you can change the Search Guard configuration without having to access your nodes via SSH.

Search Guard ships with sgadmin included:

<ES installation directory>/plugins/search-guard-5/tools

Linux

Change the permissions on that script and give it execution rights:

chmod +x plugins/search-guard-5/tools/sgadmin.sh

Windows

Before executing sgadmin.bat check that you have set JAVA_HOME environment variable, e.g.:

set JAVA_HOME=C:\Program Files\Java\jdk1.8.0_65

Replace jdk1.8.0_65 with your installed JDK or JRE version.

Standalone version

You can also download the sgadmin standalone version. It comes with all dependencies included, so you can use it on any machine you want, provided Java is installed.

To print all available command line options, execute sgadmin without any command line switches:

<ES installation directory>/plugins/search-guard-5/tools/sgadmin.sh

Using sgadmin with Keystore and Truststore files

You need to specify the key and truststore file location, their respective passwords, and the directory where the Search Guard 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 completely (-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 files are resolved relative to the directory where you execute sgadmin. You can also use absolute paths. This also applies for the configuration directory (-cd option).

If you use the certificates generated by the demo installation script, copy the truststore.jks and the kirk-keystore.jks to the tools directory and execute:

./sgadmin.sh -ts truststore.jks -ks kirk.jks  \
  -cd ../sgconfig -icl - nhnv

This will push all configuration files in the sgconfig directory to your cluster. Since the generates keystore and truststore have the default password changeit, we can omit the -kspass and -tspass switches here.

After one or more files are updated, Search Guard will automatically reload the new configuration. There is no need to restart any node.

Use the following options to control the key and truststore settings:

Name Description
-ks The location of the keystore containing the admin certificate and all intermediate certificates, if any. You can use an absolute or relative path. Relative paths are resolved relative to 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 alias of the admin certificate, if any.
-ts The location of the truststore containing the root certificate. You can use an absolute or relative path. Relative paths are resolved relative to the execution directory of sgadmin.
-tspass The password for the truststore.
-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 alias for the root certificate, if any.

Using sgadmin with PEM certificates

Instead of using Keystore and Truststore files, sgadmin also works with certificates in PEM format, for example:

./sgadmin.sh -cd ../sgconfig/ -icl -nhnv -cacert root-ca.pem -cert \
  kirk.crtfull.pem -key kirk.key.pem -keypass password
Name Description
-cert The location of the pem file containing the admin certificate and all intermediate certificates, if any. You can use an absolute or relative path. Relative paths are resolved relative to the execution directory of sgadmin.
-key The location of the pem file containing the private key of the admin certificate. You can use an absolute or relative path. Relative paths are resolved relative to the execution directory of sgadmin. The key must be in PKCS#8 format.
-keypass The password of the private key of the admin certificate, if any.
-cacert The location of the pem file containing the root certificate. You can use an absolute or relative path. Relative paths are resolved relative to the execution directory of sgadmin.

Command line options

sgadmin comes with command line options. Execute ./sgadmin.sh without any options to list them.

General

Name Description
-ff fail fast if something goes wrong, no retry

Elasticsearch settings

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.
-arc,–accept-red-cluster Execute sgadmin even if the cluster state is red. Default: sgadmin won’t execute on red cluster state

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.

Certificate validation settings

In addition to the Keystore, Truststore or PEM settings above, use the following options to control certificate validation:

Name Description
-nhnv disable-host-name-verification, do not validate hostname.
-nrhn disable-resolve-hostname, do not resolve hostname (Only relevant if -nhnv is not set.).
-noopenssl Do not use OpenSSL even if available (default: use OpenSSL if available)

Configuration files settings

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 Directory containing multiple Search Guard configuration files.
-f Single config file (cannot be used together with -cd).
-t File type.
-rl Reload the current configuration and flush the internal cache.

To upload all configuration files in a directory, use:

./sgadmin.sh -cd ../sgconfig -ts ... -tspass ... -ks ... -kspass ...

If you want to push a single configuration file, use:

./sgadmin.sh -f ../sg_internal_users.yml -t internalusers  \
    -ts ... -tspass ... -ks ... -kspass ...

the filetype must be one of:

  • config
  • roles
  • rolesmapping
  • internalusers
  • actiongroups

Cipher settings

Usually you do not need to change 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.

Backup and Restore

You can download all current configuration files from your cluster with the following command:

./sgadmin.sh -r -ts ... -tspass ... -ks ... -kspass ...

This will dump the currently active Search Guard configuration from your cluster to individual files in the working directory. You can then use these files to upload the configuration again to the same or a different cluster. This is for example useful when moving a PoC to production.

You can also specify the download location with the -cd option:

./sgadmin.sh -r -h staging.example.com -p 9300  \
    -cd /etc/backup/ -ts ... -tspass ... -ks ... -kspass ...

To upload the dumped files to another cluster use:

./sgadmin.sh -h production.example.com -p 9301 -cd /etc/backup/  \
    -ts ... -tspass ... -ks ... -kspass ...
Name Description
-r retrieve the current Search Guard configuration from a running cluster, and dump it to configuration files in the working directory
-cd Specify the directory to store the files to. You can use an absolute or relative path. Relative paths are resolved relative to the execution directory of sgadmin.

Cache invalidation

Search Guard by default caches authenticated users and their roles and permissions for one hour. You can invalidate the cache by reloading the Search Guard configuration:

./sgadmin.sh -rl -ts ... -tspass ... -ks ... -kspass ...

| Name | Description | |—|—| | -rl | reload the current Search Guard configuration stored in your cluster, invalidating any cached users, roles and permissions.|

Index and replica settings

The following switched control the Search Guard index settings.

Name Description
-i Search Guard index name, defaults to searchguard.
-er Set explicit number of replicas or autoexpand expression for searchguard index (requires Search Guard 19.1 and above)
-us Update the replica settings.
-era Enable replica auto-expand.
-dra Disable replica auto-expand.

The first time you run sgadmin.sh, the -us, -era, dra, and -rl (reload configuration), flags can cause the initial setup to fail, as the searchguard index does not yet exist.

See chapter index management for more details on how the Search Guard index is structured and how to manage it.