OpenSearch Configuration

This configuration applies only to Guice wiring.

Consult opensearch.properties to get some examples and hints.

Connection to a cluster :
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.
Or you can connect a cluster by :
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
Other options includes :
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.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.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.

Here are the different properties:
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.
Note: You can launch a tika server using this command line:
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
allow specifying search overrides and is a coma separated list of search override FQDNs. Default to none.

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