ElasticSearch Configuration

Consult elasticsearch.properties to get some examples and hints.

elasticsearch.masterHost

Is the IP (or host) of the ElasticSearch master

elasticsearch.port

Is the port of ElasticSearch master

elasticsearch.hostScheme

Optional. Only http or https are accepted, default is http. In case of https, and you want to override the default SSL Validation behavior of the client, consult the section SSL Trusting Configuration for more details.

elasticsearch.user

Optional. Basic auth username to access elasticsearch. Ignore elasticsearch.user and elasticsearch.password to not be using authentication (default behaviour). Otherwise, you need to specify both properties.

elasticsearch.password

Optional. Basic auth password to access elasticsearch. Ignore elasticsearch.user and elasticsearch.password to not be using authentication (default behaviour). Otherwise, you need to specify both properties.

elasticsearch.hosts

List of comma separated hosts. An host is composed of an address and a port separated by a ':'. Example : elasticsearch.hosts=host1:9200,host2:9200

elasticsearch.clusterName

Is the name of the cluster used by James.

elasticsearch.nb.shards

Number of shards for index provisionned by James

elasticsearch.nb.replica

Number of replica for index provisionned by James (default: 0)

elasticsearch.index.waitForActiveShards (default: 1)

Wait for a certain number of active shard copies before proceeding with the operation.

You may consult the documentation for more information.

elasticsearch.index.mailbox.name

Name of the mailbox index backed by the alias. It will be created if missing.

elasticsearch.index.name

Deprecated Use elasticsearch.index.mailbox.name instead.
Name of the mailbox index backed by the alias. It will be created if missing.

elasticsearch.alias.read.mailbox.name

Name of the alias to use by Apache James for mailbox reads. It will be created if missing. The target of the alias is the index name configured above.

elasticsearch.alias.read.name

Deprecated Use elasticsearch.alias.read.mailbox.name instead.
Name of the alias to use by Apache James for mailbox reads. It will be created if missing. The target of the alias is the index name configured above.

elasticsearch.alias.write.mailbox.name

Name of the alias to use by Apache James for mailbox writes. It will be created if missing. The target of the alias is the index name configured above.

elasticsearch.alias.write.name

Deprecated Use elasticsearch.alias.write.mailbox.name instead.
Name of the alias to use by Apache James for mailbox writes. It will be created if missing. The target of the alias is the index name configured above.

elasticsearch.retryConnection.maxRetries

Number of retries when connecting the cluster

elasticsearch.retryConnection.minDelay

Minimum delay between connection attempts

elasticsearch.indexAttachments

Indicates if you wish to index attachments or not (default: true).

elasticsearch.index.quota.ratio.name

Specify the ElasticSearch alias name used for quotas

elasticsearch.alias.read.quota.ratio.name

Specify the ElasticSearch alias name used for reading quotas

elasticsearch.alias.write.quota.ratio.name

Specify the ElasticSearch alias name used for writing quotas

ElasticSearch component can be disabled but consider it would make search feature to not work. In particular it will break JMAP protocol and SEARCH IMAP comment in an nondeterministic way. This is controlled in the search.properties file via the implementation property (defaults to ElasticSearch). Setting this configuration parameter to scanning will effectively disable ElasticSearch, no further indexation will be done however searches will rely on the scrolling search, leading to expensive and longer searches. Disabling ElasticSearch requires no extra action, however a full re-indexing needs to be carried out when enabling ElasticSearch.

In server version 3.6.0 james moved from Elasticsearch 6 to 7 and the metric reporting on Elasticsearch is deprecated. You can still use metric reporting on Elasticsearch but that requires you to run a separate Elasticsearch 6 instance and use that in your Elasticsearch metric reporting configuration.

elasticsearch.http.host

Host to report metrics on. Defaults to master host. Compatible with 6.x hosts

elasticsearch.http.port

Http port to use for publishing metrics

elasticsearch.metrics.reports.enabled

Boolean value. Enables metrics reporting.

elasticsearch.metrics.reports.period

Seconds between metric reports

elasticsearch.metrics.reports.index

Index to publish metrics on

If you want more explanation about ElasticSearch configuration, you should visit the dedicated documentation.

Tika Configuration

When using ElasticSearch, you can configure an external Tika server for extracting and indexing text from attachments. Thus you can significantly improve user experience upon text searches.

Note that to use this feature you need Guice, built with ElasticSearch

Consult tika.properties to get some examples and hints.

tika.enabled

Should Tika text extractor be used?
If true, the TikaTextExtractor will be used behind a cache.
If false, the DefaultTextExtractor will be used (naive implementation only supporting text).
Defaults to false.

tika.host

IP or domain name of your Tika server. The default value is 127.0.0.1

tika.port

Port of your tika server. The default value is 9998

tika.timeoutInMillis

Timeout when issuing request to the tika server. The default value is 3 seconds.

tika.cache.eviction.period

A cache is used to avoid, when possible, query Tika multiple time for the same attachments.
This entry determines how long after the last read an entry vanishes.
Please note that units are supported (ms - millisecond, s - second, m - minute, h - hour, d - day). Default unit is seconds.
Default value is 1 day

tika.cache.enabled

Should the cache be used? False by default

tika.cache.weight.max

Maximum weight of the cache.
A value of 0 disables the cache
Please note that units are supported (K for KB, M for MB, G for GB). Defaults is no units, so in bytes.
Default value is 100 MB.

tika.contentType.blacklist

Blacklist of content type is known-to-be-failing with Tika. Specify the list with comma separator.

docker run --name tika linagora/docker-tikaserver:1.24

SSL Trusting Configuration

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.

elasticsearch.hostScheme.https.sslValidationStrategy

Optional. Accept only default, ignore, override. Default is default

default: Use the default SSL TrustStore of the system. ignore: Ignore SSL Validation check (not recommended). override: Override the SSL Context to use a custom TrustStore containing ES server's certificate.

In some cases, you want to secure the connection from clients to ES by setting up a https protocol with a self signed certificate. And you prefer to left the system ca-certificates un touch. There are possible solutions to let the ES RestHighLevelClient to trust your self signed certificate.

First solution: ignoring SSL check. 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.

Second solution: importing a TrustStore containing the certificate into SSL context. A certificate normally contains two parts: a public part in .crt file, another private part in .key file. To trust the server, the client needs 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:

            keytool -import -v -trustcacerts -file certificatePublicFile.crt -keystore trustStoreFileName.jks -keypass fillThePassword -storepass fillThePassword
        

When there is a TrustStore file and the password to read, fill two options trustStorePath and trustStorePassword with the TrustStore location and the password. ES client will accept the certificate of ES service.

elasticsearch.hostScheme.https.trustStorePath

Optional. Use it when https is configured in elasticsearch.hostScheme, and sslValidationStrategy is override Configure Elasticsearch rest client to use this trustStore file to recognize nginx's ssl certificate. Once you chose override, you need to specify both trustStorePath and trustStorePassword.

elasticsearch.hostScheme.https.trustStorePassword

Optional. Use it when https is configured in elasticsearch.hostScheme, and sslValidationStrategy is override Configure Elasticsearch rest client to use this trustStore file with the specified password. Once you chose override, you need to specify both trustStorePath and trustStorePassword.

During SSL handshaking, the client can determine whether accept or reject connecting to a remote server by its hostname. You can configure to use which HostNameVerifier in the client.

elasticsearch.hostScheme.https.hostNameVerifier

Optional. Default is default.

default: using the default hostname verifier provided by apache http client. accept_any_hostname: accept any host (not recommended).