You are viewing a plain text version of this content. The canonical link for it is here.
Posted to server-dev@james.apache.org by ro...@apache.org on 2019/11/14 09:13:25 UTC
[james-project] 05/07: JAMES-2905 Update documentation
This is an automated email from the ASF dual-hosted git repository.
rouazana pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/james-project.git
commit e60d88ef8b8706be3cd954320253aaec3449d066
Author: Tran Tien Duc <dt...@linagora.com>
AuthorDate: Tue Nov 12 16:37:17 2019 +0700
JAMES-2905 Update documentation
---
.../destination/conf/elasticsearch.properties | 18 +++++-
.../destination/conf/elasticsearch.properties | 17 ++++++
.../destination/conf/elasticsearch.properties | 18 +++++-
.../destination/conf/elasticsearch.properties | 17 ++++++
src/site/xdoc/server/config-elasticsearch.xml | 66 +++++++++++++++++++++-
5 files changed, 131 insertions(+), 5 deletions(-)
diff --git a/dockerfiles/run/guice/cassandra-ldap/destination/conf/elasticsearch.properties b/dockerfiles/run/guice/cassandra-ldap/destination/conf/elasticsearch.properties
index 8302e15..f28c38a 100644
--- a/dockerfiles/run/guice/cassandra-ldap/destination/conf/elasticsearch.properties
+++ b/dockerfiles/run/guice/cassandra-ldap/destination/conf/elasticsearch.properties
@@ -25,8 +25,22 @@
elasticsearch.masterHost=elasticsearch
elasticsearch.port=9200
-# Optional. Only http or https are accepted, default is http
-# elasticsearch.hostScheme=http
+# Optional, default is `default`
+# Choosing the SSL check strategy when using https scheme
+# default: Use the default SSL TrustStore of the system.
+# ignore: Ignore SSL Validation check (not recommended).
+# override: Override the SSL Context to use a custome TrustStore containing ES server's certificate.
+# elasticsearch.hostScheme.https.sslValidationStrategy=default
+
+# Optional. Required when using 'https' scheme and 'override' sslValidationStrategy
+# Configure Elasticsearch rest client to use this trustStore file to recognize nginx's ssl certificate.
+# You need to specify both trustStorePath and trustStorePassword
+# elasticsearch.hostScheme.https.trustStorePath=/file/to/trust/keystore.jks
+
+# Optional. Required when using 'https' scheme and 'override' sslValidationStrategy
+# Configure Elasticsearch rest client to use this trustStore file with the specified password.
+# You need to specify both trustStorePath and trustStorePassword
+# elasticsearch.hostScheme.https.trustStorePassword=myJKSPassword
# Optional.
# Basic auth username to access elasticsearch.
diff --git a/dockerfiles/run/guice/cassandra-rabbitmq-ldap/destination/conf/elasticsearch.properties b/dockerfiles/run/guice/cassandra-rabbitmq-ldap/destination/conf/elasticsearch.properties
index 69c0eee..3490e61 100644
--- a/dockerfiles/run/guice/cassandra-rabbitmq-ldap/destination/conf/elasticsearch.properties
+++ b/dockerfiles/run/guice/cassandra-rabbitmq-ldap/destination/conf/elasticsearch.properties
@@ -27,6 +27,23 @@ elasticsearch.port=9200
# Optional. Only http or https are accepted, default is http
# elasticsearch.hostScheme=http
+# Optional, default is `default`
+# Choosing the SSL check strategy when using https scheme
+# default: Use the default SSL TrustStore of the system.
+# ignore: Ignore SSL Validation check (not recommended).
+# override: Override the SSL Context to use a custome TrustStore containing ES server's certificate.
+# elasticsearch.hostScheme.https.sslValidationStrategy=default
+
+# Optional. Required when using 'https' scheme and 'override' sslValidationStrategy
+# Configure Elasticsearch rest client to use this trustStore file to recognize nginx's ssl certificate.
+# You need to specify both trustStorePath and trustStorePassword
+# elasticsearch.hostScheme.https.trustStorePath=/file/to/trust/keystore.jks
+
+# Optional. Required when using 'https' scheme and 'override' sslValidationStrategy
+# Configure Elasticsearch rest client to use this trustStore file with the specified password.
+# You need to specify both trustStorePath and trustStorePassword
+# elasticsearch.hostScheme.https.trustStorePassword=myJKSPassword
+
# Optional.
# Basic auth username to access elasticsearch.
# Ignore elasticsearch.user and elasticsearch.password to not be using authentication (default behaviour).
diff --git a/dockerfiles/run/guice/cassandra-rabbitmq/destination/conf/elasticsearch.properties b/dockerfiles/run/guice/cassandra-rabbitmq/destination/conf/elasticsearch.properties
index 69c0eee..7c23c72 100644
--- a/dockerfiles/run/guice/cassandra-rabbitmq/destination/conf/elasticsearch.properties
+++ b/dockerfiles/run/guice/cassandra-rabbitmq/destination/conf/elasticsearch.properties
@@ -24,8 +24,22 @@
elasticsearch.masterHost=elasticsearch
elasticsearch.port=9200
-# Optional. Only http or https are accepted, default is http
-# elasticsearch.hostScheme=http
+# Optional, default is `default`
+# Choosing the SSL check strategy when using https scheme
+# default: Use the default SSL TrustStore of the system.
+# ignore: Ignore SSL Validation check (not recommended).
+# override: Override the SSL Context to use a custome TrustStore containing ES server's certificate.
+# elasticsearch.hostScheme.https.sslValidationStrategy=default
+
+# Optional. Required when using 'https' scheme and 'override' sslValidationStrategy
+# Configure Elasticsearch rest client to use this trustStore file to recognize nginx's ssl certificate.
+# You need to specify both trustStorePath and trustStorePassword
+# elasticsearch.hostScheme.https.trustStorePath=/file/to/trust/keystore.jks
+
+# Optional. Required when using 'https' scheme and 'override' sslValidationStrategy
+# Configure Elasticsearch rest client to use this trustStore file with the specified password.
+# You need to specify both trustStorePath and trustStorePassword
+# elasticsearch.hostScheme.https.trustStorePassword=myJKSPassword
# Optional.
# Basic auth username to access elasticsearch.
diff --git a/dockerfiles/run/guice/cassandra/destination/conf/elasticsearch.properties b/dockerfiles/run/guice/cassandra/destination/conf/elasticsearch.properties
index 8302e15..077e76c 100644
--- a/dockerfiles/run/guice/cassandra/destination/conf/elasticsearch.properties
+++ b/dockerfiles/run/guice/cassandra/destination/conf/elasticsearch.properties
@@ -28,6 +28,23 @@ elasticsearch.port=9200
# Optional. Only http or https are accepted, default is http
# elasticsearch.hostScheme=http
+# Optional, default is `default`
+# Choosing the SSL check strategy when using https scheme
+# default: Use the default SSL TrustStore of the system.
+# ignore: Ignore SSL Validation check (not recommended).
+# override: Override the SSL Context to use a custome TrustStore containing ES server's certificate.
+# elasticsearch.hostScheme.https.sslValidationStrategy=default
+
+# Optional. Required when using 'https' scheme and 'override' sslValidationStrategy
+# Configure Elasticsearch rest client to use this trustStore file to recognize nginx's ssl certificate.
+# You need to specify both trustStorePath and trustStorePassword
+# elasticsearch.hostScheme.https.trustStorePath=/file/to/trust/keystore.jks
+
+# Optional. Required when using 'https' scheme and 'override' sslValidationStrategy
+# Configure Elasticsearch rest client to use this trustStore file with the specified password.
+# You need to specify both trustStorePath and trustStorePassword
+# elasticsearch.hostScheme.https.trustStorePassword=myJKSPassword
+
# Optional.
# Basic auth username to access elasticsearch.
# Ignore elasticsearch.user and elasticsearch.password to not be using authentication (default behaviour).
diff --git a/src/site/xdoc/server/config-elasticsearch.xml b/src/site/xdoc/server/config-elasticsearch.xml
index b7a6213..77f0fc4 100644
--- a/src/site/xdoc/server/config-elasticsearch.xml
+++ b/src/site/xdoc/server/config-elasticsearch.xml
@@ -40,7 +40,11 @@
<dd>Is the port of ElasticSearch master</dd>
<dt><strong>elasticsearch.hostScheme</strong></dt>
- <dd>Optional. Only http or https are accepted, default is http</dd>
+ <dd>
+ Optional. Only http or https are accepted, default is http. In case of <strong>https</strong>,
+ and you want to override the default SSL Validation behavior of the client,
+ consult the section <strong>SSL Trusting Configuration</strong> for more details.
+ </dd>
<dt><strong>elasticsearch.user</strong></dt>
<dd>
@@ -186,6 +190,66 @@
</section>
+ <section name="SSL Trusting Configuration">
+
+ <p>
+ By default James will use the system TrustStore to validate https server certificates, if the certificate on
+ ES side is already in the system TrustStore, you can leave the sslValidationStrategy property empty or set it to default.
+ </p>
+
+ <dl>
+ <dt><strong>elasticsearch.hostScheme.https.sslValidationStrategy</strong></dt>
+ <dd>
+ Optional. Accept only <strong>default</strong>, <strong>ignore</strong>, <strong>override</strong>. Default is <strong>default</strong>
+ </dd>
+ <dd>
+ default: Use the default SSL TrustStore of the system.
+ ignore: Ignore SSL Validation check (not recommended).
+ override: Override the SSL Context to use a custome TrustStore containing ES server's certificate.
+ </dd>
+ </dl>
+
+ <p>
+ In some cases, you want to secure ES to protect it from unauthorized requests,
+ assuming with the ES is using <strong>https</strong> with a self signed certificate.
+ Which means you should configure the ES RestHighLevelClient to trust your self signed certificate.
+
+ There are two ways on client side: ignoring SSL check or configure to trust the server's certificate.
+ In case you want to ignore the SSL check, simply, just don't specify below options. Otherwise, configuring the trust
+ requires some prerequisites and they are explained in below block.
+
+ A certificate normally contains two parts: a public part in .crt file, another private part in .key file.
+ To trust the server, the client need to be acknowledged that the server's certificate is in the list of
+ client's TrustStore. Basically, you can create a local TrustStore file containing the public part of a remote server
+ by execute this command:
+ </p>
+
+ <code><pre>
+ keytool -import -v -trustcacerts -file certificatePublicFile.crt -keystore trustStoreFileName.jks -keypass fillThePassword -storepass fillThePassword
+ </pre></code>
+
+ <p>
+ When there is a TrustStore file and the password to read, fill two options <strong>trustStorePath</strong>
+ and <strong>trustStorePassword</strong> with the TrustStore location and the password. ES client will accept
+ the certificate of ES service.
+ </p>
+
+ <dl>
+ <dt><strong>elasticsearch.hostScheme.https.trustStorePath</strong></dt>
+ <dd>
+ Optional. Use it when https is configured in elasticsearch.hostScheme, and sslValidationStrategy is <strong>override</strong>
+ Configure Elasticsearch rest client to use this trustStore file to recognize nginx's ssl certificate.
+ Once, you chose <strong>override</strong>, you need to specify both trustStorePath and trustStorePassword.
+ </dd>
+
+ <dt><strong>elasticsearch.hostScheme.https.trustStorePassword</strong></dt>
+ <dd>
+ Optional. Use it when https is configured in elasticsearch.hostScheme, and sslValidationStrategy is <strong>override</strong>
+ Configure Elasticsearch rest client to use this trustStore file with the specified password.
+ Once, you chose <strong>override</strong>, you need to specify both trustStorePath and trustStorePassword.
+ </dd>
+ </dl>
+ </section>
</body>
</document>
---------------------------------------------------------------------
To unsubscribe, e-mail: server-dev-unsubscribe@james.apache.org
For additional commands, e-mail: server-dev-help@james.apache.org