OpenSearch Configuration

Consult opensearch.properties to get some examples and hints.

opensearch.masterHost

Is the IP (or host) of the OpenSearch master

opensearch.port

Is the port of OpenSearch master

opensearch.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.

opensearch.user

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

opensearch.password

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

opensearch.hosts

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

opensearch.clusterName

Is the name of the cluster used by James.

opensearch.nb.shards

Number of shards for index provisionned by James

opensearch.nb.replica

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

opensearch.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.

opensearch.index.mailbox.name

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

opensearch.index.name

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

opensearch.max.connections

Maximum count of HTTP connections allowed for the OpenSearch driver. Optional integer, if unspecified driver defaults applies (30 connections).

opensearch.max.connections.per.hosts

Maximum count of HTTP connections per host allowed for the OpenSearch driver. Optional integer, if unspecified driver defaults applies (10 connections).

opensearch.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.

opensearch.alias.read.name

Deprecated Use opensearch.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.

opensearch.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.

opensearch.alias.write.name

Deprecated Use opensearch.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.

opensearch.retryConnection.maxRetries

Number of retries when connecting the cluster

opensearch.retryConnection.minDelay

Minimum delay between connection attempts

opensearch.indexAttachments

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

opensearch.indexHeaders

Indicates if you wish to index headers or not (default: true). Note that specific headers (From, To, Cc, Bcc, Subject, Message-Id, Date, Content-Type) are still indexed in their dedicated type. Header indexing is expensive as each header currently need to be stored as a nested document but turning off headers indexing result in non-strict compliance with the IMAP / JMAP standards.

opensearch.message.index.optimize.move

When set to true, James will attempt to reindex from the indexed message when moved. If the message is not found, it will fall back to the old behavior (The message will be indexed from the blobStore source). Default to false.

opensearch.text.fuzziness.search

Use fuzziness on text searches. This option helps to correct user typing mistakes and makes the result a bit more flexible. Default to false.

opensearch.indexBody

Indicates if you wish to index body or not (default: true). This can be used to decrease the performance cost associated with indexing.

opensearch.indexUser

Indicates if you wish to index user or not (default: false). This can be used to have per user reports in OpenSearch Dashboards.

opensearch.index.quota.ratio.name

Specify the OpenSearch alias name used for quotas

opensearch.alias.read.quota.ratio.name

Specify the OpenSearch alias name used for reading quotas

opensearch.alias.write.quota.ratio.name

Specify the OpenSearch alias name used for writing quotas

OpenSearch 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 OpenSearch). Setting this configuration parameter to scanning will effectively disable OpenSearch, no further indexation will be done however searches will rely on the scrolling search, leading to expensive and longer searches. Disabling OpenSearch requires no extra action, however a full re-indexing needs to be carried out when enabling OpenSearch.

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

Tika Configuration

When using OpenSearch, 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 OpenSearch

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.

opensearch.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.

opensearch.hostScheme.https.trustStorePath

Optional. Use it when https is configured in opensearch.hostScheme, and sslValidationStrategy is override Configure OpenSearch 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.

opensearch.hostScheme.https.trustStorePassword

Optional. Use it when https is configured in opensearch.hostScheme, and sslValidationStrategy is override Configure OpenSearch 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.

opensearch.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).

Search overrides

Search overrides allow resolution of predefined search queries against alternative sources of data and allow bypassing OpenSearch. This is useful to handle most resynchronisation queries that are simple enough to be resolved against Cassandra.

Possible values are:


• org.apache.james.mailbox.cassandra.search.AllSearchOverride

  Some IMAP clients uses SEARCH ALL to fully list messages in a mailbox and detect deletions. This is typically done by clients not supporting QRESYNC and from an IMAP perspective is considered an optimisation as less data is transmitted compared to a FETCH command. Resolving such requests against Cassandra is enabled by this search override and likely desirable.

• org.apache.james.mailbox.cassandra.search.UidSearchOverride

  . Same as above but restricted by ranges.

• org.apache.james.mailbox.cassandra.search.DeletedSearchOverride

  . Find deleted messages by looking up in the relevant Cassandra table.

• org.apache.james.mailbox.cassandra.search.DeletedWithRangeSearchOverride

  . Same as above but limited by ranges.

• org.apache.james.mailbox.cassandra.search.NotDeletedWithRangeSearchOverride

  . List non deleted messages in a given range.
Lists all messages and filters out deleted message thus this is based on the following heuristic: most messages are not marked as deleted.

• org.apache.james.mailbox.cassandra.search.UnseenSearchOverride

  . List unseen messages in the corresponding cassandra projection.

Please note that custom overrides can be defined here.

opensearch.search.overrides

EG:

opensearch.search.overrides=org.apache.james.mailbox.cassandra.search.AllSearchOverride,org.apache.james.mailbox.cassandra.search.DeletedSearchOverride, org.apache.james.mailbox.cassandra.search.DeletedWithRangeSearchOverride,org.apache.james.mailbox.cassandra.search.NotDeletedWithRangeSearchOverride,org.apache.james.mailbox.cassandra.search.UidSearchOverride,org.apache.james.mailbox.cassandra.search.UnseenSearchOverride