Basic Usage
Content
The Search Guard configuration is stored in an index on the Elasticsearch cluster. This allows for configuration hot-reloading, and eliminates the need to place configuration files on any node.
Configuration settings are uploaded to the Search Guard configuration index using the sgadmin
tool. When installing Search Guard for the first time, you have to run sgadmin at least once to initialize the configuration index.
Search Guard ships with sgadmin included.
<ES installation directory>/plugins/search-guard-7/tools
You can also download a standalone version of sgadmin with all dependencies. You can run sgadmin from any machine that has access to the transport port of your cluster. This means that you can change the Search Guard configuration without having to access your nodes via SSH.
You can find sample sgadmin calls in the examples chapter
Prerequisites
Linux
Change the permissions on that script and give it execution rights:
chmod +x plugins/search-guard-7/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.
Configuring the admin certificate
sgadmin requires an TLS admin certificate to make configuration changes. An admin certificate is a regular TLS certificate that has been granted full access to your cluster, including the configuration index.
Admin certificates are configured in elasticsearch.yml by listing their DNs:
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.
Connecting to Elasticsearch with PEM certificates
If you use PEM certificates, you need to provide
- the root certificate in PEM format
- the admin certificate in PEM format
- the private key of the certificate in PEM format
- optional: the password of the private key
./sgadmin.sh
-cacert ../../../config/root-ca.pem
-cert ../../../config/kirk.pem
-key ../../../config/kirk-key.pem
...
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. |
Connecting to Elasticsearch with keystore 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>
Options:
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/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. |
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) |
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. |
Elasticsearch cluster 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.