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 <[email protected]> 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: [email protected] For additional commands, e-mail: [email protected]
