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 identifies itself against a Search Guard secured Elasticsearch cluster via an admin TLS certificate, either in
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.
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-7/tools
Change the permissions on that script and give it execution rights:
chmod +x plugins/search-guard-7/tools/sgadmin.sh
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
jdk1.8.0_65 with your installed JDK or JRE 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
Print all command line options
To print all available command line options, execute sgadmin without any command line switches:
<ES installation directory>/plugins/search-guard-7/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-7/tools/ and execute:
./sgadmin.sh -cd ../sgconfig/ -icl -nhnv -cacert ../../../config/root-ca.pem -cert ../../../config/kirk.pem -key ../../../config/kirk-key.pem
-cd option speficies where the Search Guard configuration files to upload to the cluster can be found.
--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
--clustername) option. Since we use self-signed certificates, we also disable hostname verification with the
-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
All PEM options:
|-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:
|-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/PFX. 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/PFX. 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.
|-ff||fail fast if something goes wrong, no retry|
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:
|-h||elasticsearch hostname, default: localhost|
|-p||elasticsearch port, default: 9300 (NOT the http port!)|
|-cn||clustername, default: elasticsearch|
|-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:
|-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.
|-cd||Directory containing multiple Search Guard configuration files.|
|-f||Single config file (cannot be used together with -cd).|
|-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 ../sgconfig/sg_internal_users.yml -t internalusers \ -ts ... -tspass ... -ks ... -kspass ...
the filetype must be one of:
Validating configuration files
Before uploading new configurations to your cluster, you can validate them:
./sgadmin.sh -cd ../sgconfig -vc <6|7> \ -ts ... -tspass ... -ks ... -kspass ...
||Validate configuration files specified by the -cd or -t switch. Version must be 6 for Search Guard 6 and 7 for Search Guard 7|
Migrating configuration files
If you upgrade from Search Guard 6 to Search Guard 7, you can automatically migrate your existing configuration files to the new syntax:
./sgadmin.sh -migrate ../sgconfig \ -ts ... -tspass ... -ks ... -kspass ...
||Migrate configuration files in
Backup and Restore
You can download all current configuration files from your cluster with the following command:
./sgadmin.sh -backup <folder> \ -ts ... -tspass ... -ks ... -kspass ...
This will dump the currently active Search Guard configuration from your cluster to individual files in the specified folder. 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.
To upload the dumped files to another cluster use:
./sgadmin.sh -h production.example.com -p 9301 -cd /etc/sgbackup/ \ -ts ... -tspass ... -ks ... -kspass ...
||retrieve the current Search Guard configuration from a running cluster, and dump it to the specified
Usually you do not need to change the cipher settings. If you do, use the following switches:
|-ec||enabled-ciphers, comma separated list of enabled TLS ciphers.|
|-ep||enabled-protocols, comma separated list of enabled TLS protocols.|
|-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.|
|-si||Displays the currently active Search Guard license|
|-w||Displays information about the used admin certificate|
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.
|-i||Search Guard index name, defaults to searchguard.|
|-er||Set explicit number of replicas or autoexpand expression for searchguard index|
|-era||Enable replica auto-expand.|
|-dra||Disable replica auto-expand.|
|-us||Update the replica settings.|
The first time you run sgadmin.sh, the
-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.