From 90e2000e9bf72e47883fa3c76f48353ef42c5f9f Mon Sep 17 00:00:00 2001
From: Tung Tran
Date: Mon, 1 Jul 2024 08:25:14 +0700
Subject: [PATCH 001/341] [Antora] Make partial for server configure section &
clean format
---
.../distributed/configure/batchsizes.adoc | 33 +-
.../distributed/configure/blobstore.adoc | 182 +--------
.../configure/collecting-contacts.adoc | 39 +-
.../configure/collecting-events.adoc | 69 +---
.../pages/distributed/configure/dns.adoc | 54 +--
.../distributed/configure/domainlist.adoc | 44 +--
.../distributed/configure/droplists.adoc | 32 +-
.../pages/distributed/configure/dsn.adoc | 219 +----------
.../distributed/configure/extensions.adoc | 61 +--
.../distributed/configure/healthcheck.adoc | 24 +-
.../pages/distributed/configure/imap.adoc | 182 +--------
.../pages/distributed/configure/index.adoc | 88 +----
.../pages/distributed/configure/jmap.adoc | 185 +--------
.../pages/distributed/configure/jmx.adoc | 66 +---
.../pages/distributed/configure/jvm.adoc | 104 +----
.../distributed/configure/listeners.adoc | 157 +-------
.../configure/mailetcontainer.adoc | 96 +----
.../pages/distributed/configure/mailets.adoc | 151 +------
.../configure/mailrepositorystore.adoc | 40 +-
.../pages/distributed/configure/matchers.adoc | 167 +-------
.../distributed/configure/opensearch.adoc | 322 +--------------
.../pages/distributed/configure/pop3.adoc | 78 +---
.../pages/distributed/configure/queue.adoc | 18 +-
.../pages/distributed/configure/rabbitmq.adoc | 172 +-------
.../configure/recipientrewritetable.adoc | 19 +-
.../pages/distributed/configure/redis.adoc | 46 +--
.../remote-delivery-error-handling.adoc | 119 +-----
.../pages/distributed/configure/search.adoc | 17 +-
.../pages/distributed/configure/sieve.adoc | 93 +----
.../distributed/configure/smtp-hooks.adoc | 371 +-----------------
.../pages/distributed/configure/smtp.adoc | 317 +--------------
.../pages/distributed/configure/spam.adoc | 192 +--------
.../pages/distributed/configure/ssl.adoc | 248 +-----------
.../pages/distributed/configure/tika.adoc | 50 +--
.../configure/usersrepository.adoc | 135 +------
.../pages/distributed/configure/vault.adoc | 40 +-
.../pages/distributed/configure/webadmin.adoc | 101 +----
.../partials/configure/batchsizes.adoc | 31 ++
.../servers/partials/configure/blobstore.adoc | 173 ++++++++
.../configure/collecting-contacts.adoc | 38 ++
.../partials/configure/collecting-events.adoc | 68 ++++
.../servers/partials/configure/dns.adoc | 52 +++
.../partials/configure/domainlist.adoc | 42 ++
.../servers/partials/configure/droplists.adoc | 30 ++
.../servers/partials/configure/dsn.adoc | 217 ++++++++++
.../partials/configure/extensions.adoc | 60 +++
.../configure/forCoreComponentsPartial.adoc | 15 +
.../configure/forExtensionsPartial.adoc | 14 +
.../configure/forProtocolsPartial.adoc | 15 +
.../forStorageDependenciesPartial.adoc | 11 +
.../partials/configure/healthcheck.adoc | 22 ++
.../servers/partials/configure/imap.adoc | 179 +++++++++
.../servers/partials/configure/jmap.adoc | 181 +++++++++
.../servers/partials/configure/jmx.adoc | 64 +++
.../servers/partials/configure/jvm.adoc | 102 +++++
.../servers/partials/configure/listeners.adoc | 156 ++++++++
.../partials/configure/mailetcontainer.adoc | 95 +++++
.../servers/partials/configure/mailets.adoc | 146 +++++++
.../configure/mailrepositorystore.adoc | 34 ++
.../servers/partials/configure/matchers.adoc | 166 ++++++++
.../partials/configure/opensearch.adoc | 310 +++++++++++++++
.../servers/partials/configure/pop3.adoc | 74 ++++
.../servers/partials/configure/queue.adoc | 16 +
.../servers/partials/configure/rabbitmq.adoc | 162 ++++++++
.../configure/recipientrewritetable.adoc | 15 +
.../servers/partials/configure/redis.adoc | 28 ++
.../remote-delivery-error-handling.adoc | 117 ++++++
.../servers/partials/configure/search.adoc | 15 +
.../servers/partials/configure/sieve.adoc | 89 +++++
.../partials/configure/smtp-hooks.adoc | 364 +++++++++++++++++
.../servers/partials/configure/smtp.adoc | 315 +++++++++++++++
.../servers/partials/configure/spam.adoc | 191 +++++++++
.../servers/partials/configure/ssl.adoc | 253 ++++++++++++
.../configure/systemPropertiesPartial.adoc | 23 ++
.../servers/partials/configure/tika.adoc | 48 +++
.../partials/configure/usersrepository.adoc | 126 ++++++
.../servers/partials/configure/vault.adoc | 29 ++
.../servers/partials/configure/webadmin.adoc | 104 +++++
78 files changed, 4324 insertions(+), 4197 deletions(-)
create mode 100644 docs/modules/servers/partials/configure/batchsizes.adoc
create mode 100644 docs/modules/servers/partials/configure/blobstore.adoc
create mode 100644 docs/modules/servers/partials/configure/collecting-contacts.adoc
create mode 100644 docs/modules/servers/partials/configure/collecting-events.adoc
create mode 100644 docs/modules/servers/partials/configure/dns.adoc
create mode 100644 docs/modules/servers/partials/configure/domainlist.adoc
create mode 100644 docs/modules/servers/partials/configure/droplists.adoc
create mode 100644 docs/modules/servers/partials/configure/dsn.adoc
create mode 100644 docs/modules/servers/partials/configure/extensions.adoc
create mode 100644 docs/modules/servers/partials/configure/forCoreComponentsPartial.adoc
create mode 100644 docs/modules/servers/partials/configure/forExtensionsPartial.adoc
create mode 100644 docs/modules/servers/partials/configure/forProtocolsPartial.adoc
create mode 100644 docs/modules/servers/partials/configure/forStorageDependenciesPartial.adoc
create mode 100644 docs/modules/servers/partials/configure/healthcheck.adoc
create mode 100644 docs/modules/servers/partials/configure/imap.adoc
create mode 100644 docs/modules/servers/partials/configure/jmap.adoc
create mode 100644 docs/modules/servers/partials/configure/jmx.adoc
create mode 100644 docs/modules/servers/partials/configure/jvm.adoc
create mode 100644 docs/modules/servers/partials/configure/listeners.adoc
create mode 100644 docs/modules/servers/partials/configure/mailetcontainer.adoc
create mode 100644 docs/modules/servers/partials/configure/mailets.adoc
create mode 100644 docs/modules/servers/partials/configure/mailrepositorystore.adoc
create mode 100644 docs/modules/servers/partials/configure/matchers.adoc
create mode 100644 docs/modules/servers/partials/configure/opensearch.adoc
create mode 100644 docs/modules/servers/partials/configure/pop3.adoc
create mode 100644 docs/modules/servers/partials/configure/queue.adoc
create mode 100644 docs/modules/servers/partials/configure/rabbitmq.adoc
create mode 100644 docs/modules/servers/partials/configure/recipientrewritetable.adoc
create mode 100644 docs/modules/servers/partials/configure/redis.adoc
create mode 100644 docs/modules/servers/partials/configure/remote-delivery-error-handling.adoc
create mode 100644 docs/modules/servers/partials/configure/search.adoc
create mode 100644 docs/modules/servers/partials/configure/sieve.adoc
create mode 100644 docs/modules/servers/partials/configure/smtp-hooks.adoc
create mode 100644 docs/modules/servers/partials/configure/smtp.adoc
create mode 100644 docs/modules/servers/partials/configure/spam.adoc
create mode 100644 docs/modules/servers/partials/configure/ssl.adoc
create mode 100644 docs/modules/servers/partials/configure/systemPropertiesPartial.adoc
create mode 100644 docs/modules/servers/partials/configure/tika.adoc
create mode 100644 docs/modules/servers/partials/configure/usersrepository.adoc
create mode 100644 docs/modules/servers/partials/configure/vault.adoc
create mode 100644 docs/modules/servers/partials/configure/webadmin.adoc
diff --git a/docs/modules/servers/pages/distributed/configure/batchsizes.adoc b/docs/modules/servers/pages/distributed/configure/batchsizes.adoc
index 4d6123e468e..be7e6bfb1c2 100644
--- a/docs/modules/servers/pages/distributed/configure/batchsizes.adoc
+++ b/docs/modules/servers/pages/distributed/configure/batchsizes.adoc
@@ -1,34 +1,5 @@
= Distributed James Server — batchsizes.properties
:navtitle: batchsizes.properties
-This files allow to define the amount of data that should be fetched 'at once' when interacting with the mailbox. This is
-needed as IMAP can generate some potentially large requests.
-
-Increasing these values tend to fasten individual requests, at the cost of enabling potential higher load.
-
-Consult this link:https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration/batchsizes.properties[example]
-to get some examples and hints.
-
-.batchsizes.properties content
-|===
-| Property name | explanation
-
-| fetch.metadata
-| Optional, defaults to 200. How many messages should be read in a batch when using FetchType.MetaData
-
-| fetch.headers
-| Optional, defaults to 200. How many messages should be read in a batch when using FetchType.Header
-
-| fetch.body
-| Optional, defaults to 100. How many messages should be read in a batch when using FetchType.Body
-
-| fetch.full
-| Optional, defaults to 50. How many messages should be read in a batch when using FetchType.Full
-
-| copy
-| Optional, defaults to 200. How many messages should be copied in a batch.
-
-| move
-| Optional, defaults to 200. How many messages should be moved in a batch.
-
-|===
\ No newline at end of file
+:sample-configuration-prefix-url: https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration
+include::partial$configure/batchsizes.adoc[]
\ No newline at end of file
diff --git a/docs/modules/servers/pages/distributed/configure/blobstore.adoc b/docs/modules/servers/pages/distributed/configure/blobstore.adoc
index 0ebcf516d5d..84673e86b45 100644
--- a/docs/modules/servers/pages/distributed/configure/blobstore.adoc
+++ b/docs/modules/servers/pages/distributed/configure/blobstore.adoc
@@ -1,6 +1,9 @@
= Distributed James Server — blobstore.properties
:navtitle: blobstore.properties
+:sample-configuration-prefix-url: https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration
+:pages-path: distributed
+
== BlobStore
This file is optional. If omitted, the *cassandra* blob store will be used.
@@ -12,7 +15,7 @@ You can choose the underlying implementation of BlobStore to fit with your James
It could be the implementation on top of Cassandra or file storage service S3 compatible like Openstack Swift and AWS S3.
-Consult link:https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration/blob.properties[blob.properties]
+Consult link:{sample-configuration-prefix-url}/blob.properties[blob.properties]
in GIT to get some examples and hints.
=== Implementation choice
@@ -22,7 +25,7 @@ in GIT to get some examples and hints.
* cassandra: use cassandra based BlobStore
* objectstorage: use Swift/AWS S3 based BlobStore
* file: (experimental) use directly the file system. Useful for legacy architecture based on shared ISCI SANs and/or
- distributed file system with no object store available.
+distributed file system with no object store available.
WARNING: JAMES-3591 Cassandra is not made to store large binary content, its use will be suboptimal compared to
Alternatives (namely S3 compatible BlobStores backed by for instance S3, MinIO or Ozone)
@@ -41,7 +44,7 @@ NOTE: If you are upgrading from James 3.5 or older, the deduplication was enable
Deduplication requires a garbage collector mechanism to effectively drop blobs. A first implementation
based on bloom filters can be used and triggered using the WebAdmin REST API. See
-xref:distributed/operate/webadmin.adoc#_running_blob_garbage_collection[Running blob garbage collection].
+xref:{pages-path}/operate/webadmin.adoc#_running_blob_garbage_collection[Running blob garbage collection].
In order to avoid concurrency issues upon garbage collection, we slice the blobs in generation, the two more recent
generations are not garbage collected.
@@ -52,54 +55,6 @@ but deleted blobs will live longer. Duration, defaults on 30 days, the default u
*deduplication.gc.generation.family*: Every time the duration is changed, this integer counter must be incremented to avoid
conflicts. Defaults to 1.
-=== Encryption choice
-
-Data can be optionally encrypted with a symmetric key using AES before being stored in the blobStore. As many user relies
-on third party for object storage, a compromised third party will not escalate to a data disclosure. Of course, a
-performance price have to be paid, as encryption takes resources.
-
-*encryption.aes.enable* : Optional boolean, defaults to false.
-
-If AES encryption is enabled, then the following properties MUST be present:
-
- - *encryption.aes.password* : String
- - *encryption.aes.salt* : Hexadecimal string
-
-The following properties CAN be supplied:
-
- - *encryption.aes.private.key.algorithm* : String, defaulting to PBKDF2WithHmacSHA512. Previously was
-PBKDF2WithHmacSHA1.
-
-WARNING: Once chosen this choice can not be reverted, all the data is either clear or encrypted. Mixed encryption
-is not supported.
-
-Here is an example of how you can generate the above values (be mindful to customize the byte lengths in order to add
-enough entropy.
-
-....
-# Password generation
-openssl rand -base64 64
-
-# Salt generation
-generate salt with : openssl rand -hex 16
-....
-
-AES blob store supports the following system properties that could be configured in `jvm.properties`:
-
-....
-# Threshold from which we should buffer the blob to a file upon encrypting
-# Unit supported: K, M, G, default to no unit
-james.blob.aes.file.threshold.encrypt=100K
-
-# Threshold from which we should buffer the blob to a file upon decrypting
-# Unit supported: K, M, G, default to no unit
-james.blob.aes.file.threshold.decrypt=256K
-
-# Maximum size of a blob. Larger blobs will be rejected.
-# Unit supported: K, M, G, default to no unit
-james.blob.aes.blob.max.size=100M
-....
-
=== Cassandra BlobStore Cache
A Cassandra cache can be enabled to reduce latency when reading small blobs frequently.
@@ -124,127 +79,4 @@ Supported units: bytes, Kib, MiB, GiB, TiB
Maximum size of stored objects expressed in bytes.
|===
-=== Object storage configuration
-
-==== AWS S3 Configuration
-
-.blobstore.properties S3 related properties
-|===
-| Property name | explanation
-
-| objectstorage.s3.endPoint
-| S3 service endpoint
-
-| objectstorage.s3.region
-| S3 region
-
-| objectstorage.s3.accessKeyId
-| https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys[S3 access key id]
-
-| objectstorage.s3.secretKey
-| https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys[S3 access key secret]
-
-| objectstorage.s3.http.concurrency
-| Allow setting the number of concurrent HTTP requests allowed by the Netty driver.
-
-| objectstorage.s3.truststore.path
-| optional: Verify the S3 server certificate against this trust store file.
-
-| objectstorage.s3.truststore.type
-| optional: Specify the type of the trust store, e.g. JKS, PKCS12
-
-| objectstorage.s3.truststore.secret
-| optional: Use this secret/password to access the trust store; default none
-
-| objectstorage.s3.truststore.algorithm
-| optional: Use this specific trust store algorithm; default SunX509
-
-| objectstorage.s3.trustall
-| optional: boolean. Defaults to false. Cannot be set to true with other trustore options. Wether James should validate
-S3 endpoint SSL certificates.
-
-| objectstorage.s3.read.timeout
-| optional: HTTP read timeout. duration, default value being second. Leaving it empty relies on S3 driver defaults.
-
-| objectstorage.s3.write.timeout
-| optional: HTTP write timeout. duration, default value being second. Leaving it empty relies on S3 driver defaults.
-
-| objectstorage.s3.connection.timeout
-| optional: HTTP connection timeout. duration, default value being second. Leaving it empty relies on S3 driver defaults.
-
-| objectstorage.s3.in.read.limit
-| optional: Object read in memory will be rejected if they exceed the size limit exposed here. Size, exemple `100M`.
-Supported units: K, M, G, defaults to B if no unit is specified. If unspecified, big object won't be prevented
-from being loaded in memory. This settings complements protocol limits.
-
-| objectstorage.s3.upload.retry.maxAttempts
-| optional: Integer. Default is zero. This property specifies the maximum number of retry attempts allowed for failed upload operations.
-
-| objectstorage.s3.upload.retry.backoffDurationMillis
-| optional: Long (Milliseconds). Default is 10 (miliseconds).
-Only takes effect when the "objectstorage.s3.upload.retry.maxAttempts" property is declared.
-This property determines the duration (in milliseconds) to wait between retry attempts for failed upload operations.
-This delay is known as backoff. The jitter factor is 0.5
-
-|===
-
-==== Buckets Configuration
-
-.Bucket configuration
-|===
-| Property name | explanation
-
-| objectstorage.bucketPrefix
-| Bucket is a concept in James and similar to Containers in Swift or Buckets in AWS S3.
-BucketPrefix is the prefix of bucket names in James BlobStore
-
-| objectstorage.namespace
-| BlobStore default bucket name. Most of blobs storing in BlobStore are inside the default bucket.
-Unless a special case like storing blobs of deleted messages.
-|===
-
-== Blob Export
-
-Blob Exporting is the mechanism to help James to export a blob from an user to another user.
-It is commonly used to export deleted messages (consult configuring deleted messages vault).
-The deleted messages are transformed into a blob and James will export that blob to the target user.
-
-This configuration helps you choose the blob exporting mechanism fit with your James setup and it is only applicable with Guice products.
-
-Consult https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration/blob.properties[blob.properties]
-in GIT to get some examples and hints.
-
-Configuration for exporting blob content:
-
-.blobstore.properties content
-|===
-| blob.export.implementation
-
-| localFile: Local File Exporting Mechanism (explained below). Default: localFile
-
-| linshare: LinShare Exporting Mechanism (explained below)
-|===
-
-=== Local File Blob Export Configuration
-
-For each request, this mechanism retrieves the content of a blob and save it to a distinct local file, then send an email containing the absolute path of that file to the target mail address.
-
-Note: that absolute file path is the file location on James server. Therefore, if there are two or more James servers connected, it should not be considered an option.
-
-*blob.export.localFile.directory*: The directory URL to store exported blob data in files, and the URL following
-http://james.apache.org/server/3/apidocs/org/apache/james/filesystem/api/FileSystem.html[James File System scheme].
-Default: file://var/blobExporting
-
-=== LinShare Blob Export Configuration
-
-Instead of exporting blobs in local file system, using https://www.linshare.org[LinShare]
-helps you upload your blobs and people you have been shared to can access those blobs by accessing to
-LinShare server and download them.
-
-This way helps you to share via whole network as long as they can access to LinShare server.
-
-To get an example or details explained, visit https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration/blob.properties[blob.properties]
-
-*blob.export.linshare.url*: The URL to connect to LinShare
-
-*blob.export.linshare.token*: The authentication token to connect to LinShare
+include::partial$configure/blobstore.adoc[]
diff --git a/docs/modules/servers/pages/distributed/configure/collecting-contacts.adoc b/docs/modules/servers/pages/distributed/configure/collecting-contacts.adoc
index ed00b04d243..418700ad921 100644
--- a/docs/modules/servers/pages/distributed/configure/collecting-contacts.adoc
+++ b/docs/modules/servers/pages/distributed/configure/collecting-contacts.adoc
@@ -1,39 +1,4 @@
= Contact collection
-== Motivation
-
-Many modern applications combines email and contacts.
-
-We want recipients of emails sent by a user to automatically be added to this user contacts, for convenience. This
-should even be performed when a user sends emails via SMTP for example using thunderbird.
-
-== Design
-
-The idea is to send AMQP messages holding information about mail envelope for a traitment via a tierce application.
-
-== Configuration
-
-We can achieve this goal by combining simple mailets building blocks.
-
-Here is a sample pipeline achieving aforementioned objectives :
-
-....
-
- extractedContacts
-
-
- amqp://${env:JAMES_AMQP_USERNAME}:${env:JAMES_AMQP_PASSWORD}@${env:JAMES_AMQP_HOST}:${env:JAMES_AMQP_PORT}
- collector:email
- extractedContacts
-
-
-....
-
-A sample message looks like:
-
-....
-{
- "userEmail": "sender@james.org",
- "emails": ["to@james.org"]
-}
-....
\ No newline at end of file
+:sample-configuration-prefix-url: https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration
+include::partial$configure/collecting-contacts.adoc[]
\ No newline at end of file
diff --git a/docs/modules/servers/pages/distributed/configure/collecting-events.adoc b/docs/modules/servers/pages/distributed/configure/collecting-events.adoc
index f103a76a23d..0d8532bf178 100644
--- a/docs/modules/servers/pages/distributed/configure/collecting-events.adoc
+++ b/docs/modules/servers/pages/distributed/configure/collecting-events.adoc
@@ -1,69 +1,4 @@
= Event collection
-== Motivation
-
-Many calendar application do add events invitation received by email directly in ones calendar.
-
-Such behaviours requires the calendar application to be aware of the ICalendar related emails a user received.
-
-== Design
-
-The idea is to write a portion of mailet pipeline extracting Icalendar attachments and to hold them as attachments that
-can later be sent to other applications over AMQP to be treated in an asynchronous, decoupled fashion.
-
-== Configuration
-
-We can achieve this goal by combining simple mailets building blocks.
-
-Here is a sample pipeline achieving aforementioned objectives :
-
-....
-
-
- text/calendar
- rawIcalendar
-
-
- rawIcalendar
-
-
- rawIcalendar
- icalendar
-
-
- icalendar
-
-
-
- icalendarAsJson
- rawIcalendar
-
-
- amqp://${env:JAMES_AMQP_USERNAME}:${env:JAMES_AMQP_PASSWORD}@${env:JAMES_AMQP_HOST}:${env:JAMES_AMQP_PORT}
- james:events
- icalendarAsJson
-
-
-....
-
-A sample message looks like:
-
-....
-{
- "ical": "RAW_DATA_AS_TEXT_FOLLOWING_ICS_FORMAT",
- "sender": "other@james.apache.org",
- "recipient": "any@james2.apache.org",
- "replyTo": "other@james.apache.org",
- "uid": "f1514f44bf39311568d640727cff54e819573448d09d2e5677987ff29caa01a9e047feb2aab16e43439a608f28671ab7c10e754ce92be513f8e04ae9ff15e65a9819cf285a6962bc",
- "dtstamp": "20170106T115036Z",
- "method": "REQUEST",
- "sequence": "0",
- "recurrence-id": null
-}
-....
-
-The following pipeline positions the X-MEETING-UID in the Header in order for mail user agent to correlate events with this mail.
-The sample look like:
-```
-X-MEETING-UID: f1514f44bf39311568d640727cff54e819573448d09d2e5677987ff29caa01a9e047feb2aab16e43439a608f28671ab7c10e754ce92be513f8e04ae9ff15e65a9819cf285a6962bc
-```
\ No newline at end of file
+:sample-configuration-prefix-url: https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration
+include::partial$configure/collecting-events.adoc[]
\ No newline at end of file
diff --git a/docs/modules/servers/pages/distributed/configure/dns.adoc b/docs/modules/servers/pages/distributed/configure/dns.adoc
index ecc0c80ce38..1954a4b6b35 100644
--- a/docs/modules/servers/pages/distributed/configure/dns.adoc
+++ b/docs/modules/servers/pages/distributed/configure/dns.adoc
@@ -1,55 +1,5 @@
= Distributed James Server — dnsservice.xml
:navtitle: dnsservice.xml
-Consult this link:https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration/dnsservice.xml[example]
-to get some examples and hints.
-
-Specifies DNS Server information for use by various components inside Apache James Server.
-
-DNS Transport services are controlled by a configuration block in
-the dnsservice.xml. This block affects SMTP remote delivery.
-
-The dnsservice tag defines the boundaries of the configuration
-block. It encloses all the relevant configuration for the DNS server.
-The behavior of the DNS service is controlled by the attributes and
-children of this tag.
-
-.dnsservice.xml content
-|===
-| Property name | explanation
-
-| servers
-| Information includes a list of DNS Servers to be used by James. These are
-specified by the server elements, each of which is a child element of the
-servers element. Each server element is the IP address of a single DNS server.
-The server elements can have multiple server children. Enter ip address of your DNS server, one IP address per server
-element. If no DNS servers are found and you have not specified any below, 127.0.0.1 will be used
-
-| autodiscover
-| true or false - If you use autodiscover and add DNS servers manually a combination of all the DNS servers will be used.
-If autodiscover is true, James will attempt to autodiscover the DNS servers configured on your underlying system.
-Currently, this works if the OS has a unix-like /etc/resolv.xml,
-or the system is Windows based with ipconfig or winipcfg. Change autodiscover to false if you would like to turn off autodiscovery
-and set the DNS servers manually in the servers section
-
-| authoritative
-| *true/false* - This tag specifies whether or not
-to require authoritative (non-cached) DNS records; to only accept DNS responses that are
-authoritative for the domain. It is primarily useful in an intranet/extranet environment.
-This should always be *false* unless you understand the implications.
-
-| maxcachesize
-| Maximum number of entries to maintain in the DNS cache (typically 50000)
-
-| negativeCacheTTL
-| Sets the maximum length of time that negative records will be stored in the DNS negative cache in
-seconds (a negative record means the name has not been found in the DNS). Values for this cache
-can be positive meaning the time in seconds before retrying to resolve the name, zero meaning no
-cache or a negative value meaning infinite caching.
-
-| singleIPperMX
-| true or false (default) - Specifies if Apache James Server must try a single server for each multihomed mx host
-
-| verbose
-| Turn on general debugging statements
-|===
+:sample-configuration-prefix-url: https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration
+include::partial$configure/dns.adoc[]
\ No newline at end of file
diff --git a/docs/modules/servers/pages/distributed/configure/domainlist.adoc b/docs/modules/servers/pages/distributed/configure/domainlist.adoc
index 53b9b0f4c46..ad5cbafffea 100644
--- a/docs/modules/servers/pages/distributed/configure/domainlist.adoc
+++ b/docs/modules/servers/pages/distributed/configure/domainlist.adoc
@@ -1,45 +1,5 @@
= Distributed James Server — domainlist.xml
:navtitle: domainlist.xml
-Consult this link:https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration/domainlist.xml[example]
-to get some examples and hints.
-
-This configuration block is defined by the *domainlist* tag.
-
-.domainlist.xml content
-|===
-| Property name | explanation
-
-| domainnames
-| Domainnames identifies the DNS namespace served by this instance of James.
-These domainnames are used for both matcher/mailet processing and SMTP auth
-to determine when a mail is intended for local delivery - Only applicable for XMLDomainList. The entries mentionned here will be created upon start.
-
-|autodetect
-|true or false - If autodetect is true, James wil attempt to discover its own host name AND
-use any explicitly specified servernames.
-If autodetect is false, James will use only the specified domainnames. Defaults to false.
-
-|autodetectIP
-|true or false - If autodetectIP is not false, James will also allow add the IP address for each servername.
-The automatic IP detection is to support RFC 2821, Sec 4.1.3, address literals. Defaults to false.
-
-|defaultDomain
-|Set the default domain which will be used if an email is send to a recipient without a domain part.
-If no defaultdomain is set the first domain of the DomainList gets used. If the default is not yet contained by the Domain List, the domain will be created upon start.
-
-|read.cache.enable
-|Experimental. Boolean, defaults to false.
-Whether or not to cache domainlist.contains calls. Enable a faster execution however writes will take time
-to propagate.
-
-|read.cache.expiracy
-|Experimental. String (duration), defaults to 10 seconds (10s). Supported units are ms, s, m, h, d, w, month, y.
-Expiracy of the cache. Longer means less reads are performed to the backend but writes will take longer to propagate.
-Low values (a few seconds) are advised.
-
-
-|===
-
-To override autodetected domainnames simply add explicit domainname elements.
-In most cases this will be necessary. By default, the domainname 'localhost' is specified. This can be removed, if required.
+:sample-configuration-prefix-url: https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration
+include::partial$configure/domainlist.adoc[]
\ No newline at end of file
diff --git a/docs/modules/servers/pages/distributed/configure/droplists.adoc b/docs/modules/servers/pages/distributed/configure/droplists.adoc
index 375b6156b7f..500aee7a5df 100644
--- a/docs/modules/servers/pages/distributed/configure/droplists.adoc
+++ b/docs/modules/servers/pages/distributed/configure/droplists.adoc
@@ -1,32 +1,6 @@
= Distributed James Server — DropLists
:navtitle: DropLists
-The DropList, also known as the mail blacklist, is a collection of
-domains and email addresses that are denied from sending emails within the system.
-It is disabled by default.
-To enable it, modify the `droplists.properties` file and include the `IsInDropList` matcher in the `mailetcontainer.xml`.
-To disable it, adjust the `droplists.properties` file and remove the `IsInDropList` matcher from the `mailetcontainer.xml`.
-
-.droplists.properties content
-|===
-| Property name | explanation
-
-| enabled
-| Boolean. Governs whether DropLists should be enabled. Defaults to `false`.
-|===
-
-== Enabling Matcher
-
-Plug the `IsInDropList` matcher within `mailetcontainer.xml` :
-
-....
-
- transport
-
-....
-
-== DropList management
-
-DropList management, including adding and deleting entries, is performed through the WebAdmin REST API.
-
-See xref:distributed/operate/webadmin.adoc#_administrating_droplists[WebAdmin DropLists].
\ No newline at end of file
+:sample-configuration-prefix-url: https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration
+:pages-path: distributed
+include::partial$configure/droplists.adoc[]
\ No newline at end of file
diff --git a/docs/modules/servers/pages/distributed/configure/dsn.adoc b/docs/modules/servers/pages/distributed/configure/dsn.adoc
index 714324b6405..8085aaa0dab 100644
--- a/docs/modules/servers/pages/distributed/configure/dsn.adoc
+++ b/docs/modules/servers/pages/distributed/configure/dsn.adoc
@@ -1,218 +1,7 @@
= Distributed James Server — Delivery Submission Notifications
:navtitle: ESMTP DSN setup
-DSN introduced in link:https://tools.ietf.org/html/rfc3461[RFC-3461] allows a SMTP sender to demand status messages,
-defined in link:https://tools.ietf.org/html/rfc3464[RFC-3464] to be sent back to the `Return-Path` upon delivery
-progress.
-
-DSN support is not enabled by default, as it needs specific configuration of the
-xref:distributed/configure/mailetcontainer.adoc[mailetcontainer.xml] to be specification compliant.
-
-To enable it you need to:
-
-- Add DSN SMTP hooks as part of the SMTP server stack
-- Configure xref:distributed/configure/mailetcontainer.adoc[mailetcontainer.xml] to generate DSN bounces when needed
-
-== Enabling DSN in SMTP server stack
-
-For this simply add the `DSN hooks` in the handler chain in `smtpserver.xml` :
-
-....
-
- <...>
-
-
-
-
-
- <...>
-
-
-
-....
-
-== Enabling DSN generation as part of mail processing
-
-For the below conditions to be matched we assume you follow
-xref:distributed/configure/remote-delivery-error-handling.adoc[RemoteDelivery error handling for MXs], which is a
-requirement for detailed RemoteDelivery error and delay handling on top of the Distributed server.
-
-Here is a sample xref:distributed/configure/mailetcontainer.adoc[mailetcontainer.xml] achieving the following DSN generation:
-
-- Generate a generic `delivered` notification if LocalDelivery succeeded, if requested
-- Generate a generic `failed` notification in case of local errors, if requested
-- Generate a specific `failed` notification in case of a non existing local user, if requested
-- Generate a specific `failed` notification in case of an address rewriting loop, if requested
-- Generate a `failed` notification in case of remote permanent errors, if requested. We blame the remote server...
-- Generate a `delayed` notification in case of temporary remote errors we are about to retry, if requested. We blame the remote server...
-- Generate a `failed` notification in case of temporary remote errors we are not going to retry (failed too many time), if requested. We blame the remote server...
-
-....
-
-
-
-
- \
-
-
-
-
-
-
-
-
-
- [FAILED]
- true
- Hi. This is the James mail server at [machine].
-I'm afraid I wasn't able to deliver your message to the following addresses.
-This is a permanent error; I've given up. Sorry it didn't work out. Below
-I include the list of recipients, and the reason why I was unable to deliver
-your message.
- failed
- 5.0.0
-
-
- cassandra://var/mail/error/
-
-
-
-
-
-
-
- false
-
-
-
- [SUCCESS]
- true
- Hi. This is the James mail server at [machine].
-I successfully delivered your message to the following addresses.
-Note that it indicates your recipients received the message but do
-not imply they read it.
- delivered
- 2.0.0
-
-
-
-
-
-
-
- outgoing
- 0
- 0
- 10
- true
-
- remote-delivery-error
-
-
-
- [FAILED]
- true
- Hi. This is the James mail server at [machine].
-I'm afraid I wasn't able to deliver your message to the following addresses.
-This is a permanent error; I've given up. Sorry it didn't work out.
-The remote server we should relay this mail to keep on failing.
-Below I include the list of recipients, and the reason why I was unable to deliver
-your message.
- failed
- 5.0.0
-
-
- cassandra://var/mail/error/remote-delivery/permanent/
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- [FAILED]
- true
- Hi. This is the James mail server at [machine].
-I'm afraid I wasn't able to deliver your message to the following addresses.
-This is a permanent error; I've given up. Sorry it didn't work out.
-The remote server we should relay this mail to returns a permanent error.
-Below I include the list of recipients, and the reason why I was unable to deliver
-your message.
- failed
- 5.0.0
-
-
-
- [DELAYED]
- true
- Hi. This is the James mail server at [machine].
-I'm afraid I wasn't able to deliver your message to the following addresses yet.
-This is a temporary error: I will keep on trying.
-Below I include the list of recipients, and the reason why I was unable to deliver
-your message.
- delayed
- 4.0.0
-
-
-
-
-
-
-
- [FAILED]
- true
- Hi. This is the James mail server at [machine].
-I'm afraid I wasn't able to deliver your message to the following addresses.
-This is a permanent error; I've given up. Sorry it didn't work out.
-The following addresses do not exist here. Sorry.
- failed
- 5.0.0
-
-
- cassandra://var/mail/address-error/
-
-
-
-
-
-
- cassandra://var/mail/relay-denied/
- Warning: You are sending an e-mail to a remote server. You must be authenticated to perform such an operation
-
-
-
-
-
- cassandra://var/mail/rrt-error/
- true
-
-
-
- [FAILED]
- true
- Hi. This is the James mail server at [machine].
-I'm afraid I wasn't able to deliver your message to the following addresses.
-This is a permanent error; I've given up. Sorry it didn't work out.
-The following addresses is caught in a rewriting loop. An admin should come and fix it (you likely want to report it).
-Once resolved the admin should be able to resume the processing of your email.
-Below I include the list of recipients, and the reason why I was unable to deliver
-your message.
- failed
- 5.1.6/defaultStatus>
-
-
-
-
-....
-
-== Limitations
-
-The out of the box tooling do not allow generating `relayed` DSN notification as RemoteDelivery misses a success
-callback.
\ No newline at end of file
+:sample-configuration-prefix-url: https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration
+:pages-path: distributed
+:mailet-repository-path-prefix: cassandra
+include::partial$configure/dsn.adoc[]
\ No newline at end of file
diff --git a/docs/modules/servers/pages/distributed/configure/extensions.adoc b/docs/modules/servers/pages/distributed/configure/extensions.adoc
index a2b496a4453..95f754529c2 100644
--- a/docs/modules/servers/pages/distributed/configure/extensions.adoc
+++ b/docs/modules/servers/pages/distributed/configure/extensions.adoc
@@ -1,61 +1,6 @@
= Distributed James Server — extensions.properties
:navtitle: extensions.properties
-This files enables an operator to define additional bindings used to instantiate others extensions
-
-*guice.extension.module*: come separated list of fully qualified class name. These classes need to implement Guice modules.
-
-Here is an example of such a class :
-
-....
-public class MyServiceModule extends AbstractModule {
- @Override
- protected void configure() {
- bind(MyServiceImpl.class).in(Scopes.SINGLETON);
- bind(MyService.class).to(MyServiceImpl.class);
- }
-}
-....
-
-Recording it in extensions.properties :
-
-....
-guice.extension.module=com.project.MyServiceModule
-....
-
-Enables to inject MyService into your extensions.
-
-
-*guice.extension.tasks*: come separated list of fully qualified class name.
-
-The extension can rely on the Task manager to supervise long-running task execution (progress, await, cancellation, scheduling...).
-These extensions need to implement Task extension modules.
-
-Here is an example of such a class :
-
-....
-public class RspamdTaskExtensionModule implements TaskExtensionModule {
-
- @Inject
- public RspamdTaskExtensionModule() {
- }
-
- @Override
- public Set> taskDTOModules() {
- return Set.of(...);
- }
-
- @Override
- public Set> taskAdditionalInformationDTOModules() {
- return Set.of(...);
- }
-}
-....
-
-Recording it in extensions.properties :
-
-....
-guice.extension.tasks=com.project.RspamdTaskExtensionModule
-....
-
-Read xref:customization:index.adoc#_defining_custom_injections_for_your_extensions[this page] for more details.
+:sample-configuration-prefix-url: https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration
+:pages-path: distributed
+include::partial$configure/extensions.adoc[]
\ No newline at end of file
diff --git a/docs/modules/servers/pages/distributed/configure/healthcheck.adoc b/docs/modules/servers/pages/distributed/configure/healthcheck.adoc
index 37c01f8c818..82a147ea2c6 100644
--- a/docs/modules/servers/pages/distributed/configure/healthcheck.adoc
+++ b/docs/modules/servers/pages/distributed/configure/healthcheck.adoc
@@ -1,25 +1,5 @@
= Distributed James Server — healthcheck.properties
:navtitle: healthcheck.properties
-Consult this link:https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration/healthcheck.properties[example]
-to get some examples and hints.
-
-Use this configuration to define the initial delay and period for the PeriodicalHealthChecks. It is only applicable with Guice products.
-
-.healthcheck.properties content
-|===
-| Property name | explanation
-
-| healthcheck.period
-| Define the period between two periodical health checks (default: 60s). Units supported are (ms - millisecond, s - second, m - minute, h - hour, d - day). Default unit is millisecond.
-
-| reception.check.user
-| User to be using for running the "mail reception" health check. The user must exist.
-If not specified, the mail reception check is a noop.
-
-| reception.check.timeout
-| Period after which mail reception is considered faulty. Defaults to one minute.
-
-| additional.healthchecks
-| List of fully qualified HealthCheck class names in addition to James' default healthchecks. Default to empty list.
-|===
\ No newline at end of file
+:sample-configuration-prefix-url: https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration
+include::partial$configure/healthcheck.adoc[]
\ No newline at end of file
diff --git a/docs/modules/servers/pages/distributed/configure/imap.adoc b/docs/modules/servers/pages/distributed/configure/imap.adoc
index 96ac8c43af6..79c6a9d93a3 100644
--- a/docs/modules/servers/pages/distributed/configure/imap.adoc
+++ b/docs/modules/servers/pages/distributed/configure/imap.adoc
@@ -1,182 +1,6 @@
= Distributed James Server — imapserver.xml
:navtitle: imapserver.xml
-Consult this link:https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration/imapserver.xml[example]
-to get some examples and hints.
-
-The IMAP4 service is controlled by a configuration block in the imap4server.xml.
-The imap4server tag defines the boundaries of the configuration block. It encloses
-all the relevant configuration for the IMAP4 server. The behavior of the IMAP4 service is
-controlled by the attributes and children of this tag.
-
-This tag has an optional boolean attribute - *enabled* - that defines whether the service is active or not.
-The value defaults to "true" if not present.
-
-The standard children of the imapserver tag are:
-
-.imapserver.xml content
-|===
-| Property name | explanation
-
-| bind
-| Configure this to bind to a specific inetaddress. This is an optional integer value. This value is the port on which this IMAP4 server is configured
-to listen. If the tag or value is absent then the service
-will bind to all network interfaces for the machine If the tag or value is omitted, the value will default to the standard IMAP4 port
-port 143 is the well-known/IANA registered port for IMAP
-port 993 is the well-known/IANA registered port for IMAPS ie over SSL/TLS
-
-| connectionBacklog
-| Number of connection backlog of the server (maximum number of queued connection requests)
-
-| compress
-| true or false - Use or don't use COMPRESS extension. Defaults to false.
-
-| maxLineLength
-| Maximal allowed line-length before a BAD response will get returned to the client
-This should be set with caution as a to high value can make the server a target for DOS (Denial of Service)!
-
-| inMemorySizeLimit
-| Optional. Size limit before we will start to stream to a temporary file.
-Defaults to 10MB. Must be a positive integer, optionally with a unit: B, K, M, G.
-
-| literalSizeLimit
-| Optional. Maximum size of a literal (IMAP APPEND).
-Defaults to 0 (unlimited). Must be a positive integer, optionally with a unit: B, K, M, G.
-
-| plainAuthDisallowed
-| Deprecated. Should use `auth.plainAuthEnabled`, `auth.requireSSL` instead.
-Whether to enable Authentication PLAIN if the connection is not encrypted via SSL or STARTTLS. Defaults to `true`.
-
-| auth.plainAuthEnabled
-| Whether to enable Authentication PLAIN/ LOGIN command. Defaults to `true`.
-
-| auth.requireSSL
-| true or false. Defaults to `true`. Whether to require SSL to authenticate. If this is required, the IMAP server will disable authentication on unencrypted channels.
-
-| auth.oidc.oidcConfigurationURL
-| Provide OIDC url address for information to user. Only configure this when you want to authenticate IMAP server using a OIDC provider.
-
-| auth.oidc.jwksURL
-| Provide url to get OIDC's JSON Web Key Set to validate user token. Only configure this when you want to authenticate IMAP server using a OIDC provider.
-
-| auth.oidc.claim
-| Claim string uses to identify user. E.g: "email_address". Only configure this when you want to authenticate IMAP server using a OIDC provider.
-
-| auth.oidc.scope
-| An OAuth scope that is valid to access the service (RF: RFC7628). Only configure this when you want to authenticate IMAP server using a OIDC provider.
-
-| timeout
-| Default to 30 minutes. After this time, inactive channels that have not performed read, write, or both operation for a while
-will be closed. Negative value disable this behaviour.
-
-| enableIdle
-| Default to true. If enabled IDLE commands will generate a server heartbeat on a regular period.
-
-| idleTimeInterval
-| Defaults to 120. Needs to be a strictly positive integer.
-
-| idleTimeIntervalUnit
-| Default to SECONDS. Needs to be a parseable TimeUnit.
-
-| disabledCaps
-| Implemented server capabilities NOT to advertise to the client. Coma separated list. Defaults to no disabled capabilities.
-
-| jmxName
-| The name given to the configuration
-
-| tls
-| Set to true to support STARTTLS or SSL for the Socket.
-To use this you need to copy sunjce_provider.jar to /path/james/lib directory. To create a new keystore execute:
-`keytool -genkey -alias james -keyalg RSA -storetype PKCS12 -keystore /path/to/james/conf/keystore`.
-Please note that each IMAP server exposed on different port can specify its own keystore, independently from any other
-TLS based protocols.
-
-| handler.helloName
-| This is the name used by the server to identify itself in the IMAP4
-protocol. If autodetect is TRUE, the server will discover its
-own host name and use that in the protocol. If discovery fails,
-the value of 'localhost' is used. If autodetect is FALSE, James
-will use the specified value.
-
-| connectiontimeout
-| Connection timeout in seconds
-
-| connectionLimit
-| Set the maximum simultaneous incoming connections for this service
-
-| connectionLimitPerIP
-| Set the maximum simultaneous incoming connections per IP for this service
-
-| concurrentRequests
-| Maximum number of IMAP requests executed simultaneously. Past that limit requests are queued. Defaults to 20.
-Negative values deactivate this feature, leading to unbounded concurrency.
-
-| maxQueueSize
-| Upper bound to the IMAP throttler queue. Upon burst, requests that cannot be queued are rejected and not executed.
-Integer, defaults to 4096, must be positive, 0 means no queue.
-
-| proxyRequired
-| Enables proxy support for this service for incoming connections. HAProxy's protocol
-(https://www.haproxy.org/download/2.7/doc/proxy-protocol.txt) is used and might be compatible
-with other proxies (e.g. traefik). If enabled, it is *required* to initiate the connection
-using HAProxy's proxy protocol.
-
-| bossWorkerCount
-| Set the maximum count of boss threads. Boss threads are responsible for accepting incoming IMAP connections
-and initializing associated resources. Optional integer, by default, boss threads are not used and this responsibility is being dealt with
-by IO threads.
-
-| ioWorkerCount
-| Set the maximum count of IO threads. IO threads are responsible for receiving incoming IMAP messages and framing them
-(split line by line). IO threads also take care of compression and SSL encryption. Their tasks are short-lived and non-blocking.
-Optional integer, defaults to 2 times the count of CPUs.
-
-| ignoreIDLEUponProcessing
-| true or false - Allow disabling the heartbeat handler. Defaults to true.
-
-| useEpoll
-| true or false - If true uses native EPOLL implementation for Netty otherwise uses NIO. Defaults to false.
-
-| gracefulShutdown
-| true or false - If true attempts a graceful shutdown, which is safer but can take time. Defaults to true.
-
-| highWriteBufferWaterMark
-| Netty's write buffer high watermark configuration. Unit supported: none, K, M. Netty defaults applied.
-
-| lowWriteBufferWaterMark
-| Netty's write buffer low watermark configuration. Unit supported: none, K, M. Netty defaults applied.
-|===
-
-== OIDC setup
-James IMAP support XOAUTH2 authentication mechanism which allow authenticating against a OIDC providers.
-Please configure `auth.oidc` part to use this.
-
-We do supply an link:https://github.com/apache/james-project/tree/master/examples/oidc[example] of such a setup.
-It uses the Keycloak OIDC provider, but usage of similar technologies is definitely doable.
-
-== Extending IMAP
-
-IMAP decoders, processors and encoder can be customized. xref:customization:imap.adoc[Read more].
-
-Check this link:https://github.com/apache/james-project/tree/master/examples/custom-imap[example].
-
-The following configuration properties are available for extensions:
-
-.imapserver.xml content
-|===
-| Property name | explanation
-
-| imapPackages
-| Configure (union) of IMAP packages. IMAP packages bundles decoders (parsing IMAP commands) processors and encoders,
-thus enable implementing new IMAP commands or replace existing IMAP processors. List of FQDNs, which can be located in
-James extensions.
-
-| additionalConnectionChecks
-| Configure (union) of additional connection checks. ConnectionCheck will check if the connection IP is secure or not.
-| customProperties
-| Properties for custom extension. Each tag is a property entry, and holds a string under the form key=value.
-|===
-
-== Mail user agents auto-configuration
-
-Check this example on link:https://github.com/apache/james-project/tree/master/examples/imap-autoconf[Mail user agents auto-configuration].
+:sample-configuration-prefix-url: https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration
+:pages-path: distributed
+include::partial$configure/imap.adoc[]
\ No newline at end of file
diff --git a/docs/modules/servers/pages/distributed/configure/index.adoc b/docs/modules/servers/pages/distributed/configure/index.adoc
index 8a99ac9a4d3..76c4453c387 100644
--- a/docs/modules/servers/pages/distributed/configure/index.adoc
+++ b/docs/modules/servers/pages/distributed/configure/index.adoc
@@ -9,85 +9,15 @@ or rely on reasonable defaults.
The following configuration files are exposed:
-== For protocols
+:sample-configuration-prefix-url: https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration
+:xref-base: distributed/configure
+:server-name: Distributed James Server
-By omitting these files, the underlying protocols will be disabled.
+include::partial$configure/forProtocolsPartial.adoc[]
-** xref:distributed/configure/imap.adoc[*imapserver.xml*] allows configuration for the IMAP protocol link:https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration/imapserver.xml[example]
-** xref:distributed/configure/jmap.adoc[*jmap.properties*] allows to configure the JMAP protocol link:https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration/jmap.properties[example]
-** xref:distributed/configure/jmx.adoc[*jmx.properties*] allows configuration of JMX being used by the Command Line Interface link:https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration/jmx.properties[example]
-** xref:distributed/configure/smtp.adoc#_lmtp_configuration[*lmtpserver.xml*] allows configuring the LMTP protocol link:https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration/lmtpserver.xml[example]
-** *managesieveserver.xml* allows configuration for ManagedSieve (unsupported) link:https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration/managesieveserver.xml[example]
-** xref:distributed/configure/pop3.adoc[*pop3server.xml*] allows configuration for the POP3 protocol (experimental) link:https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration/pop3server.xml[example]
-** xref:distributed/configure/smtp.adoc[*smtpserver.xml*] allows configuration for the SMTP protocol link:https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration/smtpserver.xml[example]
-*** xref:distributed/configure/smtp-hooks.adoc[This page] list SMTP hooks that can be used out of the box with the Distributed Server.
-** xref:distributed/configure/webadmin.adoc[*webadmin.properties*] enables configuration for the WebAdmin protocol link:https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration/webadmin.properties[example]
-** xref:distributed/configure/ssl.adoc[This page] details SSL & TLS configuration.
-** xref:distributed/configure/sieve.adoc[This page] details Sieve setup and how to enable ManageSieve.
+include::partial$configure/forStorageDependenciesPartial.adoc[]
+** xref:distributed/configure/cassandra.adoc[*cassandra.properties*] allows to configure the Cassandra driver link:{sample-configuration-prefix-url}/sample-configuration/cassandra.properties[example]
-== For storage dependencies
-
-Except specific documented cases, these files are required, at least to establish a connection with the storage components.
-
-** xref:distributed/configure/blobstore.adoc[*blobstore.properties*] allows to configure the BlobStore link:https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration/blob.properties[example]
-** xref:distributed/configure/cassandra.adoc[*cassandra.properties*] allows to configure the Cassandra driver link:https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration/cassandra.properties[example]
-** xref:distributed/configure/opensearch.adoc[*opensearch.properties*] allows to configure OpenSearch driver link:https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration/opensearch.properties[example]
-** xref:distributed/configure/rabbitmq.adoc[*rabbitmq.properties*] allows configuration for the RabbitMQ driver link:https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration/rabbitmq.properties[example]
-** xref:distributed/configure/redis.adoc[*redis.properties*] allows configuration for the Redis driver link:https://github.com/apache/james-project/blob/fabfdf4874da3aebb04e6fe4a7277322a395536a/server/mailet/rate-limiter-redis/redis.properties[example], that is used by optional
-distributed rate limiting component.
-** xref:distributed/configure/tika.adoc[*tika.properties*] allows configuring Tika as a backend for text extraction link:https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration/tika.properties[example]
-
-== For core components
-
-By omitting these files, sane default values are used.
-
-** xref:distributed/configure/batchsizes.adoc[*batchsizes.properties*] allows to configure mailbox read batch sizes link:https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration/batchsizes.properties[example]
-** xref:distributed/configure/dns.adoc[*dnsservice.xml*] allows to configure DNS resolution link:https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration/dnsservice.xml[example]
-** xref:distributed/configure/domainlist.adoc[*domainlist.xml*] allows to configure Domain storage link:https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration/domainlist.xml[example]
-** xref:distributed/configure/healthcheck.adoc[*healthcheck.properties*] allows to configure periodical healthchecks link:https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration/healthcheck.properties[example]
-** xref:distributed/configure/mailetcontainer.adoc[*mailetcontainer.xml*] allows configuring mail processing link:https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration/mailetcontainer.xml[example]
-*** xref:distributed/configure/mailets.adoc[This page] list matchers that can be used out of the box with the Distributed Server.
-*** xref:distributed/configure/matchers.adoc[This page] list matchers that can be used out of the box with the Distributed Server.
-** xref:distributed/configure/mailrepositorystore.adoc[*mailrepositorystore.xml*] enables registration of allowed MailRepository protcols and link them to MailRepository implementations link:https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration/mailrepositorystore.xml[example]
-** xref:distributed/configure/recipientrewritetable.adoc[*recipientrewritetable.xml*] enables advanced configuration for the Recipient Rewrite Table component link:https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration/recipientrewritetable.xml[example]
-*** xref:distributed/configure/matchers.adoc[This page] allows choosing the indexing technology.
-** xref:distributed/configure/usersrepository.adoc[*usersrepository.xml*] allows configuration of user storage link:https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration/usersrepository.xml[example]
-
-== For extensions
-
-By omitting these files, no extra behaviour is added.
-
-** xref:distributed/configure/vault.adoc[*deletedMessageVault.properties*] allows to configure the DeletedMessageVault link:https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration/deletedMessageVault.properties[example]
-** xref:distributed/configure/listeners.adoc[*listeners.xml*] enables configuration of Mailbox Listeners link:https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration/listeners.xml[example]
-** xref:distributed/configure/extensions.adoc[*extensions.properties*] allows to extend James behaviour by loading your extensions in it link:https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration/extensions.properties[example]
-** xref:distributed/configure/jvm.adoc[*jvm.properties*] lets you specify additional system properties without cluttering your command line
-** xref:distributed/configure/spam.adoc[This page] documents Anti-Spam setup with SpamAssassin, Rspamd.
-** xref:distributed/configure/remote-delivery-error-handling.adoc[This page] proposes a simple strategy for RemoteDelivery error handling.
-** xref:distributed/configure/collecting-contacts.adoc[This page] documents contact collection
-** xref:distributed/configure/collecting-events.adoc[This page] documents event collection
-** xref:distributed/configure/dsn.adoc[this page] specified how to support SMTP Delivery Submission Notification (link:https://tools.ietf.org/html/rfc3461[RFC-3461])
-** xref:distributed/configure/droplists.adoc[This page] allows configuring drop lists.
-
-== System properties
-
-Some tuning can be done via system properties. This includes:
-
-.System properties
-|===
-| Property name | explanation
-
-| james.message.memory.threshold
-| (Optional). String (size, integer + size units, example: `12 KIB`, supported units are bytes KIB MIB GIB TIB). Defaults to 100KIB.
-This governs the threshold MimeMessageInputStreamSource relies on for storing MimeMessage content on disk.
-Below, data is stored in memory. Above data is stored on disk.
-Lower values will lead to longer processing time but will minimize heap memory usage. Modern SSD hardware
-should however support a high throughput. Higher values will lead to faster single mail processing at the cost
-of higher heap usage.
-
-
-| james.message.usememorycopy
-|Optional. Boolean. Defaults to false. Recommended value is false.
-Should MimeMessageWrapper use a copy of the message in memory? Or should bigger message exceeding james.message.memory.threshold
-be copied to temporary files?
-
-|===
\ No newline at end of file
+include::partial$configure/forCoreComponentsPartial.adoc[]
+include::partial$configure/forExtensionsPartial.adoc[]
+include::partial$configure/systemPropertiesPartial.adoc[]
\ No newline at end of file
diff --git a/docs/modules/servers/pages/distributed/configure/jmap.adoc b/docs/modules/servers/pages/distributed/configure/jmap.adoc
index 9d7611ba130..65fb94ab6ef 100644
--- a/docs/modules/servers/pages/distributed/configure/jmap.adoc
+++ b/docs/modules/servers/pages/distributed/configure/jmap.adoc
@@ -1,184 +1,7 @@
= Distributed James Server — jmap.properties
:navtitle: jmap.properties
-https://jmap.io/[JMAP] is intended to be a new standard for email clients to connect to mail
-stores. It therefore intends to primarily replace IMAP + SMTP submission. It is also designed to be more
-generic. It does not replace MTA-to-MTA SMTP transmission.
-
-Consult this link:https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration/jmap.properties[example]
-to get some examples and hints.
-
-.jmap.properties content
-|===
-| Property name | explanation
-
-| enabled
-| true/false. Governs whether JMAP should be enabled
-
-| jmap.port
-| Optional. Defaults to 80. The port this server will be listening on. This value must be a valid
-port, ranging between 1 and 65535 (inclusive)
-
-| tls.keystoreURL
-| Keystore to be used for generating authentication tokens for password authentication mechanism.
-This should not be the same keystore than the ones used by TLS based protocols.
-
-| tls.secret
-| Password used to read the keystore
-
-| jwt.publickeypem.url
-| Optional. Coma separated list of RSA public keys URLs to validate JWT tokens allowing requests to bypass authentication.
-Defaults to an empty list.
-
-| url.prefix
-| Optional. Configuration urlPrefix for JMAP routes. Default value: http://localhost.
-
-| websocket.url.prefix
-| Optional. URL for JMAP WebSocket route. Default value: ws://localhost
-
-| email.send.max.size
-| Optional. Configuration max size for message created in RFC-8621.
-Default value: None. Supported units are B (bytes) K (KB) M (MB) G (GB).
-
-| max.size.attachments.per.mail
-| Optional. Defaults to 20MB. RFC-8621 `maxSizeAttachmentsPerEmail` advertised to JMAP client as part of the
-`urn:ietf:params:jmap:mail` capability. This needs to be at least 33% lower than `email.send.max.size` property
-(in order to account for text body, headers, base64 encoding and MIME structures).
-JMAP clients would use this property in order not to create too big emails.
-Default value: None. Supported units are B (bytes) K (KB) M (MB) G (GB).
-
-| upload.max.size
-| Optional. Configuration max size for each upload file in new JMAP-RFC-8621.
-Default value: 30M. Supported units are B (bytes) K (KB) M (MB) G (GB).
-
-| upload.quota.limit
-| Optional. Configure JMAP upload quota for total existing uploads' size per user. User exceeding the upload quota would result in old uploads being cleaned up.
-Default value: 200M. Supported units are B (bytes) K (KB) M (MB) G (GB).
-
-| view.email.query.enabled
-| Optional boolean. Defaults to false. Should simple Email/query be resolved against a Cassandra projection, or should we resolve them against OpenSearch?
-This enables a higher resilience, but the projection needs to be correctly populated.
-
-| user.provisioning.enabled
-| Optional boolean. Defaults to true. Governs whether authenticated users that do not exist locally should be created in the users repository.
-
-| authentication.strategy.rfc8621
-| Optional List[String] with delimiter `,` . Specify which authentication strategies system admin want to use for JMAP RFC-8621 server.
-The implicit package name is `org.apache.james.jmap.http`. If you have a custom authentication strategy outside this package, you have to specify its FQDN.
-If no authentication strategy is specified, JMAP RFC-8621 server will fallback to default strategies:
-`JWTAuthenticationStrategy`, `BasicAuthenticationStrategy`.
-
-| jmap.version.default
-| Optional string. Defaults to `rfc-8621`. Allowed values: rfc-8621
-Which version of the JMAP protocol should be served when none supplied in the Accept header.
-
-| dynamic.jmap.prefix.resolution.enabled
-| Optional boolean. Defaults to false. Supported Jmap session endpoint returns dynamic prefix in response.
-When its config is true, and the HTTP request to Jmap session endpoint has a `X-JMAP-PREFIX` header with the value `http://new-domain/prefix`,
-then `apiUrl, downloadUrl, uploadUrl, eventSourceUrl, webSocketUrl` in response will be changed with a new prefix. Example: The `apiUrl` will be "http://new-domain/prefix/jmap".
-If the HTTP request to Jmap session endpoint has the `X-JMAP-WEBSOCKET-PREFIX` header with the value `ws://new-domain/prefix`,
-then `capabilities."urn:ietf:params:jmap:websocket".url` in response will be "ws://new-domain/prefix/jmap/ws".
-
-| webpush.prevent.server.side.request.forgery
-| Optional boolean. Prevent server side request forgery by preventing calls to the private network ranges. Defaults to true, can be disabled for testing.
-
-| cassandra.filter.projection.activated
-|Optional boolean. Defaults to false. Casandra backends only. Whether to use or not the Cassandra projection
-for JMAP filters. This projection optimizes reads, but needs to be correctly populated. Turning it on on
-systems with filters already defined would result in those filters to be not read.
-
-| delay.sends.enabled
-| Optional boolean. Defaults to false. Whether to support or not the delay send with JMAP protocol.
-
-| disabled.capabilities
-| Optional, defaults to empty. Coma separated list of JMAP capabilities to reject.
-This allows to prevent users from using some specific JMAP extensions.
-
-| email.get.full.max.size
-| Optional, default value is 5. The max number of items for EmailGet full reads.
-
-| get.max.size
-| Optional, default value is 500. The max number of items for /get methods.
-
-| set.max.size
-| Optional, default value is 500. The max number of items for /set methods.
-|===
-
-== Wire tapping
-
-Enabling *TRACE* on `org.apache.james.jmap.wire` enables reactor-netty wiretap, logging of
-all incoming and outgoing requests, outgoing requests. This will log also potentially sensible information
-like authentication credentials.
-
-== OIDC set up
-
-The use of `XUserAuthenticationStrategy` allow delegating the authentication responsibility to a third party system,
-which could be used to set up authentication against an OIDC provider.
-
-We do supply an link:https://github.com[example] of such a setup. It combines the link:https://www.keycloak.org/[Keycloack]
-OIDC provider with the link:https://www.krakend.io/[Krackend] API gateway, but usage of similar technologies is definitely doable.
-
-== Generating a JWT key pair
-
-Apache James can alternatively be configured to check the validity of JWT tokens itself. No revocation mechanism is
-supported in such a setup, and the `sub` claim is used to identify the user. The key configuration is static.
-
-This requires the `JWTAuthenticationStrategy` authentication strategy to be used.
-
-The Distributed server enforces the use of RSA-SHA-256.
-
-One can use OpenSSL to generate a JWT key pair :
-
- # private key
- openssl genrsa -out rs256-4096-private.rsa 4096
- # public key
- openssl rsa -in rs256-4096-private.rsa -pubout > rs256-4096-public.pem
-
-The private key can be used to generate JWT tokens, for instance
-using link:https://github.com/vandium-io/jwtgen[jwtgen]:
-
- jwtgen -a RS256 -p rs256-4096-private.rsa 4096 -c "sub=bob@domain.tld" -e 3600 -V
-
-This token can then be passed as `Bearer` of the `Authorization` header :
-
- curl -H "Authorization: Bearer $token" -XPOST http://127.0.0.1:80/jmap -d '...'
-
-The public key can be referenced as `jwt.publickeypem.url` of the `jmap.properties` configuration file.
-
-== Annotated specification
-
-The [annotated documentation](https://github.com/apache/james-project/tree/master/server/protocols/jmap-rfc-8621/doc/specs/spec)
-presents the limits of the JMAP RFC-8621 implementation part of the Apache James project. We furthermore implement
-[JSON Meta Application Protocol (JMAP) Subprotocol for WebSocket](https://tools.ietf.org/html/rfc8887).
-
-Some methods / types are not yet implemented, some implementations are naive, and the PUSH is not supported yet.
-
-Users are invited to read these limitations before using actively the JMAP RFC-8621 implementation, and should ensure their
-client applications only uses supported operations.
-
-Contributions enhancing support are furthermore welcomed.
-
-The list of tested JMAP clients are:
-
- - Experiments had been run on top of [LTT.RS](https://github.com/iNPUTmice/lttrs-android). Version in the Accept
- headers needs to be explicitly set to `rfc-8621`. [Read more](https://github.com/linagora/james-project/pull/4089).
-
-== JMAP auto-configuration
-
-link:https://datatracker.ietf.org/doc/html/rfc8620[RFC-8620] defining JMAP core RFC defines precisely service location.
-
-James already redirects `http://jmap.domain.tld/.well-known/jmap` to the JMAP session.
-
-You can further help your clients by publishing extra SRV records.
-
-Eg:
-
-----
-_jmap._tcp.domain.tld. 3600 IN SRV 0 1 443 jmap.domain.tld.
-----
-
-== JMAP reverse-proxy set up
-
-James implementation adds the value of `X-Real-IP` header as part of the logging MDC.
-
-This allows for reverse proxies to cary other the IP address of the client down to the JMAP server for diagnostic purpose.
\ No newline at end of file
+:sample-configuration-prefix-url: https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration
+:server-name: Distributed James Server
+:backend-name: Cassandra
+include::partial$configure/jmap.adoc[]
\ No newline at end of file
diff --git a/docs/modules/servers/pages/distributed/configure/jmx.adoc b/docs/modules/servers/pages/distributed/configure/jmx.adoc
index 04e88db20ce..486a90ca727 100644
--- a/docs/modules/servers/pages/distributed/configure/jmx.adoc
+++ b/docs/modules/servers/pages/distributed/configure/jmx.adoc
@@ -1,67 +1,5 @@
= Distributed James Server — jmx.properties
:navtitle: jmx.properties
-== Disclaimer
-
-JMX poses several security concerns and had been leveraged to conduct arbitrary code execution.
-This threat is mitigated by not allowing remote connections to JMX, setting up authentication and pre-authentication filters.
-However, we recommend to either run James in isolation (docker / own virtual machine) or disable JMX altogether.
-
-James JMX endpoint provides command line utilities and exposes a few metrics, also available on the metric endpoint.
-
-== Configuration
-
-This is used to configure the JMX MBean server via which all management is achieved.
-
-Consult this link:https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration/jmx.properties[example]
-in GIT to get some examples and hints.
-
-.jmx.properties content
-|===
-| Property name | explanation
-
-| jmx.enabled
-| Boolean. Should the JMX server be enabled? Defaults to `true`.
-
-| jmx.address
-|The IP address (host name) the MBean Server will bind/listen to.
-
-| jmx.port
-| The port number the MBean Server will bind/listen to.
-|===
-
-To access from a remote location, it has been reported that `-Dcom.sun.management.jmxremote.ssl=false` is needed as
-a JVM argument.
-
-== JMX Security
-
-In order to set up JMX authentication, we need to put `jmxremote.password` and `jmxremote.access` file
-to `/conf` directory.
-
-- `jmxremote.password`: define the username and password, that will be used by the client (here is james-cli)
-
-File's content example:
-```
-james-admin pass1
-```
-
-- `jmxremote.access`: define the pair of username and access permission
-
-File's content example:
-```
-james-admin readwrite
-```
-
-When James runs with option `-Djames.jmx.credential.generation=true`, James will automatically generate `jmxremote.password` if the file does not exist.
-Then the default username is `james-admin` and a random password. This option defaults to true.
-
-=== James-cli
-
-When the JMX server starts with authentication configuration, it will require the client need provide username/password for bypass.
-To do that, we need set arguments `-username` and `-password` for the command request.
-
-Command example:
-```
-james-cli -h 127.0.0.1 -p 9999 -username james-admin -password pass1 listdomains
-```
-
+:sample-configuration-prefix-url: https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration
+include::partial$configure/jmx.adoc[]
\ No newline at end of file
diff --git a/docs/modules/servers/pages/distributed/configure/jvm.adoc b/docs/modules/servers/pages/distributed/configure/jvm.adoc
index 170869594b9..cbb3998dc41 100644
--- a/docs/modules/servers/pages/distributed/configure/jvm.adoc
+++ b/docs/modules/servers/pages/distributed/configure/jvm.adoc
@@ -1,105 +1,5 @@
= Distributed James Server — jvm.properties
:navtitle: jvm.properties
-This file may contain any additional system properties for tweaking JVM execution. When you normally would add a command line option `-Dmy.property=whatever`, you can put it in this file as `my.property=whatever` instead. These properties will be added as system properties on server start.
-
-Note that in some rare cases this might not work,
-when a property affects very early JVM start behaviour.
-
-For testing purposes, you may specify a different file path via the command line option `-Dextra.props=/some/other/jvm.properties`.
-
-== Control the threshold memory
-This governs the threshold MimeMessageInputStreamSource relies on for storing MimeMessage content on disk.
-
-In `jvm.properties`
-----
-james.message.memory.threshold=12K
-----
-
-(Optional). String (size, integer + size units, example: `12 KIB`, supported units are bytes KIB MIB GIB TIB). Defaults to 100KIB.
-
-== Enable the copy of message in memory
-Should MimeMessageWrapper use a copy of the message in memory? Or should bigger message exceeding james.message.memory.threshold
-be copied to temporary files?
-
-----
-james.message.usememorycopy=true
-----
-
-Optional. Boolean. Defaults to false. Recommended value is false.
-
-== Running resource leak detection
-It is used to detect a resource not be disposed of before it's garbage-collected.
-
-In `jvm.properties`
-----
-james.lifecycle.leak.detection.mode=advanced
-----
-
-Allowed mode values are: none, simple, advanced, testing
-
-The purpose of each mode is introduced in `config-system.xml`
-
-== Disabling host information in protocol MDC logging context
-
-Should we add the host in the MDC logging context for incoming IMAP, SMTP, POP3? Doing so, a DNS resolution
-is attempted for each incoming connection, which can be costly. Remote IP is always added to the logging context.
-
-
-In `jvm.properties`
-----
-james.protocols.mdc.hostname=false
-----
-
-Optional. Boolean. Defaults to true.
-
-== Change the encoding type used for the blobId
-
-By default, the blobId is encoded in base64 url. The property `james.blob.id.hash.encoding` allows to change the encoding type.
-The support value are: base16, hex, base32, base32Hex, base64, base64Url.
-
-Ex in `jvm.properties`
-----
-james.blob.id.hash.encoding=base16
-----
-
-Optional. String. Defaults to base64Url.
-
-== JMAP Quota draft compatibility
-
-Some JMAP clients depend on the JMAP Quota draft specifications. The property `james.jmap.quota.draft.compatibility` allows
-to enable JMAP Quota draft compatibility for those clients and allow them a time window to adapt to the RFC-9245 JMAP Quota.
-
-Optional. Boolean. Default to false.
-
-Ex in `jvm.properties`
-----
-james.jmap.quota.draft.compatibility=true
-----
-To enable the compatibility.
-
-== Enable S3 metrics
-
-James supports extracting some S3 client-level metrics e.g. number of connections being used, time to acquire an S3 connection, total time to finish a S3 request...
-
-The property `james.s3.metrics.enabled` allows to enable S3 metrics collection. Please pay attention that enable this
-would impact a bit on S3 performance.
-
-Optional. Boolean. Default to true.
-
-Ex in `jvm.properties`
-----
-james.s3.metrics.enabled=false
-----
-To disable the S3 metrics.
-
-== Reactor Stream Prefetch
-
-Prefetch to use in Reactor to stream convertions (S3 => InputStream). Default to 1.
-Higher values will tend to block less often at the price of higher memory consumptions.
-
-Ex in `jvm.properties`
-----
-# james.reactor.inputstream.prefetch=4
-----
-
+:sample-configuration-prefix-url: https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration
+include::partial$configure/jvm.adoc[]
\ No newline at end of file
diff --git a/docs/modules/servers/pages/distributed/configure/listeners.adoc b/docs/modules/servers/pages/distributed/configure/listeners.adoc
index 57d7772fba3..d0cf02d8482 100644
--- a/docs/modules/servers/pages/distributed/configure/listeners.adoc
+++ b/docs/modules/servers/pages/distributed/configure/listeners.adoc
@@ -1,77 +1,9 @@
= Distributed James Server — listeners.xml
:navtitle: listeners.xml
-Distributed James relies on an event bus system to enrich mailbox capabilities. Each
-operation performed on the mailbox will trigger related events, that can
-be processed asynchronously by potentially any James node on a
-distributed system.
-
-Mailbox listeners can register themselves on this event bus system to be
-called when an event is fired, allowing to do different kind of extra
-operations on the system.
-
-Distributed James allows the user to register potentially user defined additional mailbox listeners.
-
-Consult this link:https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration/listener.xml[example]
-to get some examples and hints.
-
-== Configuration
-
-The controls whether to launch group mailbox listener consumption. Defaults to true. Use with caution:
-never disable on standalone james servers, and ensure at least some instances do consume group mailbox listeners within a
-clustered topology.
-
-Mailbox listener configuration is under the XML element .
-
-Some MailboxListener allows you to specify if you want to run them synchronously or asynchronously. To do so,
-for MailboxListener that supports this, you can use the *async* attribute (optional, per mailet default) to govern the execution mode.
-If *true* the execution will be scheduled in a reactor elastic scheduler. If *false*, the execution is synchronous.
-
-Already provided additional listeners are documented below.
-
-=== SpamAssassinListener
-
-Provides per user real-time HAM/SPAM feedback to a SpamAssassin server depending on user actions.
-
-This mailet is asynchronous by default, but this behaviour can be overridden by the *async*
-configuration property.
-
-This MailboxListener is supported.
-
-Example:
-
-....
-
-
-
- org.apache.james.mailbox.spamassassin.SpamAssassinListener
-
-
-....
-
-Please note that a `spamassassin.properties` file is needed. Read also
-xref:distributed/configure/spam.adoc[this page] for extra configuration required to support this feature.
-
-=== RspamdListener
-
-Provides HAM/SPAM feedback to a Rspamd server depending on user actions.
-
-This MailboxListener is supported.
-
-Example:
-
-....
-
-
-
- org.apache.james.rspamd.RspamdListener
-
-
-....
-
-Please note that a `rspamd.properties` file is needed. Read also
-xref:distributed/configure/spam.adoc[this page] for extra configuration required to support this feature.
-
+:sample-configuration-prefix-url: https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration
+:server-name: Distributed James Server
+include::partial$configure/listeners.adoc[]
=== MailboxOperationLoggingListener
@@ -81,6 +13,7 @@ This MailboxListener is supported.
Example:
+[source,xml]
....
@@ -89,85 +22,3 @@ Example:
....
-
-=== QuotaThresholdCrossingListener
-
-Sends emails to users exceeding 80% and 99% of their quota to warn them (for instance).
-
-Here are the following properties you can configure:
-
-.QuotaThresholdCrossingListener configuration properties
-|===
-| Property name | explanation
-
-| name
-| Useful when configuring several time this listener. You might want to do so to use different rendering templates for
-different occupation thresholds.
-
-| gracePeriod
-| Period during which no more email for a given threshold should be sent.
-
-| subjectTemplate
-| Mustache template for rendering the subject of the warning email.
-
-| bodyTemplate
-| Mustache template for rendering the body of the warning email.
-
-| thresholds
-| Floating number between 0 and 1 representing the threshold of quota occupation from which a mail should be sent.
-Configuring several thresholds is supported.
-
-|===
-
-Example:
-
-....
-
-
-
- org.apache.james.mailbox.quota.mailing.listeners.QuotaThresholdCrossingListener
- QuotaThresholdCrossingListener-upper-threshold
-
-
-
- 0.8
-
-
- thirst
- conf://templates/QuotaThresholdMailSubject.mustache
- conf://templates/QuotaThresholdMailBody.mustache
- 1week/
-
-
-
-....
-
-Here are examples of templates you can use:
-
-* For subject template: `conf://templates/QuotaThresholdMailSubject.mustache`
-
-....
-Warning: Your email usage just exceeded a configured threshold
-....
-
-* For body template: `conf://templates/QuotaThresholdMailBody.mustache`
-
-....
-You receive this email because you recently exceeded a threshold related to the quotas of your email account.
-
-{{#hasExceededSizeThreshold}}
-You currently occupy more than {{sizeThreshold}} % of the total size allocated to you.
-You currently occupy {{usedSize}}{{#hasSizeLimit}} on a total of {{limitSize}} allocated to you{{/hasSizeLimit}}.
-
-{{/hasExceededSizeThreshold}}
-{{#hasExceededCountThreshold}}
-You currently occupy more than {{countThreshold}} % of the total message count allocated to you.
-You currently have {{usedCount}} messages{{#hasCountLimit}} on a total of {{limitCount}} allowed for you{{/hasCountLimit}}.
-
-{{/hasExceededCountThreshold}}
-You need to be aware that actions leading to exceeded quotas will be denied. This will result in a degraded service.
-To mitigate this issue you might reach your administrator in order to increase your configured quota. You might also delete some non important emails.
-....
-
-This MailboxListener is supported.
-
diff --git a/docs/modules/servers/pages/distributed/configure/mailetcontainer.adoc b/docs/modules/servers/pages/distributed/configure/mailetcontainer.adoc
index f9e1722d7fb..e996c276805 100644
--- a/docs/modules/servers/pages/distributed/configure/mailetcontainer.adoc
+++ b/docs/modules/servers/pages/distributed/configure/mailetcontainer.adoc
@@ -1,96 +1,6 @@
= Distributed James Server — mailetcontainer.xml
:navtitle: mailetcontainer.xml
-This documents explains how to configure Mail processing. Mails pass through the MailetContainer. The
-MailetContainer is a Matchers (condition for executing a mailet) and Mailets (execution units that perform
-actions based on incoming mail) pipeline arranged into processors (List of mailet/matcher pairs allowing
-better logical organisation). You can read more about these concepts on
-xref:distributed/architecture/index.adoc#_mail_processing[the mailet container feature description].
-
-Apache James Server includes a number of xref:distributed/configure/mailets.adoc[Packaged Mailets] and
-xref:distributed/configure/matchers.adoc[Packaged Matchers].
-
-Furthermore, you can write and use with James xref:customization:mail-processing.adoc[your own mailet and matchers].
-
-Consult this link:https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration/mailetcontainer.xml[example]
-to get some examples and hints.
-
-.mailetcontainer.xml content
-|===
-| Property name | explanation
-
-| context.postmaster
-| The body of this element is the address that the server
-will consider its postmaster address. This address will be listed as the sender address
-of all error messages that originate from James. Also, all messages addressed to
-postmaster@, where is one of the domain names whose
-mail is being handled by James, will be redirected to this email address.
-Set this to the appropriate email address for error reports
-If this is set to a non-local email address, the mail server
-will still function, but will generate a warning on startup.
-
-| spooler.threads
-| Number of simultaneous threads used to spool the mails. Set to zero, it disables mail processing - use with
-caution.
-
-| spooler.errorRepository
-| Mail repository to store email in after several unrecoverable errors. Mails failing processing, for which
-the Mailet Container could not handle Error, will be stored there after their processing had been attempted
-5 times. Note that if standard java Exception occurs, *Error handling* section below will be applied
-instead.
-|===
-
-== The Mailet Tag
-
-Consider the following simple *mailet* tag:
-
-....
-
- spam
-
-....
-
-The mailet tag has two required attributes, *match* and *class*.
-
-The *match* attribute is set to the value of the specific Matcher class to be instantiated with a an
-optional argument. If present, the argument is separated from the Matcher class name by an '='. Semantic
-interpretation of the argument is left to the particular mailet.
-
-The *class* attribute is set to the value of the Mailet class that is to be instantiated.
-
-Finally, the children of the *mailet* tag define the configuration that is passed to the Mailet. The
-tags used in this section should have no attributes or children. The names and bodies of the elements will be passed to
-the mailet as (name, value) pairs.
-
-So in the example above, a Matcher instance of RemoteAddrNotInNetwork would be instantiated, and the value "127.0.0.1"
-would be passed to the matcher. The Mailet of the pair will be an instance of ToProcessor, and it will be passed the (name, value)
-pair of ("processor", "spam").
-
-== Error handling
-
-If an exception is encountered during the execution of a mailet or a matcher, the default behaviour is to
-process the mail using the *error* processor.
-
-The *onMailetException* property allows you to override this behaviour. You can specify another
-processor than the *error* one for handling the errors of this mailet.
-
-The *ignore* special value also allows to continue processing and ignore the error.
-
-The *propagate* special value causes the mailet container to rethrow the
-exception, propagating it to the execution context. In an SMTP execution context, the spooler will then requeue
-the item and automatic retries will be setted up - note that attempts will be done for each recipients. In LMTP
-(if LMTP is configured to execute the mailetContainer), the entire mail transaction is reported as failed to the caller.
-
-Moreover, the *onMatcherException* allows you to override matcher error handling. You can
-specify another processor than the *error* one for handling the errors of this mailet. The *matchall*
-special value also allows you to match all recipients when there is an error. The *nomatch*
-special value also allows you to match no recipients when there is an error.
-
-Here is a short example to illustrate this:
-
-....
-
- deliveryError
- nomatch
-
-....
+:sample-configuration-prefix-url: https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration
+:pages-path: distributed
+include::partial$configure/mailetcontainer.adoc[]
\ No newline at end of file
diff --git a/docs/modules/servers/pages/distributed/configure/mailets.adoc b/docs/modules/servers/pages/distributed/configure/mailets.adoc
index cf19932da09..2426eae0657 100644
--- a/docs/modules/servers/pages/distributed/configure/mailets.adoc
+++ b/docs/modules/servers/pages/distributed/configure/mailets.adoc
@@ -1,151 +1,6 @@
= Distributed James Server — Mailets
:navtitle: Mailets
-This documentation page lists and documents Mailet that can be used within the
-Distributed Server MailetContainer in order to write your own mail processing logic with out-of-the-box components.
-
-== Supported mailets
-
-include::partial$AddDeliveredToHeader.adoc[]
-
-include::partial$AddFooter.adoc[]
-
-include::partial$AddSubjectPrefix.adoc[]
-
-include::partial$AmqpForwardAttribute.adoc[]
-
-include::partial$Bounce.adoc[]
-
-include::partial$ContactExtractor.adoc[]
-
-include::partial$ConvertTo7Bit.adoc[]
-
-include::partial$DeconnectionRight.adoc[]
-
-include::partial$DKIMSign.adoc[]
-
-include::partial$DKIMVerify.adoc[]
-
-include::partial$DSNBounce.adoc[]
-
-include::partial$Expires.adoc[]
-
-include::partial$ExtractMDNOriginalJMAPMessageId.adoc[]
-
-include::partial$Forward.adoc[]
-
-include::partial$ICalendarParser.adoc[]
-
-include::partial$ICALToHeader.adoc[]
-
-include::partial$ICALToJsonAttribute.adoc[]
-
-include::partial$ICSSanitizer.adoc[]
-
-include::partial$LocalDelivery.adoc[]
-
-include::partial$LDAPMatchers.adoc[]
-
-include::partial$LogMessage.adoc[]
-
-include::partial$MailAttributesListToMimeHeaders.adoc[]
-
-include::partial$MailAttributesToMimeHeaders.adoc[]
-
-include::partial$MetricsMailet.adoc[]
-
-include::partial$MimeDecodingMailet.adoc[]
-
-include::partial$NotifyPostmaster.adoc[]
-
-include::partial$NotifySender.adoc[]
-
-include::partial$Null.adoc[]
-
-include::partial$PostmasterAlias.adoc[]
-
-include::partial$RandomStoring.adoc[]
-
-include::partial$RecipientRewriteTable.adoc[]
-
-include::partial$RecipientToLowerCase.adoc[]
-
-include::partial$Redirect.adoc[]
-
-include::partial$RemoteDelivery.adoc[]
-
-include::partial$RemoveAllMailAttributes.adoc[]
-
-include::partial$RemoveMailAttribute.adoc[]
-
-include::partial$RemoveMimeHeader.adoc[]
-
-include::partial$RemoveMimeHeaderByPrefix.adoc[]
-
-include::partial$ReplaceContent.adoc[]
-
-include::partial$Resend.adoc[]
-
-include::partial$SetMailAttribute.adoc[]
-
-include::partial$SetMimeHeader.adoc[]
-
-include::partial$Sieve.adoc[]
-
-include::partial$Sign.adoc[]
-
-include::partial$SMIMECheckSignature.adoc[]
-
-include::partial$SMIMEDecrypt.adoc[]
-
-include::partial$SMIMESign.adoc[]
-
-include::partial$SpamAssassin.adoc[]
-
-include::partial$StripAttachment.adoc[]
-
-include::partial$TextCalendarBodyToAttachment.adoc[]
-
-include::partial$ToProcessor.adoc[]
-
-include::partial$ToRepository.adoc[]
-
-include::partial$ToSenderDomainRepository.adoc[]
-
-include::partial$VacationMailet.adoc[]
-
-include::partial$WithPriority.adoc[]
-
-include::partial$WithStorageDirective.adoc[]
-
-== Experimental mailets
-
-include::partial$ClamAVScan.adoc[]
-
-include::partial$ClassifyBounce.adoc[]
-
-include::partial$FromRepository.adoc[]
-
-include::partial$HeadersToHTTP.adoc[]
-
-include::partial$OnlyText.adoc[]
-
-include::partial$ManageSieveMailet.adoc[]
-
-include::partial$RecoverAttachment.adoc[]
-
-include::partial$SerialiseToHTTP.adoc[]
-
-include::partial$ServerTime.adoc[]
-
-include::partial$SPF.adoc[]
-
-include::partial$ToPlainText.adoc[]
-
-include::partial$ToSenderFolder.adoc[]
-
-include::partial$UnwrapText.adoc[]
-
-include::partial$UseHeaderRecipients.adoc[]
-
-include::partial$WrapText.adoc[]
\ No newline at end of file
+:sample-configuration-prefix-url: https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration
+:server-name: Distributed James Server
+include::partial$configure/mailets.adoc[]
\ No newline at end of file
diff --git a/docs/modules/servers/pages/distributed/configure/mailrepositorystore.adoc b/docs/modules/servers/pages/distributed/configure/mailrepositorystore.adoc
index b897530eacc..6968de99ba6 100644
--- a/docs/modules/servers/pages/distributed/configure/mailrepositorystore.adoc
+++ b/docs/modules/servers/pages/distributed/configure/mailrepositorystore.adoc
@@ -1,35 +1,9 @@
= Distributed James Server — mailrepositorystore.xml
-A `mail repository` allows storage of a mail as part of its
-processing. Standard configuration relies on the following mail
-repository.
-
-A mail repository is identified by its *url*, constituted of a *protocol* and a *path*.
-
-For instance in the url `cassandra://var/mail/error/` `cassandra` is the protocol and `var/mail/error` the path.
-
-The *mailrepositorystore.xml* file allows registration of available protocols, and their binding to actual MailRepository
-implementation. Note that extension developers can write their own MailRepository implementations, load them via the
-`extensions-jars` mechanism as documented in xref:customization:index.adoc['writing your own extensions'], and finally
-associated to a protocol in *mailrepositorystore.xml* for a usage in *mailetcontainer.xml*.
-
-== Configuration
-
-Consult this link:https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration/mailrepositorystore.xml[example]
-to get some examples and hints.
-
-....
-
- cassandra
-
-
-
- cassandra
-
-
-
-
-....
-
-Only the *CassandraMailRepository* is available by default for the Distributed Server. Mails metadata are stored in
-Cassandra while the headers and bodies are stored within the xref:distributed/architecture/index.adoc#_blobstore[BlobStore].
+:sample-configuration-prefix-url: https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration
+:pages-path: distributed
+:server-name: Distributed James Server
+:mailet-repository-path-prefix: cassandra
+:mail-repository-protocol: cassandra
+:mail-repository-class: org.apache.james.mailrepository.cassandra.CassandraMailRepository
+include::partial$configure/mailrepositorystore.adoc[]
\ No newline at end of file
diff --git a/docs/modules/servers/pages/distributed/configure/matchers.adoc b/docs/modules/servers/pages/distributed/configure/matchers.adoc
index 2d85fc3465c..944b9e46a7a 100644
--- a/docs/modules/servers/pages/distributed/configure/matchers.adoc
+++ b/docs/modules/servers/pages/distributed/configure/matchers.adoc
@@ -1,166 +1,7 @@
= Distributed James Server — Matchers
:navtitle: Matchers
-This documentation page lists and documents Matchers that can be used within the
-Distributed Server MailetContainer in order to write your own mail processing logic with out-of-the-box components.
-
-== Supported matchers
-
-include::partial$All.adoc[]
-
-include::partial$AtLeastPriority.adoc[]
-
-include::partial$AtMost.adoc[]
-
-include::partial$AtMostPriority.adoc[]
-
-include::partial$DLP.adoc[]
-
-include::partial$FetchedFrom.adoc[]
-
-include::partial$HasAttachment.adoc[]
-
-include::partial$HasException.adoc[]
-
-include::partial$HasHeader.adoc[]
-
-include::partial$HasHeaderWithPrefix.adoc[]
-
-include::partial$HasMailAttribute.adoc[]
-
-include::partial$HasMailAttributeWithValue.adoc[]
-
-include::partial$HasMailAttributeWithValueRegex.adoc[]
-
-include::partial$HasMimeType.adoc[]
-
-include::partial$HasMimeTypeParameter.adoc[]
-
-include::partial$HasPriority.adoc[]
-
-include::partial$HostIs.adoc[]
-
-include::partial$HostIsLocal.adoc[]
-
-include::partial$IsMarkedAsSpam.adoc[]
-
-include::partial$IsOverQuota.adoc[]
-
-include::partial$IsRemoteDeliveryPermanentError.adoc[]
-
-include::partial$IsRemoteDeliveryTemporaryError.adoc[]
-
-include::partial$IsSenderInRRTLoop.adoc[]
-
-include::partial$IsSingleRecipient.adoc[]
-
-include::partial$IsSMIMEEncrypted.adoc[]
-
-include::partial$IsSMIMESigned.adoc[]
-
-include::partial$IsX509CertificateSubject.adoc[]
-
-include::partial$RecipientDomainIs.adoc[]
-
-include::partial$RecipientIs.adoc[]
-
-include::partial$RecipientIsLocal.adoc[]
-
-include::partial$RecipientIsRegex.adoc[]
-
-include::partial$RelayLimit.adoc[]
-
-include::partial$RemoteAddrInNetwork.adoc[]
-
-include::partial$RemoteAddrNotInNetwork.adoc[]
-
-include::partial$RemoteDeliveryFailedWithSMTPCode.adoc[]
-
-include::partial$SenderDomainIs.adoc[]
-
-include::partial$SenderHostIs.adoc[]
-
-include::partial$SenderIs.adoc[]
-
-include::partial$SenderIsLocal.adoc[]
-
-include::partial$SenderIsNull.adoc[]
-
-include::partial$SenderIsRegex.adoc[]
-
-include::partial$SentByJmap.adoc[]
-
-include::partial$SentByMailet.adoc[]
-
-include::partial$SizeGreaterThan.adoc[]
-
-include::partial$SMTPAuthSuccessful.adoc[]
-
-include::partial$SMTPAuthUserIs.adoc[]
-
-include::partial$SMTPIsAuthNetwork.adoc[]
-
-include::partial$SubjectIs.adoc[]
-
-include::partial$SubjectStartsWith.adoc[]
-
-include::partial$TooManyRecipients.adoc[]
-
-include::partial$UserIs.adoc[]
-
-include::partial$XOriginatingIpInNetwork.adoc[]
-
-== Experimental matchers
-
-include::partial$AttachmentFileNameIs.adoc[]
-
-include::partial$CommandForListserv.adoc[]
-
-include::partial$CommandListservMatcher.adoc[]
-
-include::partial$CompareNumericHeaderValue.adoc[]
-
-include::partial$FileRegexMatcher.adoc[]
-
-include::partial$InSpammerBlacklist.adoc[]
-
-include::partial$NESSpamCheck.adoc[]
-
-include::partial$SenderInFakeDomain.adoc[]
-
-== Composite matchers
-
-It is possible to combine together matchers in order to create a composite matcher, thus simplifying your
-Mailet Container logic.
-
-Here are the available logical operations:
-
-* *And* : This matcher performs And conjunction between the two matchers: recipients needs to match both matcher in order to
-match the composite matcher.
-* *Or* : This matcher performs Or conjunction between the two matchers: consider it to be a union of the results.
-It returns recipients from the Or composition results of the child matchers.
-* *Not* : It returns recipients from the negated composition of the child Matcher(s). Consider what wasn't
-in the result set of each child matcher. Of course it is easier to understand if it only
-includes one matcher in the composition, the normal recommended use.
-* *Xor* : It returns Recipients from the Xor composition of the child matchers. Consider it to be the inequality
-operator for recipients. If any recipients match other matcher results
-then the result does not include that recipient.
-
-Here is the syntax to adopt in *mailetcontainer.xml*:
-
-....
-
-
-
-
-
-
-
-
-
-
-
- relay
-
-
-....
\ No newline at end of file
+:sample-configuration-prefix-url: https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration
+:pages-path: distributed
+:server-name: Distributed James Server
+include::partial$configure/matchers.adoc[]
\ No newline at end of file
diff --git a/docs/modules/servers/pages/distributed/configure/opensearch.adoc b/docs/modules/servers/pages/distributed/configure/opensearch.adoc
index c46cd31e86f..2144b928508 100644
--- a/docs/modules/servers/pages/distributed/configure/opensearch.adoc
+++ b/docs/modules/servers/pages/distributed/configure/opensearch.adoc
@@ -1,320 +1,8 @@
= Distributed James Server — opensearch.properties
:navtitle: opensearch.properties
-Consult this link:https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration/opensearch.properties[example]
-to get some examples and hints.
-
-If you want more explanation about OpenSearch configuration, you should visit the dedicated https://opensearch.org/[documentation].
-
-== OpenSearch Configuration
-
-This file section is used to configure the connection tp an OpenSearch cluster.
-
-Here are the properties allowing to do so :
-
-.opensearch.properties content
-|===
-| Property name | explanation
-
-| 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
-| Wait for a certain number of active shard copies before proceeding with the operation. Defaults to 1.
-You may consult the https://www.elastic.co/guide/en/elasticsearch/reference/7.10/docs-index_.html#active-shards[documentation] for more information.
-
-| opensearch.retryConnection.maxRetries
-| Number of retries when connecting the cluster
-
-| opensearch.retryConnection.minDelay
-| Minimum delay between connection attempts
-
-| 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).
-
-|===
-
-=== Mailbox search
-
-The main use of OpenSearch within the Distributed Server is indexing the mailbox content of users in order to enable
-powerful and efficient full-text search of the mailbox content.
-
-Data indexing is performed asynchronously in a reliable fashion via a MailboxListener.
-
-Here are the properties related to the use of OpenSearch for Mailbox Search:
-
-.opensearch.properties content
-|===
-| Property name | explanation
-
-| 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.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.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.
-
-|===
-
-=== Quota search
-
-Users are indexed by quota usage, allowing operators a quick audit of users quota occupation.
-
-Users quota are asynchronously indexed upon quota changes via a dedicated MailboxListener.
-
-The following properties affect quota search :
-
-.opensearch.properties content
-|===
-| Property name | explanation
-
-| 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
-|===
-
-=== Disabling OpenSearch
-
-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
-xref:distributed/operate/webadmin.adoc#_reindexing_all_mails[a full re-indexing]needs to be carried out when enabling OpenSearch.
-
-== 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.properties content
-|===
-| Property name | explanation
-
-| 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.
-
-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.properties content
-|===
-| Property name | explanation
-
-| 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.properties content
-|===
-| Property name | explanation
-
-| 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
-----
-
-== Configure dedicated language analyzers for mailbox index
-
-OpenSearch supports various language analyzers out of the box: https://www.elastic.co/guide/en/elasticsearch/reference/current/analysis-lang-analyzer.html.
-
-James could utilize this to improve the user searching experience upon his language.
-
-While one could modify mailbox index mapping programmatically to customize this behavior, here we should just document a manual way to archive this without breaking our common index' mapping code.
-
-The idea is modifying mailbox index mappings with the target language analyzer as a JSON file, then submit it directly
-to OpenSearch via cURL command to create the mailbox index before James start. Let's adapt dedicated language analyzers
-where appropriate for the following fields:
-
-.Language analyzers propose change
-|===
-| Field | Analyzer change
-
-| from.name
-| `keep_mail_and_url` analyzer -> `keep_mail_and_url_language_a` analyzer
-
-| subject
-| `keep_mail_and_url` analyzer -> `keep_mail_and_url_language_a` analyzer
-
-| to.name
-| `keep_mail_and_url` analyzer -> `keep_mail_and_url_language_a` analyzer
-
-| cc.name
-| `keep_mail_and_url` analyzer -> `keep_mail_and_url_language_a` analyzer
-
-| bcc.name
-| `keep_mail_and_url` analyzer -> `keep_mail_and_url_language_a` analyzer
-
-| textBody
-| `standard` analyzer -> `language_a` analyzer
-
-| htmlBody
-| `standard` analyzer -> `language_a` analyzer
-
-| attachments.fileName
-| `standard` analyzer -> `language_a` analyzer
-
-| attachments.textContent
-| `standard` analyzer -> `language_a` analyzer
-
-|===
-
-In there:
-
- - `keep_mail_and_url` and `standard` are our current analyzers for mailbox index.
- - `language_a` analyzer: the built-in analyzer of OpenSearch. EG: `french`
- - `keep_mail_and_url_language_a` analyzer: a custom of `keep_mail_and_url` analyzer with some language filters.Every language has
-their own filters so please have a look at filters which your language need to add. EG which need to be added for French:
-----
-"filter": {
- "french_elision": {
- "type": "elision",
- "articles_case": true,
- "articles": [
- "l", "m", "t", "qu", "n", "s",
- "j", "d", "c", "jusqu", "quoiqu",
- "lorsqu", "puisqu"
- ]
- },
- "french_stop": {
- "type": "stop",
- "stopwords": "_french_"
- },
- "french_stemmer": {
- "type": "stemmer",
- "language": "light_french"
- }
-}
-----
-
-After modifying above proposed change, you should have a JSON file that contains new setting and mapping of mailbox index. Here
-we provide https://github.com/apache/james-project/blob/master/mailbox/opensearch/example_french_index.json[a sample JSON for French language].
-If you want to customize that JSON file for your own language need, please make these modifications:
-
- - Replace the `french` analyzer with your built-in language (have a look at https://www.elastic.co/guide/en/elasticsearch/reference/current/analysis-lang-analyzer.html[built-in language analyzers])
- - Modify `keep_mail_and_url_french` analyzer' filters with your language filters, and customize the analyzer' name.
-
-Please change also `number_of_shards`, `number_of_replicas` and `index.write.wait_for_active_shards` values in the sample file according to your need.
-
-Run this cURL command with above JSON file to create `mailbox_v1` (Mailbox index' default name) index before James start:
-----
-curl -X PUT ES_IP:ES_PORT/mailbox_v1 -H "Content-Type: application/json" -d @example_french_index.json
-----
+:sample-configuration-prefix-url: https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration
+:pages-path: distributed
+:server-name: Distributed James Server
+:package-tag: cassandra
+include::partial$configure/opensearch.adoc[]
\ No newline at end of file
diff --git a/docs/modules/servers/pages/distributed/configure/pop3.adoc b/docs/modules/servers/pages/distributed/configure/pop3.adoc
index 43db960b86f..1179dadf079 100644
--- a/docs/modules/servers/pages/distributed/configure/pop3.adoc
+++ b/docs/modules/servers/pages/distributed/configure/pop3.adoc
@@ -1,77 +1,7 @@
= Distributed James Server — pop3server.xml
:navtitle: pop3server.xml
-Consult this link:https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration/pop3server.xml[example]
-to get some examples and hints.
-
-The POP3 service is controlled by a configuration block in the pop3server.xml.
-The pop3server tag defines the boundaries of the configuration block. It encloses
-all the relevant configuration for the POP3 server. The behavior of the POP service is
-controlled by the attributes and children of this tag.
-
-This tag has an optional boolean attribute - *enabled* - that defines whether the service is active or not.
-The value defaults to "true" if not present.
-
-The standard children of the pop3server tag are:
-
-.jmx.properties content
-|===
-| Property name | explanation
-
-| bind
-| Configure this to bind to a specific inetaddress. This is an optional integer value.
-This value is the port on which this POP3 server is configured
-to listen. If the tag or value is absent then the service
-will bind to all network interfaces for the machine If the tag or value is omitted,
-the value will default to the standard POP3 port, 11
-port 995 is the well-known/IANA registered port for POP3S ie over SSL/TLS
-port 110 is the well-known/IANA registered port for Standard POP3
-
-| connectionBacklog
-|
-
-| tls
-| Set to true to support STARTTLS or SSL for the Socket.
-To create a new keystore execute:
-`keytool -genkey -alias james -keyalg RSA -storetype PKCS12 -keystore /path/to/james/conf/keystore`
-Please note that each POP3 server exposed on different port can specify its own keystore, independently from any other
-TLS based protocols. Read xref:distributed/configure/ssl.adoc[SSL configuration page] for more information.
-
-| handler.helloName
-| This is the name used by the server to identify itself in the POP3
-protocol. If autodetect is TRUE, the server will discover its
-own host name and use that in the protocol. If discovery fails,
-the value of 'localhost' is used. If autodetect is FALSE, James
-will use the specified value.
-
-| handler.connectiontimeout
-| Connection timeout in seconds
-
-| handler.connectionLimit
-| Set the maximum simultaneous incoming connections for this service
-
-| handler.connectionLimitPerIP
-| Set the maximum simultaneous incoming connections per IP for this service
-
-| handler.handlerchain
-| This loads the core CommandHandlers. Only remove this if you really know what you are doing.
-
-| bossWorkerCount
-| Set the maximum count of boss threads. Boss threads are responsible for accepting incoming POP3 connections
-and initializing associated resources. Optional integer, by default, boss threads are not used and this responsibility is being dealt with
-by IO threads.
-
-| ioWorkerCount
-| Set the maximum count of IO threads. IO threads are responsible for receiving incoming POP3 messages and framing them
-(split line by line). IO threads also take care of compression and SSL encryption. Their tasks are short-lived and non-blocking.
-Optional integer, defaults to 2 times the count of CPUs.
-
-| maxExecutorCount
-| Set the maximum count of worker threads. Worker threads takes care of potentially blocking tasks like executing POP3 requests. Optional integer, defaults to 16.
-
-| useEpoll
-| true or false - If true uses native EPOLL implementation for Netty otherwise uses NIO. Defaults to false.
-
-| gracefulShutdown
-| true or false - If true attempts a graceful shutdown, which is safer but can take time. Defaults to true.
-|===
\ No newline at end of file
+:sample-configuration-prefix-url: https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration
+:pages-path: distributed
+:server-name: Distributed James Server
+include::partial$configure/pop3.adoc[]
\ No newline at end of file
diff --git a/docs/modules/servers/pages/distributed/configure/queue.adoc b/docs/modules/servers/pages/distributed/configure/queue.adoc
index ce2dfe2bff5..e9907a090a2 100644
--- a/docs/modules/servers/pages/distributed/configure/queue.adoc
+++ b/docs/modules/servers/pages/distributed/configure/queue.adoc
@@ -1,19 +1,5 @@
= Distributed James Server — queue.properties
:navtitle: queue.properties
-This configuration helps you configure mail queue you want to select.
-
-== Queue Configuration
-
-.queue.properties content
-|===
-| Property name | explanation
-
-| mail.queue.choice
-| Mail queue can be implemented by many type of message brokers: Pulsar, RabbitMQ,... This property will choose which mail queue you want, defaulting to RABBITMQ
-|===
-
-`mail.queue.choice` supports the following options:
-
-* You can specify the `RABBITMQ` if you want to choose RabbitMQ mail queue
-* You can specify the `PULSAR` if you want to choose Pulsar mail queue
+:sample-configuration-prefix-url: https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration
+include::partial$configure/queue.adoc[]
\ No newline at end of file
diff --git a/docs/modules/servers/pages/distributed/configure/rabbitmq.adoc b/docs/modules/servers/pages/distributed/configure/rabbitmq.adoc
index f0871e0d5d1..3f183ed4684 100644
--- a/docs/modules/servers/pages/distributed/configure/rabbitmq.adoc
+++ b/docs/modules/servers/pages/distributed/configure/rabbitmq.adoc
@@ -1,137 +1,8 @@
= Distributed James Server — rabbitmq.properties
:navtitle: rabbitmq.properties
-This configuration helps you configure components using RabbitMQ.
-
-Consult this link:https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration/rabbitmq.properties[example]
-to get some examples and hints.
-
-== RabbitMQ Configuration
-
-.rabbitmq.properties content
-|===
-| Property name | explanation
-
-| uri
-| the amqp URI pointing to RabbitMQ server. If you use a vhost, specify it as well at the end of the URI.
-Details about amqp URI format is in https://www.rabbitmq.com/uri-spec.html[RabbitMQ URI Specification]
-
-| management.uri
-| the URI pointing to RabbitMQ Management Service. James need to retrieve some information about listing queues
-from this service in runtime.
-Details about URI format is in https://www.rabbitmq.com/management.html#usage-ui[RabbitMQ Management URI]
-
-| management.user
-| username used to access management service
-
-| management.password
-| password used to access management service
-
-| connection.pool.retries
-| Configure retries count to retrieve a connection. Exponential backoff is performed between each retries.
-Optional integer, defaults to 10
-
-| connection.pool.min.delay.ms
-| Configure initial duration (in ms) between two connection retries. Exponential backoff is performed between each retries.
-Optional integer, defaults to 100
-
-| channel.pool.retries
-| Configure retries count to retrieve a channel. Exponential backoff is performed between each retries.
-Optional integer, defaults to 3
-
-| channel.pool.max.delay.ms
-| Configure timeout duration (in ms) to obtain a rabbitmq channel. Defaults to 30 seconds.
-Optional integer, defaults to 30 seconds.
-
-| channel.pool.size
-| Configure the size of the channel pool.
-Optional integer, defaults to 3
-
-| driver.network.recovery.interval
-| Optional, non-negative integer, default to 100ms. The interval (in ms) that RabbitMQ driver will automatic recovery wait before attempting to reconnect. See https://www.rabbitmq.com/client-libraries/java-api-guide#connection-recovery
-
-| ssl.enabled
-| Is using ssl enabled
-Optional boolean, defaults to false
-
-| ssl.management.enabled
-| Is using ssl on management api enabled
-Optional boolean, defaults to false
-
-| ssl.validation.strategy
-| Configure the validation strategy used for rabbitmq connections. Possible values are default, ignore and override.
-Optional string, defaults to using systemwide ssl configuration
-
-| ssl.truststore
-| Points to the truststore (PKCS12) used for verifying rabbitmq connection. If configured then "ssl.truststore.password" must also be configured,
-Optional string, defaults to systemwide truststore. "ssl.validation.strategy: override" must be configured if you want to use this
-
-| ssl.truststore.password
-| Configure the truststore password. If configured then "ssl.truststore" must also be configured,
-Optional string, defaults to empty string. "ssl.validation.strategy: override" must be configured if you want to use this
-
-| ssl.hostname.verifier
-| Configure host name verification. Possible options are default and accept_any_hostname
-Optional string, defaults to subject alternative name host verifier
-
-| ssl.keystore
-| Points to the keystore(PKCS12) used for client certificate authentication. If configured then "ssl.keystore.password" must also be configured,
-Optional string, defaults to empty string
-
-| ssl.keystore.password
-| Configure the keystore password. If configured then "ssl.keystore" must also be configured,
-Optional string, defaults to empty string
-
-| quorum.queues.enable
-| Boolean. Whether to activate Quorum queue usage for all queues.
-Quorum queues enables high availability.
-False (default value) results in the usage of classic queues.
-
-| quorum.queues.replication.factor
-| Strictly positive integer. The replication factor to use when creating quorum queues.
-
-| quorum.queues.delivery.limit
-| Strictly positive integer. Value for x-delivery-limit queue parameter, default to none. Setting a delivery limit can
-prevent RabbitMQ outage if message processing fails. Read https://www.rabbitmq.com/docs/quorum-queues#poison-message-handling
-
-| hosts
-| Optional, default to the host specified as part of the URI.
-Allow creating cluster aware connections.
-A coma separated list of hosts, example: hosts=ip1:5672,ip2:5672
-
-| mailqueue.publish.confirm.enabled
-| Whether or not to enable publish confirms for the mail queue. Optional boolean, defaults to true.
-
-| event.bus.publish.confirm.enabled
-| Whether or not to enable publish confirms for the event bus. Optional boolean, defaults to true.
-
-| event.bus.notification.durability.enabled
-| Whether or not the queue backing notifications should be durable. Optional boolean, defaults to true.
-
-| event.bus.propagate.dispatch.error
-| Whether to propagate errors back to the callers when eventbus fails to dispatch group events to RabbitMQ (then store the failed events in the event dead letters).
-Optional boolean, defaults to true.
-
-| vhost
-| Optional string. This parameter is only a workaround to support invalid URIs containing character like '_'.
-You still need to specify the vhost in the uri parameter.
-
-|===
-
-== Tuning RabbitMQ for quorum queue use
-
-While quorum queues are great at preserving your data and enabling High Availability, they demand more resources and
-a greater care than regular RabbitMQ queues.
-
-See link:https://www.rabbitmq.com/docs/quorum-queues#performance-tuning[this section of RabbitMQ documentation regarding RabbitMQ quroum queue performance tunning].
-
- - Provide decent amount of RAM memory to RabbitMQ. 4GB is a good start.
- - Setting a delivery limit is advised as looping messages can cause extreme memory consumptions onto quorum queues.
- - Set up Raft for small messages:
-
-....
-raft.segment_max_entries = 32768
-....
+:sample-configuration-prefix-url: https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration
+include::partial$configure/rabbitmq.adoc[]
== RabbitMQ MailQueue Configuration
@@ -153,19 +24,19 @@ Not necessarily needed for MDA deployments, mail queue management adds significa
| mailqueue.view.sliceWindow
| James divides the view into slices, each slice contains data for a given period, sliceWindow parameter controls this period.
This dividing of periods allows faster browsing of the mail queue. Tips for choosing sliceWindow are explained in
-https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration/rabbitmq.properties[rabbitmq.properties]
+{sample-configuration-prefix-url}/rabbitmq.properties[rabbitmq.properties]
| mailqueue.view.bucketCount
| Mails in a mail queue are distributed across the underlying storage service.
BucketCount describes how to be distributing mails to fit with your James setup
Tips for choosing bucketCount are explained in
-https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration/rabbitmq.properties[rabbitmq.properties]
+{sample-configuration-prefix-url}/rabbitmq.properties[rabbitmq.properties]
| mailqueue.view.updateBrowseStartPace
| To browse, James needs a starting point and to continuously update that point in runtime.
UpdateBrowseStartPace describes the probability to update the starting point.
Tips for choosing updateBrowseStartPace are explained in
-https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration/rabbitmq.properties[rabbitmq.properties]
+{sample-configuration-prefix-url}/rabbitmq.properties[rabbitmq.properties]
| mailqueue.size.metricsEnabled
| By default, the metrics are disabled for the mail queue size.
@@ -173,7 +44,7 @@ As computing the size of the mail queue is currently implemented on top of brows
sometimes it can get too big, making it impossible for the ES reporter to handle it correctly without crashing.
It can be useful then to disable it.
Tips for choosing metricsEnabled are explained in
-https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration/rabbitmq.properties[rabbitmq.properties]
+{sample-configuration-prefix-url}/rabbitmq.properties[rabbitmq.properties]
| notification.queue.ttl
| Configure queue ttl (in ms). References: https://www.rabbitmq.com/ttl.html#queue-ttl.
@@ -181,34 +52,3 @@ This is used only on queues used to share notification patterns, are exclusive t
Optional integer, defaults is 3600000.
|===
-
-== RabbitMQ Tasks Configuration
-
-Tasks are WebAdmin triggered long running jobs. RabbitMQ is used to organise their execution in a work queue,
-with an exclusive consumer.
-
-.rabbitmq.properties content
-|===
-| Property name | explanation
-
-| task.consumption.enabled
-| Whether to enable task consumption on this node.
-Disable with caution (this only makes sense in a distributed setup where other nodes consume tasks).
-Defaults to true.
-
-Limitation: Sometimes, some tasks running on James can be very heavy and take a couple of hours to complete.
-If other tasks are being triggered meanwhile on WebAdmin, they go on the TaskManagerWorkQueue and James unack them,
-telling RabbitMQ it will consume them later. If they don't get consumed before the consumer timeout setup in
-RabbitMQ (default being 30 minutes), RabbitMQ closes the channel on an exception. It is thus advised to declare a
-longer timeout in rabbitmq.conf. More https://www.rabbitmq.com/consumers.html#acknowledgement-timeout[here].
-
-| task.queue.consumer.timeout
-| Task queue consumer timeout.
-
-Optional. Duration (support multiple time units cf `DurationParser`), defaults to 1 day.
-
-Required at least RabbitMQ version 3.12 to have effect.
-This is used to avoid the task queue consumer (which could run very long tasks) being disconnected by RabbitMQ after the default acknowledgement timeout 30 minutes.
-References: https://www.rabbitmq.com/consumers.html#acknowledgement-timeout.
-
-|===
\ No newline at end of file
diff --git a/docs/modules/servers/pages/distributed/configure/recipientrewritetable.adoc b/docs/modules/servers/pages/distributed/configure/recipientrewritetable.adoc
index 108e09e56fc..983756ca61c 100644
--- a/docs/modules/servers/pages/distributed/configure/recipientrewritetable.adoc
+++ b/docs/modules/servers/pages/distributed/configure/recipientrewritetable.adoc
@@ -1,18 +1,7 @@
= Distributed James Server — recipientrewritetable.xml
:navtitle: recipientrewritetable.xml
-Here are explanations on the different kinds about xref:distributed/architecture/index.adoc#_recipient_rewrite_tables[recipient rewriting].
-
-Consult this link:https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration/recipientrewritetable.xml[example]
-to get some examples and hints.
-
-.recipientrewritetable.xml
-|===
-| Property name | explanation
-
-| recursiveMapping
-| If set to false only the first mapping will get processed - Default true.
-
-| mappingLimit
-|By setting the mappingLimit you can specify how much mapping will get processed before a bounce will send. This avoids infinity loops. Default 10.
-|===
+:sample-configuration-prefix-url: https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration
+:pages-path: distributed
+:server-name: Distributed James Server
+include::partial$configure/recipientrewritetable.adoc[]
\ No newline at end of file
diff --git a/docs/modules/servers/pages/distributed/configure/redis.adoc b/docs/modules/servers/pages/distributed/configure/redis.adoc
index 0d318b89cee..659ca53b354 100644
--- a/docs/modules/servers/pages/distributed/configure/redis.adoc
+++ b/docs/modules/servers/pages/distributed/configure/redis.adoc
@@ -1,47 +1,5 @@
= Distributed James Server — redis.properties
:navtitle: redis.properties
-This configuration helps you configure components using Redis. This so far only includes optional rate limiting component.
-
-Consult this link:https://github.com/apache/james-project/blob/fabfdf4874da3aebb04e6fe4a7277322a395536a/server/mailet/rate-limiter-redis/redis.properties[example]
-to get some examples and hints.
-
-== Redis Configuration
-
-.redis.properties content
-|===
-| Property name | explanation
-
-| redisURL
-| the Redis URI pointing to Redis server. Compulsory.
-
-| redis.topology
-| Redis server topology. Defaults to standalone. Possible values: standalone, cluster, master-replica
-
-| redis.readFrom
-| The property to determine how Lettuce routes read operations to Redis server with topologies other than standalone. Defaults to master. Possible values: master, masterPreferred, replica, replicaPreferred, any
-
-Reference: https://github.com/redis/lettuce/wiki/ReadFrom-Settings
-
-| redis.ioThreads
-| IO threads to be using for the underlying Netty networking resources. If unspecified driver defaults applies.
-
-| redis.workerThreads
-| Worker threads to be using for the underlying driver. If unspecified driver defaults applies.
-|===
-
-== Enabling Multithreading in Redis
-
-Redis 6 and later versions support multithreading, but by default, Redis operates as a single-threaded process.
-
-On a virtual machine with multiple CPU cores, you can enhance Redis performance by enabling multithreading. This can significantly improve I/O operations, particularly for workloads with high concurrency or large data volumes.
-
-See link:https://redis.io/docs/latest/operate/oss_and_stack/management/config-file/[THREADED I/O section].
-
-Example if you have a 4 cores CPU, you can enable the following lines in the `redis.conf` file:
-....
-io-threads 3
-io-threads-do-reads yes
-....
-
-However, if your machine has only 1 CPU core or your Redis usage is not intensive, you will not benefit from this.
\ No newline at end of file
+:sample-configuration-prefix-url: https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration
+include::partial$configure/redis.adoc[]
\ No newline at end of file
diff --git a/docs/modules/servers/pages/distributed/configure/remote-delivery-error-handling.adoc b/docs/modules/servers/pages/distributed/configure/remote-delivery-error-handling.adoc
index 55764e7a5d6..68efbdb38f6 100644
--- a/docs/modules/servers/pages/distributed/configure/remote-delivery-error-handling.adoc
+++ b/docs/modules/servers/pages/distributed/configure/remote-delivery-error-handling.adoc
@@ -1,117 +1,8 @@
= Distributed James Server — About RemoteDelivery error handling
:navtitle: About RemoteDelivery error handling
-The advanced server mailQueue implemented by combining RabbitMQ for messaging and Cassandra for administrative operation
-does not support delays.
-
-Delays are an important feature for Mail Exchange servers, allowing to defer in time the retries, potentially letting the
-time for the remote server to recover. Furthermore, they enable implementation of advanced features like throttling and
-rate limiting of emails sent to a given domain.
-
-As such, the use of the distributed server as a Mail Exchange server is currently discouraged.
-
-However, for operators willing to inter-operate with a limited set of well-identified, trusted remote mail servers, such
-limitation can be reconsidered. The main concern then become error handling for remote mail server failures. The following
-document will present a well tested strategy for Remote Delivery error handling leveraging standards Mail Processing components
-and mechanisms.
-
-== Expectations
-
-Such a solution should:
-
-- Attempt delivery a single time
-- Store transient and permanent failure in different mail repositories
-- After a given number of tries, transient failures should be considered permanent
-
-== Design
-
-image::remote-delivery-error-handling.png[Schema detailing the proposed solution]
-
-- Remote Delivery is configured for performing a single retry.
-- Remote Delivery attaches the error code and if the failure is permanent/temporary when transferring failed emails to the
-bounce processor.
-- The specified bounce processor will categorise the failure, and store temporary and permanent failures in different
-mail repositories.
-- A reprocessing of the temporary delivery errors mailRepository needs to be scheduled in a recurring basis. For
-instance via a CRON job calling the right webadmin endpoint.
-- A counter ensures that a configured number of delivery tries is not exceeded.
-
-=== Limitation
-
-MailRepositories are not meant for transient data storage, and thus are prone to tombstone issues.
-
-This might be acceptable if you need to send mail to well-known peers. For instance handling your mail gateway failures.
-However a Mail Exchange server doing relay on the internet would quickly hit this limitation.
-
-Also note that external triggering of the retry process is needed.
-
-== Operation
-
-Here is an example of configuration achieving the proposed solution:
-
-....
-
-
-
- outgoing
- 0
- 0
- 10
- true
-
- remote-delivery-error
-
-
-
- cassandra://var/mail/error/remote-delivery/permanent/
-
-
-
-
-
-
- cassandra://var/mail/error/remote-delivery/temporary/
-
-
-
- cassandra://var/mail/error/remote-delivery/permanent/
-
-
-
- cassandra://var/mail/error/
-
-
-....
-
-Note:
-
-- The *relay* processor holds a RemoteDelivery mailet configured to do a single try, at most 5 times (see the AtMost matcher).
-Mails exceeding the AtMost condition are considered as permanent delivery errors. Delivery errors are sent to the
-*remote-delivery-error* processor.
-- The *remote-delivery-error* stores temporary and permanent errors.
-- Permanent relay errors are stored in `cassandra://var/mail/error/remote-delivery/permanent/`.
-- Temporary relay errors are stored in `cassandra://var/mail/error/remote-delivery/temporary/`.
-
-In order to retry the relay of temporary failed emails, operators will have to configure a cron job for reprocessing
-emails from *cassandra://var/mail/error/remote-delivery/temporary/* mailRepository into the *relay* processor.
-
-This can be achieved via the following webAdmin call :
-
-....
-curl -XPATCH 'http://ip:8000/mailRepositories/cassandra%3A%2F%2Fvar%2Fmail%2Ferror%2Fremote-delivery%2Ftemporary%2F/mails?action=reprocess&processor=relay'
-....
-
-See xref:distributed/operate/webadmin.adoc#_reprocessing_mails_from_a_mail_repository[the documentation].
-
-Administrators need to keep a close eye on permanent errors (that might require audit, and potentially contacting the remote
-service supplier).
-
-To do so, one should regularly audit the content of *cassandra://var/mail/error/remote-delivery/permanent/*. This can be done
-via webAdmin calls:
-
-....
-curl -XGET 'http://ip:8000/mailRepositories/cassandra%3A%2F%2Fvar%2Fmail%2Ferror%2Fremote-delivery%2Ftemporary%2F/mails'
-....
-
-See xref:distributed/operate/webadmin.adoc#_listing_mails_contained_in_a_mail_repository[the documentation].
+:sample-configuration-prefix-url: https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration
+:pages-path: distributed
+:server-name: Distributed James Server
+:mailet-repository-path-prefix: cassandra
+include::partial$configure/remote-delivery-error-handling.adoc[]
\ No newline at end of file
diff --git a/docs/modules/servers/pages/distributed/configure/search.adoc b/docs/modules/servers/pages/distributed/configure/search.adoc
index 735b843bfa9..f4d5b156716 100644
--- a/docs/modules/servers/pages/distributed/configure/search.adoc
+++ b/docs/modules/servers/pages/distributed/configure/search.adoc
@@ -1,18 +1,5 @@
= Distributed James Server — Search configuration
:navtitle: Search configuration
-This configuration helps you configure the components used to back search.
-
-.search.properties content
-|===
-| Property name | explanation
-
-| implementation
-| The implementation to be used for search. Should be one of:
- - *opensearch* : Index and search mails into OpenSearch.
- - *scanning* : Do not index documents and perform scanning search, scrolling mailbox for matching contents.
- This implementation can have a prohibitive cost.
- - *opensearch-disabled* : Saves events to index into event dead letter. Make searches fails.
- This is useful to start James without OpenSearch while still tracking messages to index for later recovery. This
- can be used in order to ease delays for disaster recovery action plans.
-|===
\ No newline at end of file
+:sample-configuration-prefix-url: https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration
+include::partial$configure/search.adoc[]
\ No newline at end of file
diff --git a/docs/modules/servers/pages/distributed/configure/sieve.adoc b/docs/modules/servers/pages/distributed/configure/sieve.adoc
index 3874f3c6c47..b3b3c4f16fa 100644
--- a/docs/modules/servers/pages/distributed/configure/sieve.adoc
+++ b/docs/modules/servers/pages/distributed/configure/sieve.adoc
@@ -1,92 +1,7 @@
= Sieve
:navtitle: Sieve
-James servers are able to evaluate and execute Sieve scripts.
-
-Sieve is an extensible mail filtering language. It's limited
-expressiveness (no loops or variables, no tests with side
-effects) allows user created scripts to be run safely on email
-servers. Sieve is targeted at the final delivery phase (where
-an incoming email is transferred to a user's mailbox).
-
-The following Sieve capabilities are supported by Apache James:
-
- - link:https://www.ietf.org/rfc/rfc2234.txt[RFC 2234 ABNF]
- - link:https://www.ietf.org/rfc/rfc2244.txt[RFC 2244 ACAP]
- - link:https://www.ietf.org/rfc/rfc2298.txt[RFC 2298 MDN]
- - link:https://tools.ietf.org/html/rfc5228[RFC 5228 Sieve]
- - link:https://tools.ietf.org/html/rfc4790[RFC 4790 IAPCR]
- - link:https://tools.ietf.org/html/rfc5173[RFC 5173 Body Extension]
- - link:https://datatracker.ietf.org/doc/html/rfc5230[RFC 5230 Vacations]
-
-To be correctly executed, please note that the *Sieve* mailet is required to be positioned prior the
-*LocalDelivery* mailet.
-
-== Managing Sieve scripts
-
-A user willing to manage his Sieve scripts on the server can do so via several means:
-
-He can ask an admin to upload his script via the xref:distributed/operate/cli.adoc[CLI]
-
-As James supports ManageSieve (link:https://datatracker.ietf.org/doc/html/rfc5804[RFC-5804]) a user
-can thus use compatible software to manage his Sieve scripts.
-
-== ManageSieve protocol
-
-*WARNING*: ManageSieve protocol should be considered experimental.
-
-Consult link:https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration/managesieveserver.xml[managesieveserver.xml]
-in GIT to get some examples and hints.
-
-The service is controlled by a configuration block in the managesieveserver.xml.
-The managesieveserver tag defines the boundaries of the configuration block. It encloses
-all the relevant configuration for the ManageSieve server. The behavior of the ManageSieve service is
-controlled by the attributes and children of this tag.
-
-This tag has an optional boolean attribute - *enabled* - that defines whether the service is active or not.
-The value defaults to "false" if
-not present.
-
-The standard children of the managesieveserver tag are:
-
-.managesieveserver.xml content
-|===
-| Property name | explanation
-
-| bind
-| Configure this to bind to a specific inetaddress. This is an optional integer value. This value is the port on which this ManageSieve server is configured to listen. If the tag or value is absent then the service
-will bind to all network interfaces for the machine If the tag or value is omitted, the value will default to the standard ManageSieve port (port 4190 is the well-known/IANA registered port for ManageSieve.)
-
-| tls
-| Set to true to support STARTTLS or SSL for the Socket.
-To use this you need to copy sunjce_provider.jar to /path/james/lib directory. To create a new keystore execute:
-`keytool -genkey -alias james -keyalg RSA -storetype PKCS12 -keystore /path/to/james/conf/keystore`.
-Please note that each ManageSieve server exposed on different port can specify its own keystore, independently from any other
-TLS based protocols.
-
-| connectionBacklog
-| Number of connection backlog of the server (maximum number of queued connection requests)
-
-| connectiontimeout
-| Connection timeout in seconds
-
-| connectionLimit
-| Set the maximum simultaneous incoming connections for this service
-
-| connectionLimitPerIP
-| Set the maximum simultaneous incoming connections per IP for this service
-
-| bossWorkerCount
-| Set the maximum count of boss threads. Boss threads are responsible for accepting incoming ManageSieve connections
-and initializing associated resources. Optional integer, by default, boss threads are not used and this responsibility is being dealt with
-by IO threads.
-
-| ioWorkerCount
-| Set the maximum count of IO threads. IO threads are responsible for receiving incoming ManageSieve messages and framing them
-(split line by line). IO threads also take care of compression and SSL encryption. Their tasks are short-lived and non-blocking.
-Optional integer, defaults to 2 times the count of CPUs.
-
-| maxExecutorCount
-| Set the maximum count of worker threads. Worker threads takes care of potentially blocking tasks like executing ManageSieve commands.
-Optional integer, defaults to 16.
-|===
\ No newline at end of file
+:sample-configuration-prefix-url: https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration
+:pages-path: distributed
+:server-name: Distributed James Server
+include::partial$configure/sieve.adoc[]
\ No newline at end of file
diff --git a/docs/modules/servers/pages/distributed/configure/smtp-hooks.adoc b/docs/modules/servers/pages/distributed/configure/smtp-hooks.adoc
index 5dd48b0edce..45051231326 100644
--- a/docs/modules/servers/pages/distributed/configure/smtp-hooks.adoc
+++ b/docs/modules/servers/pages/distributed/configure/smtp-hooks.adoc
@@ -1,370 +1,7 @@
= Distributed James Server — SMTP Hooks
:navtitle: SMTP Hooks
-This documentation page lists and documents SMTP hooks that can be used within the
-Distributed Server SMTP protocol stack in order to customize the way your SMTP server
-behaves without of the box components.
-
-== DNSRBLHandler
-
-This command handler check against https://www.wikiwand.com/en/Domain_Name_System-based_Blackhole_List[RBL-Lists]
-(Real-time Blackhole List).
-
-If getDetail is set to true it try to retrieve information from TXT Record
-why the ip was blocked. Default to false.
-
-before you enable out the DNS RBL handler documented as an example below,
-please take a moment to review each block in the list.
-We have included some that various JAMES committers use,
-but you must decide which, if any, are appropriate
-for your environment.
-
-The mail servers hosting
-@apache.org mailing lists, for example, use a
-slightly different list than we have included below.
-And it is likely that most JAMES committers also have
-slightly different sets of lists.
-
-The SpamAssassin user's list would be one good place to discuss the
-measured quality of various block lists.
-
-NOTA BENE: the domain names, below, are terminated
-with '.' to ensure that they are absolute names in
-DNS lookups. Under some circumstances, names that
-are not explicitly absolute could be treated as
-relative names, leading to incorrect results. This
-has been observed on *nix and MS-Windows platforms
-by users of multiple mail servers, and is not JAMES
-specific. If you are unsure what this means for you,
-please speak with your local system/network admins.
-
-This handler should be considered experimental.
-
-Example configuration:
-
-....
-
-
-
- false
-
- query.bondedsender.org.
- sbl-xbl.spamhaus.org.
- dul.dnsbl.sorbs.net.
- list.dsbl.org.
-
-
-
-....
-
-== DSN hooks
-
-The Distributed server has optional support for DSN (link:https://tools.ietf.org/html/rfc3461[RFC-3461])
-
-Please read carefully xref:distributed/configure/dsn.adoc[this page].
-
-....
-
- <...>
-
-
-
-
-
- <...>
-
-
-
-....
-
-Note that a specific configuration of xref:distributed/configure/mailetcontainer.adoc[mailetcontainer.xml] is
-required as well to be spec compliant.
-
-== MailPriorityHandler
-
-This handler can add a hint to the mail which tells the MailQueue which email should get processed first.
-
-Normally the MailQueue will just handle Mails in FIFO manner.
-
-Valid priority values are 1,5,9 where 9 is the highest.
-
-This handler should be considered experimental.
-
-Example configuration:
-
-....
-
-
-
-
-
- yourdomain1
- 1
-
-
- yourdomain2
- 9
-
-
-
-
-....
-
-== MaxRcptHandler
-If activated you can limit the maximal recipients.
-
-This handler should be considered experimental.
-
-Example configuration:
-
-....
-
-
-
- 10
-
-
-....
-
-== POP3BeforeSMTPHandler
-
-This connect handler can be used to enable POP3 before SMTP support.
-
-Please note that only the ip get stored to identify an authenticated client.
-
-The expireTime is the time after which an ipAddress is handled as expired.
-
-This handler should be considered as unsupported.
-
-Example configuration:
-
-....
-
-
-
- 1 hour
-
-
-....
-
-== ResolvableEhloHeloHandler
-
-Checks for resolvable HELO/EHLO before accept the HELO/EHLO.
-
-If checkAuthNetworks is set to true sender domain will be checked also for clients that
-are allowed to relay. Default is false.
-
-This handler should be considered experimental.
-
-Example configuration:
-
-....
-
-
-
-
-....
-
-== ReverseEqualsEhloHeloHandler
-
-Checks HELO/EHLO is equal the reverse of the connecting client before accept it
-If checkAuthNetworks is set to true sender domain will be checked also for clients that
-are allowed to relay. Default is false.
-
-This handler should be considered experimental.
-
-Example configuration:
-
-....
-
-
-
-
-....
-
-== SetMimeHeaderHandler
-
-This handler allows you to add mime headers to the processed mails.
-
-This handler should be considered experimental.
-
-Example configuration:
-
-....
-
-
-
- SPF-test
- passed
-
-
-....
-
-== SpamAssassinHandler
-
-This MessageHandler could be used to check message against spamd before
-accept the email. So it's possible to reject a message on smtplevel if a
-configured hits amount is reached.
-
-This handler should be considered experimental.
-
-Example configuration:
-
-....
-
-
-
- 127.0.0.1
- 783
- 10
-
-
-....
-
-== SPFHandler
-
-This command handler can be used to reject emails with not match the SPF record of the sender domain.
-
-If checkAuthNetworks is set to true sender domain will be checked also for clients that
-are allowed to relay. Default is false.
-
-This handler should be considered experimental.
-
-Example configuration:
-
-....
-
-
-
- false
- true
-
-
-....
-
-== URIRBLHandler
-
-This MessageHandler could be used to extract domain out of the message and check
-this domains against uriRbllists. See http://www.surbl.org for more information.
-The message get rejected if a domain matched.
-
-This handler should be considered experimental.
-
-Example configuration:
-
-....
-
-
-
- reject
- true
-
- multi.surbl.org
-
-
-
-....
-
-== ValidRcptHandler
-
-With ValidRcptHandler, all email will get rejected which has no valid user.
-
-You need to add the recipient to the validRecipient list if you want
-to accept email for a recipient which not exist on the server.
-
-If you want James to act as a spamtrap or honeypot, you may comment ValidRcptHandler
-and implement the needed processors in spoolmanager.xml.
-
-This handler should be considered stable.
-
-Example configuration:
-
-....
-
-
-
-
-....
-
-== ValidSenderDomainHandler
-
-If activated mail is only accepted if the sender contains
-a resolvable domain having a valid MX Record or A Record associated!
-
-If checkAuthNetworks is set to true sender domain will be checked also for clients that
-are allowed to relay. Default is false.
-
-Example configuration:
-
-....
-
-
-
-
-....
-
-== FUTURERELEASE hooks
-
-The Distributed server has optional support for FUTURERELEASE (link:https://www.rfc-editor.org/rfc/rfc4865.html[RFC-4865])
-
-....
-
- <...>
-
-
-
-
-
-
-....
-
-== Message Transfer Priorities hooks
-
-The Distributed server has optional support for SMTP Extension for Message Transfer Priorities (link:https://www.rfc-editor.org/rfc/rfc6710.html[RFC-6710])
-
-The SMTP server does not allow positive priorities from unauthorized sources and sets the priority to the default value (0).
-
-....
-
- <...>
-
-
-
-
-
-
-
-....
-
-== DKIM checks hooks
-
-Hook for verifying DKIM signatures of incoming mails.
-
-This hook can be restricted to specific sender domains and authenticate those emails against
-their DKIM signature. Given a signed outgoing traffic this hook can use operators to accept legitimate
-emails emitted by their infrastructure but redirected without envelope changes to there own domains by
-some intermediate third parties. See link:https://issues.apache.org/jira/browse/JAMES-4032[JAMES-4032].
-
-Supported configuration elements:
-
-- *forceCRLF*: Should CRLF be forced when computing body hashes.
-- *onlyForSenderDomain*: If specified, the DKIM checks are applied just for the emails whose MAIL FROM specifies this domain. If unspecified, all emails are checked (default).
-- *signatureRequired*: If DKIM signature is checked, the absence of signature will generate failure. Defaults to false.
-- *expectedDToken*: If DKIM signature is checked, the body should contain at least one DKIM signature with this d token. If unspecified, all d tokens are considered valid (default).
-
-Example handlerchain configuration for `smtpserver.xml`:
-
-....
-
-
- true
- apache.org
- true
- apache.org
-
-
-
-....
-
-Would allow emails using `apache.org` as a MAIL FROM domain if, and only if they contain a
-valid DKIM signature for the `apache.org` domain.
\ No newline at end of file
+:sample-configuration-prefix-url: https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration
+:pages-path: distributed
+:server-name: Distributed James Server
+include::partial$configure/smtp-hooks.adoc[]
\ No newline at end of file
diff --git a/docs/modules/servers/pages/distributed/configure/smtp.adoc b/docs/modules/servers/pages/distributed/configure/smtp.adoc
index 34e22887143..85f0845c48a 100644
--- a/docs/modules/servers/pages/distributed/configure/smtp.adoc
+++ b/docs/modules/servers/pages/distributed/configure/smtp.adoc
@@ -1,316 +1,7 @@
= Distributed James Server — smtpserver.xml
:navtitle: smtpserver.xml
-== Incoming SMTP
-
-Consult this link:https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration/smtpserver.xml[example]
-to get some examples and hints.
-
-The SMTP service is controlled by a configuration block in the smptserver.xml.
-The smtpserver tag defines the boundaries of the configuration block. It encloses
-all the relevant configuration for the SMTP server. The behavior of the SMTP service is
-controlled by the attributes and children of this tag.
-
-This tag has an optional boolean attribute - *enabled* - that defines whether the service is active or not. The value defaults to "true" if
-not present.
-
-The standard children of the smtpserver tag are:
-
-.smtpserver.xml content
-|===
-| Property name | explanation
-
-| bind
-| A list of address:port separed by comma - This is an optional value. If present, this value is a string describing
-the IP address to which this service should be bound. If the tag or value is absent then the service
-will bind to all network interfaces for the machine on port 25. Port 25 is the well-known/IANA registered port for SMTP.
-Port 465 is the well-known/IANA registered port for SMTP over TLS.
-
-| connectBacklog
-|The IP address (host name) the MBean Server will bind/listen to.
-
-| tls
-| Set to true to support STARTTLS or SSL for the Socket.
-To use this you need to copy sunjce_provider.jar to /path/james/lib directory. To create a new keystore execute:
-`keytool -genkey -alias james -keyalg RSA -storetype PKCS12 -keystore /path/to/james/conf/keystore`.
-The algorithm is optional and only needs to be specified when using something other
-than the Sun JCE provider - You could use IbmX509 with IBM Java runtime.
-Please note that each SMTP/LMTP server exposed on different port can specify its own keystore, independently from any other
-TLS based protocols.
-
-| helloName
-| This is a required tag with an optional body that defines the server name
-used in the initial service greeting. The tag may have an optional attribute - *autodetect*. If
-the autodetect attribute is present and true, the service will use the local hostname
-returned by the Java libraries. If autodetect is absent or false, the body of the tag will be used. In
-this case, if nobody is present, the value "localhost" will be used.
-
-| connectionTimeout
-| This is an optional tag with a non-negative integer body. Connection timeout in seconds.
-
-| connectionLimit
-| Set the maximum simultaneous incoming connections for this service.
-
-| connectionLimitPerIP
-| Set the maximum simultaneous incoming connections per IP for this service.
-
-| proxyRequired
-| Enables proxy support for this service for incoming connections. HAProxy's protocol
-(https://www.haproxy.org/download/2.7/doc/proxy-protocol.txt) is used and might be compatible
-with other proxies (e.g. traefik). If enabled, it is *required* to initiate the connection
-using HAProxy's proxy protocol.
-
-| authRequired
-| (deprecated) use auth.announce instead.
-
-This is an optional tag with a boolean body. If true, then the server will
-announce authentication after HELO command. If this tag is absent, or the value
-is false then the client will not be prompted for authentication. Only simple user/password authentication is
-supported at this time. Supported values:
-
- * true: announced only to not authorizedAddresses
-
- * false: don't announce AUTH. If absent, *authorizedAddresses* are set to a wildcard to accept all remote hosts.
-
- * announce: like true, but always announce AUTH capability to clients
-
-Please note that emails are only relayed if, and only if, the user did authenticate, or is in an authorized network,
-regardless of this option.
-
-| auth.announce
-| This is an optional tag. Possible values are:
-
-* never: Don't announce auth.
-
-* always: always announce AUTH capability to clients.
-
-* forUnauthorizedAddresses: announced only to not authorizedAddresses
-
-Please note that emails are only relayed if, and only if, the user did authenticate, or is in an authorized network,
-regardless of this option.
-
-| auth.requireSSL
-| This is an optional tag, defaults to true. If true, authentication is not advertised via capabilities on unencrypted
-channels.
-
-| auth.plainAuthEnabled
-| This is an optional tag, defaults to true. If false, AUTH PLAIN and AUTH LOGIN will not be exposed. This setting
-can be used to enforce strong authentication mechanisms.
-
-| auth.oidc.oidcConfigurationURL
-| Provide OIDC url address for information to user. Only configure this when you want to authenticate SMTP server using a OIDC provider.
-
-| auth.oidc.jwksURL
-| Provide url to get OIDC's JSON Web Key Set to validate user token. Only configure this when you want to authenticate SMTP server using a OIDC provider.
-
-| auth.oidc.claim
-| Claim string uses to identify user. E.g: "email_address". Only configure this when you want to authenticate SMTP server using a OIDC provider.
-
-| auth.oidc.scope
-| An OAuth scope that is valid to access the service (RF: RFC7628). Only configure this when you want to authenticate SMTP server using a OIDC provider.
-
-| auth.oidc.introspection.url
-| Optional. An OAuth introspection token URL will be called to validate the token (RF: RFC7662).
-Only configure this when you want to validate the revocation token by the OIDC provider.
-Note that James always verifies the signature of the token even whether this configuration is provided or not.
-
-| auth.oidc.introspection.auth
-| Optional. Provide Authorization in header request when introspecting token.
-Eg: `Basic xyz`
-
-| auth.oidc.userinfo.url
-| Optional. An Userinfo URL will be called to validate the token (RF: OpenId.Core https://openid.net/specs/openid-connect-core-1_0.html).
-Only configure this when you want to validate the revocation token by the OIDC provider.
-Note that James always verifies the signature of the token even whether this configuration is provided or not.
-James will ignore check token by userInfo if the `auth.oidc.introspection.url` is already configured
-
-| authorizedAddresses
-| Authorize specific addresses/networks.
-
-If you use SMTP AUTH, addresses that match those specified here will
-be permitted to relay without SMTP AUTH. If you do not use SMTP
-AUTH, and you specify addresses here, then only addresses that match
-those specified will be permitted to relay.
-
-Addresses may be specified as a IP address or domain name, with an
-optional netmask, e.g.,
-
-127.*, 127.0.0.0/8, 127.0.0.0/255.0.0.0, and localhost/8 are all the same
-
-See also the RemoteAddrNotInNetwork matcher in the transport processor.
-You would generally use one OR the other approach.
-
-| verifyIdentity
-| This is an optional tag. This options governs MAIL FROM verifications, and prevents spoofing of the MAIL FROM
-envelop field.
-
-The following values are supported:
-
- - `strict`: use of a local domain in MAIL FROM requires the SMTP client to be authenticated with a matching user or one
- of its aliases. It will verify that the sender address matches the address of the user or one of its alias (from user or domain aliases).
- This prevents a user of your mail server from acting as someone else
- - `disabled`: no check is performed and third party are free to send emails as local users. Note that relaying emails will
- need third party to be authenticated thus preventing open relays.
- - `relaxed`: Based on a simple heuristic to determine if the SMTP client is a MUA or a MX (use of a valid domain in EHLO),
- we do act as `strict` for MUAs thus prompting them early for the need of authentication, but accept use of local MAIL FROM for
- MX. Authentication can then be delayed to later, eg after DATA transaction with the DKIMHook which might allow email looping through
- third party domains via mail redirection, effectively enforcing that the mail originates from our servers. See
- link:https://issues.apache.org/jira/browse/JAMES-4032[JAMES-4032] for detailed explanation.
-
-Backward compatibility is provided and thus the following values are supported:
-
- - `true`: act as `strict`
- - `false`: act as `disabled`
-
-| maxmessagesize
-| This is an optional tag with a non-negative integer body. It specifies the maximum
-size, in kbytes, of any message that will be transmitted by this SMTP server. It is a service-wide, as opposed to
-a per user, limit. If the value is zero then there is no limit. If the tag isn't specified, the service will
-default to an unlimited message size. Must be a positive integer, optionally with a unit: B, K, M, G.
-
-| heloEhloEnforcement
-| This sets whether to enforce the use of HELO/EHLO salutation before a
-MAIL command is accepted. If unspecified, the value defaults to true.
-
-| smtpGreeting
-| This sets the SMTPGreeting which will be used when connect to the smtpserver
-If none is specified a default is generated
-
-| handlerchain
-| The configuration handler chain. See xref:distributed/configure/smtp-hooks.adoc[this page] for configuring out-of the
-box extra SMTP handlers and hooks.
-
-| bossWorkerCount
-| Set the maximum count of boss threads. Boss threads are responsible for accepting incoming SMTP connections
-and initializing associated resources. Optional integer, by default, boss threads are not used and this responsibility is being dealt with
-by IO threads.
-
-| ioWorkerCount
-| Set the maximum count of IO threads. IO threads are responsible for receiving incoming SMTP messages and framing them
-(split line by line). IO threads also take care of compression and SSL encryption. Their tasks are short-lived and non-blocking.
-Optional integer, defaults to 2 times the count of CPUs.
-
-| maxExecutorCount
-| Set the maximum count of worker threads. Worker threads takes care of potentially blocking tasks like executing SMTP commands.
-Optional integer, defaults to 16.
-
-| useEpoll
-| true or false - If true uses native EPOLL implementation for Netty otherwise uses NIO. Defaults to false.
-
-| gracefulShutdown
-| true or false - If true attempts a graceful shutdown, which is safer but can take time. Defaults to true.
-
-| disabledFeatures
-| Extended SMTP features to hide in EHLO responses.
-|===
-
-=== OIDC setup
-James SMTP support XOAUTH2 authentication mechanism which allow authenticating against a OIDC providers.
-Please configure `auth.oidc` part to use this.
-
-We do supply an link:https://github.com/apache/james-project/tree/master/examples/oidc[example] of such a setup.
-It uses the Keycloak OIDC provider, but usage of similar technologies is definitely doable.
-
-== About open relays
-
-Authenticated SMTP is a method of securing your SMTP server. With SMTP AUTH enabled senders who wish to
-relay mail through the SMTP server (that is, send mail that is eventually to be delivered to another SMTP
-server) must authenticate themselves to Apache James Server before sending their message. Mail that is to be delivered
-locally does not require authentication. This method ensures that spammers cannot use your SMTP server
-to send unauthorized mail, while still enabling users who may not have fixed IP addresses to send their
-messages.
-
-Mail servers that allow spammers to send unauthorized email are known as open relays. So SMTP AUTH
-is a mechanism for ensuring that your server is not an open relay.
-
-It is extremely important that your server not be configured as an open relay. Aside from potential
-costs associated with usage by spammers, connections from servers that are determined to be open relays
-are routinely rejected by SMTP servers. This can severely impede the ability of your mail server to
-send mail.
-
-At this time Apache James Server only supports simple user name / password authentication.
-
-As mentioned above, SMTP AUTH requires that Apache James Server be able to distinguish between mail intended
-for local delivery and mail intended for remote delivery. Apache James Server makes this determination by matching the
-domain to which the mail was sent against the *DomainList* component, configured by
-xref:distributed/configure/domainlist.adoc[*domainlist.xml*].
-
-The Distributed Server is configured out of the box so as to not serve as an open relay for spammers. This is done
-by relayed emails originate from a trusted source. This includes:
-
-* Authenticated SMTP/JMAP users
-* Mails generated by the server (eg: bounces)
-* Mails originating from a trusted network as configured in *smtpserver.xml*
-
-If you wish to ensure that authenticated users can only send email from their own account, you may
-optionally set the verifyIdentity element of the smtpserver configuration block to "true".
-
-=== Verification
-
-Verify that you have not inadvertently configured your server as an open relay. This is most easily
-accomplished by using the service provided at https://mxtoolbox.com/diagnostic.aspx[mxtoolbox.com]. mxtoolbox.com will
-check your mail server and inform you if it is an open relay. This tool further more verifies additional properties like:
-
-* Your DNS configuration, especially that you mail server IP has a valid reverse DNS entry
-* That your SMTP connection is secured
-* That you are not an OpenRelay
-* This website also allow a quick lookup to ensure your mail server is not in public blacklists.
-
-Of course it is also necessary to confirm that users and log in and send
-mail through your server. This can be accomplished using any standard mail client (i.e. Thunderbird, Outlook,
-Eudora, Evolution).
-
-== LMTP Configuration
-
-Consult this link:https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration/lmtpserver.xml[example]
-to get some examples and hints.
-
-The configuration is the same of for SMTP.
-
-By default, it is deactivated. You can activate it alongside SMTP and bind for example on port 24.
-
-The default LMTP server stores directly emails in user mailboxes, without further treatment.
-
-However we do ship an alternative handler chain allowing to execute the mailet container, thus achieving a behaviour similar
-to the default SMTP protocol. Here is how to achieve this:
-
-....
-
-
- lmtpserver
- 0.0.0.0:24
- 200
- 1200
- 0
- 0
- 0
-
-
-
-
-
-....
-
-Note that by default the mailet container is executed with all recipients at once and do not allow per recipient
-error reporting. An option splitExecution allow to execute the mailet container for each recipient separately and mitigate this
-limitation at the cost of performance.
-
-....
-
-
- lmtpserver
- 0.0.0.0:24
- 200
- 1200
- 0
- 0
- 0
-
-
-
- true
-
-
-
-
-....
\ No newline at end of file
+:sample-configuration-prefix-url: https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration
+:pages-path: distributed
+:server-name: Distributed James Server
+include::partial$configure/smtp.adoc[]
\ No newline at end of file
diff --git a/docs/modules/servers/pages/distributed/configure/spam.adoc b/docs/modules/servers/pages/distributed/configure/spam.adoc
index 8a7839d6048..4b7dabd7972 100644
--- a/docs/modules/servers/pages/distributed/configure/spam.adoc
+++ b/docs/modules/servers/pages/distributed/configure/spam.adoc
@@ -1,190 +1,8 @@
= Distributed James Server — Anti-Spam configuration
:navtitle: Anti-Spam configuration
-Anti-Spam system can be configured via two main different mechanisms:
-
-* SMTP Hooks;
-* Mailets;
-
-== AntiSpam SMTP Hooks
-
-"FastFail" SMTP Hooks acts to reject before spooling
-on the SMTP level. The Spam detector hook can be used as a fastfail hook, therefore
-Spam filtering system must run as a server on the same machine as the Apache James Server.
-
-SMTP Hooks for non-existent users, DSN filter, domains with invalid MX record,
-can also be configured.
-
-*SpamAssassinHandler* (experimental) also enables to classify the messages as spam or not
-with a configurable score threshold (`0.0`, non-configurable). Only a global database is supported. Per user spam
-detection is not supported by this hook.
-
-== AntiSpam Mailets
-
-James' repository provide two AntiSpam mailets: SpamAssassin and RspamdScanner.
-We can select one in them for filtering spam mail.
-
-* *SpamAssassin and RspamdScanner* Mailet is designed to classify the messages as spam or not
-with a configurable score threshold. Usually a message will only be
-considered as spam if it matches multiple criteria; matching just a single test
-will not usually be enough to reach the threshold. Note that this mailet is executed on a per-user basis.
-
-=== Rspamd
-
-The Rspamd extension (optional) requires an extra configuration file `rspamd.properties` to configure RSpamd connection
-
-.rspamd.properties content
-|===
-| Property name | explanation
-
-| rSpamdUrl
-| URL defining the Rspamd's server. Eg: http://rspamd:11334
-
-| rSpamdPassword
-| Password for pass authentication when request to Rspamd's server. Eg: admin
-
-| rspamdTimeout
-| Integer. Timeout for http requests to Rspamd. Default to 15 seconds.
-
-| perUserBayes
-| Boolean. Whether to scan/learn mails using per-user Bayes. Default to false.
-|===
-
-`RspamdScanner` supports the following options:
-
-* You can specify the `virusProcessor` if you want to enable virus scanning for mail. Upon configurable `virusProcessor`
-you can specify how James process mail virus. We provide a sample Rspamd mailet and `virusProcessor` configuration:
-
-* You can specify the `rejectSpamProcessor`. Emails marked as `rejected` by Rspamd will be redirected to this
-processor. This corresponds to emails with the highest spam score, thus delivering them to users as marked as spam
-might not even be desirable.
-
-* The `rewriteSubject` option allows to rewritte subjects when asked by Rspamd.
-
-This mailet can scan mails against per-user Bayes by configure `perUserBayes` in `rspamd.properties`. This is achieved
-through the use of Rspamd `Deliver-To` HTTP header. If true, Rspamd will be called for each recipient of the mail, which comes at a performance cost. If true, subjects are not rewritten.
-If true `virusProcessor` and `rejectSpamProcessor` are honnered per user, at the cost of email copies. Default to false.
-
-Here is an example of mailet pipeline conducting out RspamdScanner execution:
-
-....
-
-
- true
- virus
- spam
-
-
- Spam
-
-
-
-
-
-
-
- file://var/mail/virus/
-
-
-
-
-
- all
- .*
-
-
- [VIRUS]
-
-
-
-
-
-
- cassandra://var/mail/spam
-
-
-....
-
-==== Feedback for Rspamd
-If enabled, the `RspamdListener` will base on the Mailbox event to detect the message is a spam or not, then James will send report `spam` or `ham` to Rspamd.
-This listener can report mails to per-user Bayes by configure `perUserBayes` in `rspamd.properties`.
-The Rspamd listener needs to explicitly be registered with xref:distributed/configure/listeners.adoc[listeners.xml].
-
-Example:
-
-....
-
-
- org.apache.james.rspamd.RspamdListener
-
-
-....
-
-For more detail about how to use Rspamd's extension: `third-party/rspamd/index.md`
-
-Alternatively, batch reports can be triggered on user mailbox content via webAdmin. link:https://github.com/apache/james-project/tree/master/third-party/rspamd#additional-webadmin-endpoints[Read more].
-
-
-=== SpamAssassin
-Here is an example of mailet pipeline conducting out SpamAssassin execution:
-
-....
-
- ignore
- spamassassin
- 783
-
-
-
- org.apache.james.spamassassin.status; X-JAMES-SPAMASSASSIN-STATUS
- org.apache.james.spamassassin.flag; X-JAMES-SPAMASSASSIN-FLAG
-
-
- Spam
-
-....
-
-* *BayesianAnalysis* (unsupported) in the Mailet uses Bayesian probability to classify mail as
-spam or not spam. It relies on the training data coming from the users’ judgment.
-Users need to manually judge as spam and send to spam@thisdomain.com, oppositely,
-if not spam they then send to not.spam@thisdomain.com. BayesianAnalysisfeeder learns
-from this training dataset, and build predictive models based on Bayesian probability.
-There will be a certain table for maintaining the frequency of Corpus for keywords
-in the database. Every 10 mins a thread in the BayesianAnalysis will check and update
-the table. Also, the correct approach is to send the original spam or non-spam
-as an attachment to another message sent to the feeder in order to avoid bias from the
-current sender's email header.
-
-==== Feedback for SpamAssassin
-
-If enabled, the `SpamAssassinListener` will asynchronously report users mails moved to the `Spam` mailbox as Spam,
-and other mails as `Ham`, effectively populating the user database for per user spam detection. This enables a per-user
-Spam categorization to be conducted out by the SpamAssassin mailet, the SpamAssassin hook being unaffected.
-
-The SpamAssassin listener requires an extra configuration file `spamassassin.properties` to configure SpamAssassin connection (optional):
-
-.spamassassin.properties content
-|===
-| Property name | explanation
-
-| spamassassin.host
-| Hostname of the SpamAssassin server. Defaults to 127.0.0.1.
-
-| spamassassin.port
-| Port of the SpamAssassin server. Defaults to 783.
-|===
-
-Note that this configuration file only affects the listener, and not the hook or mailet.
-
-The SpamAssassin listener needs to explicitly be registered with xref:distributed/configure/listeners.adoc[listeners.xml].
-
-Example:
-
-....
-
-
- org.apache.james.mailbox.spamassassin.SpamAssassinListener
- true
-
-
-....
+:sample-configuration-prefix-url: https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration
+:pages-path: distributed
+:server-name: Distributed James Server
+:mailet-repository-path-prefix: cassandra
+include::partial$configure/spam.adoc[]
\ No newline at end of file
diff --git a/docs/modules/servers/pages/distributed/configure/ssl.adoc b/docs/modules/servers/pages/distributed/configure/ssl.adoc
index b21a17fa3a8..f77590ec95a 100644
--- a/docs/modules/servers/pages/distributed/configure/ssl.adoc
+++ b/docs/modules/servers/pages/distributed/configure/ssl.adoc
@@ -1,247 +1,7 @@
= Distributed James Server — SSL & TLS configuration
:navtitle: SSL & TLS configuration
-This document explains how to enable James 3.0 servers to use Transport Layer Security (TLS)
-for encrypted client-server communication.
-
-== Configure a Server to Use SSL/TLS
-
-Each of the servers xref:distributed/configure/smtp.adoc[SMTP - LMTP],
-xref:distributed/configure/pop3.adoc[POP3] and xref:distributed/configure/imap.adoc[IMAP]
-supports use of SSL/TLS.
-
-TLS (Transport Layer Security) and SSL (Secure Sockets Layer) are protocols that provide
-data encryption and authentication between applications in scenarios where that data is
-being sent across an insecure network, such as checking your email
-(How does the Secure Socket Layer work?). The terms SSL and TLS are often used
-interchangeably or in conjunction with each other (TLS/SSL),
-but one is in fact the predecessor of the other — SSL 3.0 served as the basis
-for TLS 1.0 which, as a result, is sometimes referred to as SSL 3.1.
-
-You need to add a block in the corresponding configuration file (smtpserver.xml, pop3server.xml, imapserver.xml,..)
-
-....
-
- file://conf/keystore
- PKCS12
- yoursecret
- org.bouncycastle.jce.provider.BouncyCastleProvider
-
-....
-
-Alternatively TLS keys can be supplied via PEM files:
-
-....
-
- file://conf/private.key
- file://conf/certs.self-signed.csr
-
-....
-
-An optional secret might be specified for the private key:
-
-....
-
- file://conf/private.key
- file://conf/certs.self-signed.csr
- yoursecret
-
-....
-
-Optionally, TLS protocols and/or cipher suites can be specified explicitly (smtpserver.xml, pop3server.xml, imapserver.xml,..).
-Otherwise, the default protocols and cipher suites of the used JDK will be used:
-....
-
-
- TLSv1.2
- TLSv1.1
- TLSv1
- SSLv3
-
-
- TLS_AES_256_GCM_SHA384
- TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256
-
-
-....
-
-Each of these block has an optional boolean configuration element socketTLS and startTLS which is used to toggle
-use of SSL or TLS for the service.
-
-With socketTLS (SSL/TLS in Thunderbird), all the communication is encrypted.
-
-With startTLS (STARTTLS in Thunderbird), the preamble is readable, but the rest is encrypted.
-
-....
-* OK JAMES IMAP4rev1 Server Server 192.168.1.4 is ready.
-* CAPABILITY IMAP4rev1 LITERAL+ CHILDREN WITHIN STARTTLS IDLE NAMESPACE UIDPLUS UNSELECT AUTH=PLAIN
-1 OK CAPABILITY completed.
-2 OK STARTTLS Begin TLS negotiation now.
-... rest is encrypted...
-....
-
-You can only enable one of the both at the same time for a service.
-
-It is also recommended to change the port number on which the service will listen:
-
-* POP3 - port 110, Secure POP3 - port 995
-* IMAP - port 143, Secure IMAP4 - port 993
-* SMTP - port 25, Secure SMTP - port 465
-
-You will now need to create your certificate store and place it in the james/conf/ folder with the name you defined in the keystore tag.
-
-Please note `JKS` keystore format is also supported (default value if no keystore type is specified):
-
-....
-
- file://conf/keystore
- JKS
- yoursecret
- org.bouncycastle.jce.provider.BouncyCastleProvider
-
-....
-
-
-=== Client authentication via certificates
-
-When you enable TLS, you may also configure the server to require a client certificate for authentication:
-
-....
-
- file://conf/keystore
- JKS
- yoursecret
-
-
- file://conf/truststore
- JKS
- yoursecret
- false
-
-
-....
-
-James verifies client certificates against the provided truststore. You can fill it with trusted peer certificates directly, or an issuer certificate (CA) if you trust all certificates created by it. If you omit the truststore configuration, James will use the Java default truststore instead, effectively trusting any known CA.
-
-James can optionally enable OCSP verifications for client certificates against Certificate Revocation List referenced
-in the certificate itself.
-
-== Creating your own PEM keys
-
-The following commands can be used to create self signed PEM keys:
-
-....
-# Generating your private key
-openssl genrsa -des3 -out private.key 2048
-
-# Creating your certificates
-openssl req -new -key private.key -out certs.csr
-
-# Signing the certificate yourself
-openssl x509 -req -days 365 -in certs.csr -signkey private.key -out certs.self-signed.csr
-
-# Removing the password from the private key
-# Not necessary if you supply the secret in the configuration
-openssl rsa -in private.key -out private.nopass.key
-....
-
-You may then supply this TLS configuration:
-
-....
-
- file://conf/private.nopass.key
- file://conf/certs.self-signed.csr
-
-....
-
-== Certificate Keystores
-
-This section gives more indication for users relying on keystores.
-
-=== Creating your own Certificate Keystore
-
-(Adapted from the Tomcat 4.1 documentation)
-
-James currently operates only on JKS or PKCS12 format keystores. This is Java's standard "Java KeyStore" format, and is
-the format created by the keytool command-line utility. This tool is included in the JDK.
-
-To import an existing certificate into a JKS keystore, please read the documentation (in your JDK documentation package)
-about keytool.
-
-To create a new keystore from scratch, containing a single self-signed Certificate, execute the following from a terminal
-command line:
-
-....
-keytool -genkey -alias james -keyalg RSA -storetype PKCS12 -keystore your_keystore_filename
-....
-
-(The RSA algorithm should be preferred as a secure algorithm, and this also ensures general compatibility with other
-servers and components.)
-
-As a suggested standard, create the keystore in the james/conf directory, with a name like james.keystore.
-
-After executing this command, you will first be prompted for the keystore password.
-
-Next, you will be prompted for general information about this Certificate, such as company, contact name, and so on.
-This information may be displayed to users when importing into the certificate store of the client, so make sure that
-the information provided here matches what they will expect.
-
-Important: in the "distinguished name", set the "common name" (CN) to the DNS name of your James server, the one
-you will use to access it from your mail client (like "mail.xyz.com").
-
-Finally, you will be prompted for the key password, which is the password specifically for this Certificate
-(as opposed to any other Certificates stored in the same keystore file).
-
-If everything was successful, you now have a keystore file with a Certificate that can be used by your server.
-
-You MUST have only one certificate in the keystore file used by James.
-
-=== Installing a Certificate provided by a Certificate Authority
-
-(Adapted from the Tomcat 4.1 documentation
-
-To obtain and install a Certificate from a Certificate Authority (like verisign.com, thawte.com or trustcenter.de)
-you should have read the previous section and then follow these instructions:
-
-==== Create a local Certificate Signing Request (CSR)
-
-In order to obtain a Certificate from the Certificate Authority of your choice you have to create a so called
-Certificate Signing Request (CSR). That CSR will be used by the Certificate Authority to create a Certificate
-that will identify your James server as "secure". To create a CSR follow these steps:
-
-* Create a local Certificate as described in the previous section.
-
-The CSR is then created with:
-
-....
- keytool -certreq -keyalg RSA -alias james -file certreq.csr -keystore your_keystore_filename
-....
-
-Now you have a file called certreq.csr. The file is encoded in PEM format. You can submit it to the Certificate Authority
-(look at the documentation of the Certificate Authority website on how to do this). In return you get a Certificate.
-
-Now that you have your Certificate you can import it into you local keystore. First of all you may have to import a so
-called Chain Certificate or Root Certificate into your keystore (the major Certificate Authorities are already in place,
-so it's unlikely that you will need to perform this step). After that you can procede with importing your Certificate.
-
-==== Optionally Importing a so called Chain Certificate or Root Certificate
-
-Download a Chain Certificate from the Certificate Authority you obtained the Certificate from.
-
-* For Verisign.com go to: http://www.verisign.com/support/install/intermediate.html
-* For Trustcenter.de go to: http://www.trustcenter.de/certservices/cacerts/en/en.htm#server
-* For Thawte.com go to: http://www.thawte.com/certs/trustmap.html (seems no longer valid)
-
-==== Import the Chain Certificate into you keystore
-
-....
-keytool -import -alias root -keystore your_keystore_filename -trustcacerts -file filename_of_the_chain_certificate
-....
-
-And finally import your new Certificate (It must be in X509 format):
-
-....
-keytool -import -alias james -keystore your_keystore_filename -trustcacerts -file your_certificate_filename
-....
-
-See also http://www.agentbob.info/agentbob/79.html[this page]
\ No newline at end of file
+:sample-configuration-prefix-url: https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration
+:pages-path: distributed
+:server-name: Distributed James Server
+include::partial$configure/ssl.adoc[]
\ No newline at end of file
diff --git a/docs/modules/servers/pages/distributed/configure/tika.adoc b/docs/modules/servers/pages/distributed/configure/tika.adoc
index fdb2cc9cf7a..604b31e4865 100644
--- a/docs/modules/servers/pages/distributed/configure/tika.adoc
+++ b/docs/modules/servers/pages/distributed/configure/tika.adoc
@@ -1,51 +1,5 @@
= Distributed James Server — tika.properties
:navtitle: tika.properties
-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: You can launch a tika server using this command line:
-
-....
-docker run --name tika linagora/docker-tikaserver:1.24
-....
-
-Here are the different properties:
-
-.tika.properties content
-|===
-| Property name | explanation
-
-| 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.
-|===
+:sample-configuration-prefix-url: https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration
+include::partial$configure/tika.adoc[]
\ No newline at end of file
diff --git a/docs/modules/servers/pages/distributed/configure/usersrepository.adoc b/docs/modules/servers/pages/distributed/configure/usersrepository.adoc
index ff07f7929e3..d4cef0a23f7 100644
--- a/docs/modules/servers/pages/distributed/configure/usersrepository.adoc
+++ b/docs/modules/servers/pages/distributed/configure/usersrepository.adoc
@@ -1,136 +1,5 @@
= Distributed James Server — usersrepository.xml
:navtitle: usersrepository.xml
-User repositories are required to store James user information and authentication data.
-
-Consult this link:https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration/usersrepository.xml[example]
-to get some examples and hints.
-
-== The user data model
-
-A user has two attributes: username and password.
-
-A valid user should satisfy these criteria:
-
-* username and password cannot be null or empty
-* username should not be longer than 255 characters
-* username can not contain '/'
-* username can not contain multiple domain delimiter('@')
-* A username can have only a local part when virtualHosting is disabled. E.g.'myUser'
-* When virtualHosting is enabled, a username should have a domain part, and the domain part should be concatenated
-after a domain delimiter('@'). E.g. 'myuser@james.org'
-
-A user is always considered as lower cased, so 'myUser' and 'myuser' are the same user, and can be used as well as
-recipient local part than as login for different protocols.
-
-== Configuration
-
-.usersrepository.xml content
-|===
-| Property name | explanation
-
-| enableVirtualHosting
-| true or false. Add domain support for users (default: false, except for Cassandra Users Repository)
-
-| administratorId
-|user's name. Allow a user to access to the https://tools.ietf.org/html/rfc4616#section-2[impersonation command],
-acting on the behalf of any user.
-
-| verifyFailureDelay
-| Delay after a failed authentication attempt with an invalid user name or password. Duration string defaulting to seconds, e.g. `2`, `2s`, `2000ms`. Default `0s` (disabled).
-
-| algorithm
-| use a specific hash algorithm to compute passwords, with optional mode `plain` (default) or `salted`; e.g. `SHA-512`, `SHA-512/plain`, `SHA-512/salted`, `PBKDF2`, `PBKDF2-SHA512` (default).
-Note: When using `PBKDF2` or `PBKDF2-SHA512` one can specify the iteration count and the key size in bytes. You can specify it as part of the algorithm. EG: `PBKDF2-SHA512-2000-512` will use
-2000 iterations with a key size of 512 bytes.
-
-| hashingMode
-| specify the hashing mode to use if there is none recorded in the database: `plain` (default) for newer installations or `legacy` for older ones
-
-|===
-
-== Configuring a LDAP
-
-Alternatively you can authenticate your users against a LDAP server. You need to configure
-the properties for accessing your LDAP server in this file.
-
-Consult this link:https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration/usersrepository.xml[example]
-to get some examples and hints.
-
-Example:
-
-....
-
- true
-
-....
-
-SSL can be enabled by using `ldaps` scheme. `trustAllCerts` option can be used to trust all LDAP client certificates
-(optional, defaults to false).
-
-Example:
-
-....
-
- true
-
-....
-
-Moreover, per domain base DN can be configured:
-
-....
-true
-
- ou=People,o=other.com,ou=system
-
-
-....
-
-You can connect to multiple LDAP servers for better availability by using `ldapHosts` option (fallback to `ldapHost` is supported) to specify the list of LDAP Server URL with the comma `,` delimiter. We do support different schemas for LDAP servers.
-
-Example:
-
-....
-
- true
-
-....
-
-When VirtualHosting is on, you can enable local part as login username by configure the `resolveLocalPartAttribute`.
-This is the LDAP attribute that allows to retrieve the local part of users. Optional, default to empty, which disables login with local part as username.
-
-Example:
-
-....
-
- true
-
-....
-
-The "userListBase" configuration option is used to differentiate users that can login from those that are listed
- as regular users. This is useful for dis-activating users, for instance.
-
-A different values from "userBase" can be used for setting up virtual logins,
-for instance in conjunction with "resolveLocalPartAttribute". This can also be used to manage
-disactivated users (in "userListBase" but not in "userBase").
-
-Note that "userListBase" can not be specified on a per-domain-basis.
-
-=== LDAP connection pool size tuning
-
-Apache James offers some options for configuring the LDAP connection pool used by unboundid:
-
-* *poolSize*: (optional, default = 4) The maximum number of connection in the pool. Note that if the pool is exhausted,
-extra connections will be created on the fly as needed.
-* *maxWaitTime*: (optional, default = 1000) the number of milli seconds to wait before creating off-pool connections,
-using a pool connection if released in time. This effectively smooth out traffic burst, thus in some case can help
-not overloading the LDAP
-* *connectionTimeout:* (optional) Sets the connection timeout on the underlying to the specified integer value
-* *readTimeout:* (optional) Sets property the read timeout to the specified integer value.
\ No newline at end of file
+:sample-configuration-prefix-url: https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration
+include::partial$configure/usersrepository.adoc[]
\ No newline at end of file
diff --git a/docs/modules/servers/pages/distributed/configure/vault.adoc b/docs/modules/servers/pages/distributed/configure/vault.adoc
index 2f7a4836a8d..97ee4a32476 100644
--- a/docs/modules/servers/pages/distributed/configure/vault.adoc
+++ b/docs/modules/servers/pages/distributed/configure/vault.adoc
@@ -1,38 +1,8 @@
= Distributed James Server — deletedMessageVault.properties
:navtitle: deletedMessageVault.properties
-Deleted Messages Vault is the component in charge of retaining messages before they are going to be deleted.
-Messages stored in the Deleted Messages Vault could be deleted after exceeding their retentionPeriod (explained below).
-It also supports to restore or export messages matching with defined criteria in
-xref:distributed/operate/webadmin.adoc#_deleted_messages_vault[WebAdmin deleted messages vault document] by using
-xref:distributed/operate/webadmin.adoc#_deleted_messages_vault[WebAdmin endpoints].
-
-== Deleted Messages Vault Configuration
-
-Once the vault is active, James will start moving deleted messages to it asynchronously.
-
-The Deleted Messages Vault also stores and manages deleted messages into a BlobStore. The BlobStore can be either
-based on an object storage or on Cassandra. For configuring the BlobStore the vault will use, you can look at
-xref:distributed/configure/blobstore.adoc[*blobstore.properties*] BlobStore Configuration section.
-
-== deletedMessageVault.properties
-
-Consult this link:https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration/deletedMessageVault.properties[example]
-to get some examples and hints.
-
-.deletedMessageVault.properties content
-|===
-| Property name | explanation
-
-| enabled
-| Allows to enable or disable usage of the Deleted Message Vault. Default to false.
-
-| workQueueEnabled
-| Enable work queue to be used with deleted message vault. Default to false.
-
-| retentionPeriod
-| Deleted messages stored in the Deleted Messages Vault are expired after this period (default: 1 year). It can be expressed in *y* years, *d* days, *h* hours, ...
-
-| restoreLocation
-| Messages restored from the Deleted Messages Vault are placed in a mailbox with this name (default: ``Restored-Messages``). The mailbox will be created if it does not exist yet.
-|===
+:sample-configuration-prefix-url: https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration
+:pages-path: distributed
+:server-name: Distributed James Server
+:backend-name: Cassandra
+include::partial$configure/vault.adoc[]
\ No newline at end of file
diff --git a/docs/modules/servers/pages/distributed/configure/webadmin.adoc b/docs/modules/servers/pages/distributed/configure/webadmin.adoc
index 767f4fca47b..13393213f99 100644
--- a/docs/modules/servers/pages/distributed/configure/webadmin.adoc
+++ b/docs/modules/servers/pages/distributed/configure/webadmin.adoc
@@ -1,100 +1,7 @@
= Distributed James Server — webadmin.properties
:navtitle: webadmin.properties
-The web administration supports for now the CRUD operations on the domains, the users, their mailboxes and their quotas,
-managing mail repositories, performing cassandra migrations, and much more, as described in the following sections.
-
-*WARNING*: This API allows authentication only via the use of JWT. If not
-configured with JWT, an administrator should ensure an attacker can not
-use this API.
-
-By the way, some endpoints are not filtered by authentication. Those endpoints are not related to data stored in James,
-for example: Swagger documentation & James health checks.
-
-== Configuration
-
-Consult this link:https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration/webadmin.properties[example]
-to get some examples and hints.
-
-.webadmin.properties content
-|===
-| Property name | explanation
-
-| enabled
-| Define if WebAdmin is launched (default: false)
-
-| port
-| Define WebAdmin's port (default: 8080)
-
-| host
-| Define WebAdmin's host (default: localhost, use 0.0.0.0 to listen on all addresses)
-
-| cors.enable
-| Allow the Cross-origin resource sharing (default: false)
-
-| cors.origin
-| Specify ths CORS origin (default: null)
-
-| jwt.enable
-| Allow JSON Web Token as an authentication mechanism (default: false)
-
-| https.enable
-| Use https (default: false)
-
-| https.keystore
-| Specify a keystore file for https (default: null)
-
-| https.password
-| Specify the keystore password (default: null)
-
-| https.trust.keystore
-| Specify a truststore file for https (default: null)
-
-| https.trust.password
-| Specify the truststore password (default: null)
-
-| jwt.publickeypem.url
-| Optional. JWT tokens allow request to bypass authentication. Path to the JWT public key.
-Defaults to the `jwt.publickeypem.url` value of `jmap.properties` file if unspecified
-(legacy behaviour)
-
-| extensions.routes
-| List of Routes specified as fully qualified class name that should be loaded in addition to your product routes list. Routes
-needs to be on the classpath or in the ./extensions-jars folder. Read mode about
-xref:customization:webadmin-routes.adoc[creating you own webadmin routes].
-
-| maxThreadCount
-| Maximum threads used by the underlying Jetty server. Optional.
-
-| minThreadCount
-| Minimum threads used by the underlying Jetty server. Optional.
-
-|===
-
-== Generating a JWT key pair
-
-The Distributed server enforces the use of RSA-SHA-256.
-
-One can use OpenSSL to generate a JWT key pair :
-
- # private key
- openssl genrsa -out rs256-4096-private.rsa 4096
- # public key
- openssl rsa -in rs256-4096-private.rsa -pubout > rs256-4096-public.pem
-
-The private key can be used to generate JWT tokens, for instance
-using link:https://github.com/vandium-io/jwtgen[jwtgen]:
-
- jwtgen -a RS256 -p rs256-4096-private.rsa 4096 -c "sub=bob@domain.tld" -c "admin=true" -e 3600 -V
-
-This token can then be passed as `Bearer` of the `Authorization` header :
-
- curl -H "Authorization: Bearer $token" -XGET http://127.0.0.1:8000/domains
-
-The public key can be referenced as `jwt.publickeypem.url` of the `jmap.properties` configuration file.
-
-== Reverse-proxy set up
-
-WebAdmin adds the value of `X-Real-IP` header as part of the logging MDC.
-
-This allows for reverse proxies to cary other the IP address of the client down to the JMAP server for diagnostic purpose.
+:sample-configuration-prefix-url: https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration
+:pages-path: distributed
+:server-name: Distributed James Server
+include::partial$configure/webadmin.adoc[]
\ No newline at end of file
diff --git a/docs/modules/servers/partials/configure/batchsizes.adoc b/docs/modules/servers/partials/configure/batchsizes.adoc
new file mode 100644
index 00000000000..6e123c9f90b
--- /dev/null
+++ b/docs/modules/servers/partials/configure/batchsizes.adoc
@@ -0,0 +1,31 @@
+This files allow to define the amount of data that should be fetched 'at once' when interacting with the mailbox. This is
+needed as IMAP can generate some potentially large requests.
+
+Increasing these values tend to fasten individual requests, at the cost of enabling potential higher load.
+
+Consult this link:{sample-configuration-prefix-url}/batchsizes.properties[example]
+to get some examples and hints.
+
+.batchsizes.properties content
+|===
+| Property name | explanation
+
+| fetch.metadata
+| Optional, defaults to 200. How many messages should be read in a batch when using FetchType.MetaData
+
+| fetch.headers
+| Optional, defaults to 200. How many messages should be read in a batch when using FetchType.Header
+
+| fetch.body
+| Optional, defaults to 100. How many messages should be read in a batch when using FetchType.Body
+
+| fetch.full
+| Optional, defaults to 50. How many messages should be read in a batch when using FetchType.Full
+
+| copy
+| Optional, defaults to 200. How many messages should be copied in a batch.
+
+| move
+| Optional, defaults to 200. How many messages should be moved in a batch.
+
+|===
\ No newline at end of file
diff --git a/docs/modules/servers/partials/configure/blobstore.adoc b/docs/modules/servers/partials/configure/blobstore.adoc
new file mode 100644
index 00000000000..e928386bbbe
--- /dev/null
+++ b/docs/modules/servers/partials/configure/blobstore.adoc
@@ -0,0 +1,173 @@
+
+=== Encryption choice
+
+Data can be optionally encrypted with a symmetric key using AES before being stored in the blobStore. As many user relies
+on third party for object storage, a compromised third party will not escalate to a data disclosure. Of course, a
+performance price have to be paid, as encryption takes resources.
+
+*encryption.aes.enable* : Optional boolean, defaults to false.
+
+If AES encryption is enabled, then the following properties MUST be present:
+
+ - *encryption.aes.password* : String
+ - *encryption.aes.salt* : Hexadecimal string
+
+The following properties CAN be supplied:
+
+ - *encryption.aes.private.key.algorithm* : String, defaulting to PBKDF2WithHmacSHA512. Previously was
+PBKDF2WithHmacSHA1.
+
+WARNING: Once chosen this choice can not be reverted, all the data is either clear or encrypted. Mixed encryption
+is not supported.
+
+Here is an example of how you can generate the above values (be mindful to customize the byte lengths in order to add
+enough entropy.
+
+....
+# Password generation
+openssl rand -base64 64
+
+# Salt generation
+generate salt with : openssl rand -hex 16
+....
+
+AES blob store supports the following system properties that could be configured in `jvm.properties`:
+
+....
+# Threshold from which we should buffer the blob to a file upon encrypting
+# Unit supported: K, M, G, default to no unit
+james.blob.aes.file.threshold.encrypt=100K
+
+# Threshold from which we should buffer the blob to a file upon decrypting
+# Unit supported: K, M, G, default to no unit
+james.blob.aes.file.threshold.decrypt=256K
+
+# Maximum size of a blob. Larger blobs will be rejected.
+# Unit supported: K, M, G, default to no unit
+james.blob.aes.blob.max.size=100M
+....
+
+=== Object storage configuration
+
+==== AWS S3 Configuration
+
+.blobstore.properties S3 related properties
+|===
+| Property name | explanation
+
+| objectstorage.s3.endPoint
+| S3 service endpoint
+
+| objectstorage.s3.region
+| S3 region
+
+| objectstorage.s3.accessKeyId
+| https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys[S3 access key id]
+
+| objectstorage.s3.secretKey
+| https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys[S3 access key secret]
+
+| objectstorage.s3.http.concurrency
+| Allow setting the number of concurrent HTTP requests allowed by the Netty driver.
+
+| objectstorage.s3.truststore.path
+| optional: Verify the S3 server certificate against this trust store file.
+
+| objectstorage.s3.truststore.type
+| optional: Specify the type of the trust store, e.g. JKS, PKCS12
+
+| objectstorage.s3.truststore.secret
+| optional: Use this secret/password to access the trust store; default none
+
+| objectstorage.s3.truststore.algorithm
+| optional: Use this specific trust store algorithm; default SunX509
+
+| objectstorage.s3.trustall
+| optional: boolean. Defaults to false. Cannot be set to true with other trustore options. Wether James should validate
+S3 endpoint SSL certificates.
+
+| objectstorage.s3.read.timeout
+| optional: HTTP read timeout. duration, default value being second. Leaving it empty relies on S3 driver defaults.
+
+| objectstorage.s3.write.timeout
+| optional: HTTP write timeout. duration, default value being second. Leaving it empty relies on S3 driver defaults.
+
+| objectstorage.s3.connection.timeout
+| optional: HTTP connection timeout. duration, default value being second. Leaving it empty relies on S3 driver defaults.
+
+| objectstorage.s3.in.read.limit
+| optional: Object read in memory will be rejected if they exceed the size limit exposed here. Size, exemple `100M`.
+Supported units: K, M, G, defaults to B if no unit is specified. If unspecified, big object won't be prevented
+from being loaded in memory. This settings complements protocol limits.
+
+| objectstorage.s3.upload.retry.maxAttempts
+| optional: Integer. Default is zero. This property specifies the maximum number of retry attempts allowed for failed upload operations.
+
+| objectstorage.s3.upload.retry.backoffDurationMillis
+| optional: Long (Milliseconds). Default is 10 (miliseconds).
+Only takes effect when the "objectstorage.s3.upload.retry.maxAttempts" property is declared.
+This property determines the duration (in milliseconds) to wait between retry attempts for failed upload operations.
+This delay is known as backoff. The jitter factor is 0.5
+
+|===
+
+==== Buckets Configuration
+
+.Bucket configuration
+|===
+| Property name | explanation
+
+| objectstorage.bucketPrefix
+| Bucket is a concept in James and similar to Containers in Swift or Buckets in AWS S3.
+BucketPrefix is the prefix of bucket names in James BlobStore
+
+| objectstorage.namespace
+| BlobStore default bucket name. Most of blobs storing in BlobStore are inside the default bucket.
+Unless a special case like storing blobs of deleted messages.
+|===
+
+== Blob Export
+
+Blob Exporting is the mechanism to help James to export a blob from an user to another user.
+It is commonly used to export deleted messages (consult configuring deleted messages vault).
+The deleted messages are transformed into a blob and James will export that blob to the target user.
+
+This configuration helps you choose the blob exporting mechanism fit with your James setup and it is only applicable with Guice products.
+
+Consult {sample-configuration-prefix-url}/blob.properties[blob.properties]
+in GIT to get some examples and hints.
+
+Configuration for exporting blob content:
+
+.blobstore.properties content
+|===
+| blob.export.implementation
+
+| localFile: Local File Exporting Mechanism (explained below). Default: localFile
+
+| linshare: LinShare Exporting Mechanism (explained below)
+|===
+
+=== Local File Blob Export Configuration
+
+For each request, this mechanism retrieves the content of a blob and save it to a distinct local file, then send an email containing the absolute path of that file to the target mail address.
+
+Note: that absolute file path is the file location on James server. Therefore, if there are two or more James servers connected, it should not be considered an option.
+
+*blob.export.localFile.directory*: The directory URL to store exported blob data in files, and the URL following
+http://james.apache.org/server/3/apidocs/org/apache/james/filesystem/api/FileSystem.html[James File System scheme].
+Default: file://var/blobExporting
+
+=== LinShare Blob Export Configuration
+
+Instead of exporting blobs in local file system, using https://www.linshare.org[LinShare]
+helps you upload your blobs and people you have been shared to can access those blobs by accessing to
+LinShare server and download them.
+
+This way helps you to share via whole network as long as they can access to LinShare server.
+
+To get an example or details explained, visit {sample-configuration-prefix-url}/blob.properties[blob.properties]
+
+*blob.export.linshare.url*: The URL to connect to LinShare
+
+*blob.export.linshare.token*: The authentication token to connect to LinShare
diff --git a/docs/modules/servers/partials/configure/collecting-contacts.adoc b/docs/modules/servers/partials/configure/collecting-contacts.adoc
new file mode 100644
index 00000000000..ed103124559
--- /dev/null
+++ b/docs/modules/servers/partials/configure/collecting-contacts.adoc
@@ -0,0 +1,38 @@
+== Motivation
+
+Many modern applications combines email and contacts.
+
+We want recipients of emails sent by a user to automatically be added to this user contacts, for convenience. This
+should even be performed when a user sends emails via SMTP for example using thunderbird.
+
+== Design
+
+The idea is to send AMQP messages holding information about mail envelope for a traitment via a tierce application.
+
+== Configuration
+
+We can achieve this goal by combining simple mailets building blocks.
+
+Here is a sample pipeline achieving aforementioned objectives :
+
+[source,xml]
+....
+
+ extractedContacts
+
+
+ amqp://${env:JAMES_AMQP_USERNAME}:${env:JAMES_AMQP_PASSWORD}@${env:JAMES_AMQP_HOST}:${env:JAMES_AMQP_PORT}
+ collector:email
+ extractedContacts
+
+
+....
+
+A sample message looks like:
+
+....
+{
+ "userEmail": "sender@james.org",
+ "emails": ["to@james.org"]
+}
+....
\ No newline at end of file
diff --git a/docs/modules/servers/partials/configure/collecting-events.adoc b/docs/modules/servers/partials/configure/collecting-events.adoc
new file mode 100644
index 00000000000..4a3ee1f87d0
--- /dev/null
+++ b/docs/modules/servers/partials/configure/collecting-events.adoc
@@ -0,0 +1,68 @@
+== Motivation
+
+Many calendar application do add events invitation received by email directly in ones calendar.
+
+Such behaviours requires the calendar application to be aware of the ICalendar related emails a user received.
+
+== Design
+
+The idea is to write a portion of mailet pipeline extracting Icalendar attachments and to hold them as attachments that
+can later be sent to other applications over AMQP to be treated in an asynchronous, decoupled fashion.
+
+== Configuration
+
+We can achieve this goal by combining simple mailets building blocks.
+
+Here is a sample pipeline achieving aforementioned objectives :
+
+[source,xml]
+....
+
+
+ text/calendar
+ rawIcalendar
+
+
+ rawIcalendar
+
+
+ rawIcalendar
+ icalendar
+
+
+ icalendar
+
+
+
+ icalendarAsJson
+ rawIcalendar
+
+
+ amqp://${env:JAMES_AMQP_USERNAME}:${env:JAMES_AMQP_PASSWORD}@${env:JAMES_AMQP_HOST}:${env:JAMES_AMQP_PORT}
+ james:events
+ icalendarAsJson
+
+
+....
+
+A sample message looks like:
+
+....
+{
+ "ical": "RAW_DATA_AS_TEXT_FOLLOWING_ICS_FORMAT",
+ "sender": "other@james.apache.org",
+ "recipient": "any@james2.apache.org",
+ "replyTo": "other@james.apache.org",
+ "uid": "f1514f44bf39311568d640727cff54e819573448d09d2e5677987ff29caa01a9e047feb2aab16e43439a608f28671ab7c10e754ce92be513f8e04ae9ff15e65a9819cf285a6962bc",
+ "dtstamp": "20170106T115036Z",
+ "method": "REQUEST",
+ "sequence": "0",
+ "recurrence-id": null
+}
+....
+
+The following pipeline positions the X-MEETING-UID in the Header in order for mail user agent to correlate events with this mail.
+The sample look like:
+```
+X-MEETING-UID: f1514f44bf39311568d640727cff54e819573448d09d2e5677987ff29caa01a9e047feb2aab16e43439a608f28671ab7c10e754ce92be513f8e04ae9ff15e65a9819cf285a6962bc
+```
\ No newline at end of file
diff --git a/docs/modules/servers/partials/configure/dns.adoc b/docs/modules/servers/partials/configure/dns.adoc
new file mode 100644
index 00000000000..e61491f20e5
--- /dev/null
+++ b/docs/modules/servers/partials/configure/dns.adoc
@@ -0,0 +1,52 @@
+Consult this link:{sample-configuration-prefix-url}/dnsservice.xml[example]
+to get some examples and hints.
+
+Specifies DNS Server information for use by various components inside Apache James Server.
+
+DNS Transport services are controlled by a configuration block in
+the dnsservice.xml. This block affects SMTP remote delivery.
+
+The dnsservice tag defines the boundaries of the configuration
+block. It encloses all the relevant configuration for the DNS server.
+The behavior of the DNS service is controlled by the attributes and
+children of this tag.
+
+.dnsservice.xml content
+|===
+| Property name | explanation
+
+| servers
+| Information includes a list of DNS Servers to be used by James. These are
+specified by the server elements, each of which is a child element of the
+servers element. Each server element is the IP address of a single DNS server.
+The server elements can have multiple server children. Enter ip address of your DNS server, one IP address per server
+element. If no DNS servers are found and you have not specified any below, 127.0.0.1 will be used
+
+| autodiscover
+| true or false - If you use autodiscover and add DNS servers manually a combination of all the DNS servers will be used.
+If autodiscover is true, James will attempt to autodiscover the DNS servers configured on your underlying system.
+Currently, this works if the OS has a unix-like /etc/resolv.xml,
+or the system is Windows based with ipconfig or winipcfg. Change autodiscover to false if you would like to turn off autodiscovery
+and set the DNS servers manually in the servers section
+
+| authoritative
+| *true/false* - This tag specifies whether or not
+to require authoritative (non-cached) DNS records; to only accept DNS responses that are
+authoritative for the domain. It is primarily useful in an intranet/extranet environment.
+This should always be *false* unless you understand the implications.
+
+| maxcachesize
+| Maximum number of entries to maintain in the DNS cache (typically 50000)
+
+| negativeCacheTTL
+| Sets the maximum length of time that negative records will be stored in the DNS negative cache in
+seconds (a negative record means the name has not been found in the DNS). Values for this cache
+can be positive meaning the time in seconds before retrying to resolve the name, zero meaning no
+cache or a negative value meaning infinite caching.
+
+| singleIPperMX
+| true or false (default) - Specifies if Apache James Server must try a single server for each multihomed mx host
+
+| verbose
+| Turn on general debugging statements
+|===
diff --git a/docs/modules/servers/partials/configure/domainlist.adoc b/docs/modules/servers/partials/configure/domainlist.adoc
new file mode 100644
index 00000000000..bd693f7094b
--- /dev/null
+++ b/docs/modules/servers/partials/configure/domainlist.adoc
@@ -0,0 +1,42 @@
+Consult this link:{sample-configuration-prefix-url}/domainlist.xml[example]
+to get some examples and hints.
+
+This configuration block is defined by the *domainlist* tag.
+
+.domainlist.xml content
+|===
+| Property name | explanation
+
+| domainnames
+| Domainnames identifies the DNS namespace served by this instance of James.
+These domainnames are used for both matcher/mailet processing and SMTP auth
+to determine when a mail is intended for local delivery - Only applicable for XMLDomainList. The entries mentionned here will be created upon start.
+
+|autodetect
+|true or false - If autodetect is true, James wil attempt to discover its own host name AND
+use any explicitly specified servernames.
+If autodetect is false, James will use only the specified domainnames. Defaults to false.
+
+|autodetectIP
+|true or false - If autodetectIP is not false, James will also allow add the IP address for each servername.
+The automatic IP detection is to support RFC 2821, Sec 4.1.3, address literals. Defaults to false.
+
+|defaultDomain
+|Set the default domain which will be used if an email is send to a recipient without a domain part.
+If no defaultdomain is set the first domain of the DomainList gets used. If the default is not yet contained by the Domain List, the domain will be created upon start.
+
+|read.cache.enable
+|Experimental. Boolean, defaults to false.
+Whether or not to cache domainlist.contains calls. Enable a faster execution however writes will take time
+to propagate.
+
+|read.cache.expiracy
+|Experimental. String (duration), defaults to 10 seconds (10s). Supported units are ms, s, m, h, d, w, month, y.
+Expiracy of the cache. Longer means less reads are performed to the backend but writes will take longer to propagate.
+Low values (a few seconds) are advised.
+
+
+|===
+
+To override autodetected domainnames simply add explicit domainname elements.
+In most cases this will be necessary. By default, the domainname 'localhost' is specified. This can be removed, if required.
diff --git a/docs/modules/servers/partials/configure/droplists.adoc b/docs/modules/servers/partials/configure/droplists.adoc
new file mode 100644
index 00000000000..f08ae18a9b7
--- /dev/null
+++ b/docs/modules/servers/partials/configure/droplists.adoc
@@ -0,0 +1,30 @@
+The DropList, also known as the mail blacklist, is a collection of
+domains and email addresses that are denied from sending emails within the system.
+It is disabled by default.
+To enable it, modify the `droplists.properties` file and include the `IsInDropList` matcher in the `mailetcontainer.xml`.
+To disable it, adjust the `droplists.properties` file and remove the `IsInDropList` matcher from the `mailetcontainer.xml`.
+
+.droplists.properties content
+|===
+| Property name | explanation
+
+| enabled
+| Boolean. Governs whether DropLists should be enabled. Defaults to `false`.
+|===
+
+== Enabling Matcher
+
+Plug the `IsInDropList` matcher within `mailetcontainer.xml` :
+
+[source,xml]
+....
+
+ transport
+
+....
+
+== DropList management
+
+DropList management, including adding and deleting entries, is performed through the WebAdmin REST API.
+
+See xref:{pages-path}/operate/webadmin.adoc#_administrating_droplists[WebAdmin DropLists].
\ No newline at end of file
diff --git a/docs/modules/servers/partials/configure/dsn.adoc b/docs/modules/servers/partials/configure/dsn.adoc
new file mode 100644
index 00000000000..9ff0cfb3f72
--- /dev/null
+++ b/docs/modules/servers/partials/configure/dsn.adoc
@@ -0,0 +1,217 @@
+DSN introduced in link:https://tools.ietf.org/html/rfc3461[RFC-3461] allows a SMTP sender to demand status messages,
+defined in link:https://tools.ietf.org/html/rfc3464[RFC-3464] to be sent back to the `Return-Path` upon delivery
+progress.
+
+DSN support is not enabled by default, as it needs specific configuration of the
+xref:{pages-path}/configure/mailetcontainer.adoc[mailetcontainer.xml] to be specification compliant.
+
+To enable it you need to:
+
+- Add DSN SMTP hooks as part of the SMTP server stack
+- Configure xref:{pages-path}/configure/mailetcontainer.adoc[mailetcontainer.xml] to generate DSN bounces when needed
+
+== Enabling DSN in SMTP server stack
+
+For this simply add the `DSN hooks` in the handler chain in `smtpserver.xml` :
+
+[source,xml]
+....
+
+ <...>
+
+
+
+
+
+ <...>
+
+
+
+....
+
+== Enabling DSN generation as part of mail processing
+
+For the below conditions to be matched we assume you follow
+xref:{pages-path}/configure/remote-delivery-error-handling.adoc[RemoteDelivery error handling for MXs], which is a
+requirement for detailed RemoteDelivery error and delay handling on top of the {server-name}.
+
+Here is a sample xref:{pages-path}/configure/mailetcontainer.adoc[mailetcontainer.xml] achieving the following DSN generation:
+
+- Generate a generic `delivered` notification if LocalDelivery succeeded, if requested
+- Generate a generic `failed` notification in case of local errors, if requested
+- Generate a specific `failed` notification in case of a non existing local user, if requested
+- Generate a specific `failed` notification in case of an address rewriting loop, if requested
+- Generate a `failed` notification in case of remote permanent errors, if requested. We blame the remote server...
+- Generate a `delayed` notification in case of temporary remote errors we are about to retry, if requested. We blame the remote server...
+- Generate a `failed` notification in case of temporary remote errors we are not going to retry (failed too many time), if requested. We blame the remote server...
+
+[subs=attributes+,xml]
+----
+
+
+
+
+ \
+
+
+
+
+
+
+
+
+
+ [FAILED]
+ true
+ Hi. This is the James mail server at [machine].
+I'm afraid I wasn't able to deliver your message to the following addresses.
+This is a permanent error; I've given up. Sorry it didn't work out. Below
+I include the list of recipients, and the reason why I was unable to deliver
+your message.
+ failed
+ 5.0.0
+
+
+ {mailet-repository-path-prefix}://var/mail/error/
+
+
+
+
+
+
+
+ false
+
+
+
+ [SUCCESS]
+ true
+ Hi. This is the James mail server at [machine].
+I successfully delivered your message to the following addresses.
+Note that it indicates your recipients received the message but do
+not imply they read it.
+ delivered
+ 2.0.0
+
+
+
+
+
+
+
+ outgoing
+ 0
+ 0
+ 10
+ true
+
+ remote-delivery-error
+
+
+
+ [FAILED]
+ true
+ Hi. This is the James mail server at [machine].
+I'm afraid I wasn't able to deliver your message to the following addresses.
+This is a permanent error; I've given up. Sorry it didn't work out.
+The remote server we should relay this mail to keep on failing.
+Below I include the list of recipients, and the reason why I was unable to deliver
+your message.
+ failed
+ 5.0.0
+
+
+ {mailet-repository-path-prefix}://var/mail/error/remote-delivery/permanent/
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ [FAILED]
+ true
+ Hi. This is the James mail server at [machine].
+I'm afraid I wasn't able to deliver your message to the following addresses.
+This is a permanent error; I've given up. Sorry it didn't work out.
+The remote server we should relay this mail to returns a permanent error.
+Below I include the list of recipients, and the reason why I was unable to deliver
+your message.
+ failed
+ 5.0.0
+
+
+
+ [DELAYED]
+ true
+ Hi. This is the James mail server at [machine].
+I'm afraid I wasn't able to deliver your message to the following addresses yet.
+This is a temporary error: I will keep on trying.
+Below I include the list of recipients, and the reason why I was unable to deliver
+your message.
+ delayed
+ 4.0.0
+
+
+
+
+
+
+
+ [FAILED]
+ true
+ Hi. This is the James mail server at [machine].
+I'm afraid I wasn't able to deliver your message to the following addresses.
+This is a permanent error; I've given up. Sorry it didn't work out.
+The following addresses do not exist here. Sorry.
+ failed
+ 5.0.0
+
+
+ {mailet-repository-path-prefix}://var/mail/address-error/
+
+
+
+
+
+
+ {mailet-repository-path-prefix}://var/mail/relay-denied/
+ Warning: You are sending an e-mail to a remote server. You must be authenticated to perform such an operation
+
+
+
+
+
+ {mailet-repository-path-prefix}://var/mail/rrt-error/
+ true
+
+
+
+ [FAILED]
+ true
+ Hi. This is the James mail server at [machine].
+I'm afraid I wasn't able to deliver your message to the following addresses.
+This is a permanent error; I've given up. Sorry it didn't work out.
+The following addresses is caught in a rewriting loop. An admin should come and fix it (you likely want to report it).
+Once resolved the admin should be able to resume the processing of your email.
+Below I include the list of recipients, and the reason why I was unable to deliver
+your message.
+ failed
+ 5.1.6
+
+
+
+
+----
+
+== Limitations
+
+The out of the box tooling do not allow generating `relayed` DSN notification as RemoteDelivery misses a success
+callback.
\ No newline at end of file
diff --git a/docs/modules/servers/partials/configure/extensions.adoc b/docs/modules/servers/partials/configure/extensions.adoc
new file mode 100644
index 00000000000..6c2ae7cbaa9
--- /dev/null
+++ b/docs/modules/servers/partials/configure/extensions.adoc
@@ -0,0 +1,60 @@
+This files enables an operator to define additional bindings used to instantiate others extensions
+
+*guice.extension.module*: come separated list of fully qualified class name. These classes need to implement Guice modules.
+
+Here is an example of such a class :
+
+[source,java]
+....
+public class MyServiceModule extends AbstractModule {
+ @Override
+ protected void configure() {
+ bind(MyServiceImpl.class).in(Scopes.SINGLETON);
+ bind(MyService.class).to(MyServiceImpl.class);
+ }
+}
+....
+
+Recording it in extensions.properties :
+
+....
+guice.extension.module=com.project.MyServiceModule
+....
+
+Enables to inject MyService into your extensions.
+
+
+*guice.extension.tasks*: come separated list of fully qualified class name.
+
+The extension can rely on the Task manager to supervise long-running task execution (progress, await, cancellation, scheduling...).
+These extensions need to implement Task extension modules.
+
+Here is an example of such a class :
+
+[source,java]
+....
+public class RspamdTaskExtensionModule implements TaskExtensionModule {
+
+ @Inject
+ public RspamdTaskExtensionModule() {
+ }
+
+ @Override
+ public Set> taskDTOModules() {
+ return Set.of(...);
+ }
+
+ @Override
+ public Set> taskAdditionalInformationDTOModules() {
+ return Set.of(...);
+ }
+}
+....
+
+Recording it in extensions.properties :
+
+....
+guice.extension.tasks=com.project.RspamdTaskExtensionModule
+....
+
+Read xref:{pages-path}/extending/index.adoc#_defining_custom_injections_for_your_extensions[this page] for more details.
\ No newline at end of file
diff --git a/docs/modules/servers/partials/configure/forCoreComponentsPartial.adoc b/docs/modules/servers/partials/configure/forCoreComponentsPartial.adoc
new file mode 100644
index 00000000000..2ea8a961022
--- /dev/null
+++ b/docs/modules/servers/partials/configure/forCoreComponentsPartial.adoc
@@ -0,0 +1,15 @@
+== For core components
+
+By omitting these files, sane default values are used.
+
+** xref:{xref-base}/batchsizes.adoc[*batchsizes.properties*] allows to configure mailbox read batch sizes link:{sample-configuration-prefix-url}/sample-configuration/batchsizes.properties[example]
+** xref:{xref-base}/dns.adoc[*dnsservice.xml*] allows to configure DNS resolution link:{sample-configuration-prefix-url}/sample-configuration/dnsservice.xml[example]
+** xref:{xref-base}/domainlist.adoc[*domainlist.xml*] allows to configure Domain storage link:{sample-configuration-prefix-url}/sample-configuration/domainlist.xml[example]
+** xref:{xref-base}/healthcheck.adoc[*healthcheck.properties*] allows to configure periodical healthchecks link:{sample-configuration-prefix-url}/sample-configuration/healthcheck.properties[example]
+** xref:{xref-base}/mailetcontainer.adoc[*mailetcontainer.xml*] allows configuring mail processing link:{sample-configuration-prefix-url}/sample-configuration/mailetcontainer.xml[example]
+*** xref:{xref-base}/mailets.adoc[This page] list matchers that can be used out of the box with the {server-name}.
+*** xref:{xref-base}/matchers.adoc[This page] list matchers that can be used out of the box with the {server-name}.
+** xref:{xref-base}/mailrepositorystore.adoc[*mailrepositorystore.xml*] enables registration of allowed MailRepository protcols and link them to MailRepository implementations link:{sample-configuration-prefix-url}/sample-configuration/mailrepositorystore.xml[example]
+** xref:{xref-base}/recipientrewritetable.adoc[*recipientrewritetable.xml*] enables advanced configuration for the Recipient Rewrite Table component link:{sample-configuration-prefix-url}/sample-configuration/recipientrewritetable.xml[example]
+*** xref:{xref-base}/matchers.adoc[This page] allows choosing the indexing technology.
+** xref:{xref-base}/usersrepository.adoc[*usersrepository.xml*] allows configuration of user storage link:{sample-configuration-prefix-url}/sample-configuration/usersrepository.xml[example]
diff --git a/docs/modules/servers/partials/configure/forExtensionsPartial.adoc b/docs/modules/servers/partials/configure/forExtensionsPartial.adoc
new file mode 100644
index 00000000000..49720b50432
--- /dev/null
+++ b/docs/modules/servers/partials/configure/forExtensionsPartial.adoc
@@ -0,0 +1,14 @@
+== For extensions
+
+By omitting these files, no extra behaviour is added.
+
+** xref:{xref-base}/vault.adoc[*deletedMessageVault.properties*] allows to configure the DeletedMessageVault link:{sample-configuration-prefix-url}/sample-configuration/deletedMessageVault.properties[example]
+** xref:{xref-base}/listeners.adoc[*listeners.xml*] enables configuration of Mailbox Listeners link:{sample-configuration-prefix-url}/sample-configuration/listeners.xml[example]
+** xref:{xref-base}/extensions.adoc[*extensions.properties*] allows to extend James behaviour by loading your extensions in it link:{sample-configuration-prefix-url}/sample-configuration/extensions.properties[example]
+** xref:{xref-base}/jvm.adoc[*jvm.properties*] lets you specify additional system properties without cluttering your command line
+** xref:{xref-base}/spam.adoc[This page] documents Anti-Spam setup with SpamAssassin, Rspamd.
+** xref:{xref-base}/remote-delivery-error-handling.adoc[This page] proposes a simple strategy for RemoteDelivery error handling.
+** xref:{xref-base}/collecting-contacts.adoc[This page] documents contact collection
+** xref:{xref-base}/collecting-events.adoc[This page] documents event collection
+** xref:{xref-base}/dsn.adoc[This page] specified how to support SMTP Delivery Submission Notification (link:https://tools.ietf.org/html/rfc3461[RFC-3461])
+** xref:{xref-base}/droplists.adoc[This page] allows configuring drop lists.
\ No newline at end of file
diff --git a/docs/modules/servers/partials/configure/forProtocolsPartial.adoc b/docs/modules/servers/partials/configure/forProtocolsPartial.adoc
new file mode 100644
index 00000000000..0999218482c
--- /dev/null
+++ b/docs/modules/servers/partials/configure/forProtocolsPartial.adoc
@@ -0,0 +1,15 @@
+== For protocols
+
+By omitting these files, the underlying protocols will be disabled.
+
+** xref:{xref-base}/imap.adoc[*imapserver.xml*] allows configuration for the IMAP protocol link:{sample-configuration-prefix-url}imapserver.xml[example]
+** xref:{xref-base}/jmap.adoc[*jmap.properties*] allows to configure the JMAP protocol link:{sample-configuration-prefix-url}jmap.properties[example]
+** xref:{xref-base}/jmx.adoc[*jmx.properties*] allows configuration of JMX being used by the Command Line Interface link:{sample-configuration-prefix-url}jmx.properties[example]
+** xref:{xref-base}/smtp.adoc#_lmtp_configuration[*lmtpserver.xml*] allows configuring the LMTP protocol link:{sample-configuration-prefix-url}lmtpserver.xml[example]
+** *managesieveserver.xml* allows configuration for ManagedSieve (unsupported) link:{sample-configuration-prefix-url}managesieveserver.xml[example]
+** xref:{xref-base}/pop3.adoc[*pop3server.xml*] allows configuration for the POP3 protocol (experimental) link:{sample-configuration-prefix-url}pop3server.xml[example]
+** xref:{xref-base}/smtp.adoc[*smtpserver.xml*] allows configuration for the SMTP protocol link:{sample-configuration-prefix-url}smtpserver.xml[example]
+*** xref:{xref-base}/smtp-hooks.adoc[This page] list SMTP hooks that can be used out of the box with the {server-name}.
+** xref:{xref-base}/webadmin.adoc[*webadmin.properties*] enables configuration for the WebAdmin protocol link:{sample-configuration-prefix-url}webadmin.properties[example]
+** xref:{xref-base}/ssl.adoc[This page] details SSL & TLS configuration.
+** xref:{xref-base}/sieve.adoc[This page] details Sieve setup and how to enable ManageSieve.
\ No newline at end of file
diff --git a/docs/modules/servers/partials/configure/forStorageDependenciesPartial.adoc b/docs/modules/servers/partials/configure/forStorageDependenciesPartial.adoc
new file mode 100644
index 00000000000..2d498aeda1c
--- /dev/null
+++ b/docs/modules/servers/partials/configure/forStorageDependenciesPartial.adoc
@@ -0,0 +1,11 @@
+== For storage dependencies
+
+Except specific documented cases, these files are required, at least to establish a connection with the storage components.
+
+** xref:{xref-base}/blobstore.adoc[*blobstore.properties*] allows to configure the BlobStore link:{sample-configuration-prefix-url}/sample-configuration/blob.properties[example]
+
+** xref:{xref-base}/opensearch.adoc[*opensearch.properties*] allows to configure OpenSearch driver link:{sample-configuration-prefix-url}/sample-configuration/opensearch.properties[example]
+** xref:{xref-base}/rabbitmq.adoc[*rabbitmq.properties*] allows configuration for the RabbitMQ driver link:{sample-configuration-prefix-url}/sample-configuration/rabbitmq.properties[example]
+** xref:{xref-base}/redis.adoc[*redis.properties*] allows configuration for the Redis driver link:https://github.com/apache/james-project/blob/fabfdf4874da3aebb04e6fe4a7277322a395536a/server/mailet/rate-limiter-redis/redis.properties[example], that is used by optional
+distributed rate limiting component.
+** xref:{xref-base}/tika.adoc[*tika.properties*] allows configuring Tika as a backend for text extraction link:{sample-configuration-prefix-url}/sample-configuration/tika.properties[example]
\ No newline at end of file
diff --git a/docs/modules/servers/partials/configure/healthcheck.adoc b/docs/modules/servers/partials/configure/healthcheck.adoc
new file mode 100644
index 00000000000..afcb1098a85
--- /dev/null
+++ b/docs/modules/servers/partials/configure/healthcheck.adoc
@@ -0,0 +1,22 @@
+Consult this link:{sample-configuration-prefix-url}/healthcheck.properties[example]
+to get some examples and hints.
+
+Use this configuration to define the initial delay and period for the PeriodicalHealthChecks. It is only applicable with Guice products.
+
+.healthcheck.properties content
+|===
+| Property name | explanation
+
+| healthcheck.period
+| Define the period between two periodical health checks (default: 60s). Units supported are (ms - millisecond, s - second, m - minute, h - hour, d - day). Default unit is millisecond.
+
+| reception.check.user
+| User to be using for running the "mail reception" health check. The user must exist.
+If not specified, the mail reception check is a noop.
+
+| reception.check.timeout
+| Period after which mail reception is considered faulty. Defaults to one minute.
+
+| additional.healthchecks
+| List of fully qualified HealthCheck class names in addition to James' default healthchecks. Default to empty list.
+|===
\ No newline at end of file
diff --git a/docs/modules/servers/partials/configure/imap.adoc b/docs/modules/servers/partials/configure/imap.adoc
new file mode 100644
index 00000000000..05decc72200
--- /dev/null
+++ b/docs/modules/servers/partials/configure/imap.adoc
@@ -0,0 +1,179 @@
+Consult this link:{sample-configuration-prefix-url}/imapserver.xml[example]
+to get some examples and hints.
+
+The IMAP4 service is controlled by a configuration block in the imap4server.xml.
+The imap4server tag defines the boundaries of the configuration block. It encloses
+all the relevant configuration for the IMAP4 server. The behavior of the IMAP4 service is
+controlled by the attributes and children of this tag.
+
+This tag has an optional boolean attribute - *enabled* - that defines whether the service is active or not.
+The value defaults to "true" if not present.
+
+The standard children of the imapserver tag are:
+
+.imapserver.xml content
+|===
+| Property name | explanation
+
+| bind
+| Configure this to bind to a specific inetaddress. This is an optional integer value. This value is the port on which this IMAP4 server is configured
+to listen. If the tag or value is absent then the service
+will bind to all network interfaces for the machine If the tag or value is omitted, the value will default to the standard IMAP4 port
+port 143 is the well-known/IANA registered port for IMAP
+port 993 is the well-known/IANA registered port for IMAPS ie over SSL/TLS
+
+| connectionBacklog
+| Number of connection backlog of the server (maximum number of queued connection requests)
+
+| compress
+| true or false - Use or don't use COMPRESS extension. Defaults to false.
+
+| maxLineLength
+| Maximal allowed line-length before a BAD response will get returned to the client
+This should be set with caution as a to high value can make the server a target for DOS (Denial of Service)!
+
+| inMemorySizeLimit
+| Optional. Size limit before we will start to stream to a temporary file.
+Defaults to 10MB. Must be a positive integer, optionally with a unit: B, K, M, G.
+
+| literalSizeLimit
+| Optional. Maximum size of a literal (IMAP APPEND).
+Defaults to 0 (unlimited). Must be a positive integer, optionally with a unit: B, K, M, G.
+
+| plainAuthDisallowed
+| Deprecated. Should use `auth.plainAuthEnabled`, `auth.requireSSL` instead.
+Whether to enable Authentication PLAIN if the connection is not encrypted via SSL or STARTTLS. Defaults to `true`.
+
+| auth.plainAuthEnabled
+| Whether to enable Authentication PLAIN/ LOGIN command. Defaults to `true`.
+
+| auth.requireSSL
+| true or false. Defaults to `true`. Whether to require SSL to authenticate. If this is required, the IMAP server will disable authentication on unencrypted channels.
+
+| auth.oidc.oidcConfigurationURL
+| Provide OIDC url address for information to user. Only configure this when you want to authenticate IMAP server using a OIDC provider.
+
+| auth.oidc.jwksURL
+| Provide url to get OIDC's JSON Web Key Set to validate user token. Only configure this when you want to authenticate IMAP server using a OIDC provider.
+
+| auth.oidc.claim
+| Claim string uses to identify user. E.g: "email_address". Only configure this when you want to authenticate IMAP server using a OIDC provider.
+
+| auth.oidc.scope
+| An OAuth scope that is valid to access the service (RF: RFC7628). Only configure this when you want to authenticate IMAP server using a OIDC provider.
+
+| timeout
+| Default to 30 minutes. After this time, inactive channels that have not performed read, write, or both operation for a while
+will be closed. Negative value disable this behaviour.
+
+| enableIdle
+| Default to true. If enabled IDLE commands will generate a server heartbeat on a regular period.
+
+| idleTimeInterval
+| Defaults to 120. Needs to be a strictly positive integer.
+
+| idleTimeIntervalUnit
+| Default to SECONDS. Needs to be a parseable TimeUnit.
+
+| disabledCaps
+| Implemented server capabilities NOT to advertise to the client. Coma separated list. Defaults to no disabled capabilities.
+
+| jmxName
+| The name given to the configuration
+
+| tls
+| Set to true to support STARTTLS or SSL for the Socket.
+To use this you need to copy sunjce_provider.jar to /path/james/lib directory. To create a new keystore execute:
+`keytool -genkey -alias james -keyalg RSA -storetype PKCS12 -keystore /path/to/james/conf/keystore`.
+Please note that each IMAP server exposed on different port can specify its own keystore, independently from any other
+TLS based protocols.
+
+| handler.helloName
+| This is the name used by the server to identify itself in the IMAP4
+protocol. If autodetect is TRUE, the server will discover its
+own host name and use that in the protocol. If discovery fails,
+the value of 'localhost' is used. If autodetect is FALSE, James
+will use the specified value.
+
+| connectiontimeout
+| Connection timeout in seconds
+
+| connectionLimit
+| Set the maximum simultaneous incoming connections for this service
+
+| connectionLimitPerIP
+| Set the maximum simultaneous incoming connections per IP for this service
+
+| concurrentRequests
+| Maximum number of IMAP requests executed simultaneously. Past that limit requests are queued. Defaults to 20.
+Negative values deactivate this feature, leading to unbounded concurrency.
+
+| maxQueueSize
+| Upper bound to the IMAP throttler queue. Upon burst, requests that cannot be queued are rejected and not executed.
+Integer, defaults to 4096, must be positive, 0 means no queue.
+
+| proxyRequired
+| Enables proxy support for this service for incoming connections. HAProxy's protocol
+(https://www.haproxy.org/download/2.7/doc/proxy-protocol.txt) is used and might be compatible
+with other proxies (e.g. traefik). If enabled, it is *required* to initiate the connection
+using HAProxy's proxy protocol.
+
+| bossWorkerCount
+| Set the maximum count of boss threads. Boss threads are responsible for accepting incoming IMAP connections
+and initializing associated resources. Optional integer, by default, boss threads are not used and this responsibility is being dealt with
+by IO threads.
+
+| ioWorkerCount
+| Set the maximum count of IO threads. IO threads are responsible for receiving incoming IMAP messages and framing them
+(split line by line). IO threads also take care of compression and SSL encryption. Their tasks are short-lived and non-blocking.
+Optional integer, defaults to 2 times the count of CPUs.
+
+| ignoreIDLEUponProcessing
+| true or false - Allow disabling the heartbeat handler. Defaults to true.
+
+| useEpoll
+| true or false - If true uses native EPOLL implementation for Netty otherwise uses NIO. Defaults to false.
+
+| gracefulShutdown
+| true or false - If true attempts a graceful shutdown, which is safer but can take time. Defaults to true.
+
+| highWriteBufferWaterMark
+| Netty's write buffer high watermark configuration. Unit supported: none, K, M. Netty defaults applied.
+
+| lowWriteBufferWaterMark
+| Netty's write buffer low watermark configuration. Unit supported: none, K, M. Netty defaults applied.
+|===
+
+== OIDC setup
+James IMAP support XOAUTH2 authentication mechanism which allow authenticating against a OIDC providers.
+Please configure `auth.oidc` part to use this.
+
+We do supply an link:https://github.com/apache/james-project/tree/master/examples/oidc[example] of such a setup.
+It uses the Keycloak OIDC provider, but usage of similar technologies is definitely doable.
+
+== Extending IMAP
+
+IMAP decoders, processors and encoder can be customized. xref:{pages-path}/extending/imap.adoc[Read more].
+
+Check this link:https://github.com/apache/james-project/tree/master/examples/custom-imap[example].
+
+The following configuration properties are available for extensions:
+
+.imapserver.xml content
+|===
+| Property name | explanation
+
+| imapPackages
+| Configure (union) of IMAP packages. IMAP packages bundles decoders (parsing IMAP commands) processors and encoders,
+thus enable implementing new IMAP commands or replace existing IMAP processors. List of FQDNs, which can be located in
+James extensions.
+
+| additionalConnectionChecks
+| Configure (union) of additional connection checks. ConnectionCheck will check if the connection IP is secure or not.
+| customProperties
+| Properties for custom extension. Each tag is a property entry, and holds a string under the form key=value.
+|===
+
+== Mail user agents auto-configuration
+
+Check this example on link:https://github.com/apache/james-project/tree/master/examples/imap-autoconf[Mail user agents auto-configuration].
diff --git a/docs/modules/servers/partials/configure/jmap.adoc b/docs/modules/servers/partials/configure/jmap.adoc
new file mode 100644
index 00000000000..5dbfd835078
--- /dev/null
+++ b/docs/modules/servers/partials/configure/jmap.adoc
@@ -0,0 +1,181 @@
+https://jmap.io/[JMAP] is intended to be a new standard for email clients to connect to mail
+stores. It therefore intends to primarily replace IMAP + SMTP submission. It is also designed to be more
+generic. It does not replace MTA-to-MTA SMTP transmission.
+
+Consult this link:{sample-configuration-prefix-url}/jmap.properties[example]
+to get some examples and hints.
+
+.jmap.properties content
+|===
+| Property name | explanation
+
+| enabled
+| true/false. Governs whether JMAP should be enabled
+
+| jmap.port
+| Optional. Defaults to 80. The port this server will be listening on. This value must be a valid
+port, ranging between 1 and 65535 (inclusive)
+
+| tls.keystoreURL
+| Keystore to be used for generating authentication tokens for password authentication mechanism.
+This should not be the same keystore than the ones used by TLS based protocols.
+
+| tls.secret
+| Password used to read the keystore
+
+| jwt.publickeypem.url
+| Optional. Coma separated list of RSA public keys URLs to validate JWT tokens allowing requests to bypass authentication.
+Defaults to an empty list.
+
+| url.prefix
+| Optional. Configuration urlPrefix for JMAP routes. Default value: http://localhost.
+
+| websocket.url.prefix
+| Optional. URL for JMAP WebSocket route. Default value: ws://localhost
+
+| email.send.max.size
+| Optional. Configuration max size for message created in RFC-8621.
+Default value: None. Supported units are B (bytes) K (KB) M (MB) G (GB).
+
+| max.size.attachments.per.mail
+| Optional. Defaults to 20MB. RFC-8621 `maxSizeAttachmentsPerEmail` advertised to JMAP client as part of the
+`urn:ietf:params:jmap:mail` capability. This needs to be at least 33% lower than `email.send.max.size` property
+(in order to account for text body, headers, base64 encoding and MIME structures).
+JMAP clients would use this property in order not to create too big emails.
+Default value: None. Supported units are B (bytes) K (KB) M (MB) G (GB).
+
+| upload.max.size
+| Optional. Configuration max size for each upload file in new JMAP-RFC-8621.
+Default value: 30M. Supported units are B (bytes) K (KB) M (MB) G (GB).
+
+| upload.quota.limit
+| Optional. Configure JMAP upload quota for total existing uploads' size per user. User exceeding the upload quota would result in old uploads being cleaned up.
+Default value: 200M. Supported units are B (bytes) K (KB) M (MB) G (GB).
+
+| view.email.query.enabled
+| Optional boolean. Defaults to false. Should simple Email/query be resolved against a {backend-name} projection, or should we resolve them against OpenSearch?
+This enables a higher resilience, but the projection needs to be correctly populated.
+
+| user.provisioning.enabled
+| Optional boolean. Defaults to true. Governs whether authenticated users that do not exist locally should be created in the users repository.
+
+| authentication.strategy.rfc8621
+| Optional List[String] with delimiter `,` . Specify which authentication strategies system admin want to use for JMAP RFC-8621 server.
+The implicit package name is `org.apache.james.jmap.http`. If you have a custom authentication strategy outside this package, you have to specify its FQDN.
+If no authentication strategy is specified, JMAP RFC-8621 server will fallback to default strategies:
+`JWTAuthenticationStrategy`, `BasicAuthenticationStrategy`.
+
+| jmap.version.default
+| Optional string. Defaults to `rfc-8621`. Allowed values: rfc-8621
+Which version of the JMAP protocol should be served when none supplied in the Accept header.
+
+| dynamic.jmap.prefix.resolution.enabled
+| Optional boolean. Defaults to false. Supported Jmap session endpoint returns dynamic prefix in response.
+When its config is true, and the HTTP request to Jmap session endpoint has a `X-JMAP-PREFIX` header with the value `http://new-domain/prefix`,
+then `apiUrl, downloadUrl, uploadUrl, eventSourceUrl, webSocketUrl` in response will be changed with a new prefix. Example: The `apiUrl` will be "http://new-domain/prefix/jmap".
+If the HTTP request to Jmap session endpoint has the `X-JMAP-WEBSOCKET-PREFIX` header with the value `ws://new-domain/prefix`,
+then `capabilities."urn:ietf:params:jmap:websocket".url` in response will be "ws://new-domain/prefix/jmap/ws".
+
+| webpush.prevent.server.side.request.forgery
+| Optional boolean. Prevent server side request forgery by preventing calls to the private network ranges. Defaults to true, can be disabled for testing.
+
+| cassandra.filter.projection.activated
+|Optional boolean. Defaults to false. Casandra backends only. Whether to use or not the Cassandra projection
+for JMAP filters. This projection optimizes reads, but needs to be correctly populated. Turning it on on
+systems with filters already defined would result in those filters to be not read.
+
+| delay.sends.enabled
+| Optional boolean. Defaults to false. Whether to support or not the delay send with JMAP protocol.
+
+| disabled.capabilities
+| Optional, defaults to empty. Coma separated list of JMAP capabilities to reject.
+This allows to prevent users from using some specific JMAP extensions.
+
+| email.get.full.max.size
+| Optional, default value is 5. The max number of items for EmailGet full reads.
+
+| get.max.size
+| Optional, default value is 500. The max number of items for /get methods.
+
+| set.max.size
+| Optional, default value is 500. The max number of items for /set methods.
+|===
+
+== Wire tapping
+
+Enabling *TRACE* on `org.apache.james.jmap.wire` enables reactor-netty wiretap, logging of
+all incoming and outgoing requests, outgoing requests. This will log also potentially sensible information
+like authentication credentials.
+
+== OIDC set up
+
+The use of `XUserAuthenticationStrategy` allow delegating the authentication responsibility to a third party system,
+which could be used to set up authentication against an OIDC provider.
+
+We do supply an link:https://github.com[example] of such a setup. It combines the link:https://www.keycloak.org/[Keycloack]
+OIDC provider with the link:https://www.krakend.io/[Krackend] API gateway, but usage of similar technologies is definitely doable.
+
+== Generating a JWT key pair
+
+Apache James can alternatively be configured to check the validity of JWT tokens itself. No revocation mechanism is
+supported in such a setup, and the `sub` claim is used to identify the user. The key configuration is static.
+
+This requires the `JWTAuthenticationStrategy` authentication strategy to be used.
+
+The {server-name} enforces the use of RSA-SHA-256.
+
+One can use OpenSSL to generate a JWT key pair :
+
+ # private key
+ openssl genrsa -out rs256-4096-private.rsa 4096
+ # public key
+ openssl rsa -in rs256-4096-private.rsa -pubout > rs256-4096-public.pem
+
+The private key can be used to generate JWT tokens, for instance
+using link:https://github.com/vandium-io/jwtgen[jwtgen]:
+
+ jwtgen -a RS256 -p rs256-4096-private.rsa 4096 -c "sub=bob@domain.tld" -e 3600 -V
+
+This token can then be passed as `Bearer` of the `Authorization` header :
+
+ curl -H "Authorization: Bearer $token" -XPOST http://127.0.0.1:80/jmap -d '...'
+
+The public key can be referenced as `jwt.publickeypem.url` of the `jmap.properties` configuration file.
+
+== Annotated specification
+
+The [annotated documentation](https://github.com/apache/james-project/tree/master/server/protocols/jmap-rfc-8621/doc/specs/spec)
+presents the limits of the JMAP RFC-8621 implementation part of the Apache James project. We furthermore implement
+[JSON Meta Application Protocol (JMAP) Subprotocol for WebSocket](https://tools.ietf.org/html/rfc8887).
+
+Some methods / types are not yet implemented, some implementations are naive, and the PUSH is not supported yet.
+
+Users are invited to read these limitations before using actively the JMAP RFC-8621 implementation, and should ensure their
+client applications only uses supported operations.
+
+Contributions enhancing support are furthermore welcomed.
+
+The list of tested JMAP clients are:
+
+ - Experiments had been run on top of [LTT.RS](https://github.com/iNPUTmice/lttrs-android). Version in the Accept
+ headers needs to be explicitly set to `rfc-8621`. [Read more](https://github.com/linagora/james-project/pull/4089).
+
+== JMAP auto-configuration
+
+link:https://datatracker.ietf.org/doc/html/rfc8620[RFC-8620] defining JMAP core RFC defines precisely service location.
+
+James already redirects `http://jmap.domain.tld/.well-known/jmap` to the JMAP session.
+
+You can further help your clients by publishing extra SRV records.
+
+Eg:
+
+----
+_jmap._tcp.domain.tld. 3600 IN SRV 0 1 443 jmap.domain.tld.
+----
+
+== JMAP reverse-proxy set up
+
+James implementation adds the value of `X-Real-IP` header as part of the logging MDC.
+
+This allows for reverse proxies to cary other the IP address of the client down to the JMAP server for diagnostic purpose.
\ No newline at end of file
diff --git a/docs/modules/servers/partials/configure/jmx.adoc b/docs/modules/servers/partials/configure/jmx.adoc
new file mode 100644
index 00000000000..706bd52298e
--- /dev/null
+++ b/docs/modules/servers/partials/configure/jmx.adoc
@@ -0,0 +1,64 @@
+== Disclaimer
+
+JMX poses several security concerns and had been leveraged to conduct arbitrary code execution.
+This threat is mitigated by not allowing remote connections to JMX, setting up authentication and pre-authentication filters.
+However, we recommend to either run James in isolation (docker / own virtual machine) or disable JMX altogether.
+
+James JMX endpoint provides command line utilities and exposes a few metrics, also available on the metric endpoint.
+
+== Configuration
+
+This is used to configure the JMX MBean server via which all management is achieved.
+
+Consult this link:{sample-configuration-prefix-url}/jmx.properties[example]
+in GIT to get some examples and hints.
+
+.jmx.properties content
+|===
+| Property name | explanation
+
+| jmx.enabled
+| Boolean. Should the JMX server be enabled? Defaults to `true`.
+
+| jmx.address
+|The IP address (host name) the MBean Server will bind/listen to.
+
+| jmx.port
+| The port number the MBean Server will bind/listen to.
+|===
+
+To access from a remote location, it has been reported that `-Dcom.sun.management.jmxremote.ssl=false` is needed as
+a JVM argument.
+
+== JMX Security
+
+In order to set up JMX authentication, we need to put `jmxremote.password` and `jmxremote.access` file
+to `/conf` directory.
+
+- `jmxremote.password`: define the username and password, that will be used by the client (here is james-cli)
+
+File's content example:
+```
+james-admin pass1
+```
+
+- `jmxremote.access`: define the pair of username and access permission
+
+File's content example:
+```
+james-admin readwrite
+```
+
+When James runs with option `-Djames.jmx.credential.generation=true`, James will automatically generate `jmxremote.password` if the file does not exist.
+Then the default username is `james-admin` and a random password. This option defaults to true.
+
+=== James-cli
+
+When the JMX server starts with authentication configuration, it will require the client need provide username/password for bypass.
+To do that, we need set arguments `-username` and `-password` for the command request.
+
+Command example:
+```
+james-cli -h 127.0.0.1 -p 9999 -username james-admin -password pass1 listdomains
+```
+
diff --git a/docs/modules/servers/partials/configure/jvm.adoc b/docs/modules/servers/partials/configure/jvm.adoc
new file mode 100644
index 00000000000..08e59812644
--- /dev/null
+++ b/docs/modules/servers/partials/configure/jvm.adoc
@@ -0,0 +1,102 @@
+This file may contain any additional system properties for tweaking JVM execution. When you normally would add a command line option `-Dmy.property=whatever`, you can put it in this file as `my.property=whatever` instead. These properties will be added as system properties on server start.
+
+Note that in some rare cases this might not work,
+when a property affects very early JVM start behaviour.
+
+For testing purposes, you may specify a different file path via the command line option `-Dextra.props=/some/other/jvm.properties`.
+
+== Control the threshold memory
+This governs the threshold MimeMessageInputStreamSource relies on for storing MimeMessage content on disk.
+
+In `jvm.properties`
+----
+james.message.memory.threshold=12K
+----
+
+(Optional). String (size, integer + size units, example: `12 KIB`, supported units are bytes KIB MIB GIB TIB). Defaults to 100KIB.
+
+== Enable the copy of message in memory
+Should MimeMessageWrapper use a copy of the message in memory? Or should bigger message exceeding james.message.memory.threshold
+be copied to temporary files?
+
+----
+james.message.usememorycopy=true
+----
+
+Optional. Boolean. Defaults to false. Recommended value is false.
+
+== Running resource leak detection
+It is used to detect a resource not be disposed of before it's garbage-collected.
+
+In `jvm.properties`
+----
+james.lifecycle.leak.detection.mode=advanced
+----
+
+Allowed mode values are: none, simple, advanced, testing
+
+The purpose of each mode is introduced in `config-system.xml`
+
+== Disabling host information in protocol MDC logging context
+
+Should we add the host in the MDC logging context for incoming IMAP, SMTP, POP3? Doing so, a DNS resolution
+is attempted for each incoming connection, which can be costly. Remote IP is always added to the logging context.
+
+
+In `jvm.properties`
+----
+james.protocols.mdc.hostname=false
+----
+
+Optional. Boolean. Defaults to true.
+
+== Change the encoding type used for the blobId
+
+By default, the blobId is encoded in base64 url. The property `james.blob.id.hash.encoding` allows to change the encoding type.
+The support value are: base16, hex, base32, base32Hex, base64, base64Url.
+
+Ex in `jvm.properties`
+----
+james.blob.id.hash.encoding=base16
+----
+
+Optional. String. Defaults to base64Url.
+
+== JMAP Quota draft compatibility
+
+Some JMAP clients depend on the JMAP Quota draft specifications. The property `james.jmap.quota.draft.compatibility` allows
+to enable JMAP Quota draft compatibility for those clients and allow them a time window to adapt to the RFC-9245 JMAP Quota.
+
+Optional. Boolean. Default to false.
+
+Ex in `jvm.properties`
+----
+james.jmap.quota.draft.compatibility=true
+----
+To enable the compatibility.
+
+== Enable S3 metrics
+
+James supports extracting some S3 client-level metrics e.g. number of connections being used, time to acquire an S3 connection, total time to finish a S3 request...
+
+The property `james.s3.metrics.enabled` allows to enable S3 metrics collection. Please pay attention that enable this
+would impact a bit on S3 performance.
+
+Optional. Boolean. Default to true.
+
+Ex in `jvm.properties`
+----
+james.s3.metrics.enabled=false
+----
+To disable the S3 metrics.
+
+== Reactor Stream Prefetch
+
+Prefetch to use in Reactor to stream convertions (S3 => InputStream). Default to 1.
+Higher values will tend to block less often at the price of higher memory consumptions.
+
+Ex in `jvm.properties`
+----
+# james.reactor.inputstream.prefetch=4
+----
+
diff --git a/docs/modules/servers/partials/configure/listeners.adoc b/docs/modules/servers/partials/configure/listeners.adoc
new file mode 100644
index 00000000000..4b8acb66709
--- /dev/null
+++ b/docs/modules/servers/partials/configure/listeners.adoc
@@ -0,0 +1,156 @@
+{server-name} relies on an event bus system to enrich mailbox capabilities. Each
+operation performed on the mailbox will trigger related events, that can
+be processed asynchronously by potentially any James node on a
+distributed system.
+
+Mailbox listeners can register themselves on this event bus system to be
+called when an event is fired, allowing to do different kind of extra
+operations on the system.
+
+{server-name} allows the user to register potentially user defined additional mailbox listeners.
+
+Consult this link:{sample-configuration-prefix-url}/listener.xml[example]
+to get some examples and hints.
+
+== Configuration
+
+The controls whether to launch group mailbox listener consumption. Defaults to true. Use with caution:
+never disable on standalone james servers, and ensure at least some instances do consume group mailbox listeners within a
+clustered topology.
+
+Mailbox listener configuration is under the XML element .
+
+Some MailboxListener allows you to specify if you want to run them synchronously or asynchronously. To do so,
+for MailboxListener that supports this, you can use the *async* attribute (optional, per mailet default) to govern the execution mode.
+If *true* the execution will be scheduled in a reactor elastic scheduler. If *false*, the execution is synchronous.
+
+Already provided additional listeners are documented below.
+
+=== SpamAssassinListener
+
+Provides per user real-time HAM/SPAM feedback to a SpamAssassin server depending on user actions.
+
+This mailet is asynchronous by default, but this behaviour can be overridden by the *async*
+configuration property.
+
+This MailboxListener is supported.
+
+Example:
+
+[source,xml]
+....
+
+
+
+ org.apache.james.mailbox.spamassassin.SpamAssassinListener
+
+
+....
+
+Please note that a `spamassassin.properties` file is needed. Read also
+xref:{pages-path}/configure/spam.adoc[this page] for extra configuration required to support this feature.
+
+=== RspamdListener
+
+Provides HAM/SPAM feedback to a Rspamd server depending on user actions.
+
+This MailboxListener is supported.
+
+Example:
+
+[source,xml]
+....
+
+
+
+ org.apache.james.rspamd.RspamdListener
+
+
+....
+
+Please note that a `rspamd.properties` file is needed. Read also
+xref:{pages-path}/configure/spam.adoc[this page] for extra configuration required to support this feature.
+
+
+=== QuotaThresholdCrossingListener
+
+Sends emails to users exceeding 80% and 99% of their quota to warn them (for instance).
+
+Here are the following properties you can configure:
+
+.QuotaThresholdCrossingListener configuration properties
+|===
+| Property name | explanation
+
+| name
+| Useful when configuring several time this listener. You might want to do so to use different rendering templates for
+different occupation thresholds.
+
+| gracePeriod
+| Period during which no more email for a given threshold should be sent.
+
+| subjectTemplate
+| Mustache template for rendering the subject of the warning email.
+
+| bodyTemplate
+| Mustache template for rendering the body of the warning email.
+
+| thresholds
+| Floating number between 0 and 1 representing the threshold of quota occupation from which a mail should be sent.
+Configuring several thresholds is supported.
+
+|===
+
+Example:
+
+[source,xml]
+....
+
+
+
+ org.apache.james.mailbox.quota.mailing.listeners.QuotaThresholdCrossingListener
+ QuotaThresholdCrossingListener-upper-threshold
+
+
+
+ 0.8
+
+
+ thirst
+ conf://templates/QuotaThresholdMailSubject.mustache
+ conf://templates/QuotaThresholdMailBody.mustache
+ 1week/
+
+
+
+....
+
+Here are examples of templates you can use:
+
+* For subject template: `conf://templates/QuotaThresholdMailSubject.mustache`
+
+....
+Warning: Your email usage just exceeded a configured threshold
+....
+
+* For body template: `conf://templates/QuotaThresholdMailBody.mustache`
+
+....
+You receive this email because you recently exceeded a threshold related to the quotas of your email account.
+
+{{#hasExceededSizeThreshold}}
+You currently occupy more than {{sizeThreshold}} % of the total size allocated to you.
+You currently occupy {{usedSize}}{{#hasSizeLimit}} on a total of {{limitSize}} allocated to you{{/hasSizeLimit}}.
+
+{{/hasExceededSizeThreshold}}
+{{#hasExceededCountThreshold}}
+You currently occupy more than {{countThreshold}} % of the total message count allocated to you.
+You currently have {{usedCount}} messages{{#hasCountLimit}} on a total of {{limitCount}} allowed for you{{/hasCountLimit}}.
+
+{{/hasExceededCountThreshold}}
+You need to be aware that actions leading to exceeded quotas will be denied. This will result in a degraded service.
+To mitigate this issue you might reach your administrator in order to increase your configured quota. You might also delete some non important emails.
+....
+
+This MailboxListener is supported.
+
diff --git a/docs/modules/servers/partials/configure/mailetcontainer.adoc b/docs/modules/servers/partials/configure/mailetcontainer.adoc
new file mode 100644
index 00000000000..a3e7c56e29a
--- /dev/null
+++ b/docs/modules/servers/partials/configure/mailetcontainer.adoc
@@ -0,0 +1,95 @@
+This documents explains how to configure Mail processing. Mails pass through the MailetContainer. The
+MailetContainer is a Matchers (condition for executing a mailet) and Mailets (execution units that perform
+actions based on incoming mail) pipeline arranged into processors (List of mailet/matcher pairs allowing
+better logical organisation). You can read more about these concepts on
+xref:{pages-path}/architecture/index.adoc#_mail_processing[the mailet container feature description].
+
+Apache James Server includes a number of xref:{pages-path}/configure/mailets.adoc[Packaged Mailets] and
+xref:{pages-path}/configure/matchers.adoc[Packaged Matchers].
+
+Furthermore, you can write and use with James xref:{pages-path}/extending/mail-processing.adoc[your own mailet and matchers].
+
+Consult this link:{sample-configuration-prefix-url}/mailetcontainer.xml[example]
+to get some examples and hints.
+
+.mailetcontainer.xml content
+|===
+| Property name | explanation
+
+| context.postmaster
+| The body of this element is the address that the server
+will consider its postmaster address. This address will be listed as the sender address
+of all error messages that originate from James. Also, all messages addressed to
+postmaster@, where is one of the domain names whose
+mail is being handled by James, will be redirected to this email address.
+Set this to the appropriate email address for error reports
+If this is set to a non-local email address, the mail server
+will still function, but will generate a warning on startup.
+
+| spooler.threads
+| Number of simultaneous threads used to spool the mails. Set to zero, it disables mail processing - use with
+caution.
+
+| spooler.errorRepository
+| Mail repository to store email in after several unrecoverable errors. Mails failing processing, for which
+the Mailet Container could not handle Error, will be stored there after their processing had been attempted
+5 times. Note that if standard java Exception occurs, *Error handling* section below will be applied
+instead.
+|===
+
+== The Mailet Tag
+
+Consider the following simple *mailet* tag:
+
+[source,xml]
+....
+
+ spam
+
+....
+
+The mailet tag has two required attributes, *match* and *class*.
+
+The *match* attribute is set to the value of the specific Matcher class to be instantiated with a an
+optional argument. If present, the argument is separated from the Matcher class name by an '='. Semantic
+interpretation of the argument is left to the particular mailet.
+
+The *class* attribute is set to the value of the Mailet class that is to be instantiated.
+
+Finally, the children of the *mailet* tag define the configuration that is passed to the Mailet. The
+tags used in this section should have no attributes or children. The names and bodies of the elements will be passed to
+the mailet as (name, value) pairs.
+
+So in the example above, a Matcher instance of RemoteAddrNotInNetwork would be instantiated, and the value "127.0.0.1"
+would be passed to the matcher. The Mailet of the pair will be an instance of ToProcessor, and it will be passed the (name, value)
+pair of ("processor", "spam").
+
+== Error handling
+
+If an exception is encountered during the execution of a mailet or a matcher, the default behaviour is to
+process the mail using the *error* processor.
+
+The *onMailetException* property allows you to override this behaviour. You can specify another
+processor than the *error* one for handling the errors of this mailet.
+
+The *ignore* special value also allows to continue processing and ignore the error.
+
+The *propagate* special value causes the mailet container to rethrow the
+exception, propagating it to the execution context. In an SMTP execution context, the spooler will then requeue
+the item and automatic retries will be setted up - note that attempts will be done for each recipients. In LMTP
+(if LMTP is configured to execute the mailetContainer), the entire mail transaction is reported as failed to the caller.
+
+Moreover, the *onMatcherException* allows you to override matcher error handling. You can
+specify another processor than the *error* one for handling the errors of this mailet. The *matchall*
+special value also allows you to match all recipients when there is an error. The *nomatch*
+special value also allows you to match no recipients when there is an error.
+
+Here is a short example to illustrate this:
+
+[source,xml]
+....
+
+ deliveryError
+ nomatch
+
+....
\ No newline at end of file
diff --git a/docs/modules/servers/partials/configure/mailets.adoc b/docs/modules/servers/partials/configure/mailets.adoc
new file mode 100644
index 00000000000..5c20ff872a1
--- /dev/null
+++ b/docs/modules/servers/partials/configure/mailets.adoc
@@ -0,0 +1,146 @@
+This documentation page lists and documents Mailet that can be used within the
+{server-name} MailetContainer in order to write your own mail processing logic with out-of-the-box components.
+
+== Supported mailets
+
+include::partial$AddDeliveredToHeader.adoc[]
+
+include::partial$AddFooter.adoc[]
+
+include::partial$AddSubjectPrefix.adoc[]
+
+include::partial$AmqpForwardAttribute.adoc[]
+
+include::partial$Bounce.adoc[]
+
+include::partial$ContactExtractor.adoc[]
+
+include::partial$ConvertTo7Bit.adoc[]
+
+include::partial$DKIMSign.adoc[]
+
+include::partial$DKIMVerify.adoc[]
+
+include::partial$DSNBounce.adoc[]
+
+include::partial$Expires.adoc[]
+
+include::partial$ExtractMDNOriginalJMAPMessageId.adoc[]
+
+include::partial$Forward.adoc[]
+
+include::partial$ICalendarParser.adoc[]
+
+include::partial$ICALToHeader.adoc[]
+
+include::partial$ICALToJsonAttribute.adoc[]
+
+include::partial$ICSSanitizer.adoc[]
+
+include::partial$LocalDelivery.adoc[]
+
+include::partial$LogMessage.adoc[]
+
+include::partial$MailAttributesListToMimeHeaders.adoc[]
+
+include::partial$MailAttributesToMimeHeaders.adoc[]
+
+include::partial$MetricsMailet.adoc[]
+
+include::partial$MimeDecodingMailet.adoc[]
+
+include::partial$NotifyPostmaster.adoc[]
+
+include::partial$NotifySender.adoc[]
+
+include::partial$Null.adoc[]
+
+include::partial$PostmasterAlias.adoc[]
+
+include::partial$RandomStoring.adoc[]
+
+include::partial$RecipientRewriteTable.adoc[]
+
+include::partial$RecipientToLowerCase.adoc[]
+
+include::partial$Redirect.adoc[]
+
+include::partial$RemoteDelivery.adoc[]
+
+include::partial$RemoveAllMailAttributes.adoc[]
+
+include::partial$RemoveMailAttribute.adoc[]
+
+include::partial$RemoveMimeHeader.adoc[]
+
+include::partial$RemoveMimeHeaderByPrefix.adoc[]
+
+include::partial$ReplaceContent.adoc[]
+
+include::partial$Resend.adoc[]
+
+include::partial$SetMailAttribute.adoc[]
+
+include::partial$SetMimeHeader.adoc[]
+
+include::partial$Sieve.adoc[]
+
+include::partial$Sign.adoc[]
+
+include::partial$SMIMECheckSignature.adoc[]
+
+include::partial$SMIMEDecrypt.adoc[]
+
+include::partial$SMIMESign.adoc[]
+
+include::partial$SpamAssassin.adoc[]
+
+include::partial$StripAttachment.adoc[]
+
+include::partial$TextCalendarBodyToAttachment.adoc[]
+
+include::partial$ToProcessor.adoc[]
+
+include::partial$ToRepository.adoc[]
+
+include::partial$ToSenderDomainRepository.adoc[]
+
+include::partial$VacationMailet.adoc[]
+
+include::partial$WithPriority.adoc[]
+
+include::partial$WithStorageDirective.adoc[]
+
+== Experimental mailets
+
+include::partial$AddHabeasWarrantMark.adoc[]
+
+include::partial$ClamAVScan.adoc[]
+
+include::partial$ClassifyBounce.adoc[]
+
+include::partial$FromRepository.adoc[]
+
+include::partial$HeadersToHTTP.adoc[]
+
+include::partial$OnlyText.adoc[]
+
+include::partial$ManageSieveMailet.adoc[]
+
+include::partial$RecoverAttachment.adoc[]
+
+include::partial$SerialiseToHTTP.adoc[]
+
+include::partial$ServerTime.adoc[]
+
+include::partial$SPF.adoc[]
+
+include::partial$ToPlainText.adoc[]
+
+include::partial$ToSenderFolder.adoc[]
+
+include::partial$UnwrapText.adoc[]
+
+include::partial$UseHeaderRecipients.adoc[]
+
+include::partial$WrapText.adoc[]
\ No newline at end of file
diff --git a/docs/modules/servers/partials/configure/mailrepositorystore.adoc b/docs/modules/servers/partials/configure/mailrepositorystore.adoc
new file mode 100644
index 00000000000..e0c7b88bc24
--- /dev/null
+++ b/docs/modules/servers/partials/configure/mailrepositorystore.adoc
@@ -0,0 +1,34 @@
+A `mail repository` allows storage of a mail as part of its
+processing. Standard configuration relies on the following mail
+repository.
+
+A mail repository is identified by its *url*, constituted of a *protocol* and a *path*.
+
+For instance in the url `{mailet-repository-path-prefix}://var/mail/error/` `{mail-repository-protocol}` is the protocol and `var/mail/error` the path.
+
+The *mailrepositorystore.xml* file allows registration of available protocols, and their binding to actual MailRepository
+implementation. Note that extension developers can write their own MailRepository implementations, load them via the
+`extensions-jars` mechanism as documented in xref:{pages-path}/extending/index.adoc['writing your own extensions'], and finally
+associated to a protocol in *mailrepositorystore.xml* for a usage in *mailetcontainer.xml*.
+
+== Configuration
+
+Consult this link:{sample-configuration-prefix-url}/mailrepositorystore.xml[example]
+to get some examples and hints.
+
+[subs=attributes+,xml]
+----
+
+ {mail-repository-protocol}
+
+
+
+ {mail-repository-protocol}
+
+
+
+
+----
+
+Only the *{mail-repository-class}* is available by default for the {server-name}. Mails metadata are stored in
+{mail-repository-protocol} while the headers and bodies are stored within the xref:{pages-path}/architecture/index.adoc#_blobstore[BlobStore].
diff --git a/docs/modules/servers/partials/configure/matchers.adoc b/docs/modules/servers/partials/configure/matchers.adoc
new file mode 100644
index 00000000000..a7e7526a512
--- /dev/null
+++ b/docs/modules/servers/partials/configure/matchers.adoc
@@ -0,0 +1,166 @@
+This documentation page lists and documents Matchers that can be used within the
+{server-name} MailetContainer in order to write your own mail processing logic with out-of-the-box components.
+
+== Supported matchers
+
+include::partial$All.adoc[]
+
+include::partial$AtLeastPriority.adoc[]
+
+include::partial$AtMost.adoc[]
+
+include::partial$AtMostPriority.adoc[]
+
+include::partial$DLP.adoc[]
+
+include::partial$FetchedFrom.adoc[]
+
+include::partial$HasAttachment.adoc[]
+
+include::partial$HasException.adoc[]
+
+include::partial$HasHeader.adoc[]
+
+include::partial$HasHeaderWithPrefix.adoc[]
+
+include::partial$HasMailAttribute.adoc[]
+
+include::partial$HasMailAttributeWithValue.adoc[]
+
+include::partial$HasMailAttributeWithValueRegex.adoc[]
+
+include::partial$HasMimeType.adoc[]
+
+include::partial$HasMimeTypeParameter.adoc[]
+
+include::partial$HasPriority.adoc[]
+
+include::partial$HostIs.adoc[]
+
+include::partial$HostIsLocal.adoc[]
+
+include::partial$IsMarkedAsSpam.adoc[]
+
+include::partial$IsOverQuota.adoc[]
+
+include::partial$IsRemoteDeliveryPermanentError.adoc[]
+
+include::partial$IsRemoteDeliveryTemporaryError.adoc[]
+
+include::partial$IsSenderInRRTLoop.adoc[]
+
+include::partial$IsSingleRecipient.adoc[]
+
+include::partial$IsSMIMEEncrypted.adoc[]
+
+include::partial$IsSMIMESigned.adoc[]
+
+include::partial$IsX509CertificateSubject.adoc[]
+
+include::partial$RecipientDomainIs.adoc[]
+
+include::partial$RecipientIs.adoc[]
+
+include::partial$RecipientIsLocal.adoc[]
+
+include::partial$RecipientIsRegex.adoc[]
+
+include::partial$RelayLimit.adoc[]
+
+include::partial$RemoteAddrInNetwork.adoc[]
+
+include::partial$RemoteAddrNotInNetwork.adoc[]
+
+include::partial$RemoteDeliveryFailedWithSMTPCode.adoc[]
+
+include::partial$SenderDomainIs.adoc[]
+
+include::partial$SenderHostIs.adoc[]
+
+include::partial$SenderIs.adoc[]
+
+include::partial$SenderIsLocal.adoc[]
+
+include::partial$SenderIsNull.adoc[]
+
+include::partial$SenderIsRegex.adoc[]
+
+include::partial$SentByJmap.adoc[]
+
+include::partial$SentByMailet.adoc[]
+
+include::partial$SizeGreaterThan.adoc[]
+
+include::partial$SMTPAuthSuccessful.adoc[]
+
+include::partial$SMTPAuthUserIs.adoc[]
+
+include::partial$SMTPIsAuthNetwork.adoc[]
+
+include::partial$SubjectIs.adoc[]
+
+include::partial$SubjectStartsWith.adoc[]
+
+include::partial$TooManyRecipients.adoc[]
+
+include::partial$UserIs.adoc[]
+
+include::partial$XOriginatingIpInNetwork.adoc[]
+
+== Experimental matchers
+
+include::partial$AttachmentFileNameIs.adoc[]
+
+include::partial$CommandForListserv.adoc[]
+
+include::partial$CommandListservMatcher.adoc[]
+
+include::partial$CompareNumericHeaderValue.adoc[]
+
+include::partial$FileRegexMatcher.adoc[]
+
+include::partial$HasHabeasWarrantMark.adoc[]
+
+include::partial$InSpammerBlacklist.adoc[]
+
+include::partial$NESSpamCheck.adoc[]
+
+include::partial$SenderInFakeDomain.adoc[]
+
+== Composite matchers
+
+It is possible to combine together matchers in order to create a composite matcher, thus simplifying your
+Mailet Container logic.
+
+Here are the available logical operations:
+
+* *And* : This matcher performs And conjunction between the two matchers: recipients needs to match both matcher in order to
+match the composite matcher.
+* *Or* : This matcher performs Or conjunction between the two matchers: consider it to be a union of the results.
+It returns recipients from the Or composition results of the child matchers.
+* *Not* : It returns recipients from the negated composition of the child Matcher(s). Consider what wasn't
+in the result set of each child matcher. Of course it is easier to understand if it only
+includes one matcher in the composition, the normal recommended use.
+* *Xor* : It returns Recipients from the Xor composition of the child matchers. Consider it to be the inequality
+operator for recipients. If any recipients match other matcher results
+then the result does not include that recipient.
+
+Here is the syntax to adopt in *mailetcontainer.xml*:
+
+[source,xml]
+....
+
+
+
+
+
+
+
+
+
+
+
+ relay
+
+
+....
\ No newline at end of file
diff --git a/docs/modules/servers/partials/configure/opensearch.adoc b/docs/modules/servers/partials/configure/opensearch.adoc
new file mode 100644
index 00000000000..14b1a929b96
--- /dev/null
+++ b/docs/modules/servers/partials/configure/opensearch.adoc
@@ -0,0 +1,310 @@
+== 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 {package-tag}.
+
+Possible values are:
+
+- `org.apache.james.mailbox.{package-tag}.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.{package-tag}.search.UidSearchOverride`. Same as above but restricted by ranges.
+- `org.apache.james.mailbox.{package-tag}.search.DeletedSearchOverride`. Find deleted messages by looking up in the relevant Cassandra
+table.
+- `org.apache.james.mailbox.{package-tag}.search.DeletedWithRangeSearchOverride`. Same as above but limited by ranges.
+- `org.apache.james.mailbox.{package-tag}.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.{package-tag}.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:
+
+[subs=attributes+]
+----
+opensearch.search.overrides=org.apache.james.mailbox.{package-tag}.search.AllSearchOverride,org.apache.james.mailbox.{package-tag}.search.DeletedSearchOverride, org.apache.james.mailbox.{package-tag}.search.DeletedWithRangeSearchOverride,org.apache.james.mailbox.{package-tag}.search.NotDeletedWithRangeSearchOverride,org.apache.james.mailbox.{package-tag}.search.UidSearchOverride,org.apache.james.mailbox.{package-tag}.search.UnseenSearchOverride
+----
+
+Consult this link:{sample-configuration-prefix-url}/opensearch.properties[example]
+to get some examples and hints.
+
+If you want more explanation about OpenSearch configuration, you should visit the dedicated https://opensearch.org/[documentation].
+
+== OpenSearch Configuration
+
+This file section is used to configure the connection tp an OpenSearch cluster.
+
+Here are the properties allowing to do so :
+
+.opensearch.properties content
+|===
+| Property name | explanation
+
+| 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
+| Wait for a certain number of active shard copies before proceeding with the operation. Defaults to 1.
+You may consult the https://www.elastic.co/guide/en/elasticsearch/reference/7.10/docs-index_.html#active-shards[documentation] for more information.
+
+| opensearch.retryConnection.maxRetries
+| Number of retries when connecting the cluster
+
+| opensearch.retryConnection.minDelay
+| Minimum delay between connection attempts
+
+| 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).
+
+|===
+
+=== Mailbox search
+
+The main use of OpenSearch within the {server-name} is indexing the mailbox content of users in order to enable
+powerful and efficient full-text search of the mailbox content.
+
+Data indexing is performed asynchronously in a reliable fashion via a MailboxListener.
+
+Here are the properties related to the use of OpenSearch for Mailbox Search:
+
+.opensearch.properties content
+|===
+| Property name | explanation
+
+| 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.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.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.
+|===
+
+=== Quota search
+
+Users are indexed by quota usage, allowing operators a quick audit of users quota occupation.
+
+Users quota are asynchronously indexed upon quota changes via a dedicated MailboxListener.
+
+The following properties affect quota search :
+
+.opensearch.properties content
+|===
+| Property name | explanation
+
+| 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
+|===
+
+=== Disabling OpenSearch
+
+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
+xref:{pages-path}/operate/webadmin.adoc#_reindexing_all_mails[a full re-indexing]needs to be carried out when enabling OpenSearch.
+
+== 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.properties content
+|===
+| Property name | explanation
+
+| 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.
+
+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.properties content
+|===
+| Property name | explanation
+
+| 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.properties content
+|===
+| Property name | explanation
+
+| 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).
+
+|===
+
+== Configure dedicated language analyzers for mailbox index
+
+OpenSearch supports various language analyzers out of the box: https://www.elastic.co/guide/en/elasticsearch/reference/current/analysis-lang-analyzer.html.
+
+James could utilize this to improve the user searching experience upon his language.
+
+While one could modify mailbox index mapping programmatically to customize this behavior, here we should just document a manual way to archive this without breaking our common index' mapping code.
+
+The idea is modifying mailbox index mappings with the target language analyzer as a JSON file, then submit it directly
+to OpenSearch via cURL command to create the mailbox index before James start. Let's adapt dedicated language analyzers
+where appropriate for the following fields:
+
+.Language analyzers propose change
+|===
+| Field | Analyzer change
+
+| from.name
+| `keep_mail_and_url` analyzer -> `keep_mail_and_url_language_a` analyzer
+
+| subject
+| `keep_mail_and_url` analyzer -> `keep_mail_and_url_language_a` analyzer
+
+| to.name
+| `keep_mail_and_url` analyzer -> `keep_mail_and_url_language_a` analyzer
+
+| cc.name
+| `keep_mail_and_url` analyzer -> `keep_mail_and_url_language_a` analyzer
+
+| bcc.name
+| `keep_mail_and_url` analyzer -> `keep_mail_and_url_language_a` analyzer
+
+| textBody
+| `standard` analyzer -> `language_a` analyzer
+
+| htmlBody
+| `standard` analyzer -> `language_a` analyzer
+
+| attachments.fileName
+| `standard` analyzer -> `language_a` analyzer
+
+| attachments.textContent
+| `standard` analyzer -> `language_a` analyzer
+
+|===
+
+In there:
+
+ - `keep_mail_and_url` and `standard` are our current analyzers for mailbox index.
+ - `language_a` analyzer: the built-in analyzer of OpenSearch. EG: `french`
+ - `keep_mail_and_url_language_a` analyzer: a custom of `keep_mail_and_url` analyzer with some language filters.Every language has
+their own filters so please have a look at filters which your language need to add. EG which need to be added for French:
+----
+"filter": {
+ "french_elision": {
+ "type": "elision",
+ "articles_case": true,
+ "articles": [
+ "l", "m", "t", "qu", "n", "s",
+ "j", "d", "c", "jusqu", "quoiqu",
+ "lorsqu", "puisqu"
+ ]
+ },
+ "french_stop": {
+ "type": "stop",
+ "stopwords": "_french_"
+ },
+ "french_stemmer": {
+ "type": "stemmer",
+ "language": "light_french"
+ }
+}
+----
+
+After modifying above proposed change, you should have a JSON file that contains new setting and mapping of mailbox index. Here
+we provide https://github.com/apache/james-project/blob/master/mailbox/opensearch/example_french_index.json[a sample JSON for French language].
+If you want to customize that JSON file for your own language need, please make these modifications:
+
+ - Replace the `french` analyzer with your built-in language (have a look at https://www.elastic.co/guide/en/elasticsearch/reference/current/analysis-lang-analyzer.html[built-in language analyzers])
+ - Modify `keep_mail_and_url_french` analyzer' filters with your language filters, and customize the analyzer' name.
+
+Please change also `number_of_shards`, `number_of_replicas` and `index.write.wait_for_active_shards` values in the sample file according to your need.
+
+Run this cURL command with above JSON file to create `mailbox_v1` (Mailbox index' default name) index before James start:
+----
+curl -X PUT ES_IP:ES_PORT/mailbox_v1 -H "Content-Type: application/json" -d @example_french_index.json
+----
diff --git a/docs/modules/servers/partials/configure/pop3.adoc b/docs/modules/servers/partials/configure/pop3.adoc
new file mode 100644
index 00000000000..dc01589791f
--- /dev/null
+++ b/docs/modules/servers/partials/configure/pop3.adoc
@@ -0,0 +1,74 @@
+Consult this link:{sample-configuration-prefix-url}/pop3server.xml[example]
+to get some examples and hints.
+
+The POP3 service is controlled by a configuration block in the pop3server.xml.
+The pop3server tag defines the boundaries of the configuration block. It encloses
+all the relevant configuration for the POP3 server. The behavior of the POP service is
+controlled by the attributes and children of this tag.
+
+This tag has an optional boolean attribute - *enabled* - that defines whether the service is active or not.
+The value defaults to "true" if not present.
+
+The standard children of the pop3server tag are:
+
+.jmx.properties content
+|===
+| Property name | explanation
+
+| bind
+| Configure this to bind to a specific inetaddress. This is an optional integer value.
+This value is the port on which this POP3 server is configured
+to listen. If the tag or value is absent then the service
+will bind to all network interfaces for the machine If the tag or value is omitted,
+the value will default to the standard POP3 port, 11
+port 995 is the well-known/IANA registered port for POP3S ie over SSL/TLS
+port 110 is the well-known/IANA registered port for Standard POP3
+
+| connectionBacklog
+|
+
+| tls
+| Set to true to support STARTTLS or SSL for the Socket.
+To create a new keystore execute:
+`keytool -genkey -alias james -keyalg RSA -storetype PKCS12 -keystore /path/to/james/conf/keystore`
+Please note that each POP3 server exposed on different port can specify its own keystore, independently from any other
+TLS based protocols. Read xref:{pages-path}/configure/ssl.adoc[SSL configuration page] for more information.
+
+| handler.helloName
+| This is the name used by the server to identify itself in the POP3
+protocol. If autodetect is TRUE, the server will discover its
+own host name and use that in the protocol. If discovery fails,
+the value of 'localhost' is used. If autodetect is FALSE, James
+will use the specified value.
+
+| handler.connectiontimeout
+| Connection timeout in seconds
+
+| handler.connectionLimit
+| Set the maximum simultaneous incoming connections for this service
+
+| handler.connectionLimitPerIP
+| Set the maximum simultaneous incoming connections per IP for this service
+
+| handler.handlerchain
+| This loads the core CommandHandlers. Only remove this if you really know what you are doing.
+
+| bossWorkerCount
+| Set the maximum count of boss threads. Boss threads are responsible for accepting incoming POP3 connections
+and initializing associated resources. Optional integer, by default, boss threads are not used and this responsibility is being dealt with
+by IO threads.
+
+| ioWorkerCount
+| Set the maximum count of IO threads. IO threads are responsible for receiving incoming POP3 messages and framing them
+(split line by line). IO threads also take care of compression and SSL encryption. Their tasks are short-lived and non-blocking.
+Optional integer, defaults to 2 times the count of CPUs.
+
+| maxExecutorCount
+| Set the maximum count of worker threads. Worker threads takes care of potentially blocking tasks like executing POP3 requests. Optional integer, defaults to 16.
+
+| useEpoll
+| true or false - If true uses native EPOLL implementation for Netty otherwise uses NIO. Defaults to false.
+
+| gracefulShutdown
+| true or false - If true attempts a graceful shutdown, which is safer but can take time. Defaults to true.
+|===
\ No newline at end of file
diff --git a/docs/modules/servers/partials/configure/queue.adoc b/docs/modules/servers/partials/configure/queue.adoc
new file mode 100644
index 00000000000..cbec12d7252
--- /dev/null
+++ b/docs/modules/servers/partials/configure/queue.adoc
@@ -0,0 +1,16 @@
+This configuration helps you configure mail queue you want to select.
+
+== Queue Configuration
+
+.queue.properties content
+|===
+| Property name | explanation
+
+| mail.queue.choice
+| Mail queue can be implemented by many type of message brokers: Pulsar, RabbitMQ,... This property will choose which mail queue you want, defaulting to RABBITMQ
+|===
+
+`mail.queue.choice` supports the following options:
+
+* You can specify the `RABBITMQ` if you want to choose RabbitMQ mail queue
+* You can specify the `PULSAR` if you want to choose Pulsar mail queue
diff --git a/docs/modules/servers/partials/configure/rabbitmq.adoc b/docs/modules/servers/partials/configure/rabbitmq.adoc
new file mode 100644
index 00000000000..689bb17a57c
--- /dev/null
+++ b/docs/modules/servers/partials/configure/rabbitmq.adoc
@@ -0,0 +1,162 @@
+This configuration helps you configure components using RabbitMQ.
+
+Consult this link:{sample-configuration-prefix-url}/rabbitmq.properties[example]
+to get some examples and hints.
+
+== RabbitMQ Configuration
+
+.rabbitmq.properties content
+|===
+| Property name | explanation
+
+| uri
+| the amqp URI pointing to RabbitMQ server. If you use a vhost, specify it as well at the end of the URI.
+Details about amqp URI format is in https://www.rabbitmq.com/uri-spec.html[RabbitMQ URI Specification]
+
+| management.uri
+| the URI pointing to RabbitMQ Management Service. James need to retrieve some information about listing queues
+from this service in runtime.
+Details about URI format is in https://www.rabbitmq.com/management.html#usage-ui[RabbitMQ Management URI]
+
+| management.user
+| username used to access management service
+
+| management.password
+| password used to access management service
+
+| connection.pool.retries
+| Configure retries count to retrieve a connection. Exponential backoff is performed between each retries.
+Optional integer, defaults to 10
+
+| connection.pool.min.delay.ms
+| Configure initial duration (in ms) between two connection retries. Exponential backoff is performed between each retries.
+Optional integer, defaults to 100
+
+| channel.pool.retries
+| Configure retries count to retrieve a channel. Exponential backoff is performed between each retries.
+Optional integer, defaults to 3
+
+| channel.pool.max.delay.ms
+| Configure timeout duration (in ms) to obtain a rabbitmq channel. Defaults to 30 seconds.
+Optional integer, defaults to 30 seconds.
+
+| channel.pool.size
+| Configure the size of the channel pool.
+Optional integer, defaults to 3
+
+| driver.network.recovery.interval
+| Optional, non-negative integer, default to 100ms. The interval (in ms) that RabbitMQ driver will automatic recovery wait before attempting to reconnect. See https://www.rabbitmq.com/client-libraries/java-api-guide#connection-recovery
+
+| ssl.enabled
+| Is using ssl enabled
+Optional boolean, defaults to false
+
+| ssl.management.enabled
+| Is using ssl on management api enabled
+Optional boolean, defaults to false
+
+| ssl.validation.strategy
+| Configure the validation strategy used for rabbitmq connections. Possible values are default, ignore and override.
+Optional string, defaults to using systemwide ssl configuration
+
+| ssl.truststore
+| Points to the truststore (PKCS12) used for verifying rabbitmq connection. If configured then "ssl.truststore.password" must also be configured,
+Optional string, defaults to systemwide truststore. "ssl.validation.strategy: override" must be configured if you want to use this
+
+| ssl.truststore.password
+| Configure the truststore password. If configured then "ssl.truststore" must also be configured,
+Optional string, defaults to empty string. "ssl.validation.strategy: override" must be configured if you want to use this
+
+| ssl.hostname.verifier
+| Configure host name verification. Possible options are default and accept_any_hostname
+Optional string, defaults to subject alternative name host verifier
+
+| ssl.keystore
+| Points to the keystore(PKCS12) used for client certificate authentication. If configured then "ssl.keystore.password" must also be configured,
+Optional string, defaults to empty string
+
+| ssl.keystore.password
+| Configure the keystore password. If configured then "ssl.keystore" must also be configured,
+Optional string, defaults to empty string
+
+| quorum.queues.enable
+| Boolean. Whether to activate Quorum queue usage for all queues.
+Quorum queues enables high availability.
+False (default value) results in the usage of classic queues.
+
+| quorum.queues.replication.factor
+| Strictly positive integer. The replication factor to use when creating quorum queues.
+
+| quorum.queues.delivery.limit
+| Strictly positive integer. Value for x-delivery-limit queue parameter, default to none. Setting a delivery limit can
+prevent RabbitMQ outage if message processing fails. Read https://www.rabbitmq.com/docs/quorum-queues#poison-message-handling
+
+| hosts
+| Optional, default to the host specified as part of the URI.
+Allow creating cluster aware connections.
+A coma separated list of hosts, example: hosts=ip1:5672,ip2:5672
+
+| mailqueue.publish.confirm.enabled
+| Whether or not to enable publish confirms for the mail queue. Optional boolean, defaults to true.
+
+| event.bus.publish.confirm.enabled
+| Whether or not to enable publish confirms for the event bus. Optional boolean, defaults to true.
+
+| event.bus.notification.durability.enabled
+| Whether or not the queue backing notifications should be durable. Optional boolean, defaults to true.
+
+| event.bus.propagate.dispatch.error
+| Whether to propagate errors back to the callers when eventbus fails to dispatch group events to RabbitMQ (then store the failed events in the event dead letters).
+Optional boolean, defaults to true.
+
+| vhost
+| Optional string. This parameter is only a workaround to support invalid URIs containing character like '_'.
+You still need to specify the vhost in the uri parameter.
+
+|===
+
+== Tuning RabbitMQ for quorum queue use
+
+While quorum queues are great at preserving your data and enabling High Availability, they demand more resources and
+a greater care than regular RabbitMQ queues.
+
+See link:https://www.rabbitmq.com/docs/quorum-queues#performance-tuning[this section of RabbitMQ documentation regarding RabbitMQ quroum queue performance tunning].
+
+ - Provide decent amount of RAM memory to RabbitMQ. 4GB is a good start.
+ - Setting a delivery limit is advised as looping messages can cause extreme memory consumptions onto quorum queues.
+ - Set up Raft for small messages:
+
+....
+raft.segment_max_entries = 32768
+....
+
+== RabbitMQ Tasks Configuration
+
+Tasks are WebAdmin triggered long running jobs. RabbitMQ is used to organise their execution in a work queue,
+with an exclusive consumer.
+
+.rabbitmq.properties content
+|===
+| Property name | explanation
+
+| task.consumption.enabled
+| Whether to enable task consumption on this node.
+Disable with caution (this only makes sense in a distributed setup where other nodes consume tasks).
+Defaults to true.
+
+Limitation: Sometimes, some tasks running on James can be very heavy and take a couple of hours to complete.
+If other tasks are being triggered meanwhile on WebAdmin, they go on the TaskManagerWorkQueue and James unack them,
+telling RabbitMQ it will consume them later. If they don't get consumed before the consumer timeout setup in
+RabbitMQ (default being 30 minutes), RabbitMQ closes the channel on an exception. It is thus advised to declare a
+longer timeout in rabbitmq.conf. More https://www.rabbitmq.com/consumers.html#acknowledgement-timeout[here].
+
+| task.queue.consumer.timeout
+| Task queue consumer timeout.
+
+Optional. Duration (support multiple time units cf `DurationParser`), defaults to 1 day.
+
+Required at least RabbitMQ version 3.12 to have effect.
+This is used to avoid the task queue consumer (which could run very long tasks) being disconnected by RabbitMQ after the default acknowledgement timeout 30 minutes.
+References: https://www.rabbitmq.com/consumers.html#acknowledgement-timeout.
+
+|===
\ No newline at end of file
diff --git a/docs/modules/servers/partials/configure/recipientrewritetable.adoc b/docs/modules/servers/partials/configure/recipientrewritetable.adoc
new file mode 100644
index 00000000000..67edfe32ad5
--- /dev/null
+++ b/docs/modules/servers/partials/configure/recipientrewritetable.adoc
@@ -0,0 +1,15 @@
+Here are explanations on the different kinds about xref:{pages-path}/architecture/index.adoc#_recipient_rewrite_tables[recipient rewriting].
+
+Consult this link:{sample-configuration-prefix-url}/recipientrewritetable.xml[example]
+to get some examples and hints.
+
+.recipientrewritetable.xml
+|===
+| Property name | explanation
+
+| recursiveMapping
+| If set to false only the first mapping will get processed - Default true.
+
+| mappingLimit
+|By setting the mappingLimit you can specify how much mapping will get processed before a bounce will send. This avoids infinity loops. Default 10.
+|===
diff --git a/docs/modules/servers/partials/configure/redis.adoc b/docs/modules/servers/partials/configure/redis.adoc
new file mode 100644
index 00000000000..183e335b671
--- /dev/null
+++ b/docs/modules/servers/partials/configure/redis.adoc
@@ -0,0 +1,28 @@
+This configuration helps you configure components using Redis. This so far only includes optional rate limiting component.
+
+Consult this link:https://github.com/apache/james-project/blob/fabfdf4874da3aebb04e6fe4a7277322a395536a/server/mailet/rate-limiter-redis/redis.properties[example]
+to get some examples and hints.
+
+== Redis Configuration
+
+.redis.properties content
+|===
+| Property name | explanation
+
+| redisURL
+| the Redis URI pointing to Redis server. Compulsory.
+
+| redis.topology
+| Redis server topology. Defaults to standalone. Possible values: standalone, cluster, master-replica
+
+| redis.readFrom
+| The property to determine how Lettuce routes read operations to Redis server with topologies other than standalone. Defaults to master. Possible values: master, masterPreferred, replica, replicaPreferred, any
+
+Reference: https://github.com/redis/lettuce/wiki/ReadFrom-Settings
+
+| redis.ioThreads
+| IO threads to be using for the underlying Netty networking resources. If unspecified driver defaults applies.
+
+| redis.workerThreads
+| Worker threads to be using for the underlying driver. If unspecified driver defaults applies.
+|===
diff --git a/docs/modules/servers/partials/configure/remote-delivery-error-handling.adoc b/docs/modules/servers/partials/configure/remote-delivery-error-handling.adoc
new file mode 100644
index 00000000000..25d7c121bcc
--- /dev/null
+++ b/docs/modules/servers/partials/configure/remote-delivery-error-handling.adoc
@@ -0,0 +1,117 @@
+The advanced server mailQueue implemented by combining RabbitMQ for messaging and {mailet-repository-path-prefix} for administrative operation
+does not support delays.
+
+Delays are an important feature for Mail Exchange servers, allowing to defer in time the retries, potentially letting the
+time for the remote server to recover. Furthermore, they enable implementation of advanced features like throttling and
+rate limiting of emails sent to a given domain.
+
+As such, the use of the distributed server as a Mail Exchange server is currently discouraged.
+
+However, for operators willing to inter-operate with a limited set of well-identified, trusted remote mail servers, such
+limitation can be reconsidered. The main concern then become error handling for remote mail server failures. The following
+document will present a well tested strategy for Remote Delivery error handling leveraging standards Mail Processing components
+and mechanisms.
+
+== Expectations
+
+Such a solution should:
+
+- Attempt delivery a single time
+- Store transient and permanent failure in different mail repositories
+- After a given number of tries, transient failures should be considered permanent
+
+== Design
+
+image::remote-delivery-error-handling.png[Schema detailing the proposed solution]
+
+- Remote Delivery is configured for performing a single retry.
+- Remote Delivery attaches the error code and if the failure is permanent/temporary when transferring failed emails to the
+bounce processor.
+- The specified bounce processor will categorise the failure, and store temporary and permanent failures in different
+mail repositories.
+- A reprocessing of the temporary delivery errors mailRepository needs to be scheduled in a recurring basis. For
+instance via a CRON job calling the right webadmin endpoint.
+- A counter ensures that a configured number of delivery tries is not exceeded.
+
+=== Limitation
+
+MailRepositories are not meant for transient data storage, and thus are prone to tombstone issues.
+
+This might be acceptable if you need to send mail to well-known peers. For instance handling your mail gateway failures.
+However a Mail Exchange server doing relay on the internet would quickly hit this limitation.
+
+Also note that external triggering of the retry process is needed.
+
+== Operation
+
+Here is an example of configuration achieving the proposed solution:
+
+[subs=attributes+,xml]
+----
+
+
+
+ outgoing
+ 0
+ 0
+ 10
+ true
+
+ remote-delivery-error
+
+
+
+ {mailet-repository-path-prefix}://var/mail/error/remote-delivery/permanent/
+
+
+
+
+
+
+ {mailet-repository-path-prefix}://var/mail/error/remote-delivery/temporary/
+
+
+
+ {mailet-repository-path-prefix}://var/mail/error/remote-delivery/permanent/
+
+
+
+ {mailet-repository-path-prefix}://var/mail/error/
+
+
+----
+
+Note:
+
+- The *relay* processor holds a RemoteDelivery mailet configured to do a single try, at most 5 times (see the AtMost matcher).
+Mails exceeding the AtMost condition are considered as permanent delivery errors. Delivery errors are sent to the
+*remote-delivery-error* processor.
+- The *remote-delivery-error* stores temporary and permanent errors.
+- Permanent relay errors are stored in `{mailet-repository-path-prefix}://var/mail/error/remote-delivery/permanent/`.
+- Temporary relay errors are stored in `{mailet-repository-path-prefix}://var/mail/error/remote-delivery/temporary/`.
+
+In order to retry the relay of temporary failed emails, operators will have to configure a cron job for reprocessing
+emails from *{mailet-repository-path-prefix}://var/mail/error/remote-delivery/temporary/* mailRepository into the *relay* processor.
+
+This can be achieved via the following webAdmin call :
+
+[subs=attributes+]
+----
+curl -XPATCH 'http://ip:8000/mailRepositories/{mailet-repository-path-prefix}%3A%2F%2Fvar%2Fmail%2Ferror%2Fremote-delivery%2Ftemporary%2F/mails?action=reprocess&processor=relay'
+----
+
+See xref:{pages-path}/operate/webadmin.adoc#_reprocessing_mails_from_a_mail_repository[the documentation].
+
+Administrators need to keep a close eye on permanent errors (that might require audit, and potentially contacting the remote
+service supplier).
+
+To do so, one should regularly audit the content of *{mailet-repository-path-prefix}://var/mail/error/remote-delivery/permanent/*. This can be done
+via webAdmin calls:
+
+[subs=attributes+]
+----
+curl -XGET 'http://ip:8000/mailRepositories/{mailet-repository-path-prefix}%3A%2F%2Fvar%2Fmail%2Ferror%2Fremote-delivery%2Ftemporary%2F/mails'
+----
+
+See xref:{pages-path}/operate/webadmin.adoc#_listing_mails_contained_in_a_mail_repository[the documentation].
diff --git a/docs/modules/servers/partials/configure/search.adoc b/docs/modules/servers/partials/configure/search.adoc
new file mode 100644
index 00000000000..239e266c21e
--- /dev/null
+++ b/docs/modules/servers/partials/configure/search.adoc
@@ -0,0 +1,15 @@
+This configuration helps you configure the components used to back search.
+
+.search.properties content
+|===
+| Property name | explanation
+
+| implementation
+| The implementation to be used for search. Should be one of:
+ - *opensearch* : Index and search mails into OpenSearch.
+ - *scanning* : Do not index documents and perform scanning search, scrolling mailbox for matching contents.
+ This implementation can have a prohibitive cost.
+ - *opensearch-disabled* : Saves events to index into event dead letter. Make searches fails.
+ This is useful to start James without OpenSearch while still tracking messages to index for later recovery. This
+ can be used in order to ease delays for disaster recovery action plans.
+|===
\ No newline at end of file
diff --git a/docs/modules/servers/partials/configure/sieve.adoc b/docs/modules/servers/partials/configure/sieve.adoc
new file mode 100644
index 00000000000..7ecd4c452f7
--- /dev/null
+++ b/docs/modules/servers/partials/configure/sieve.adoc
@@ -0,0 +1,89 @@
+James servers are able to evaluate and execute Sieve scripts.
+
+Sieve is an extensible mail filtering language. It's limited
+expressiveness (no loops or variables, no tests with side
+effects) allows user created scripts to be run safely on email
+servers. Sieve is targeted at the final delivery phase (where
+an incoming email is transferred to a user's mailbox).
+
+The following Sieve capabilities are supported by Apache James:
+
+ - link:https://www.ietf.org/rfc/rfc2234.txt[RFC 2234 ABNF]
+ - link:https://www.ietf.org/rfc/rfc2244.txt[RFC 2244 ACAP]
+ - link:https://www.ietf.org/rfc/rfc2298.txt[RFC 2298 MDN]
+ - link:https://tools.ietf.org/html/rfc5228[RFC 5228 Sieve]
+ - link:https://tools.ietf.org/html/rfc4790[RFC 4790 IAPCR]
+ - link:https://tools.ietf.org/html/rfc5173[RFC 5173 Body Extension]
+ - link:https://datatracker.ietf.org/doc/html/rfc5230[RFC 5230 Vacations]
+
+To be correctly executed, please note that the *Sieve* mailet is required to be positioned prior the
+*LocalDelivery* mailet.
+
+== Managing Sieve scripts
+
+A user willing to manage his Sieve scripts on the server can do so via several means:
+
+He can ask an admin to upload his script via the xref:{pages-path}/operate/cli.adoc[CLI]
+
+As James supports ManageSieve (link:https://datatracker.ietf.org/doc/html/rfc5804[RFC-5804]) a user
+can thus use compatible software to manage his Sieve scripts.
+
+== ManageSieve protocol
+
+*WARNING*: ManageSieve protocol should be considered experimental.
+
+Consult link:{sample-configuration-prefix-url}/managesieveserver.xml[managesieveserver.xml]
+in GIT to get some examples and hints.
+
+The service is controlled by a configuration block in the managesieveserver.xml.
+The managesieveserver tag defines the boundaries of the configuration block. It encloses
+all the relevant configuration for the ManageSieve server. The behavior of the ManageSieve service is
+controlled by the attributes and children of this tag.
+
+This tag has an optional boolean attribute - *enabled* - that defines whether the service is active or not.
+The value defaults to "false" if
+not present.
+
+The standard children of the managesieveserver tag are:
+
+.managesieveserver.xml content
+|===
+| Property name | explanation
+
+| bind
+| Configure this to bind to a specific inetaddress. This is an optional integer value. This value is the port on which this ManageSieve server is configured to listen. If the tag or value is absent then the service
+will bind to all network interfaces for the machine If the tag or value is omitted, the value will default to the standard ManageSieve port (port 4190 is the well-known/IANA registered port for ManageSieve.)
+
+| tls
+| Set to true to support STARTTLS or SSL for the Socket.
+To use this you need to copy sunjce_provider.jar to /path/james/lib directory. To create a new keystore execute:
+`keytool -genkey -alias james -keyalg RSA -storetype PKCS12 -keystore /path/to/james/conf/keystore`.
+Please note that each ManageSieve server exposed on different port can specify its own keystore, independently from any other
+TLS based protocols.
+
+| connectionBacklog
+| Number of connection backlog of the server (maximum number of queued connection requests)
+
+| connectiontimeout
+| Connection timeout in seconds
+
+| connectionLimit
+| Set the maximum simultaneous incoming connections for this service
+
+| connectionLimitPerIP
+| Set the maximum simultaneous incoming connections per IP for this service
+
+| bossWorkerCount
+| Set the maximum count of boss threads. Boss threads are responsible for accepting incoming ManageSieve connections
+and initializing associated resources. Optional integer, by default, boss threads are not used and this responsibility is being dealt with
+by IO threads.
+
+| ioWorkerCount
+| Set the maximum count of IO threads. IO threads are responsible for receiving incoming ManageSieve messages and framing them
+(split line by line). IO threads also take care of compression and SSL encryption. Their tasks are short-lived and non-blocking.
+Optional integer, defaults to 2 times the count of CPUs.
+
+| maxExecutorCount
+| Set the maximum count of worker threads. Worker threads takes care of potentially blocking tasks like executing ManageSieve commands.
+Optional integer, defaults to 16.
+|===
\ No newline at end of file
diff --git a/docs/modules/servers/partials/configure/smtp-hooks.adoc b/docs/modules/servers/partials/configure/smtp-hooks.adoc
new file mode 100644
index 00000000000..a660051a1d6
--- /dev/null
+++ b/docs/modules/servers/partials/configure/smtp-hooks.adoc
@@ -0,0 +1,364 @@
+This documentation page lists and documents SMTP hooks that can be used within the
+{server-name} SMTP protocol stack in order to customize the way your SMTP server
+behaves without of the box components.
+
+== DNSRBLHandler
+
+This command handler check against https://www.wikiwand.com/en/Domain_Name_System-based_Blackhole_List[RBL-Lists]
+(Real-time Blackhole List).
+
+If getDetail is set to true it try to retrieve information from TXT Record
+why the ip was blocked. Default to false.
+
+before you enable out the DNS RBL handler documented as an example below,
+please take a moment to review each block in the list.
+We have included some that various JAMES committers use,
+but you must decide which, if any, are appropriate
+for your environment.
+
+The mail servers hosting
+@apache.org mailing lists, for example, use a
+slightly different list than we have included below.
+And it is likely that most JAMES committers also have
+slightly different sets of lists.
+
+The SpamAssassin user's list would be one good place to discuss the
+measured quality of various block lists.
+
+NOTA BENE: the domain names, below, are terminated
+with '.' to ensure that they are absolute names in
+DNS lookups. Under some circumstances, names that
+are not explicitly absolute could be treated as
+relative names, leading to incorrect results. This
+has been observed on *nix and MS-Windows platforms
+by users of multiple mail servers, and is not JAMES
+specific. If you are unsure what this means for you,
+please speak with your local system/network admins.
+
+This handler should be considered experimental.
+
+Example configuration:
+
+[source,xml]
+....
+
+
+
+ false
+
+ query.bondedsender.org.
+ sbl-xbl.spamhaus.org.
+ dul.dnsbl.sorbs.net.
+ list.dsbl.org.
+
+
+
+....
+
+== DSN hooks
+
+The {server-name} has optional support for DSN (link:https://tools.ietf.org/html/rfc3461[RFC-3461])
+
+Please read carefully xref:{pages-path}/configure/dsn.adoc[this page].
+
+[source,xml]
+....
+
+ <...>
+
+
+
+
+
+ <...>
+
+
+
+....
+
+Note that a specific configuration of xref:{pages-path}/configure/mailetcontainer.adoc[mailetcontainer.xml] is
+required as well to be spec compliant.
+
+== MailPriorityHandler
+
+This handler can add a hint to the mail which tells the MailQueue which email should get processed first.
+
+Normally the MailQueue will just handle Mails in FIFO manner.
+
+Valid priority values are 1,5,9 where 9 is the highest.
+
+This handler should be considered experimental.
+
+Example configuration:
+
+[source,xml]
+....
+
+
+
+
+
+ yourdomain1
+ 1
+
+
+ yourdomain2
+ 9
+
+
+
+
+....
+
+== MaxRcptHandler
+If activated you can limit the maximal recipients.
+
+This handler should be considered experimental.
+
+Example configuration:
+
+[source,xml]
+....
+
+
+
+ 10
+
+
+....
+
+== POP3BeforeSMTPHandler
+
+This connect handler can be used to enable POP3 before SMTP support.
+
+Please note that only the ip get stored to identify an authenticated client.
+
+The expireTime is the time after which an ipAddress is handled as expired.
+
+This handler should be considered as unsupported.
+
+Example configuration:
+
+[source,xml]
+....
+
+
+
+ 1 hour
+
+
+....
+
+== ResolvableEhloHeloHandler
+
+Checks for resolvable HELO/EHLO before accept the HELO/EHLO.
+
+If checkAuthNetworks is set to true sender domain will be checked also for clients that
+are allowed to relay. Default is false.
+
+This handler should be considered experimental.
+
+Example configuration:
+
+[source,xml]
+....
+
+
+
+
+....
+
+== ReverseEqualsEhloHeloHandler
+
+Checks HELO/EHLO is equal the reverse of the connecting client before accept it
+If checkAuthNetworks is set to true sender domain will be checked also for clients that
+are allowed to relay. Default is false.
+
+This handler should be considered experimental.
+
+Example configuration:
+
+[source,xml]
+....
+
+
+
+
+....
+
+== SetMimeHeaderHandler
+
+This handler allows you to add mime headers to the processed mails.
+
+This handler should be considered experimental.
+
+Example configuration:
+
+[source,xml]
+....
+
+
+
+ SPF-test
+ passed
+
+
+....
+
+== SpamAssassinHandler
+
+This MessageHandler could be used to check message against spamd before
+accept the email. So it's possible to reject a message on smtplevel if a
+configured hits amount is reached.
+
+This handler should be considered experimental.
+
+Example configuration:
+
+[source,xml]
+....
+
+
+
+ 127.0.0.1
+ 783
+ 10
+
+
+....
+
+== SPFHandler
+
+This command handler can be used to reject emails with not match the SPF record of the sender domain.
+
+If checkAuthNetworks is set to true sender domain will be checked also for clients that
+are allowed to relay. Default is false.
+
+This handler should be considered experimental.
+
+Example configuration:
+
+[source,xml]
+....
+
+
+
+ false
+ true
+
+
+....
+
+== URIRBLHandler
+
+This MessageHandler could be used to extract domain out of the message and check
+this domains against uriRbllists. See http://www.surbl.org for more information.
+The message get rejected if a domain matched.
+
+This handler should be considered experimental.
+
+Example configuration:
+
+[source,xml]
+....
+
+
+
+ reject
+ true
+
+ multi.surbl.org
+
+
+
+....
+
+== ValidRcptHandler
+
+With ValidRcptHandler, all email will get rejected which has no valid user.
+
+You need to add the recipient to the validRecipient list if you want
+to accept email for a recipient which not exist on the server.
+
+If you want James to act as a spamtrap or honeypot, you may comment ValidRcptHandler
+and implement the needed processors in spoolmanager.xml.
+
+This handler should be considered stable.
+
+Example configuration:
+
+[source,xml]
+....
+
+
+
+
+....
+
+== ValidSenderDomainHandler
+
+If activated mail is only accepted if the sender contains
+a resolvable domain having a valid MX Record or A Record associated!
+
+If checkAuthNetworks is set to true sender domain will be checked also for clients that
+are allowed to relay. Default is false.
+
+Example configuration:
+
+[source,xml]
+....
+
+
+
+
+....
+
+== FUTURERELEASE hooks
+
+The {server-name} has optional support for FUTURERELEASE (link:https://www.rfc-editor.org/rfc/rfc4865.html[RFC-4865])
+
+[source,xml]
+....
+
+ <...>
+
+
+
+
+
+
+....
+
+== DKIM checks hooks
+
+Hook for verifying DKIM signatures of incoming mails.
+
+This hook can be restricted to specific sender domains and authenticate those emails against
+their DKIM signature. Given a signed outgoing traffic this hook can use operators to accept legitimate
+emails emitted by their infrastructure but redirected without envelope changes to there own domains by
+some intermediate third parties. See link:https://issues.apache.org/jira/browse/JAMES-4032[JAMES-4032].
+
+Supported configuration elements:
+
+- *forceCRLF*: Should CRLF be forced when computing body hashes.
+- *onlyForSenderDomain*: If specified, the DKIM checks are applied just for the emails whose MAIL FROM specifies this domain. If unspecified, all emails are checked (default).
+- *signatureRequired*: If DKIM signature is checked, the absence of signature will generate failure. Defaults to false.
+- *expectedDToken*: If DKIM signature is checked, the body should contain at least one DKIM signature with this d token. If unspecified, all d tokens are considered valid (default).
+
+Example handlerchain configuration for `smtpserver.xml`:
+
+[source,xml]
+....
+
+
+ true
+ apache.org
+ true
+ apache.org
+
+
+
+....
+
+Would allow emails using `apache.org` as a MAIL FROM domain if, and only if they contain a
+valid DKIM signature for the `apache.org` domain.
\ No newline at end of file
diff --git a/docs/modules/servers/partials/configure/smtp.adoc b/docs/modules/servers/partials/configure/smtp.adoc
new file mode 100644
index 00000000000..d2d8d519c4e
--- /dev/null
+++ b/docs/modules/servers/partials/configure/smtp.adoc
@@ -0,0 +1,315 @@
+== Incoming SMTP
+
+Consult this link:{sample-configuration-prefix-url}/smtpserver.xml[example]
+to get some examples and hints.
+
+The SMTP service is controlled by a configuration block in the smptserver.xml.
+The smtpserver tag defines the boundaries of the configuration block. It encloses
+all the relevant configuration for the SMTP server. The behavior of the SMTP service is
+controlled by the attributes and children of this tag.
+
+This tag has an optional boolean attribute - *enabled* - that defines whether the service is active or not. The value defaults to "true" if
+not present.
+
+The standard children of the smtpserver tag are:
+
+.smtpserver.xml content
+|===
+| Property name | explanation
+
+| bind
+| A list of address:port separed by comma - This is an optional value. If present, this value is a string describing
+the IP address to which this service should be bound. If the tag or value is absent then the service
+will bind to all network interfaces for the machine on port 25. Port 25 is the well-known/IANA registered port for SMTP.
+Port 465 is the well-known/IANA registered port for SMTP over TLS.
+
+| connectBacklog
+|The IP address (host name) the MBean Server will bind/listen to.
+
+| tls
+| Set to true to support STARTTLS or SSL for the Socket.
+To use this you need to copy sunjce_provider.jar to /path/james/lib directory. To create a new keystore execute:
+`keytool -genkey -alias james -keyalg RSA -storetype PKCS12 -keystore /path/to/james/conf/keystore`.
+The algorithm is optional and only needs to be specified when using something other
+than the Sun JCE provider - You could use IbmX509 with IBM Java runtime.
+Please note that each SMTP/LMTP server exposed on different port can specify its own keystore, independently from any other
+TLS based protocols.
+
+| helloName
+| This is a required tag with an optional body that defines the server name
+used in the initial service greeting. The tag may have an optional attribute - *autodetect*. If
+the autodetect attribute is present and true, the service will use the local hostname
+returned by the Java libraries. If autodetect is absent or false, the body of the tag will be used. In
+this case, if nobody is present, the value "localhost" will be used.
+
+| connectionTimeout
+| This is an optional tag with a non-negative integer body. Connection timeout in seconds.
+
+| connectionLimit
+| Set the maximum simultaneous incoming connections for this service.
+
+| connectionLimitPerIP
+| Set the maximum simultaneous incoming connections per IP for this service.
+
+| proxyRequired
+| Enables proxy support for this service for incoming connections. HAProxy's protocol
+(https://www.haproxy.org/download/2.7/doc/proxy-protocol.txt) is used and might be compatible
+with other proxies (e.g. traefik). If enabled, it is *required* to initiate the connection
+using HAProxy's proxy protocol.
+
+| authRequired
+| (deprecated) use auth.announce instead.
+
+This is an optional tag with a boolean body. If true, then the server will
+announce authentication after HELO command. If this tag is absent, or the value
+is false then the client will not be prompted for authentication. Only simple user/password authentication is
+supported at this time. Supported values:
+
+ * true: announced only to not authorizedAddresses
+
+ * false: don't announce AUTH. If absent, *authorizedAddresses* are set to a wildcard to accept all remote hosts.
+
+ * announce: like true, but always announce AUTH capability to clients
+
+Please note that emails are only relayed if, and only if, the user did authenticate, or is in an authorized network,
+regardless of this option.
+
+| auth.announce
+| This is an optional tag. Possible values are:
+
+* never: Don't announce auth.
+
+* always: always announce AUTH capability to clients.
+
+* forUnauthorizedAddresses: announced only to not authorizedAddresses
+
+Please note that emails are only relayed if, and only if, the user did authenticate, or is in an authorized network,
+regardless of this option.
+
+| auth.requireSSL
+| This is an optional tag, defaults to true. If true, authentication is not advertised via capabilities on unencrypted
+channels.
+
+| auth.plainAuthEnabled
+| This is an optional tag, defaults to true. If false, AUTH PLAIN and AUTH LOGIN will not be exposed. This setting
+can be used to enforce strong authentication mechanisms.
+
+| auth.oidc.oidcConfigurationURL
+| Provide OIDC url address for information to user. Only configure this when you want to authenticate SMTP server using a OIDC provider.
+
+| auth.oidc.jwksURL
+| Provide url to get OIDC's JSON Web Key Set to validate user token. Only configure this when you want to authenticate SMTP server using a OIDC provider.
+
+| auth.oidc.claim
+| Claim string uses to identify user. E.g: "email_address". Only configure this when you want to authenticate SMTP server using a OIDC provider.
+
+| auth.oidc.scope
+| An OAuth scope that is valid to access the service (RF: RFC7628). Only configure this when you want to authenticate SMTP server using a OIDC provider.
+
+| auth.oidc.introspection.url
+| Optional. An OAuth introspection token URL will be called to validate the token (RF: RFC7662).
+Only configure this when you want to validate the revocation token by the OIDC provider.
+Note that James always verifies the signature of the token even whether this configuration is provided or not.
+
+| auth.oidc.introspection.auth
+| Optional. Provide Authorization in header request when introspecting token.
+Eg: `Basic xyz`
+
+| auth.oidc.userinfo.url
+| Optional. An Userinfo URL will be called to validate the token (RF: OpenId.Core https://openid.net/specs/openid-connect-core-1_0.html).
+Only configure this when you want to validate the revocation token by the OIDC provider.
+Note that James always verifies the signature of the token even whether this configuration is provided or not.
+James will ignore check token by userInfo if the `auth.oidc.introspection.url` is already configured
+
+| authorizedAddresses
+| Authorize specific addresses/networks.
+
+If you use SMTP AUTH, addresses that match those specified here will
+be permitted to relay without SMTP AUTH. If you do not use SMTP
+AUTH, and you specify addresses here, then only addresses that match
+those specified will be permitted to relay.
+
+Addresses may be specified as a IP address or domain name, with an
+optional netmask, e.g.,
+
+127.*, 127.0.0.0/8, 127.0.0.0/255.0.0.0, and localhost/8 are all the same
+
+See also the RemoteAddrNotInNetwork matcher in the transport processor.
+You would generally use one OR the other approach.
+
+| verifyIdentity
+| This is an optional tag. This options governs MAIL FROM verifications, and prevents spoofing of the MAIL FROM
+envelop field.
+
+The following values are supported:
+
+ - `strict`: use of a local domain in MAIL FROM requires the SMTP client to be authenticated with a matching user or one
+ of its aliases. It will verify that the sender address matches the address of the user or one of its alias (from user or domain aliases).
+ This prevents a user of your mail server from acting as someone else
+ - `disabled`: no check is performed and third party are free to send emails as local users. Note that relaying emails will
+ need third party to be authenticated thus preventing open relays.
+ - `relaxed`: Based on a simple heuristic to determine if the SMTP client is a MUA or a MX (use of a valid domain in EHLO),
+ we do act as `strict` for MUAs thus prompting them early for the need of authentication, but accept use of local MAIL FROM for
+ MX. Authentication can then be delayed to later, eg after DATA transaction with the DKIMHook which might allow email looping through
+ third party domains via mail redirection, effectively enforcing that the mail originates from our servers. See
+ link:https://issues.apache.org/jira/browse/JAMES-4032[JAMES-4032] for detailed explanation.
+
+Backward compatibility is provided and thus the following values are supported:
+
+ - `true`: act as `strict`
+ - `false`: act as `disabled`
+
+| maxmessagesize
+| This is an optional tag with a non-negative integer body. It specifies the maximum
+size, in kbytes, of any message that will be transmitted by this SMTP server. It is a service-wide, as opposed to
+a per user, limit. If the value is zero then there is no limit. If the tag isn't specified, the service will
+default to an unlimited message size. Must be a positive integer, optionally with a unit: B, K, M, G.
+
+| heloEhloEnforcement
+| This sets whether to enforce the use of HELO/EHLO salutation before a
+MAIL command is accepted. If unspecified, the value defaults to true.
+
+| smtpGreeting
+| This sets the SMTPGreeting which will be used when connect to the smtpserver
+If none is specified a default is generated
+
+| handlerchain
+| The configuration handler chain. See xref:{pages-path}/configure/smtp-hooks.adoc[this page] for configuring out-of the
+box extra SMTP handlers and hooks.
+
+| bossWorkerCount
+| Set the maximum count of boss threads. Boss threads are responsible for accepting incoming SMTP connections
+and initializing associated resources. Optional integer, by default, boss threads are not used and this responsibility is being dealt with
+by IO threads.
+
+| ioWorkerCount
+| Set the maximum count of IO threads. IO threads are responsible for receiving incoming SMTP messages and framing them
+(split line by line). IO threads also take care of compression and SSL encryption. Their tasks are short-lived and non-blocking.
+Optional integer, defaults to 2 times the count of CPUs.
+
+| maxExecutorCount
+| Set the maximum count of worker threads. Worker threads takes care of potentially blocking tasks like executing SMTP commands.
+Optional integer, defaults to 16.
+
+| useEpoll
+| true or false - If true uses native EPOLL implementation for Netty otherwise uses NIO. Defaults to false.
+
+| gracefulShutdown
+| true or false - If true attempts a graceful shutdown, which is safer but can take time. Defaults to true.
+
+| disabledFeatures
+| Extended SMTP features to hide in EHLO responses.
+|===
+
+=== OIDC setup
+James SMTP support XOAUTH2 authentication mechanism which allow authenticating against a OIDC providers.
+Please configure `auth.oidc` part to use this.
+
+We do supply an link:https://github.com/apache/james-project/tree/master/examples/oidc[example] of such a setup.
+It uses the Keycloak OIDC provider, but usage of similar technologies is definitely doable.
+
+== About open relays
+
+Authenticated SMTP is a method of securing your SMTP server. With SMTP AUTH enabled senders who wish to
+relay mail through the SMTP server (that is, send mail that is eventually to be delivered to another SMTP
+server) must authenticate themselves to Apache James Server before sending their message. Mail that is to be delivered
+locally does not require authentication. This method ensures that spammers cannot use your SMTP server
+to send unauthorized mail, while still enabling users who may not have fixed IP addresses to send their
+messages.
+
+Mail servers that allow spammers to send unauthorized email are known as open relays. So SMTP AUTH
+is a mechanism for ensuring that your server is not an open relay.
+
+It is extremely important that your server not be configured as an open relay. Aside from potential
+costs associated with usage by spammers, connections from servers that are determined to be open relays
+are routinely rejected by SMTP servers. This can severely impede the ability of your mail server to
+send mail.
+
+At this time Apache James Server only supports simple user name / password authentication.
+
+As mentioned above, SMTP AUTH requires that Apache James Server be able to distinguish between mail intended
+for local delivery and mail intended for remote delivery. Apache James Server makes this determination by matching the
+domain to which the mail was sent against the *DomainList* component, configured by
+xref:{pages-path}/configure/domainlist.adoc[*domainlist.xml*].
+
+The {server-name} is configured out of the box so as to not serve as an open relay for spammers. This is done
+by relayed emails originate from a trusted source. This includes:
+
+* Authenticated SMTP/JMAP users
+* Mails generated by the server (eg: bounces)
+* Mails originating from a trusted network as configured in *smtpserver.xml*
+
+If you wish to ensure that authenticated users can only send email from their own account, you may
+optionally set the verifyIdentity element of the smtpserver configuration block to "true".
+
+=== Verification
+
+Verify that you have not inadvertently configured your server as an open relay. This is most easily
+accomplished by using the service provided at https://mxtoolbox.com/diagnostic.aspx[mxtoolbox.com]. mxtoolbox.com will
+check your mail server and inform you if it is an open relay. This tool further more verifies additional properties like:
+
+* Your DNS configuration, especially that you mail server IP has a valid reverse DNS entry
+* That your SMTP connection is secured
+* That you are not an OpenRelay
+* This website also allow a quick lookup to ensure your mail server is not in public blacklists.
+
+Of course it is also necessary to confirm that users and log in and send
+mail through your server. This can be accomplished using any standard mail client (i.e. Thunderbird, Outlook,
+Eudora, Evolution).
+
+== LMTP Configuration
+
+Consult this link:{sample-configuration-prefix-url}/lmtpserver.xml[example]
+to get some examples and hints.
+
+The configuration is the same of for SMTP.
+
+By default, it is deactivated. You can activate it alongside SMTP and bind for example on port 24.
+
+The default LMTP server stores directly emails in user mailboxes, without further treatment.
+
+However we do ship an alternative handler chain allowing to execute the mailet container, thus achieving a behaviour similar
+to the default SMTP protocol. Here is how to achieve this:
+
+[source,xml]
+....
+
+
+ lmtpserver
+ 0.0.0.0:24
+ 200
+ 1200
+ 0
+ 0
+ 0
+
+
+
+
+
+....
+
+Note that by default the mailet container is executed with all recipients at once and do not allow per recipient
+error reporting. An option splitExecution allow to execute the mailet container for each recipient separately and mitigate this
+limitation at the cost of performance.
+
+[source,xml]
+....
+
+
+ lmtpserver
+ 0.0.0.0:24
+ 200
+ 1200
+ 0
+ 0
+ 0
+
+
+
+ true
+
+
+
+
+....
\ No newline at end of file
diff --git a/docs/modules/servers/partials/configure/spam.adoc b/docs/modules/servers/partials/configure/spam.adoc
new file mode 100644
index 00000000000..5e5b8b2d6f0
--- /dev/null
+++ b/docs/modules/servers/partials/configure/spam.adoc
@@ -0,0 +1,191 @@
+Anti-Spam system can be configured via two main different mechanisms:
+
+* SMTP Hooks;
+* Mailets;
+
+== AntiSpam SMTP Hooks
+
+"FastFail" SMTP Hooks acts to reject before spooling
+on the SMTP level. The Spam detector hook can be used as a fastfail hook, therefore
+Spam filtering system must run as a server on the same machine as the Apache James Server.
+
+SMTP Hooks for non-existent users, DSN filter, domains with invalid MX record,
+can also be configured.
+
+*SpamAssassinHandler* (experimental) also enables to classify the messages as spam or not
+with a configurable score threshold (`0.0`, non-configurable). Only a global database is supported. Per user spam
+detection is not supported by this hook.
+
+== AntiSpam Mailets
+
+James' repository provide two AntiSpam mailets: SpamAssassin and RspamdScanner.
+We can select one in them for filtering spam mail.
+
+* *SpamAssassin and RspamdScanner* Mailet is designed to classify the messages as spam or not
+with a configurable score threshold. Usually a message will only be
+considered as spam if it matches multiple criteria; matching just a single test
+will not usually be enough to reach the threshold. Note that this mailet is executed on a per-user basis.
+
+=== Rspamd
+
+The Rspamd extension (optional) requires an extra configuration file `rspamd.properties` to configure RSpamd connection
+
+.rspamd.properties content
+|===
+| Property name | explanation
+
+| rSpamdUrl
+| URL defining the Rspamd's server. Eg: http://rspamd:11334
+
+| rSpamdPassword
+| Password for pass authentication when request to Rspamd's server. Eg: admin
+
+| rspamdTimeout
+| Integer. Timeout for http requests to Rspamd. Default to 15 seconds.
+
+| perUserBayes
+| Boolean. Whether to scan/learn mails using per-user Bayes. Default to false.
+|===
+
+`RspamdScanner` supports the following options:
+
+* You can specify the `virusProcessor` if you want to enable virus scanning for mail. Upon configurable `virusProcessor`
+you can specify how James process mail virus. We provide a sample Rspamd mailet and `virusProcessor` configuration:
+
+* You can specify the `rejectSpamProcessor`. Emails marked as `rejected` by Rspamd will be redirected to this
+processor. This corresponds to emails with the highest spam score, thus delivering them to users as marked as spam
+might not even be desirable.
+
+* The `rewriteSubject` option allows to rewritte subjects when asked by Rspamd.
+
+This mailet can scan mails against per-user Bayes by configure `perUserBayes` in `rspamd.properties`. This is achieved
+through the use of Rspamd `Deliver-To` HTTP header. If true, Rspamd will be called for each recipient of the mail, which comes at a performance cost. If true, subjects are not rewritten.
+If true `virusProcessor` and `rejectSpamProcessor` are honnered per user, at the cost of email copies. Default to false.
+
+Here is an example of mailet pipeline conducting out RspamdScanner execution:
+
+[subs=attributes+,xml]
+----
+
+
+ true
+ virus
+ spam
+
+
+ Spam
+
+
+
+
+
+
+
+ file://var/mail/virus/
+
+
+
+
+
+ all
+ .*
+
+
+ [VIRUS]
+
+
+
+
+
+
+ {mailet-repository-path-prefix}://var/mail/spam
+
+
+----
+
+==== Feedback for Rspamd
+If enabled, the `RspamdListener` will base on the Mailbox event to detect the message is a spam or not, then James will send report `spam` or `ham` to Rspamd.
+This listener can report mails to per-user Bayes by configure `perUserBayes` in `rspamd.properties`.
+The Rspamd listener needs to explicitly be registered with xref:{pages-path}/configure/listeners.adoc[listeners.xml].
+
+Example:
+
+[source,xml]
+....
+
+
+ org.apache.james.rspamd.RspamdListener
+
+
+....
+
+For more detail about how to use Rspamd's extension: `third-party/rspamd/index.md`
+
+Alternatively, batch reports can be triggered on user mailbox content via webAdmin. link:https://github.com/apache/james-project/tree/master/third-party/rspamd#additional-webadmin-endpoints[Read more].
+
+
+=== SpamAssassin
+Here is an example of mailet pipeline conducting out SpamAssassin execution:
+
+[source,xml]
+....
+
+ ignore
+ spamassassin
+ 783
+
+
+
+ org.apache.james.spamassassin.status; X-JAMES-SPAMASSASSIN-STATUS
+ org.apache.james.spamassassin.flag; X-JAMES-SPAMASSASSIN-FLAG
+
+
+ Spam
+
+....
+
+* *BayesianAnalysis* (unsupported) in the Mailet uses Bayesian probability to classify mail as
+spam or not spam. It relies on the training data coming from the users’ judgment.
+Users need to manually judge as spam and send to spam@thisdomain.com, oppositely,
+if not spam they then send to not.spam@thisdomain.com. BayesianAnalysisfeeder learns
+from this training dataset, and build predictive models based on Bayesian probability.
+There will be a certain table for maintaining the frequency of Corpus for keywords
+in the database. Every 10 mins a thread in the BayesianAnalysis will check and update
+the table. Also, the correct approach is to send the original spam or non-spam
+as an attachment to another message sent to the feeder in order to avoid bias from the
+current sender's email header.
+
+==== Feedback for SpamAssassin
+
+If enabled, the `SpamAssassinListener` will asynchronously report users mails moved to the `Spam` mailbox as Spam,
+and other mails as `Ham`, effectively populating the user database for per user spam detection. This enables a per-user
+Spam categorization to be conducted out by the SpamAssassin mailet, the SpamAssassin hook being unaffected.
+
+The SpamAssassin listener requires an extra configuration file `spamassassin.properties` to configure SpamAssassin connection (optional):
+
+.spamassassin.properties content
+|===
+| Property name | explanation
+
+| spamassassin.host
+| Hostname of the SpamAssassin server. Defaults to 127.0.0.1.
+
+| spamassassin.port
+| Port of the SpamAssassin server. Defaults to 783.
+|===
+
+Note that this configuration file only affects the listener, and not the hook or mailet.
+
+The SpamAssassin listener needs to explicitly be registered with xref:{pages-path}/configure/listeners.adoc[listeners.xml].
+
+Example:
+
+[source,xml]
+....
+
+
+ org.apache.james.mailbox.spamassassin.SpamAssassinListener
+ true
+
+
+....
diff --git a/docs/modules/servers/partials/configure/ssl.adoc b/docs/modules/servers/partials/configure/ssl.adoc
new file mode 100644
index 00000000000..df740c26bb4
--- /dev/null
+++ b/docs/modules/servers/partials/configure/ssl.adoc
@@ -0,0 +1,253 @@
+This document explains how to enable James 3.0 servers to use Transport Layer Security (TLS)
+for encrypted client-server communication.
+
+== Configure a Server to Use SSL/TLS
+
+Each of the servers xref:{pages-path}/configure/smtp.adoc[SMTP - LMTP],
+xref:{pages-path}/configure/pop3.adoc[POP3] and xref:{pages-path}/configure/imap.adoc[IMAP]
+supports use of SSL/TLS.
+
+TLS (Transport Layer Security) and SSL (Secure Sockets Layer) are protocols that provide
+data encryption and authentication between applications in scenarios where that data is
+being sent across an insecure network, such as checking your email
+(How does the Secure Socket Layer work?). The terms SSL and TLS are often used
+interchangeably or in conjunction with each other (TLS/SSL),
+but one is in fact the predecessor of the other — SSL 3.0 served as the basis
+for TLS 1.0 which, as a result, is sometimes referred to as SSL 3.1.
+
+You need to add a block in the corresponding configuration file (smtpserver.xml, pop3server.xml, imapserver.xml,..)
+
+[source,xml]
+....
+
+ file://conf/keystore
+ PKCS12
+ yoursecret
+ org.bouncycastle.jce.provider.BouncyCastleProvider
+
+....
+
+Alternatively TLS keys can be supplied via PEM files:
+
+[source,xml]
+....
+
+ file://conf/private.key
+ file://conf/certs.self-signed.csr
+
+....
+
+An optional secret might be specified for the private key:
+
+[source,xml]
+....
+
+ file://conf/private.key
+ file://conf/certs.self-signed.csr
+ yoursecret
+
+....
+
+Optionally, TLS protocols and/or cipher suites can be specified explicitly (smtpserver.xml, pop3server.xml, imapserver.xml,..).
+Otherwise, the default protocols and cipher suites of the used JDK will be used:
+
+[source,xml]
+....
+
+
+ TLSv1.2
+ TLSv1.1
+ TLSv1
+ SSLv3
+
+
+ TLS_AES_256_GCM_SHA384
+ TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256
+
+
+....
+
+Each of these block has an optional boolean configuration element socketTLS and startTLS which is used to toggle
+use of SSL or TLS for the service.
+
+With socketTLS (SSL/TLS in Thunderbird), all the communication is encrypted.
+
+With startTLS (STARTTLS in Thunderbird), the preamble is readable, but the rest is encrypted.
+
+....
+* OK JAMES IMAP4rev1 Server Server 192.168.1.4 is ready.
+* CAPABILITY IMAP4rev1 LITERAL+ CHILDREN WITHIN STARTTLS IDLE NAMESPACE UIDPLUS UNSELECT AUTH=PLAIN
+1 OK CAPABILITY completed.
+2 OK STARTTLS Begin TLS negotiation now.
+... rest is encrypted...
+....
+
+You can only enable one of the both at the same time for a service.
+
+It is also recommended to change the port number on which the service will listen:
+
+* POP3 - port 110, Secure POP3 - port 995
+* IMAP - port 143, Secure IMAP4 - port 993
+* SMTP - port 25, Secure SMTP - port 465
+
+You will now need to create your certificate store and place it in the james/conf/ folder with the name you defined in the keystore tag.
+
+Please note `JKS` keystore format is also supported (default value if no keystore type is specified):
+
+[source,xml]
+....
+
+ file://conf/keystore
+ JKS
+ yoursecret
+ org.bouncycastle.jce.provider.BouncyCastleProvider
+
+....
+
+
+=== Client authentication via certificates
+
+When you enable TLS, you may also configure the server to require a client certificate for authentication:
+
+[source,xml]
+....
+
+ file://conf/keystore
+ JKS
+ yoursecret
+
+
+ file://conf/truststore
+ JKS
+ yoursecret
+ false
+
+
+....
+
+James verifies client certificates against the provided truststore. You can fill it with trusted peer certificates directly, or an issuer certificate (CA) if you trust all certificates created by it. If you omit the truststore configuration, James will use the Java default truststore instead, effectively trusting any known CA.
+
+James can optionally enable OCSP verifications for client certificates against Certificate Revocation List referenced
+in the certificate itself.
+
+== Creating your own PEM keys
+
+The following commands can be used to create self signed PEM keys:
+
+[source,xml]
+....
+# Generating your private key
+openssl genrsa -des3 -out private.key 2048
+
+# Creating your certificates
+openssl req -new -key private.key -out certs.csr
+
+# Signing the certificate yourself
+openssl x509 -req -days 365 -in certs.csr -signkey private.key -out certs.self-signed.csr
+
+# Removing the password from the private key
+# Not necessary if you supply the secret in the configuration
+openssl rsa -in private.key -out private.nopass.key
+....
+
+You may then supply this TLS configuration:
+
+[source,xml]
+....
+
+ file://conf/private.nopass.key
+ file://conf/certs.self-signed.csr
+
+....
+
+== Certificate Keystores
+
+This section gives more indication for users relying on keystores.
+
+=== Creating your own Certificate Keystore
+
+(Adapted from the Tomcat 4.1 documentation)
+
+James currently operates only on JKS or PKCS12 format keystores. This is Java's standard "Java KeyStore" format, and is
+the format created by the keytool command-line utility. This tool is included in the JDK.
+
+To import an existing certificate into a JKS keystore, please read the documentation (in your JDK documentation package)
+about keytool.
+
+To create a new keystore from scratch, containing a single self-signed Certificate, execute the following from a terminal
+command line:
+
+....
+keytool -genkey -alias james -keyalg RSA -storetype PKCS12 -keystore your_keystore_filename
+....
+
+(The RSA algorithm should be preferred as a secure algorithm, and this also ensures general compatibility with other
+servers and components.)
+
+As a suggested standard, create the keystore in the james/conf directory, with a name like james.keystore.
+
+After executing this command, you will first be prompted for the keystore password.
+
+Next, you will be prompted for general information about this Certificate, such as company, contact name, and so on.
+This information may be displayed to users when importing into the certificate store of the client, so make sure that
+the information provided here matches what they will expect.
+
+Important: in the "distinguished name", set the "common name" (CN) to the DNS name of your James server, the one
+you will use to access it from your mail client (like "mail.xyz.com").
+
+Finally, you will be prompted for the key password, which is the password specifically for this Certificate
+(as opposed to any other Certificates stored in the same keystore file).
+
+If everything was successful, you now have a keystore file with a Certificate that can be used by your server.
+
+You MUST have only one certificate in the keystore file used by James.
+
+=== Installing a Certificate provided by a Certificate Authority
+
+(Adapted from the Tomcat 4.1 documentation
+
+To obtain and install a Certificate from a Certificate Authority (like verisign.com, thawte.com or trustcenter.de)
+you should have read the previous section and then follow these instructions:
+
+==== Create a local Certificate Signing Request (CSR)
+
+In order to obtain a Certificate from the Certificate Authority of your choice you have to create a so called
+Certificate Signing Request (CSR). That CSR will be used by the Certificate Authority to create a Certificate
+that will identify your James server as "secure". To create a CSR follow these steps:
+
+* Create a local Certificate as described in the previous section.
+
+The CSR is then created with:
+
+....
+ keytool -certreq -keyalg RSA -alias james -file certreq.csr -keystore your_keystore_filename
+....
+
+Now you have a file called certreq.csr. The file is encoded in PEM format. You can submit it to the Certificate Authority
+(look at the documentation of the Certificate Authority website on how to do this). In return you get a Certificate.
+
+Now that you have your Certificate you can import it into you local keystore. First of all you may have to import a so
+called Chain Certificate or Root Certificate into your keystore (the major Certificate Authorities are already in place,
+so it's unlikely that you will need to perform this step). After that you can procede with importing your Certificate.
+
+==== Optionally Importing a so called Chain Certificate or Root Certificate
+
+Download a Chain Certificate from the Certificate Authority you obtained the Certificate from.
+
+* For Verisign.com go to: http://www.verisign.com/support/install/intermediate.html
+* For Trustcenter.de go to: http://www.trustcenter.de/certservices/cacerts/en/en.htm#server
+* For Thawte.com go to: http://www.thawte.com/certs/trustmap.html (seems no longer valid)
+
+==== Import the Chain Certificate into you keystore
+
+....
+keytool -import -alias root -keystore your_keystore_filename -trustcacerts -file filename_of_the_chain_certificate
+....
+
+And finally import your new Certificate (It must be in X509 format):
+
+....
+keytool -import -alias james -keystore your_keystore_filename -trustcacerts -file your_certificate_filename
+....
+
+See also http://www.agentbob.info/agentbob/79.html[this page]
\ No newline at end of file
diff --git a/docs/modules/servers/partials/configure/systemPropertiesPartial.adoc b/docs/modules/servers/partials/configure/systemPropertiesPartial.adoc
new file mode 100644
index 00000000000..40648e9b9df
--- /dev/null
+++ b/docs/modules/servers/partials/configure/systemPropertiesPartial.adoc
@@ -0,0 +1,23 @@
+== System properties
+
+Some tuning can be done via system properties. This includes:
+
+.System properties
+|===
+| Property name | explanation
+
+| james.message.memory.threshold
+| (Optional). String (size, integer + size units, example: `12 KIB`, supported units are bytes KIB MIB GIB TIB). Defaults to 100KIB.
+This governs the threshold MimeMessageInputStreamSource relies on for storing MimeMessage content on disk.
+Below, data is stored in memory. Above data is stored on disk.
+Lower values will lead to longer processing time but will minimize heap memory usage. Modern SSD hardware
+should however support a high throughput. Higher values will lead to faster single mail processing at the cost
+of higher heap usage.
+
+
+| james.message.usememorycopy
+|Optional. Boolean. Defaults to false. Recommended value is false.
+Should MimeMessageWrapper use a copy of the message in memory? Or should bigger message exceeding james.message.memory.threshold
+be copied to temporary files?
+
+|===
\ No newline at end of file
diff --git a/docs/modules/servers/partials/configure/tika.adoc b/docs/modules/servers/partials/configure/tika.adoc
new file mode 100644
index 00000000000..4e2ae166620
--- /dev/null
+++ b/docs/modules/servers/partials/configure/tika.adoc
@@ -0,0 +1,48 @@
+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: You can launch a tika server using this command line:
+
+....
+docker run --name tika linagora/docker-tikaserver:1.24
+....
+
+Here are the different properties:
+
+.tika.properties content
+|===
+| Property name | explanation
+
+| 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.
+|===
diff --git a/docs/modules/servers/partials/configure/usersrepository.adoc b/docs/modules/servers/partials/configure/usersrepository.adoc
new file mode 100644
index 00000000000..e8d40e67a6a
--- /dev/null
+++ b/docs/modules/servers/partials/configure/usersrepository.adoc
@@ -0,0 +1,126 @@
+User repositories are required to store James user information and authentication data.
+
+Consult this link:{sample-configuration-prefix-url}/usersrepository.xml[example]
+to get some examples and hints.
+
+== The user data model
+
+A user has two attributes: username and password.
+
+A valid user should satisfy these criteria:
+
+* username and password cannot be null or empty
+* username should not be longer than 255 characters
+* username can not contain '/'
+* username can not contain multiple domain delimiter('@')
+* A username can have only a local part when virtualHosting is disabled. E.g.'myUser'
+* When virtualHosting is enabled, a username should have a domain part, and the domain part should be concatenated
+after a domain delimiter('@'). E.g. 'myuser@james.org'
+
+A user is always considered as lower cased, so 'myUser' and 'myuser' are the same user, and can be used as well as
+recipient local part than as login for different protocols.
+
+== Configuration
+
+.usersrepository.xml content
+|===
+| Property name | explanation
+
+| enableVirtualHosting
+| true or false. Add domain support for users (default: false, except for Cassandra Users Repository)
+
+| administratorId
+|user's name. Allow a user to access to the https://tools.ietf.org/html/rfc4616#section-2[impersonation command],
+acting on the behalf of any user.
+
+| verifyFailureDelay
+| Delay after a failed authentication attempt with an invalid user name or password. Duration string defaulting to seconds, e.g. `2`, `2s`, `2000ms`. Default `0s` (disabled).
+
+| algorithm
+| use a specific hash algorithm to compute passwords, with optional mode `plain` (default) or `salted`; e.g. `SHA-512`, `SHA-512/plain`, `SHA-512/salted`, `PBKDF2`, `PBKDF2-SHA512` (default).
+Note: When using `PBKDF2` or `PBKDF2-SHA512` one can specify the iteration count and the key size in bytes. You can specify it as part of the algorithm. EG: `PBKDF2-SHA512-2000-512` will use
+2000 iterations with a key size of 512 bytes.
+
+| hashingMode
+| specify the hashing mode to use if there is none recorded in the database: `plain` (default) for newer installations or `legacy` for older ones
+
+|===
+
+== Configuring a LDAP
+
+Alternatively you can authenticate your users against a LDAP server. You need to configure
+the properties for accessing your LDAP server in this file.
+
+Consult this link:{sample-configuration-prefix-url}/usersrepository.xml[example]
+to get some examples and hints.
+
+Example:
+
+[source,xml]
+....
+
+ true
+
+....
+
+SSL can be enabled by using `ldaps` scheme. `trustAllCerts` option can be used to trust all LDAP client certificates
+(optional, defaults to false).
+
+Example:
+
+[source,xml]
+....
+
+ true
+
+....
+
+Moreover, per domain base DN can be configured:
+
+[source,xml]
+....
+true
+
+ ou=People,o=other.com,ou=system
+
+
+....
+
+You can connect to multiple LDAP servers for better availability by using `ldapHosts` option (fallback to `ldapHost` is supported) to specify the list of LDAP Server URL with the comma `,` delimiter. We do support different schemas for LDAP servers.
+
+Example:
+
+[source,xml]
+....
+
+ true
+
+....
+
+When VirtualHosting is on, you can enable local part as login username by configure the `resolveLocalPartAttribute`.
+This is the LDAP attribute that allows to retrieve the local part of users. Optional, default to empty, which disables login with local part as username.
+
+Example:
+
+[source,xml]
+....
+
+ true
+
+....
+
+The "userListBase" configuration option is used to differentiate users that can login from those that are listed
+ as regular users. This is useful for dis-activating users, for instance.
+
+A different values from "userBase" can be used for setting up virtual logins,
+for instance in conjunction with "resolveLocalPartAttribute". This can also be used to manage
+disactivated users (in "userListBase" but not in "userBase").
+
+Note that "userListBase" can not be specified on a per-domain-basis.
diff --git a/docs/modules/servers/partials/configure/vault.adoc b/docs/modules/servers/partials/configure/vault.adoc
new file mode 100644
index 00000000000..b631222e748
--- /dev/null
+++ b/docs/modules/servers/partials/configure/vault.adoc
@@ -0,0 +1,29 @@
+Deleted Messages Vault is the component in charge of retaining messages before they are going to be deleted.
+Messages stored in the Deleted Messages Vault could be deleted after exceeding their retentionPeriod (explained below).
+It also supports to restore or export messages matching with defined criteria in
+xref:{pages-path}/operate/webadmin.adoc#_deleted_messages_vault[WebAdmin deleted messages vault document] by using
+xref:{pages-path}/operate/webadmin.adoc#_deleted_messages_vault[WebAdmin endpoints].
+
+== Deleted Messages Vault Configuration
+
+Once the vault is active, James will start moving deleted messages to it asynchronously.
+
+The Deleted Messages Vault also stores and manages deleted messages into a BlobStore. The BlobStore can be either
+based on an object storage or on {backend-name}. For configuring the BlobStore the vault will use, you can look at
+xref:{pages-path}/configure/blobstore.adoc[*blobstore.properties*] BlobStore Configuration section.
+
+== deletedMessageVault.properties
+
+Consult this link:{sample-configuration-prefix-url}/deletedMessageVault.properties[example]
+to get some examples and hints.
+
+.deletedMessageVault.properties content
+|===
+| Property name | explanation
+
+| retentionPeriod
+| Deleted messages stored in the Deleted Messages Vault are expired after this period (default: 1 year). It can be expressed in *y* years, *d* days, *h* hours, ...
+
+| restoreLocation
+| Messages restored from the Deleted Messages Vault are placed in a mailbox with this name (default: ``Restored-Messages``). The mailbox will be created if it does not exist yet.
+|===
diff --git a/docs/modules/servers/partials/configure/webadmin.adoc b/docs/modules/servers/partials/configure/webadmin.adoc
new file mode 100644
index 00000000000..61da6ed21fa
--- /dev/null
+++ b/docs/modules/servers/partials/configure/webadmin.adoc
@@ -0,0 +1,104 @@
+The web administration supports for now the CRUD operations on:
+
+- The domains
+- The users
+- Their mailboxes
+- Their quotas
+- Managing mail repositories
+- Performing cassandra migrations [small]*_(only for Distributed James Server that uses cassandra as backend)_*
+- And much more, as described in the following sections.
+
+*WARNING*: This API allows authentication only via the use of JWT. If not
+configured with JWT, an administrator should ensure an attacker can not
+use this API.
+
+By the way, some endpoints are not filtered by authentication. Those endpoints are not related to data stored in James,
+for example: Swagger documentation & James health checks.
+
+== Configuration
+
+Consult this link:{sample-configuration-prefix-url}/webadmin.properties[example]
+to get some examples and hints.
+
+.webadmin.properties content
+|===
+| Property name | explanation
+
+| enabled
+| Define if WebAdmin is launched (default: false)
+
+| port
+| Define WebAdmin's port (default: 8080)
+
+| host
+| Define WebAdmin's host (default: localhost, use 0.0.0.0 to listen on all addresses)
+
+| cors.enable
+| Allow the Cross-origin resource sharing (default: false)
+
+| cors.origin
+| Specify ths CORS origin (default: null)
+
+| jwt.enable
+| Allow JSON Web Token as an authentication mechanism (default: false)
+
+| https.enable
+| Use https (default: false)
+
+| https.keystore
+| Specify a keystore file for https (default: null)
+
+| https.password
+| Specify the keystore password (default: null)
+
+| https.trust.keystore
+| Specify a truststore file for https (default: null)
+
+| https.trust.password
+| Specify the truststore password (default: null)
+
+| jwt.publickeypem.url
+| Optional. JWT tokens allow request to bypass authentication. Path to the JWT public key.
+Defaults to the `jwt.publickeypem.url` value of `jmap.properties` file if unspecified
+(legacy behaviour)
+
+| extensions.routes
+| List of Routes specified as fully qualified class name that should be loaded in addition to your product routes list. Routes
+needs to be on the classpath or in the ./extensions-jars folder. Read mode about
+xref:{pages-path}/extending/webadmin-routes.adoc[creating you own webadmin routes].
+
+| maxThreadCount
+| Maximum threads used by the underlying Jetty server. Optional.
+
+| minThreadCount
+| Minimum threads used by the underlying Jetty server. Optional.
+
+|===
+
+== Generating a JWT key pair
+
+The {server-name} enforces the use of RSA-SHA-256.
+
+One can use OpenSSL to generate a JWT key pair :
+
+ # private key
+ openssl genrsa -out rs256-4096-private.rsa 4096
+ # public key
+ openssl rsa -in rs256-4096-private.rsa -pubout > rs256-4096-public.pem
+
+The private key can be used to generate JWT tokens, for instance
+using link:https://github.com/vandium-io/jwtgen[jwtgen]:
+
+ jwtgen -a RS256 -p rs256-4096-private.rsa 4096 -c "sub=bob@domain.tld" -c "admin=true" -e 3600 -V
+
+This token can then be passed as `Bearer` of the `Authorization` header :
+
+ curl -H "Authorization: Bearer $token" -XGET http://127.0.0.1:8000/domains
+
+The public key can be referenced as `jwt.publickeypem.url` of the `jmap.properties` configuration file.
+
+== Reverse-proxy set up
+
+WebAdmin adds the value of `X-Real-IP` header as part of the logging MDC.
+
+This allows for reverse proxies to cary other the IP address of the client down to the JMAP server for diagnostic purpose.
\ No newline at end of file
From 75fc4d5229fd8be6cd584f1720bf9d16ffffb355 Mon Sep 17 00:00:00 2001
From: Tung Tran
Date: Wed, 3 Jul 2024 12:01:33 +0700
Subject: [PATCH 002/341] [Antora] Clone Benchmarks section files to /partials
---
.../partials/benchmark/db-benchmark.adoc | 455 ++++++++++++++++++
.../partials/benchmark/james-benchmark.adoc | 100 ++++
2 files changed, 555 insertions(+)
create mode 100644 docs/modules/servers/partials/benchmark/db-benchmark.adoc
create mode 100644 docs/modules/servers/partials/benchmark/james-benchmark.adoc
diff --git a/docs/modules/servers/partials/benchmark/db-benchmark.adoc b/docs/modules/servers/partials/benchmark/db-benchmark.adoc
new file mode 100644
index 00000000000..a3e42d7b340
--- /dev/null
+++ b/docs/modules/servers/partials/benchmark/db-benchmark.adoc
@@ -0,0 +1,455 @@
+= Distributed James Server -- Database benchmarks
+:navtitle: Database benchmarks
+
+This document provides basic performance of Distributed James' databases, benchmark methodologies as a basis for a James administrator who
+can test and evaluate if his Distributed James databases are performing well.
+
+It includes:
+
+* A sample deployment topology
+* Propose benchmark methodology and base performance for each database. This aims to help operators to quickly identify
+performance issues and compliance of their databases.
+
+== Sample deployment topology
+
+We deploy a sample topology of Distributed James with these following databases:
+
+- Apache Cassandra 4 as main database: 3 nodes, each node has 8 OVH vCores CPU and 30 GB memory limit (OVH b2-30 instance).
+- OpenDistro 1.13.1 as search engine: 3 nodes, each node has 8 OVH vCores CPU and 30 GB memory limit (OVH b2-30 instance).
+- RabbitMQ 3.8.17 as message queue: 3 Kubernetes pods, each pod has 0.6 OVH vCore CPU and 2 GB memory limit.
+- OVH Swift S3 as an object storage
+
+With the above system, our email service operates stably with valuable performance.
+For a more details, it can handle a load throughput up to about 1000 JMAP requests per second with 99th percentile latency is 400ms.
+
+== Benchmark methodologies and base performances
+We are willing to share the benchmark methodologies and the result to you as a reference to evaluate your Distributed James' performance.
+Other evaluation methods are welcome, as long as your databases exhibit similar or even better performance than ours.
+It is up to your business needs. If your databases shows results that fall far from our baseline performance, there's a good chance that
+there are problems with your system, and you need to check it out thoroughly.
+
+=== Benchmark Cassandra
+
+==== Benchmark methodology
+===== Benchmark tool
+
+We use https://cassandra.apache.org/doc/latest/cassandra/tools/cassandra_stress.html[cassandra-stress tool] - an official
+tool of Cassandra for stress loading tests.
+
+The cassandra-stress tool is a Java-based stress testing utility for basic benchmarking and load testing a Cassandra cluster.
+Data modeling choices can greatly affect application performance. Significant load testing over several trials is the best method for discovering issues with a particular data model. The cassandra-stress tool is an effective tool for populating a cluster and stress testing CQL tables and queries. Use cassandra-stress to:
+
+- Quickly determine how a schema performs.
+- Understand how your database scales.
+- Optimize your data model and settings.
+- Determine production capacity.
+
+There are several operation types:
+
+- write-only, read-only, and mixed workloads of standard data
+- write-only and read-only workloads for counter columns
+- user configured workloads, running custom queries on custom schemas
+
+===== How to benchmark
+
+Here we are using a simple case to test and compare Cassandra performance between different setup environments.
+
+[source,yaml]
+----
+keyspace: stresscql
+
+keyspace_definition: |
+ CREATE KEYSPACE stresscql WITH replication = {'class': 'SimpleStrategy', 'replication_factor': 3};
+
+table: mixed_workload
+
+table_definition: |
+ CREATE TABLE mixed_workload (
+ key uuid PRIMARY KEY,
+ a blob,
+ b blob
+ ) WITH COMPACT STORAGE
+
+columnspec:
+ - name: a
+ size: uniform(1..10000)
+ - name: b
+ size: uniform(1..100000)
+
+insert:
+ partitions: fixed(1)
+
+queries:
+ read:
+ cql: select * from mixed_workload where key = ?
+ fields: samerow
+----
+
+Create the yaml file as above and copy to a Cassandra node.
+
+Insert some sample data:
+
+[source,bash]
+----
+cassandra-stress user profile=mixed_workload.yml n=100000 "ops(insert=1)" cl=ONE -mode native cql3 user= password= -node -rate threads=8 -graph file=./graph_insert.xml title=Benchmark revision=insert_ONE
+----
+
+Read intensive scenario:
+
+[source,bash]
+----
+cassandra-stress user profile=mixed_workload.yml n=100000 "ops(insert=1,read=4)" cl=ONE -mode native cql3 user= password= -node -rate threads=8 -graph file=./graph_mixed.xml title=Benchmark revision=mixed_ONE
+----
+
+In there:
+
+- n=100000: The number of insert batches, not number of individual insert operations.
+- rate threads=8: The number of concurrent threads. If not specified it will start with 4 threads and increase until server reaches a limit.
+- ops(insert=1,read=4): This will execute insert and read queries in the ratio 1:4.
+- graph: Export results to graph in html format.
+
+==== Sample benchmark result
+image::cassandra_stress_test_result_1.png[]
+
+image::cassandra_stress_test_result_2.png[]
+
+==== References
+https://www.datastax.com/blog/improved-cassandra-21-stress-tool-benchmark-any-schema-part-1[Datastax - Cassandra stress tool]
+
+https://www.instaclustr.com/deep-diving-cassandra-stress-part-3-using-yaml-profiles/[Deep Diving cassandra-stress – Part 3 (Using YAML Profiles)]
+
+=== Benchmark OpenSearch
+
+==== Benchmark methodology
+
+===== Benchmark tool
+We use https://github.com/opensearch-project/opensearch-benchmark[opensearch-benchmark] - an official OpenSearch benchmarking tool.
+It provides the following features:
+
+- Automatically create OpenSearch clusters, stress tests them, and delete them.
+- Manage stress testing data and solutions by OpenSearch version.
+- Present stress testing data in a comprehensive way, allowing you to compare and analyze the data of different stress tests and store the data on a particular OpenSearch instance for secondary analysis.
+- Collect Java Virtual Machine (JVM) details, such as memory and garbage collection (GC) data, to locate performance problems.
+
+===== How to benchmark
+To install the `opensearch-benchmark` tool, you need Python 3.8+ including pip3 first, then run:
+```
+python3 -m pip install opensearch-benchmark
+```
+
+If you have any trouble or need more detailed instructions, please look in the https://github.com/opensearch-project/OpenSearch-Benchmark/blob/main/DEVELOPER_GUIDE.md[detailed installation guide].
+
+Let's see which workloads (simulation profiles) that `opensearch-benchmark` provides: ```opensearch-benchmark list worloads```.
+For our James use case, we are interested in ```pmc``` workload: ```Full-text benchmark with academic papers from PMC```.
+
+Run the below script to benchmark against your OpenSearch cluster:
+
+[source,bash]
+----
+opensearch-benchmark execute_test --pipeline=benchmark-only --workload=[workload-name] --target-host=[ip_node1:port_node1],[ip_node2:port_node2],[ip_node3:port_node3] --client-options="use_ssl:false,verify_certs:false,basic_auth_user:'[user]',basic_auth_password:'[password]'"
+----
+
+In there:
+
+* --pipeline=benchmark-only: benchmark against a running cluster
+* workload-name: the workload you want to benchmark
+* ip:port: OpenSearch Node' socket
+* user/password: OpenSearch authentication credentials
+
+==== Sample benchmark result
+===== PMC worload
+
+[source]
+----
+| Metric | Task | Value | Unit |
+|---------------------------------------------------------------:|------------------------------:|------------:|--------:|
+| Min Throughput | index-append | 734.63 | docs/s |
+| Mean Throughput | index-append | 763.16 | docs/s |
+| Median Throughput | index-append | 746.5 | docs/s |
+| Max Throughput | index-append | 833.51 | docs/s |
+| 50th percentile latency | index-append | 4738.57 | ms |
+| 90th percentile latency | index-append | 8129.1 | ms |
+| 99th percentile latency | index-append | 11734.5 | ms |
+| 100th percentile latency | index-append | 14662.9 | ms |
+| 50th percentile service time | index-append | 4738.57 | ms |
+| 90th percentile service time | index-append | 8129.1 | ms |
+| 99th percentile service time | index-append | 11734.5 | ms |
+| 100th percentile service time | index-append | 14662.9 | ms |
+| error rate | index-append | 0 | % |
+| Min Throughput | default | 19.94 | ops/s |
+| Mean Throughput | default | 19.95 | ops/s |
+| Median Throughput | default | 19.95 | ops/s |
+| Max Throughput | default | 19.96 | ops/s |
+| 50th percentile latency | default | 23.1322 | ms |
+| 90th percentile latency | default | 25.4129 | ms |
+| 99th percentile latency | default | 29.1382 | ms |
+| 100th percentile latency | default | 29.4762 | ms |
+| 50th percentile service time | default | 21.4895 | ms |
+| 90th percentile service time | default | 23.589 | ms |
+| 99th percentile service time | default | 26.6134 | ms |
+| 100th percentile service time | default | 27.9068 | ms |
+| error rate | default | 0 | % |
+| Min Throughput | term | 19.93 | ops/s |
+| Mean Throughput | term | 19.94 | ops/s |
+| Median Throughput | term | 19.94 | ops/s |
+| Max Throughput | term | 19.95 | ops/s |
+| 50th percentile latency | term | 31.0684 | ms |
+| 90th percentile latency | term | 34.1419 | ms |
+| 99th percentile latency | term | 74.7904 | ms |
+| 100th percentile latency | term | 103.663 | ms |
+| 50th percentile service time | term | 29.6775 | ms |
+| 90th percentile service time | term | 32.4288 | ms |
+| 99th percentile service time | term | 36.013 | ms |
+| 100th percentile service time | term | 102.193 | ms |
+| error rate | term | 0 | % |
+| Min Throughput | phrase | 19.94 | ops/s |
+| Mean Throughput | phrase | 19.95 | ops/s |
+| Median Throughput | phrase | 19.95 | ops/s |
+| Max Throughput | phrase | 19.95 | ops/s |
+| 50th percentile latency | phrase | 23.0255 | ms |
+| 90th percentile latency | phrase | 26.1607 | ms |
+| 99th percentile latency | phrase | 31.2094 | ms |
+| 100th percentile latency | phrase | 45.5012 | ms |
+| 50th percentile service time | phrase | 21.5109 | ms |
+| 90th percentile service time | phrase | 24.4144 | ms |
+| 99th percentile service time | phrase | 26.1865 | ms |
+| 100th percentile service time | phrase | 43.5122 | ms |
+| error rate | phrase | 0 | % |
+
+----------------------------------
+[INFO] SUCCESS (took 1772 seconds)
+----------------------------------
+----
+
+===== PMC custom workload
+We customized the PMC workload by increasing search throughput target to figure out our OpenSearch cluster limit.
+
+The result is that with 25-30 request/s we have a 99th percentile latency of 1s.
+
+==== References
+The `opensearch-benchmark` tool seems to be a fork of the official benchmark tool https://github.com/elastic/rally[EsRally] of Elasticsearch.
+The `opensearch-benchmark` tool is not adopted widely yet, so we believe some EsRally references could help as well:
+
+- https://www.alibabacloud.com/blog/esrally-official-stress-testing-tool-for-elasticsearch_597102[esrally: Official Stress Testing Tool for Elasticsearch]
+
+- https://esrally.readthedocs.io/en/latest/adding_tracks.html[Create a custom EsRally track]
+
+- https://discuss.elastic.co/t/why-the-percentile-latency-is-several-times-more-than-service-time/69630[Why the percentile latency is several times more than service time]
+
+=== Benchmark RabbitMQ
+
+==== Benchmark methodology
+
+===== Benchmark tool
+We use https://github.com/rabbitmq/rabbitmq-perf-test[rabbitmq-perf-test] tool.
+
+===== How to benchmark
+Using PerfTestMulti for more friendly:
+
+- Provide input scenario from a single file
+- Provide output result as a single file. Can be visualized result file by the chart (graph WebUI)
+
+Run a command like below:
+
+[source,bash]
+----
+bin/runjava com.rabbitmq.perf.PerfTestMulti [scenario-file] [result-file]
+----
+
+In order to visualize result, coping [result-file] to ```/html/examples/[result-file]```.
+Start webserver to view graph by the command:
+
+[source,bash]
+----
+bin/runjava com.rabbitmq.perf.WebServer
+----
+Then browse: http://localhost:8080/examples/sample.html
+
+==== Sample benchmark result
+- Scenario file:
+
+[source]
+----
+[{'name': 'consume', 'type': 'simple',
+'uri': 'amqp://james:eeN7Auquaeng@localhost:5677',
+'params':
+ [{'time-limit': 30, 'producer-count': 2, 'consumer-count': 4}]}]
+----
+
+- Result file:
+
+[source,json]
+----
+{
+ "consume": {
+ "send-bytes-rate": 0,
+ "recv-msg-rate": 4330.225080385852,
+ "avg-latency": 18975254,
+ "send-msg-rate": 455161.3183279743,
+ "recv-bytes-rate": 0,
+ "samples": [{
+ "elapsed": 15086,
+ "send-bytes-rate": 0,
+ "recv-msg-rate": 0,
+ "send-msg-rate": 0.06628662335940608,
+ "recv-bytes-rate": 0
+ },
+ {
+ "elapsed": 16086,
+ "send-bytes-rate": 0,
+ "recv-msg-rate": 1579,
+ "max-latency": 928296,
+ "min-latency": 278765,
+ "avg-latency": 725508,
+ "send-msg-rate": 388994,
+ "recv-bytes-rate": 0
+ },
+ {
+ "elapsed": 48184,
+ "send-bytes-rate": 0,
+ "recv-msg-rate": 3768.4918347742555,
+ "max-latency": 32969370,
+ "min-latency": 31852685,
+ "avg-latency": 32385432,
+ "send-msg-rate": 0,
+ "recv-bytes-rate": 0
+ },
+ {
+ "elapsed": 49186,
+ "send-bytes-rate": 0,
+ "recv-msg-rate": 4416.167664670658,
+ "max-latency": 33953465,
+ "min-latency": 32854771,
+ "avg-latency": 33373113,
+ "send-msg-rate": 0,
+ "recv-bytes-rate": 0
+ }]
+ }
+}
+----
+
+- Key result points:
+
+|===
+|Metrics |Unit |Result
+
+|Publisher throughput (the sending rate)
+|messages / second
+|3111
+
+|Consumer throughput (the receiving rate)
+|messages / second
+|4404
+|===
+
+=== Benchmark S3 storage
+
+==== Benchmark methodology
+
+===== Benchmark tool
+We use https://github.com/dvassallo/s3-benchmark[s3-benchmark] tool.
+
+===== How to benchmark
+1. Make sure you set up appropriate S3 credentials with `awscli`.
+2. If you are using a compatible S3 storage of cloud providers like OVH, you would need to configure
+`awscli-plugin-endpoint`. E.g: https://docs.ovh.com/au/en/storage/getting_started_with_the_swift_S3_API/[Getting started with the OVH Swift S3 API]
+3. Install `s3-benchmark` tool and run the command:
+
+[source,bash]
+----
+./s3-benchmark -endpoint=[endpoint] -region=[region] -bucket-name=[bucket-name] -payloads-min=[payload-min] -payloads-max=[payload-max] threads-max=[threads-max]
+----
+
+==== Sample benchmark result
+We did S3 performance testing with suitable email objects sizes: 4 KB, 128 KB, 1 MB, 8 MB.
+
+Result:
+
+[source,bash]
+----
+--- SETUP --------------------------------------------------------------------------------------------------------------------
+
+Uploading 4 KB objects
+ 100% |████████████████████████████████████████| [4s:0s]
+Uploading 128 KB objects
+ 100% |████████████████████████████████████████| [9s:0s]
+Uploading 1 MB objects
+ 100% |████████████████████████████████████████| [8s:0s]
+Uploading 8 MB objects
+ 100% |████████████████████████████████████████| [10s:0s]
+
+--- BENCHMARK ----------------------------------------------------------------------------------------------------------------
+
+Download performance with 4 KB objects (b2-30)
+ +-------------------------------------------------------------------------------------------------+
+ | Time to First Byte (ms) | Time to Last Byte (ms) |
++---------+----------------+------------------------------------------------+------------------------------------------------+
+| Threads | Throughput | avg min p25 p50 p75 p90 p99 max | avg min p25 p50 p75 p90 p99 max |
++---------+----------------+------------------------------------------------+------------------------------------------------+
+| 8 | 0.6 MB/s | 36 10 17 22 36 57 233 249 | 37 10 17 22 36 57 233 249 |
+| 9 | 0.6 MB/s | 30 10 15 21 33 45 82 234 | 30 10 15 21 33 45 83 235 |
+| 10 | 0.2 MB/s | 55 11 18 22 28 52 248 1075 | 55 11 18 22 28 52 249 1075 |
+| 11 | 0.3 MB/s | 66 11 18 23 45 233 293 683 | 67 11 19 23 45 233 293 683 |
+| 12 | 0.6 MB/s | 35 12 19 22 43 55 67 235 | 35 12 19 22 43 56 67 235 |
+| 13 | 0.2 MB/s | 68 11 19 26 58 79 279 1037 | 68 11 19 26 58 80 279 1037 |
+| 14 | 0.6 MB/s | 43 17 20 24 52 56 230 236 | 43 17 20 25 52 56 230 236 |
+| 15 | 0.2 MB/s | 69 11 16 23 50 66 274 1299 | 69 11 16 24 50 66 274 1299 |
+| 16 | 0.5 MB/s | 52 9 19 31 81 95 228 237 | 53 9 19 31 81 95 229 237 |
++---------+----------------+------------------------------------------------+------------------------------------------------+
+
+Download performance with 128 KB objects (b2-30)
+ +-------------------------------------------------------------------------------------------------+
+ | Time to First Byte (ms) | Time to Last Byte (ms) |
++---------+----------------+------------------------------------------------+------------------------------------------------+
+| Threads | Throughput | avg min p25 p50 p75 p90 p99 max | avg min p25 p50 p75 p90 p99 max |
++---------+----------------+------------------------------------------------+------------------------------------------------+
+| 8 | 3.3 MB/s | 71 16 22 28 39 66 232 1768 | 73 16 23 29 43 67 233 1769 |
+| 9 | 3.6 MB/s | 74 9 19 23 34 58 239 1646 | 75 10 20 24 37 59 240 1647 |
+| 10 | 2.9 MB/s | 97 16 21 24 48 89 656 2034 | 99 17 21 26 49 92 657 2035 |
+| 11 | 3.0 MB/s | 100 10 21 26 39 64 1049 2029 | 101 11 21 27 40 65 1050 2030 |
+| 12 | 3.0 MB/s | 76 12 19 24 44 56 256 2012 | 77 13 20 25 48 69 258 2013 |
+| 13 | 6.1 MB/s | 73 10 13 20 43 223 505 1026 | 74 10 15 21 43 224 506 1027 |
+| 14 | 5.5 MB/s | 81 11 15 23 51 240 666 1060 | 82 12 16 23 54 241 667 1060 |
+| 15 | 2.7 MB/s | 80 10 19 28 43 59 234 2222 | 84 11 25 34 47 60 236 2224 |
+| 16 | 18.6 MB/s | 58 10 19 26 61 224 248 266 | 61 10 22 29 65 224 249 267 |
++---------+----------------+------------------------------------------------+------------------------------------------------+
+
+Download performance with 1 MB objects (b2-30)
+ +-------------------------------------------------------------------------------------------------+
+ | Time to First Byte (ms) | Time to Last Byte (ms) |
++---------+----------------+------------------------------------------------+------------------------------------------------+
+| Threads | Throughput | avg min p25 p50 p75 p90 p99 max | avg min p25 p50 p75 p90 p99 max |
++---------+----------------+------------------------------------------------+------------------------------------------------+
+| 8 | 56.4 MB/s | 41 12 26 34 43 57 94 235 | 136 30 69 100 161 284 345 396 |
+| 9 | 55.2 MB/s | 53 19 32 39 50 69 238 247 | 149 26 84 117 164 245 324 655 |
+| 10 | 33.9 MB/s | 74 17 27 37 50 77 456 1060 | 177 29 97 134 205 273 484 1076 |
+| 11 | 57.3 MB/s | 56 26 35 44 57 71 251 298 | 185 40 93 129 216 329 546 871 |
+| 12 | 37.7 MB/s | 66 21 33 43 58 73 102 1024 | 202 24 81 125 205 427 839 1222 |
+| 13 | 57.6 MB/s | 59 24 35 40 58 71 275 289 | 215 40 94 181 288 393 500 674 |
+| 14 | 47.1 MB/s | 73 18 46 56 66 75 475 519 | 229 30 116 221 272 441 603 686 |
+| 15 | 58.2 MB/s | 65 11 40 51 63 75 260 294 | 243 29 132 174 265 485 831 849 |
+| 16 | 23.1 MB/s | 96 14 46 55 62 80 124 2022 | 278 31 124 187 249 634 827 2028 |
++---------+----------------+------------------------------------------------+------------------------------------------------+
+
+Download performance with 8 MB objects (b2-30)
+ +-------------------------------------------------------------------------------------------------+
+ | Time to First Byte (ms) | Time to Last Byte (ms) |
++---------+----------------+------------------------------------------------+------------------------------------------------+
+| Threads | Throughput | avg min p25 p50 p75 p90 p99 max | avg min p25 p50 p75 p90 p99 max |
++---------+----------------+------------------------------------------------+------------------------------------------------+
+| 8 | 58.4 MB/s | 88 35 65 79 88 96 288 307 | 1063 458 564 759 928 1151 4967 6841 |
+| 9 | 50.4 MB/s | 137 32 52 69 145 286 509 1404 | 1212 160 471 581 1720 2873 3744 4871 |
+| 10 | 58.2 MB/s | 77 46 54 66 77 98 275 285 | 1319 377 432 962 1264 3232 4266 6151 |
+| 11 | 58.4 MB/s | 97 32 63 72 80 91 323 707 | 1429 325 593 722 1648 3020 6172 6370 |
+| 12 | 58.5 MB/s | 108 26 65 81 91 261 301 519 | 1569 472 696 1101 1915 3175 4066 5110 |
+| 13 | 56.1 MB/s | 115 35 69 83 93 125 329 1092 | 1712 458 801 1165 2354 3559 3865 5945 |
+| 14 | 58.6 MB/s | 103 26 70 78 88 112 309 656 | 1807 789 999 1269 1998 3258 5201 6651 |
+| 15 | 58.3 MB/s | 113 31 55 67 79 134 276 1490 | 1947 497 1081 1756 2730 3557 3799 3974 |
+| 16 | 58.0 MB/s | 99 35 67 79 96 146 282 513 | 2091 531 882 1136 2161 6034 6686 6702 |
++---------+----------------+------------------------------------------------+------------------------------------------------+
+----
+
+We believe that the actual OVH Swift S3' throughput should be at least about 100 MB/s. This was not fully achieved due to
+network limitations of the client machine performing the benchmark.
+
+
diff --git a/docs/modules/servers/partials/benchmark/james-benchmark.adoc b/docs/modules/servers/partials/benchmark/james-benchmark.adoc
new file mode 100644
index 00000000000..07040bb90fa
--- /dev/null
+++ b/docs/modules/servers/partials/benchmark/james-benchmark.adoc
@@ -0,0 +1,100 @@
+= Distributed James Server benchmark
+:navtitle: James benchmarks
+
+This document provides benchmark methodology and basic performance of Distributed James as a basis for a James administrator who
+can test and evaluate if his Distributed James is performing well.
+
+It includes:
+
+* A sample Distributed James deployment topology
+* Propose benchmark methodology
+* Sample performance results
+
+This aims to help operators quickly identify performance issues.
+
+== Sample deployment topology
+
+We deploy a sample topology of Distributed James with these following components:
+
+- Distributed James: 3 Kubernetes pods, each pod has 2 OVH vCore CPU and 4 GB memory limit.
+- Apache Cassandra 4 as main database: 3 nodes, each node has 8 OVH vCores CPU and 30 GB memory limit (OVH b2-30 instance).
+- OpenDistro 1.13.1 as search engine: 3 nodes, each node has 8 OVH vCores CPU and 30 GB memory limit (OVH b2-30 instance).
+- RabbitMQ 3.8.17 as message queue: 3 Kubernetes pods, each pod has 0.6 OVH vCore CPU and 2 GB memory limit.
+- OVH Swift S3 as an object storage
+
+== Benchmark methodology and base performance
+
+=== Provision testing data
+
+Before doing the performance test, you should make sure you have a Distributed James up and running with some provisioned testing
+data so that it is representative of reality.
+
+Please follow these steps to provision testing data:
+
+* Prepare James with a custom `mailetcontainer.xml` having Random storing mailet. This help us easily setting a good amount of
+provisioned emails.
+
+Add this under transport processor
+----
+
+----
+
+* Modify https://github.com/apache/james-project/tree/master/docs/modules/servers/pages/distributed/benchmark/provision.sh[provision.sh]
+upon your need (number of users, mailboxes, emails to be provisioned).
+
+Currently, this script provisions 10 users, 15 mailboxes and hundreds of emails for example. Normally to make the performance test representative, you
+should provision thousands of users, thousands of mailboxes and millions of emails.
+
+* Add the permission to execute the script:
+----
+chmod +x provision.sh
+----
+
+* Install postfix (to get the smtp-source command):
+----
+sudo apt-get install postfix
+----
+
+* Run the provision script:
+----
+./provision.sh
+----
+
+After provisioning once, you should remove the Random storing mailet and move on to performance testing phase.
+
+=== Provide performance testing method
+
+We introduce the tailored https://github.com/linagora/james-gatling[James Gatling] which bases on https://gatling.io/[Gatling - Load testing framework]
+for performance testing against IMAP/JMAP servers. Other testing method is welcome as long as you feel it is appropriate.
+
+Here are steps to do performance testing with James Gatling:
+
+* Setup James Gatling with `sbt` build tool
+
+* Configure the `Configuration.scala` to point to your Distributed James IMAP/JMAP server(s). For more configuration details, please read
+https://github.com/linagora/james-gatling#readme[James Gatling Readme].
+
+* Run the performance testing simulation:
+----
+$ sbt
+> gatling:testOnly SIMULATION_FQDN
+----
+
+In there: `SIMULATION_FQDN` is fully qualified class name of a performance test simulation.
+
+We did provide a lot of simulations in `org.apache.james.gatling.simulation` path. You can have a look and choose the suitable simulation.
+`sbt gatling:testOnly org.apache.james.gatling.simulation.imap.PlatformValidationSimulation` is a good starting point. Or you can even customize your simulation also!
+
+Some symbolic simulations we often use:
+
+* IMAP: `org.apache.james.gatling.simulation.imap.PlatformValidationSimulation`
+* JMAP rfc8621: `org.apache.james.gatling.simulation.jmap.rfc8621.PushPlatformValidationSimulation`
+
+=== Base performance result
+
+A sample IMAP performance testing result (PlatformValidationSimulation):
+
+image::james-imap-base-performance.png[]
+
+If you get a IMAP performance far below this base performance, you should consider investigating for performance issues.
+
From 369f932c20ea36ddc96d8454ab3e181c6cce48b4 Mon Sep 17 00:00:00 2001
From: Tung Tran
Date: Wed, 3 Jul 2024 12:47:40 +0700
Subject: [PATCH 003/341] [Antora] Make partial for server Benchmarks
---
...ames-imap-base-performance-distributed.png | Bin 0 -> 695993 bytes
.../images/james-imap-base-performance.png | Bin 192914 -> 0 bytes
.../benchmark/benchmark_prepare.adoc | 1 +
.../distributed/benchmark/db-benchmark.adoc | 377 +-----------------
.../pages/distributed/benchmark/index.adoc | 11 +-
.../benchmark/james-benchmark.adoc | 102 +----
.../partials/benchmark/db-benchmark.adoc | 103 +----
.../servers/partials/benchmark/index.adoc | 7 +
.../partials/benchmark/james-benchmark.adoc | 27 +-
9 files changed, 42 insertions(+), 586 deletions(-)
create mode 100644 docs/modules/servers/assets/images/james-imap-base-performance-distributed.png
delete mode 100644 docs/modules/servers/assets/images/james-imap-base-performance.png
create mode 100644 docs/modules/servers/pages/distributed/benchmark/benchmark_prepare.adoc
create mode 100644 docs/modules/servers/partials/benchmark/index.adoc
diff --git a/docs/modules/servers/assets/images/james-imap-base-performance-distributed.png b/docs/modules/servers/assets/images/james-imap-base-performance-distributed.png
new file mode 100644
index 0000000000000000000000000000000000000000..aa693982a6f4cc6a33b6f0a33f7bd71eb883bd0e
GIT binary patch
literal 695993
zcmc$`XH-?$wk>Q9m=#e3!4e7(5y>FYKu{#ZCP)%ckPMQu36Ug)h$I1p0%Ri~k~2t>
zEFx@zwCc`L|C9ilixv2EM7L$_{<
zD{b4h$79>J-H!YA;3s;#U*++y{Z=G~2eF+jdL*nu?>&uP!4q
zT8Hr7ElYx(;oetW_224_Uw9SsnXTGDTen^!zrVUXQ(Oht=5@D++%e
z$Z@gD5$QeLwnd*)s#jK*vNv6*wA=d45Q~QDyAR^tSAt~i8xl7!OKTrDmbg9F7Cy3b
zA79(!`YGZ#ab!iLF?KXBh2h!J>-+xr?|;xyjCaug=MV5lFH$ex+WcQX6BcJ&`Cq>~
zdo*w`;D27N{D$}|vHx-XXGf15`+s_|+75b3irqdH{T=iN{^L3Rx$S+v6;J97Zz#Ub
z
zpDy|T=ZlqpUflbCqrq{Rz#2^0dX_^I9{--mN+iax)O18lhnjg^|4AdEs5%*-`#NP}
z*j=4Hgw)OUEJuEdBvy?>ZXTcLkUn?&lCctN8?xjVn>Wm#W|NoI_3
zM@Rn8w1>H77G7~mx3X^hG4&*dMV*a`_V8Z5h{>oO)p;q(Y*f`F^MmtFw<;-Sx3Ty<
zArb{>5C5_kQcYTjqEh(zlF{Se(ek3_TAY%%t7t%rNkyO4Pvvh4>r>zC&T5k`1WOM-
zyuu@!pD-w&s1l>VayPx*N-*;CSqke@#9%?s>)Q#0v^&YB(+{gygDF;A=_C}b^1E1k
z=B_^detn&tsM>bYSAxRxi^ycU!}b3@F6Gnj9_GrVss9}xzbB;DGv4_4=!tBC`TpRW
zjEF*k$c9XZ+>55!H+&_o6R!VEG-}QLn@r+}iD`M!dy{z^oeJ>{QzS$5gaQrYRd$
z{)pS6+*f|$zr%4>=);}T_e3J2d->UA)o*mrC(Yj+
z6uS0eO`bro2`t-aGqRMz4GP~Qp0aBB-ZQ?XX1PZE@aBlx7QyT7EseB)U0av^%HC5B
z6YiFmTOQ4Cxa<5uXW!yjv!UQm-PJfkdHv(!eGk&DIjI+3Ul$5Pd@IgZ=m+9KbG7(_
zuIZj^xfc*`j6GtbI-r_#(zjwRj&7Idzwa3*vR{v(n*I;E<1P2()6{qQ4f@m@awi!R
zz29fHi23Nhp5NqCNqS|gouI`YRByQb)1BmDvHx+79mo&h>aX3?pRCTN#6rmuQu`?I
z2V&s0wB!&j`A&faif-4ymKXutLw_Zgyu{=j1;@L4%-ptlFz`F_2g$f*W6P?RMR;
zO8&82%kEA2f8&~*FS&6%bKPkUVFGcM9O80ES>)D-u0+&6+
zS3m70dkA-s#$m6W5%o-1jekcdQgqIZBkZ3qK6AWFH2+Qv79|pu*h6kH1(Cl`M5KPX
zd{?tFcim;SPoF{G+Ai_`Y2aOikm`)1TT+v^M?x
zDb8`Uq|ZwDFY#|3K6J9p-*^s5D6&ve7)mI_DV17eN9#&l@<(@30k{%YSzl@uCXr
zeb(UdxcRDu
z`Eq^hhq*sHydt>54u;7*w-PvbdM&1LBsMuYI9W6Mv(1QomPNY^$7%AhAP`8xWgBrU
z6jZ(y52TDTU)2tMy~joAE5Re{(wjW`AM1j+nTccccoU*_nx5Xs)%8hx`;~t0oGYDW
zhM9dtYeh9RDS3JRLK?oK`*vC7zBP@O+-FV5{4>1Ef;ps?Q%tO}xBZXj&l{{a*LPD<
zQQ>G&`c`BfDg0BLRDF*NtNWK+!hWxi(6A`IwZ%zWhg62s2g&KjOXMh(?{1vMlnFyq
zA(R#YTGMIP|8ZY}M|f70+1|X6jMd7s^){#y8>$()SXWo~s@hQXP-J%JOG1@AhvOm}H+TBr{0g4M!1Ma!>+i3!
zQ85HdAM>wFnMxAmi#VIz>0fWCz4mEMjzCZ$Ao0Cpp}@8vsb=K{QJnkFtmJ9n(oRMvCXnZ
z$Nm!c#i@-wLJq%5#$Jyz%(fuVtA`#M_VWbZe7G{VZ@SRo_53Mz4j~~2Qj2Kzac}YJ
z`!*lcf<7T)7Z>@)CniYU3y%}023l4mbF~iVcWquZJi7ls9;dvl_pzjWdOO>Vk>@#9
zn>*4Tyk6+)`fV}#J~j17bfa&)G2`+5l~v3F?(52`=Z_5!59jg-%h=eQczksmfq;bK
z_wwaKr)946^mKesI_`T*`?Vz|1d}Ldbz7T2x{XbFjN<2Z)6#|1{J_9tdm0Z1BC(HH
z=p6cNN@B>!&gK>tK6v%Ujh$GZW!G-rC07m#&mGvUkK(E~6Sxp#37MJqC%X{vh?e92
zl6d;xOH0k)j%vANU%qGJ9KO`E^;gu?f?0RL{`@ZYsutaWffIgyeoDH!Qa5h=g&U4w
zV)m&xANYV01?h^m0IkEDuixw(qRpeXa?I^!Z?NGN`q!E>G*!1=*WUl!&em?W_{Ju{
zjIXoBgo#FVB9g#^YWJ#|kx0}}Z$~T}X1=Z+`Z8(XV`HZzOvfBi-#@>CA1`SQvHWvR
z%AbDz^r>WdS>VQv8*J?CDTPkK&!6u(d{$8W_U+oU*|sSvtf;;XkwR6Smc{i!@}kwP
z$(qP%Z?D)qKO(mN*GQDh%g2u&Yc}k^6f9k?&lw*df0~YtDe&fB^@dG$T?JDQOiW^8
zW1kik65h=W+o=biRA1D=H~aC
z<7Id4c)XU?wo(&(k@m{NXDKP{&d$!bn!c^=>!og&0Dl_(&+Z$};o;#^PJLO+tH3HU
zGBO-ju2lc{L0Nt8l@_}f&_<+OfzIWL*5ug2!pQh|reF4J9SJ$f4|r;R{bDmPFu)=%
zPWK!ssjEAP|7$bjTb%6lBCQRT3l!Jrr=7;`{M~E}ys~rWPE^f3d-q_pvR3Vg_
zWa?+$Nz*2=vIkXv`t<4Rip@w^SeOLK?sKlNxA>Exp_AJHukY@9b-;5+g}(R0l{>Y9
z5{jrIz7;-Q7B`wRQh)3(n;E*e{>w;=nf5TMc52kV)WTCaCR&cd7ILok$9IoTPbb7z
zE)4zY;Ugg_DV6KGLUG&ocH3kY4U@SqVQcw0^u9o`TOP*EsK^bu2Cq(z%7@*
zS;TAcbx26YD(a`T$u8B8?~aT&c6hsvy%0Zt3{b`*n?|+T*EAiDY@dVP@j;E^K(vyK+dn;j&Ql%?h6$5(q(
zUWtv_h9e@M6|dJ8ms@0~>y_;R0+tG(8!BE8*}8u2C?0dKZ^gs1c`I#Fy=Pq2%d-Q8
zOWg+d?|a_kx)rB%P0=ssnwr|FeEZ2SBlAt)zh9S?t?x)UuB(TbRMTvlUV3veZB8_#rVd*RndguTO82w6&@$yz#sF
zLHP5=5rYR0UTm$1Z82XiT0T$Z>zS7)cx!Y0WzEpTj~_o;^_TB|NiWv$?c32lt591(
z{|f!mi3MPewn7*Fe23{u!}MeOc1;QJDWCM0yyCLRW?8htgq6l&+F`Z&+qm0t;E*ug
z5zTCi;K3u6E_Q=ok5QdE1#AW6(q}8^G+)mTytC`+wI`+T7(M9D^Kb1bIAU9Py-0zh
zQ$fR=kM?ED#Wr49zzP3pw`rljl`gR6$=N8MD7|}Bo8+|6;?c*ST3q_;7j4r6%0~=R
zFS)q5q(59KFWLy0|NTCJC0Lq`jg3n{z%kRusJo6aUyD7Dlp34uu#<*=F~U0mzc5$o
zMUP*qSzq6QcA+@|z>BvYdo@Ap-lyq0AJK@AyM6oi!9$Towq`#+|KPvo>L4X7rq63zH%M56;b
zI__|XxroR%7rinc93LM?5WJ6%AATA1*S`Spde#S`w7L1Ey@zRg1Gbg}ES_8b(Dg}NLkWlnnR1e&ztlW%KZS%s-
z?xYwCWB-06h#+Opun%iFxF*55Nq|KVxX?R
zo|~Uv>U^L$$&O(=fj#IZ(+f!hAXchVAvsokJEqTWJPHe=jtP8`X06k8wW^9a?Csn0
z!P034RrY+A9lwJ+9uWwCQc|Qj%^PN!cRp-xApng@$34+WRA5(A*U>T5doRuuR63o?
zOi8i*s61on+qYi~)BES06O)o|C{n&kr0k31NK-$kO={vf6j3k9@@
zHQBLH`aBEyLWYdeao2N|N{4KZAKYVXZvH2gFQ=ej!^-@rPwH%=&Yn2`-wiD&fm^d6U%UPHtiTUhX&3U*gSY6}iNiMpNEZsxj_
z-*X@7+ScAahR6yq^?*m3E9{=Dt80r>dddV~q@j^N)gWp$HoUAaNAOf;mzky*8oQYp
z4)_D8
zERsaRoeh4LOpXc?u#zt-~t|vXyd+$0qQKynji#+mDa1OqF
z|Ne?PVh02Jx3;#MH*P$oj%KCuJ$UF)V7;NSrDZ}&O2c|Sp0w}Nu^uH#Po%NW?Z1c{
z6Oz#`z@@|y?+X24YlcXQt@ovROIgYCXgCXlSO#3!CjC
z_0zuo{>_84Dt=y1)xE=v?@8&o$;ruKcLEC~xz%-a49&{o0|EoE8<#OjXubu2P*~XY
z(W3Sq7u%&voFXEHtZxRb1ZJEIGcu`dGI(VfLTbZ$JZBw$u1BS}n=Nm+UAeNdGV&z|M?ztWvNzBKgX^|1q&Lu#>${~{AWcYypTEG$F}
zoe$hsTU(26|D)lB$go|3#cHVLBoi~Uv8id9N#=3iiaLXc=CQxuzkiIvphAdK
z=XrRnW#C;3jWz$a=td(t(;_)SsY8*M>vrIht0nU0$pN;4^tfcy^9a<83Ts+HK^@w!
zTF(Qg!XhJXG^?C>a_Cn_W>BP%Luhq$TAKCd>ej}V<8WAl@q-5?Ll3csrAet92Tq&_
zLRLd*d|+V_lbji>&L+okdT^$1B(;cXpnSc*!na^{ID+kR>R+`(*yEwuLYI~9rJ}O0
zUs^H6f81R6CAwD=f5r%iCb
z1G6AKaDI@EO-(OiPh^;YF^3IGZpsAL-Uk{*d?4|oX5!qUY0-IY5^m4iG?hO>y8N#m
zc7ubTzlu59^@|t1`wP;<(B;kk%c|N(aH?kMH_JSFb4Q{ETzb}`!g`luh__w?7WYgW
zp%U=$@PwYEKkW6ivQn~WK5{zrQgflswSV5
zH0ba`$$X<&W9ieqW0R8=llHL_f;h3Ri|t11^I}`v_zUM5bp(AXuJn56-ov5O^`oOK
zsReUBPDQ$hz9oPB_}5KF?BwvuNVHL7l!&1wquwsL9=9d!^!^FYQ#v_RTcMFdnIs(p
zN5|8?6<>B@VoDs$ThSKqtI6ogcVZU#xEVCKt#Uq5r3Wi}BZ?7BsDNvTCO
zSU!A)^TgEvk;T(%OVcCmM$vH{{TpOJ8FE?Iu&2lkrGX3epEdYA=x{bFr`d{AE3Mf@
z_tAOTMK+4A`DORGM+7m;gZl;Fi6E_&+16cc_bz2ZE63__tW>~U>0Wv=KMHo!Fukd>
zvvzu;dm8xbFq%n{=pEpz+XgndF^!E=Wl5LI`2^by7nP(ePO<&**{2+PS%!
zx)m5SpIZT${ET`~K&glR=8Do0|w|(Sf)S
z9e{Fb)F3vh0dnweZ4_@gAdyHQqf*n-GNS!&96?bKUTiZc`2GDhdb;-$dAXAXb2S$Y
ze}Ide)Wtt=snOrvyi_JQJ&r9016MW
zOTNTg0qZ9f72qz8+vi6vOpt6wzx|=(zA_X+weu&LaS7u#TCSFN|I*fW8lW0rsiU(K
zXW>2;b7<)P=6d7STLqSKqiDCvDteDPtc9JO9V#Kac3!#1X5&`aNVG>3idMJN$XRk|
z*vyKQJU>L!mTQxcJNY2Ia(1A~X{pO$*0~S|(hEg~QsR&3#&ob-jqZ!wo5Ply&x==+
ziu)1MXj$gS-4i$fvA(sQEm67vFW^QHJ^);}2OLtTm7x#_697mJQ6jbEW9%|rD3xey
z{=0U#KB7I};WC2#BcliL=hPXxuJj03c6m0c1f=Ru9F4OB(OiOp(%R-{i|)`b*xBvc
zu^pWfP?(UGgoJgaMKkeEQKgxfgg<&)AKrVV)b`A?Ww#H+9?vrwj~^W3>}XLM}J
zu=Y(oz{rCWW%N
zIX(q0OtdN{s)UAx@v60(wSNwiqVKBDOM2Yu`o3gLIU($Ac%^>RzGZ&`^6R>ci^q5(Ff!vi;c=3G?vcBg6Xn}o3PvH
z1@O+_6L}8!`ue@}Q@k*Nh4+KGQi9-=|pI*{IH=@Ksb;V(d7Hv`L$l}Gn`ey~w
z(`|lrZ|u7ybcaQ)225^xMn?H)+i8%;^%4A>e1_%~o7{)@pH+BD@GUMicXT`dNmy8S4(q!Vq|~7Z{3g;lKKSzSp&temAye1k;OZRp+Or(3oI{`aOgiVl2_yKU>>U^CNu
zZQJn3NUrVJab~%*_Yn&2eF6(F}o_-Ft+te0oV45g!$0Xl)&+rt5Z6Lh*qmKh@!YmoMiWJeC|-e7=Cz
zKu@^Gk0R*6DRwJV7xV+5P0IAsfPK`pcqD0nPG`HO-AOXn-BFZ*gy&|f=;wbo%Y)Ow
zX&3@{yASdZ`RUDFju*{ijFECSeP4E?i}3uCJg^tN6FSXqk1e-`Xt73o9oqCNlT7r1
z^|;&O<%-J+gkVU1Zto}hCr(oA2KIK`SRjRkhwG!P8V+f`SLg*GBiAmRf#&vh?-UvW
z4dSk;Nl{QpXr=Usd&%m;1ezn}plS{to^r8`W--u_kIQSLGKFFyCRC3f8I?
zA8fK?DE&)@sb2ae5v@N0DN-($D489uR6Xhkj>M~Ws2>R&B|woq1dKAdb=KXS3xQUo
ztb76u-TX-7JQkptM5dY(DcB=i=ThoGo6r>zGC
z*z7&Bxh=m-jxS;eA|+1nT&?crE2Ai<=Ln#Z(I+ST&!mr$Qgs`Fp#oAS0AtAL3N?b>
zb!K~Kwq-(A)|;gskLcQv%UHTwE-pfdy@$DV=vsY!eL*ThpOv+-;YN)2@)xfh0wahb
zgL)&5k{WoELs+;D`0=`dL9B+NJ@={0I)i`%&&u>5IgqRRU6rUv)Ou9%j*gDDjOx)m
zyHwGQ-^!xvGdJe#Qgw^zI9O-pA_XgIYCzvKuTP~^-cCqJ7#khEJ5cE_JYUECdvTE*
z3KvrguJfGXO|m1dO`;Kvc3TWv5m8MpsJq7n#K?VX7pXtKCA4#)Dt|((thH6OXlr8{
zCW`uslPyb@ckezzDoAx-xQN!@>j-`2!~(>D`hga}L_8%}SuJ*w2>ssTgZu$}J$s>L
zpB2gqsvioCj9@t9{pu!}4={T8@RferGa}JZgbqcC`t<3$6RnrfXg2eqvEz;mJT1VoN(x1M335B@pOT$^A56Q{*EiB&LJ70v&}lw7o6MyeTbgQS22JG22}ZsLWBzn+)H}qnm17uE>iH%X;3_1g
z@1)M#97q2yDtft7{#QbB^1_?Fvqb3%^)&r7^_z?*)NX&8PF^TIr6?;rbU@dAPD;^l
zZq(%bkeo{KHsY<|Ok&cbsoyJ85^?$&+Q_V6Z3dRs>Vt}9Dnl9UV-ILX)Eh2}r*2N7
z0dp0#eA8+YZm1(XGVhdruU$V)ffahU7LUAh(!~S+vWevA+IBs7O6f0&r0mnK*XQh`
zpYhz(#N>`k^Ujfnxev_D?qOTWz!>^;2$mUn4z)BsEiDjP6UHGRto`q_*sFSb&lxqm
z#o3!7V`58>wayR38elkZY)l|0IXO$?C+?IaC|&qz!QZpBxnyi?{9Y;13KjU&;0?Bs6_mat49#9)O
zm2h%emlZ2F^UxlSJrq=BaPVp4(8B^qlDGvMlsPcBWCU+v@sgaskXF9GCB(2$0R9yB
zplx$O{G9;D3t@+>w&=Jm5Rl)U#uF2)acz?sIEzj;Em=us!x{&Rm
zi+mj&{m>pRqezJa08;9P*Wua7X;;WmUm*BY|J@`y^&?SPcy%-uybl?-4%LPLK9O4p
zJUQqFa!N+UiBZVm3s^G*dz7Z`2j-4aq7N;y0a6v@4DOp71N2*=o15-XuT>`|J3sYE
z3r3P3$DrzEpOwIJkl4zJ)zwwBcf)I<010YpAuH6XTM;r$vn#ITz5;DE0!IMq5=3R3
z#Dw*+=*X8#|Bx>A_ERcWHBizQ#RJ0IuoZlu|8g9rTj&+hk%bk*P;uY
zU!6#uPtx7+0smJt>u(7|MtOPpu91ewfp70`kb7}QVLAxP02BpVn`?|g)r4CKUJ_`#
zkmZ1BQOO`bX1f+|xEHtA$dl~Q`&I?ekCc0#z`;uM*m93@Uo|cXWuOeGs(-c^FB?(k
zliUez5jzPWu3qde;<4=IaT84sDq`{0TJgwWbx^^|a0Hf_O>hOv!~DhG
zq>1|w0f7w3?KDDA=G@T|i)@?4Um9QfIB59HdJ_|(^gFZ6KM+mar&R{7Alo)4$j=W)
zSkA@LZ@eG}3kV(9qjG?EMjE5Z|+0TV?Td?
zkoYywuJKUJrw?{#{W+05nwKW9iYOp=W8@N-5asOibng-H)XSr>0gh{v*y24m0s(~lKabyHavu!?G8f?F73be9=-!}SkXaI&{E4Zlc(|`zMH|U30uUk}
zRFzc+Y<2CT1D