Version: 6.x-22
Community

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 any node.

Configuration settings are loaded into the 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 .pem or .jks format.

If the Search Guard index is inititialized, you can also use the Kibana Configuration GUI to change users, roles and permissions. However, you need to run sgadmin at least once to initialize the index and configure the authentication and authorization methods you would like to use.

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-6/tools

Linux

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

chmod +x plugins/search-guard-6/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.

You can find all versions on Maven Central.

Choose the Search Guard version you are running and download and unpack either:

  • sgadmin-standalone.tar.gz or
  • sgadmin-standalone.zip

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

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

Using sgadmin with PEM certificates

In order to use sgadmin for pushing configuration changes to Search Guard, you need to provide your admin certificate to the tool.

If you use the certificates generated by the demo installation script, cd in the <ES installation directory>/plugins/search-guard-6/tools/ and execute:

./sgadmin.sh -cd ../sgconfig/ -icl -nhnv  
   -cacert ../../../config/root-ca.pem 
   -cert ../../../config/kirk.pem 
   -key ../../../config/kirk-key.pem 

The -cd option speficies where the Search Guard configuration files to upload to the cluster can be found.

The -icl (--ignore-clustername) option tells Search Guard to upload the config regardless of the cluster name. As an alternative you can also specify the clustername with the -cn (--clustername) option. Since we use self-signed certificates, we also disable hostname verification with the -nhnv (--disable-host-name-verification) option.

The -cacert, -cert and -key switches define the location of your Root CA certificate, the admin certificate and the private key for the admin certificate. If the private key has a password, specify it with the -keypass switch.

All PEM options:

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.

Using sgadmin with Keystore and Truststore files

You can also use keystore files in JKS format in conjunction with sgadmin, for example:

./sgadmin.sh -cd ../sgconfig -icl -nhnv 
  -ts <path/to/truststore> -tspass <truststore password> 
  -ks <path/to/keystore> -kspass <keystore password> 
  

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.

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

Use the following options to control certificate validation:

Name Description
-nhnv disable-host-name-verification, do not validate hostname. Default: false
-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 the cipher settings. If you do, use the following switches:

Name Description
-ec enabled-ciphers, comma separated list of enabled TLS ciphers.
-ep enabled-protocols, comma separated list of enabled 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.

Rescue tools

Name Description
-dci Delete the Search Guard configuration index and exit. May be useful if the cluster state is red due to a corrupt Search Guard index.
-esa Enable shard allocation and exit. May be useful if you disabled shard allocation while performing a full cluster restart, and you need to recreate the Search Guard index.

License information

Name Description
-si Displays the currently active Search Guard license

Whoami

Name Description
-w Displays information about the used admin certificate

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.
-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.