Browse Source

Add docs for new reindex.ssl settings (#38486)

Reindex from remote now supports configurable SSL/TLS (node level)
settings. This change adds documentation relating to those settings

Relates: #37527
Tim Vernum 6 years ago
parent
commit
4f68a4a439
1 changed files with 95 additions and 0 deletions
  1. 95 0
      docs/reference/docs/reindex.asciidoc

+ 95 - 0
docs/reference/docs/reindex.asciidoc

@@ -427,6 +427,8 @@ The `host` parameter must contain a scheme, host, port (e.g.
 The `username` and `password` parameters are optional, and when they are present `_reindex`
 will connect to the remote Elasticsearch node using basic auth. Be sure to use `https` when
 using basic auth or the password will be sent in plain text.
+There are a range of <<reindex-ssl,settings>> available to configure the behaviour of the
+ `https` connection.
 
 Remote hosts have to be explicitly whitelisted in elasticsearch.yml using the
 `reindex.remote.whitelist` property. It can be set to a comma delimited list
@@ -518,6 +520,99 @@ POST _reindex
 // TEST[s/^/PUT source\n/]
 // TEST[s/otherhost:9200/\${host}/]
 
+[float]
+[[reindex-ssl]]
+==== Configuring SSL parameters
+
+Reindex from remote supports configurable SSL settings. These must be
+specified in the `elasticsearch.yml` file, with the exception of the
+secure settings, which you add in the Elasticsearch keystore.
+It is not possible to configure SSL in the body of the `_reindex` request.
+
+The following settings are supported:
+
+`reindex.ssl.certificate_authorities`::
+List of paths to PEM encoded certificate files that should be trusted. 
+You cannot specify both `reindex.ssl.certificate_authorities` and
+`reindex.ssl.truststore.path`.
+
+`reindex.ssl.truststore.path`::
+The path to the Java Keystore file that contains the certificates to trust.
+This keystore can be in "JKS" or "PKCS#12" format.
+You cannot specify both `reindex.ssl.certificate_authorities` and
+`reindex.ssl.truststore.path`.
+
+`reindex.ssl.truststore.password`::
+The password to the truststore (`reindex.ssl.truststore.path`).
+This setting cannot be used with `reindex.ssl.truststore.secure_password`.
+
+`reindex.ssl.truststore.secure_password` (<<secure-settings,Secure>>)::
+The password to the truststore (`reindex.ssl.truststore.path`).
+This setting cannot be used with `reindex.ssl.truststore.password`.
+
+`reindex.ssl.truststore.type`::
+The type of the truststore (`reindex.ssl.truststore.path`).
+Must be either `jks` or `PKCS12`. If the truststore path ends in ".p12", ".pfx"
+or "pkcs12", this setting defaults to `PKCS12`. Otherwise, it defaults to `jks`.
+
+`reindex.ssl.verification_mode`::
+Indicates the type of verification to protect against man in the middle attacks
+and certificate forgery. 
+One of `full` (verify the hostname and the certificate path), `certificate`
+(verify the certificate path, but not the hostname) or `none` (perform no
+verification - this is strongly discouraged in production environments).
+Defaults to `full`.
+
+`reindex.ssl.certificate`::
+Specifies the path to the PEM encoded certificate (or certificate chain) to be
+used for HTTP client authentication (if required by the remote cluster)
+This setting requires that `reindex.ssl.key` also be set.
+You cannot specify both `reindex.ssl.certificate` and `reindex.ssl.keystore.path`.
+
+`reindex.ssl.key`::
+Specifies the path to the PEM encoded private key associated with the
+certificate used for client authentication (`reindex.ssl.certificate`).
+You cannot specify both `reindex.ssl.key` and `reindex.ssl.keystore.path`.
+
+`reindex.ssl.key_passphrase`::
+Specifies the passphrase to decrypt the PEM encoded private key
+(`reindex.ssl.key`) if it is encrypted.
+Cannot be used with `reindex.ssl.secure_key_passphrase`. 
+
+`reindex.ssl.secure_key_passphrase` (<<secure-settings,Secure>>)::
+Specifies the passphrase to decrypt the PEM encoded private key
+(`reindex.ssl.key`) if it is encrypted.
+Cannot be used with `reindex.ssl.key_passphrase`. 
+
+`reindex.ssl.keystore.path`::
+Specifies the path to the keystore that contains a private key and certificate
+to be used for HTTP client authentication (if required by the remote cluster).
+This keystore can be in "JKS" or "PKCS#12" format.
+You cannot specify both `reindex.ssl.key` and `reindex.ssl.keystore.path`.
+
+`reindex.ssl.keystore.type`::
+The type of the keystore (`reindex.ssl.keystore.path`). Must be either `jks` or `PKCS12`.
+If the keystore path ends in ".p12", ".pfx" or "pkcs12", this setting defaults 
+to `PKCS12`. Otherwise, it defaults to `jks`.
+
+`reindex.ssl.keystore.password`::
+The password to the keystore (`reindex.ssl.keystore.path`). This setting cannot be used 
+with `reindex.ssl.keystore.secure_password`.
+
+`reindex.ssl.keystore.secure_password` (<<secure-settings,Secure>>)::
+The password to the keystore (`reindex.ssl.keystore.path`).
+This setting cannot be used with `reindex.ssl.keystore.password`.
+
+`reindex.ssl.keystore.key_password`::
+The password for the key in the keystore (`reindex.ssl.keystore.path`).
+Defaults to the keystore password. This setting cannot be used with 
+`reindex.ssl.keystore.secure_key_password`.
+
+`reindex.ssl.keystore.secure_key_password` (<<secure-settings,Secure>>)::
+The password for the key in the keystore (`reindex.ssl.keystore.path`).
+Defaults to the keystore password. This setting cannot be used with 
+`reindex.ssl.keystore.key_password`.
+
 [float]
 === URL Parameters